Clarify primacy of data model vs. syntax #539

jricher · 2019-04-08T23:20:59Z

No description provided.

…zations are representations of that structure

brentzundel

I approve this PR, but see many uses of the lower-case "must"
While I do not have a problem with the non-normative use of the word "must," others may, so it may be a good idea to re-word those sentences.

awoie · 2019-04-09T17:08:26Z

I also support the PR.

jricher · 2019-04-10T15:04:25Z

I approve this PR, but see many uses of the lower-case "must"
While I do not have a problem with the non-normative use of the word "must," others may, so it may be a good idea to re-word those sentences.

That's a fair criticism and I'd be fine with rewording "must" as "needs to" as appropriate.

msporny · 2019-04-10T01:42:22Z

index.html

@@ -512,7 +512,11 @@ <h3>Use Cases and Requirements</h3>
          </li>
          <li>
 <a>Verifiable credentials</a> and <a>verifiable presentations</a> must be


Looks like we missed some "must"s in the last set of changes. We will need to remember to do so after pulling in this PR. I'm going to suggest changes based on a switch away from "musts".

Yes, the section is non-normative, yes the "must" is lowercase and isn't expressed according to the RFC MUST... but readers have been confused by lowercase "must" in the specification, so we've gone to great lengths to remove all normative-looking language from all sections of the spec.

msporny · 2019-04-10T01:46:15Z

index.html

@@ -512,7 +512,11 @@ <h3>Use Cases and Requirements</h3>
          </li>
          <li>
 <a>Verifiable credentials</a> and <a>verifiable presentations</a> must be
-serializable in one or more interoperable machine-readable data formats.
+serializable in one or more machine-readable data formats. 
+Any serialization of a verifiable credential or verifiable presentation must


Replace "must be" with "are" or equivalent non-normative sounding text.

Be sure to wrap defined concepts in the specification in <a></a>. So, for the above, <a>verifiable credential</a> and <a>verifiable presentations</a>.

msporny · 2019-04-10T01:47:37Z

index.html

@@ -512,7 +512,11 @@ <h3>Use Cases and Requirements</h3>
          </li>
          <li>
 <a>Verifiable credentials</a> and <a>verifiable presentations</a> must be


Replace "must" with "are" or equivalent non-normative sounding text.

msporny · 2019-04-10T01:49:00Z

index.html

@@ -2897,6 +2908,13 @@ <h3>JSON</h3>
 Other values MUST be represented as a String type.
          </li>
        </ul>
+
+        <p>


Change to <p class="note">

msporny · 2019-04-10T01:58:42Z

index.html

+serializable in one or more machine-readable data formats. 
+Any serialization of a verifiable credential or verifiable presentation must
+be transformable to the generic data model of this document in a deterministic
+process such that the resulting verifiable credential can be processed


Fix <a>verifiable credential</a>

msporny · 2019-04-10T02:01:14Z

index.html

@@ -2897,6 +2908,13 @@ <h3>JSON</h3>
 Other values MUST be represented as a String type.
          </li>
        </ul>
+
+        <p>
+NOTE: as the transformations listed herein have potentially incompatible interpretations,


Remove "NOTE:" as ReSpec will do it's magic to highlight this paragraph as a note.

msporny · 2019-04-10T02:04:05Z

index.html

@@ -2985,7 +3003,13 @@ <h2>Proof Formats</h2>
        <p>
 The data model described in this specification is designed to be proof format
 agnostic. This specification does not normatively require any particular digital
-proof or signature format. At the time of publication, at least two proof
+proof or signature format. While the data model is the canonical representation
+of the verifiable credentials document, the proofing mechanisms 


change "the verifiable credentials document" to "of a <a>verifiable credential</a> or a <a>verifiable presentation</a>" or something equivalent. We don't define what a "verifiable credentials document" is (nor do we want to).

msporny · 2019-04-10T02:05:07Z

index.html

-proof or signature format. At the time of publication, at least two proof
+proof or signature format. While the data model is the canonical representation
+of the verifiable credentials document, the proofing mechanisms 
+for the verifiable credentials are often tied to the syntax used 


Proofing mechanisms are for verifiable credentials and verifiable presentations... so you will either have to call both of them out here, or just strike "for the verifiable credentials".

msporny · 2019-04-10T02:06:11Z

index.html

+of the verifiable credentials document, the proofing mechanisms 
+for the verifiable credentials are often tied to the syntax used 
+in the transmission of the document between parties. As such, each proofing
+mechanism must specify whether the validation of the proof is calculated


Replace "must" with "is expected to" or some equivalent sounding non-normative language.

msporny · 2019-04-10T02:12:58Z

index.html

-added to the <code>vc</code> <a>property</a> of the JWT. The following
-paragraphs describe these encoding rules.
+added to the <code>vc</code> <a>property</a> of the JWT. As with all JWTs,
+the JWS based signature of a verifiable credential in the JWT syntax is


Fix <a>verifiable credential</a>

msporny · 2019-04-13T15:29:01Z

re: IPR failure

There is just an issue w/ mapping @jricher's Github account to his W3C account. He is clearly in the group representing SecureKey and as such there are no IPR concerns:

https://www.w3.org/2000/09/dbwg/details?group=98922&public=1&order=org

I'm ignoring the IPR warning as it's a non-issue. Ensuring /cc Chairs and W3C Staff (can we fix his affiliation?) -- @burnburn @stonematt @ashimura ... if not, I'm going to merge (when this PR is ready) anyway. Stop me if you disagree.

msporny · 2019-04-13T15:30:09Z

Holding on merging this PR until @jricher applies the editorial changes suggested in the conversation.

stonematt · 2019-04-14T01:33:04Z

VCWG Teleconference Resolution: https://www.w3.org/2019/04/09-vcwg-minutes.html#resolution04

RESOLUTION: The specification is clear wrt. using JWT and JWS with the VC Data Model. The VCWG acknowledges that a W3C Recommendation for RDF Dataset Canonicalization, Linked Data Proofs, and Linked Data Signatures does not exist, and that the Verifiable Credentials Data Model specification, as well as a number of Linked Data Working Groups at W3C, would benefit from such a set of standards. The VCWG strongly recommends the creation of a W3C Working Group to create such a set of W3C Recommendations. Additionally, non-normative text should be added to the specification that suggests that data needs to be translated to/from the data model and to pay particular attention to the proof extension point, once this PR is in, issue #487 should be closed.

index.html

Co-Authored-By: jricher <[email protected]>

jricher added 2 commits April 8, 2019 19:18

clarified that the data model is the canonical format and all seriali…

99789c3

…zations are representations of that structure

mark JSON as non-deterministic because of all the SHOULDs

3476271

brentzundel approved these changes Apr 9, 2019

View reviewed changes

This was referenced Apr 9, 2019

Address concerns raised by @jricher about syntaxes. #532

Closed

Clarify that multiple proof mechanisms are supported. #531

Merged

msporny requested changes Apr 10, 2019

View reviewed changes

ken-ebert approved these changes Apr 10, 2019

View reviewed changes

This was referenced Apr 14, 2019

4.7 Proofs #487

Closed

Section 4.1 Context #483

Closed

4.8 Expiration #496

Closed

fix editorial comments

831d2ac

TallTed reviewed Apr 15, 2019

View reviewed changes