Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Removing proofs from examples #817

Closed
wants to merge 4 commits into from
Closed

Removing proofs from examples #817

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1f574ef
Add PR review process for 2021 (#774)
wyc Jul 13, 2021
10c3244
Update SVG diagram with SVG fixes.
chaals Aug 25, 2021
fd81113
Removing proofs from examples
David-Chadwick Sep 9, 2021
adfeca1
Merge branch 'v1.1' into Removing-Proof
kdenhartog Nov 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
30 changes: 30 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,33 @@ mailing list as well.

### Other useful links
* [Public group email archive](https://lists.w3.org/Archives/Public/public-vc-wg/)

## Process Overview for VC Data Model Pull Requests
1. For now, we will focus only on merging new errata PRs into this repository,
but encourage activity related to new features.
2. Once a PR is opened, chairs and editors make judgement call on whether
changes are substantive or editorial.
<dl>
<dt>Editorial</dt>
<dd>Mark with "editorial" tag, merge into branch "v1.1"</dd>
<dt>Substantive</dt>
<dd>Mark with "substantial" tag. Bugfixes are merged into separate branch "v1.2". New Features stay around as an open PR.</dd>
</dl>
3. W3C CCG is notified of PRs that will be merged in the next 14 days if there
are no objections.
4. When it's determined a new reccomendation should go out, the W3C Verifiable
Credentials Working Group members meet, review all the PRs that have been
merged, and make a formal recommendation if agreement is reached.

### Roadmap for 2021
- 1 editorial update (v1.1?)
- 1 substantive update (v1.2?)
- VC Test Suite Refactoring
- Start planning VC v2 Work, request a rechartering 3-6 months before end of
year to keep VC WG functioning.

### Focus areas
- [v1] Fixing a specific bug
- [v1] Update examples in the spec to make them modern
- [v2] VC `@context` needs updating, possibly with security vocab modularized
into smaller components instead of all included into a large context file.
114 changes: 113 additions & 1 deletion diagrams/credential-graph.svg
View file
Open in desktop
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
182 changes: 181 additions & 1 deletion diagrams/presentation-graph.svg
View file
Open in desktop
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
86 changes: 35 additions & 51 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -910,7 +910,7 @@ <h3>Concrete Lifecycle Example</h3>
<a>verifiable credential</a> in a digital wallet.
</p>

<pre class="example nohighlight" title="A simple example of a verifiable credential">
<pre class="example nohighlight" title="A simple example of a verifiable credential with a JSON-LD Proof">
{
<span class='comment'>// set the context, which establishes the special terms we will be using
// such as 'issuer' and 'alumniOf'.</span>
Expand Down Expand Up @@ -974,7 +974,7 @@ <h3>Concrete Lifecycle Example</h3>
<a>verifiable presentation</a>. The <a>verifiable presentation</a> is sent to
the <a>verifier</a> and <a>verified</a>.
</p>
<pre class="example nohighlight" title="A simple example of a verifiable presentation">
<pre class="example nohighlight" title="A simple example of a verifiable presentation with a JSON-LD Proof">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
Expand Down Expand Up @@ -1133,8 +1133,7 @@ <h3>Contexts</h3>
"lang": "fr"
}]
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

Expand Down Expand Up @@ -1230,15 +1229,14 @@ <h3>Identifiers</h3>
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

<p>
The example above uses two types of identifiers. The first identifier is for
the <a>verifiable credential</a> and uses an HTTP-based URL. The second
identifier is for the <a>subject</a> of the <a>verifiable credential</a> (the
the <a>credential</a> and uses an HTTP-based URL. The second
identifier is for the <a>subject</a> of the <a>credential</a> (the
thing the <a>claims</a> are about) and uses a <a>decentralized identifier</a>,
also known as a <a>DID</a>.
</p>
Expand All @@ -1262,16 +1260,16 @@ <h3>Types</h3>

<p>
Software systems that process the kinds of objects specified in this document
use type information to determine whether or not a provided
<a>verifiable credential</a> or <a>verifiable presentation</a> is appropriate.
use type information to determine whether or not a provided (verifiable)
<a>credential</a> or (verifiable) <a>presentation</a> is appropriate.
Comment on lines +1240 to +1241
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
use type information to determine whether or not a provided (verifiable)
<a>credential</a> or (verifiable) <a>presentation</a> is appropriate.
use type information to determine whether or not a provided <a>credential</a>,
<a>verifiable credential</a>, <a>presentation</a>, or <a>verifiable
presentation</a> is appropriate.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok accepted

This specification defines a <code>type</code> <a>property</a> for the
expression of type information.
</p>

<p>
<a>Verifiable credentials</a> and <a>verifiable presentations</a> MUST have a
<code>type</code> <a>property</a>. That is, any <a>credential</a> or
<a>presentation</a> that does not have <code>type</code> <a>property</a>
<a>presentation</a> that does not have a <code>type</code> <a>property</a>
<em>is not <a>verifiable</a></em>, so is neither a <a>verifiable credential</a>
nor a <a>verifiable presentation</a>.
</p>
Expand Down Expand Up @@ -1304,8 +1302,7 @@ <h3>Types</h3>
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

Expand Down Expand Up @@ -1490,7 +1487,7 @@ <h3>Credential Subject</h3>
</p>

<p>
A <a>verifiable credential</a> MUST have a <code>credentialSubject</code>
A <a>credential</a> MUST have a <code>credentialSubject</code>
<a>property</a>.
</p>

Expand All @@ -1499,7 +1496,7 @@ <h3>Credential Subject</h3>
<dd>
The value of the <code>credentialSubject</code> <a>property</a> is defined as
a set of objects that contain one or more properties that are each related to a
<a>subject</a> of the <a>verifiable credential</a>. Each object MAY contain an
<a>subject</a> of the (verifiable) <a>credential</a>. Each object MAY contain an
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<a>subject</a> of the (verifiable) <a>credential</a>. Each object MAY contain an
<a>subject</a> of the <a>credential</a> or <a>verifiable credential</a>. Each
object MAY contain an

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok accepted. But please note that the current recommendation is inconsistent throughout the entire text in that sometimes it refers to credential and sometimes to verifiable credential, almost randomly it would seem.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess we have some careful review to make, to ensure that all of these correctly refer to one or the other or both, possibly with additional text to explain why any given instance is one or the other or both.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. But its not a simple quick task. Because the original text was crafted over several years by different authors, with multiple edits of different sections as well, then many inconsistencies have crept in. I used the shorthand (verifiable)credential to imply that both credential and verifiable credential are equally applicable in this sentence.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I understand the shorthand, but many readers may not, and shorthand should generally be avoided in technical docs such as this, unless the intended meaning of that shorthand is clearly defined and every instance of the shorthand links back to that definition.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps introducing this shorthand into the definitions section might be advantageous. It would make subsequent editing simpler, and it would resolve the "and" or "or" grammatical issue below :-)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The immediate concern I have with that is making sure the definitions tools can handle the parenthetical <a>(verifiable) credential</a> differently than <a>verifiable credential</a>. I don't know whether they would recognize that difference today.

The definitely available way to handle this is the way I've already been aiming toward -- i.e., <a>verifiable credential</a> and/or <a>credential</a> or <a>credential</a> and/or <a>verifiable credential</a>.

<code>id</code>, as described in Section <a href="#identifiers"></a>.
</dd>
</dl>
Expand All @@ -1518,14 +1515,13 @@ <h3>Credential Subject</h3>
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

<p>
It is possible to express information related to multiple <a>subjects</a> in a
<a>verifiable credential</a>. The example below specifies two <a>subjects</a>
It is possible to express information related to multiple <a>subjects</a> in a (verifiable)
<a>credential</a>. The example below specifies two <a>subjects</a>
Comment on lines +1504 to +1505
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It is possible to express information related to multiple <a>subjects</a> in a (verifiable)
<a>credential</a>. The example below specifies two <a>subjects</a>
It is possible to express information related to multiple <a>subjects</a> in a
<a>credential</a> or <a>verifiable credential</a>. The example below specifies
two <a>subjects</a>

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok accepted

who are spouses. Note the use of array notation to associate multiple
<a>subjects</a> with the <code>credentialSubject</code> property.
</p>
Expand All @@ -1546,8 +1542,7 @@ <h3>Credential Subject</h3>
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Morgan Doe",
"spouse": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}]</span>,
"proof": { <span class="comment">...</span> }
}]</span> }
}
</pre>

Expand All @@ -1562,7 +1557,7 @@ <h3>Issuer</h3>
</p>

<p>
A <a>verifiable credential</a> MUST have an <code>issuer</code> <a>property</a>.
A <a>credential</a> MUST have an <code>issuer</code> <a>property</a>.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A <a>credential</a> MUST have an <code>issuer</code> <a>property</a>.
A <a>credential</a> or <a>verifiable credential</a> MUST have an
<code>issuer</code> <a>property</a>.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rejected. A VC that is produced using JWT proofs does not have an issuer property as it has been replaced by the iss claim. This is the reason for specifically excluding verifiable credential in this text.

Copy link
Member

@TallTed TallTed Sep 10, 2021 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. I think that this JWT-specific lack should be noted explicitly. Something like --

Suggested change
A <a>credential</a> MUST have an <code>issuer</code> <a>property</a>.
Each <a>credential</a> or <a>verifiable credential</a> MUST have an
<code>issuer</code> <a>property</a> or equivalent, such as the
`iss` claim in a JWT-based <a>verifiable credential</a>.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you want to add verifiable credential then it should be "and" and not "or"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it should be <a>credential</a> or <a>verifiable credential</a>, because any given instance will only be one or the other, because we've somehow tacitly agreed that <a>credential</a> means <a>unverifiable credential</a> (rather than <a>credentials</a> being the generic that includes all <a>verifiable credentials</a> and <a>unverifiable credentials</a>).

Even if that were not the case, A <a>credential</a> and <a>verifiable credential</a> MUST ... makes no sense.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we will just have to agree to differ on this. Perhaps US and English grammar are different. But to me, "A or B must do something" means that only one of them must do it, whilst "Both A and B must do something" means that both must do it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've edited my suggestion, changing the leading A to Each which I think makes the sentence mean the same in both UK and US English, even with the or, which I continue to think is appropriate here, because each document in question is one or the other, not one and the other.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes this makes sense because each means we are talking about a singular object.

</p>

<dl>
Expand Down Expand Up @@ -1593,8 +1588,7 @@ <h3>Issuer</h3>
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

Expand Down Expand Up @@ -1622,8 +1616,7 @@ <h3>Issuer</h3>
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

Expand Down Expand Up @@ -1672,8 +1665,7 @@ <h3>Issuance Date</h3>
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

Expand Down Expand Up @@ -1814,8 +1806,7 @@ <h3>Expiration</h3>
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": { <span class="comment">...</span> }
}
}
</pre>

Expand Down Expand Up @@ -1886,8 +1877,7 @@ <h3>Status</h3>
<span class="highlight">"credentialStatus": {
"id": "https://example.edu/status/24",
"type": "CredentialStatusList2017"
}</span>,
"proof": { <span class="comment">...</span> }
}</span>
}
</pre>

Expand Down Expand Up @@ -1915,7 +1905,7 @@ <h3>Presentations</h3>

<p>
A <a>verifiable presentation</a> is typically composed of the following
properties:
properties along with a proof mechanism:
</p>

<dl>
Expand Down Expand Up @@ -1946,9 +1936,9 @@ <h3>Presentations</h3>
</dd>
<dt><var>proof</var></dt>
<dd>
If present, the value of the <code>proof</code> <a>property</a> ensures that
the <a>presentation</a> is <a>verifiable</a>. For details related to the use of
this property, see Section <a href="#proofs-signatures"></a>.
If present, the value of the embedded <code>proof</code> <a>property</a> ensures that
the <a>presentation</a> is <a>verifiable</a>. For details related to the use of proof
mechanisms, see Section <a href="#proofs-signatures"></a>.
</dd>
</dl>

Expand Down Expand Up @@ -2288,7 +2278,7 @@ <h3>Extensibility</h3>
Let us assume we start with the <a>verifiable credential</a> shown below.
</p>

<pre class="example nohighlight" title="A simple credential">
<pre class="example nohighlight" title="A simple credential with an embedded proof">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
Expand Down Expand Up @@ -2342,7 +2332,7 @@ <h3>Extensibility</h3>
</p>

<pre class="example nohighlight"
title="A verifiable credential with a custom extension">
title="A verifiable credential with an embedded proof and a custom extension">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
Expand Down Expand Up @@ -2527,8 +2517,7 @@ <h3>Data Schemas</h3>
<span class="highlight">"credentialSchema": {
"id": "https://example.org/examples/degree.json",
"type": "JsonSchemaValidator2018"
}</span>,
"proof": { <span class="comment">...</span> }
}</span>
}
</pre>

Expand Down Expand Up @@ -2657,8 +2646,7 @@ <h3>Refreshing</h3>
<span class="highlight">"refreshService": {
"id": "https://example.edu/refresh/3732"
"type": "ManualRefreshService2018",
}</span>,
"proof": { <span class="comment">...</span> }
}</span>
}
</pre>

Expand Down Expand Up @@ -2743,8 +2731,7 @@ <h3>Terms of Use</h3>
"target": "http://example.edu/credentials/3732",
"action": ["Archival"]
}]
}</span>,
"proof": { <span class="comment">...</span> }
}</span>
}
</pre>

Expand Down Expand Up @@ -2790,8 +2777,7 @@ <h3>Terms of Use</h3>
"target": "http://example.edu/credentials/3732",
"action": ["3rdPartyCorrelation"]
}]
}</span>,
"proof": [ ... ]
}</span>
}
</pre>

Expand Down Expand Up @@ -2893,8 +2879,7 @@ <h3>Evidence</h3>
"evidenceDocument": "Fluid Dynamics Focus",
"subjectPresence": "Digital",
"documentPresence": "Digital"
}]</span>,
"proof": { <span class="comment">...</span> }
}]</span>
}
</pre>

Expand Down Expand Up @@ -3191,13 +3176,12 @@ <h3>Disputes</h3>
},
}</span>,
"issuer": "https://example.com/people#me",
"issuanceDate": "2017-12-05T14:27:42Z",
"proof": { <span class="comment">...</span> }
"issuanceDate": "2017-12-05T14:27:42Z"
}
</pre>

<p>
In the above <a>verifiable credential</a> the <a>issuer</a> is claiming that
In the above <a>credential</a> the <a>issuer</a> is claiming that
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In the above <a>credential</a> the <a>issuer</a> is claiming that
In the above <a>credential</a>, the <a>issuer</a> is claiming that

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok accepted

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that there are buttons on each suggested change, to "Commit suggestion" or "Add suggestion to batch", the latter of which leads to a subsequent "Commit batch", which avoid the need for "Ok accepted" comments and should make applying such suggestions faster and easier.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because I am a git novice, I found whilst updating my previous PR (808) that committing changes on the web site messed up my local GitHub copy and I could no longer push a revised version from my PC to the web, as they had become out of sync. So I prefer to make all the changes on my local GitHub copy then push the revised version up to web.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know there's a way around that issue. I can't tell you how to access it because I don't use local git at all; all my interactions are through GitHub's web interface. :-/

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you like how everything reads on your local branch the simple answer is to force push to the remote branch. This can be done with something like the following:

git push --force origin Removing-Proof

This is effectively overwriting any changes that exists on github to match the git log on your local computer. This is a bit of a double edged sword in that it could overwrite things you thought were supposed to be there that only existed on github but not locally. If you get stuck you can ping me and I can help you figure out how to untangle it as well.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we could spend a few minutes at the next VCWG meeting to discuss how best to author PRs for novices I would appreciate it (web vs desktop vc command line etc.) Ease of use being the primary factor :-)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[@David-Chadwick] If we could spend a few minutes at the next VCWG meeting to discuss how best to author PRs for novices I would appreciate it (web vs desktop vc command line etc.) Ease of use being the primary factor :-)

Best to reply to the meeting's AGENDA email, or email the chairs & editors directly, with this request.

(My personal answer is to use the GitHub interface as much as possible, as that seems to have the fewest foot-guns, and really is set up pretty well for non-coders and coders alike. I have only rarely had to appeal to someone else to use the command-line tools to achieve something I couldn't do easily though the website, and those times were mostly about global search-and-replace of a few typos that had permeated a repo.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we're unable to get to this, I'm happy to find a time that we could cover some of the basics in a tutorial that we post in the CCG as a recording since I think it's useful for some of the initiatives they're doing to be more inclusive as well.

the address in the disputed <a>verifiable credential</a> is wrong.
</p>

Expand Down