Vocabulary improvement Phase 1 #1209

iherman · 2023-07-21T09:59:33Z

This is the first of several steps to clean up the Credentials Vocabulary. The main changes are:

Anchors have been added to all term definition to allow for an external reference. That is the only change on the spec text itself, no content has been changed. Note that this change takes care of issue (Editorial) systematically adding an anchor to each property #1080
For all properties, and also for some of the classes, a defined by tag has been added in the (YAML) vocabulary definition. This is translated into the rdfs:isDefinedBy statement in the formal vocabularies, and a textual translation thereof in the HTML text. Any other text in the property definitions had been removed. Bottom line: the official term definition is the in VCWG specifications, the vocabulary just "refers" to that. Some additional comments:
- There is one term in the vocabulary, namely serviceEndpoint that has no formal definition. The vocabulary has a comment on this, and this must be solved asap
- All terms are actually defined in the VCDM spec. The only exception is the JsonSchema2023 class is defined by the schema spec.
- The deprecated terms refer back to the v1.1 of the VCDM specification.
- Some classes have no direct reference in the spec, their roles are, sort of, "scaffolding" in the vocabulary. This is perfectly fine, they are intermediary classes and carry no other role.
- The definition of deprecated terms is kept to the bare minimum. In particular, no range or domain statement on other elements on the vocabulary are kept. After all, these are mostly placeholder items, to avoid 404-s on their relevant identifiers.
- This part of the PR takes care of issue Add references in vocabulary that link back to the VCDM document #1061

For reviewers

The PR does not include the visible files, i.e., the vocabulary in HTML/JSON-LD/Turtle. This is because the generation of these files happen automatically by a GitHub action. To make the reviews possible:

The files have been generated separately, and can be reached from the relevant index file in the tool repository for review.
The textual changes are to be made on the vocab/credentials/v2/vocabulary.yml and, for the text framework in the generated HTML, on the vocab/credentials/v2/template.html files. (These are the vocabulary generation input files.)

Preview | Diff

OR13 · 2023-07-21T12:13:51Z

vocab/credentials/v2/vocabulary.yml

-  - id: odrl
-    value: http://www.w3.org/ns/odrl/2/
+# prefix:
+#   - id: odrl


Prefer removing rather than commenting.

I did not see any resolution on that so far, so I preferred to put it into a comment to be sure there is a consensus around this. Personally, I am in favor of removing it...

OR13 · 2023-07-21T12:16:06Z

vocab/credentials/v2/vocabulary.yml


  - id: serviceEndpoint
-    label: service endpoint
+    label: Service endpoint


This seems like DID Core Terminology.

Maybe... but how did this land in this vocabulary?

I wonder whether this was added during the expansion of the issuer-holder-verifier trinity to include coordinator, service, etc., for each?

OR13 · 2023-07-21T12:18:09Z

vocab/credentials/v2/vocabulary.yml

    domain: cred:VerifiablePresentation
    range: cred:VerifiableCredentialGraph
-    comment: The value of the `verifiableCredential` property MUST identify a <a href="#VerifiableCredentialGraph">Verifiable credential graph</a> (informally, it indirectly identifies a <a href="#VerifiableCredential">Verifiable credential</a> contained in a separate graph).
+    comment: The value of the property must identify a <a href="#VerifiableCredentialGraph">Verifiable credential graph</a> (informally, it indirectly identifies a <a href="#VerifiableCredential">Verifiable credential</a> contained in a separate graph).


I don't understand what this is saying

Which part? The main sentence or the parenthetical one?

The value of the property is not a verifiable credential. It is a separate (rdf) graph that contains a (single) verifiable credential. This is what the JSON-LD "@container": "@graph" statement in the @context file leads to in terms of RDF.

TallTed

I further wonder about the several terms that are left without comment descriptions.

vocab/credentials/v2/vocabulary.yml

TallTed · 2023-07-21T15:38:17Z

vocab/credentials/v2/vocabulary.yml

-    comment: |
-      A Presentation is data derived from one or more Credentials, issued by one or more `issuers`, that is shared with a specific `verifier`. A Verifiable Presentation is a tamper-evident Presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. Certain types of verifiable presentations might contain data that is synthesized from, but do not contain, the original verifiable credentials (for example, zero-knowledge proofs).


I think this comment should not be deleted, though some edit does seem worthwhile.

Perhaps we can snag updates from the presentation related PRs for this section.

Do you propose to keep it for now and then handle it in a separate issue/PR? That is fine with me. I do not think the discussion should block the merge of this PR...

@TallTed I have reinstated the text in the latest commit.

What I would prefer is to wait until this PR is merged and then I would welcome a separate issue (or PR) proposing a replacement text.

(There are already several PRs that might add new entries to the vocabulary, and I would prefer to handle those on the improved version of the vocabulary.)

@iherman -- A fine plan. Might be worth memorializing whatever we plan to do (or review) later, after merging this PR, in new issue(s).

@TallTed could I rely on you raising a new issue when the time comes regarding this specific question? This is your question after all... I will take care of the other issues (essentially, missing term definitions in the spec).

vocab/credentials/v2/vocabulary.yml

msporny

This is an improvement over what we have today. Approving given that @TallTed and @OR13's comments are addressed.

iherman · 2023-07-24T10:06:47Z

I further wonder about the several terms that are left without comment descriptions.

The guideline is that comments should not appear if there is a "defined by" field: go to the official spec for the definition.

This is not an absolute rule, there may be cases when an extra local explanation is necessary, like in the case of the usage of RDF Graphs. Or when the class is really some sort of local, RDF term that is more or less necessary to provide a consistent structure to the vocabulary (e.g., common supertypes for classes that are used in practice as objects of properties). But those are (and should be) rare.

Does this answer your concern, @TallTed ?

TallTed · 2023-07-24T17:26:38Z

The guideline is that comments should not appear if there is a "defined by" field: go to the official spec for the definition.

OK. That was not clear from reading the PR. It might be worth adding such a statement to the description of the Credentials Vocabulary itself; inline and near the start, if possible.

pchampin

I noticed several issues with the generated Turtle and JSON-LD files.
One of them is due to an error in the Yaml file (for which I requested a change).
Others are due to issues in yml2vocab itself, for which I made two PRs w3c/yml2vocab#13 and w3c/yml2vocab#14

vocab/credentials/v2/vocabulary.yml

iherman · 2023-07-25T07:05:58Z

I noticed several issues with the generated Turtle and JSON-LD files. One of them is due to an error in the Yaml file (for which I requested a change). Others are due to issues in yml2vocab itself, for which I made two PRs w3c/yml2vocab#13 and w3c/yml2vocab#14

For the records: the ymlvocab errors have been taken care of, and a new version of the npm library published.

iherman · 2023-07-25T12:25:29Z

The guideline is that comments should not appear if there is a "defined by" field: go to the official spec for the definition.

OK. That was not clear from reading the PR. It might be worth adding such a statement to the description of the Credentials Vocabulary itself; inline and near the start, if possible.

@TallTed I have added a new, general section into the template (see also in the preview). I would welcome your review to finalize it (please, review, and possibly propose replacement texts in the template.html file of this repo).

Note that, if we agree on the final text, I will also do the same change on the security vocabulary.

Thx.

TallTed

Minor tweaks.

vocab/credentials/v2/template.html

iherman · 2023-07-26T07:10:03Z

I believe all outstanding questions/suggestions have been addressed. From my point of view, this is ready to be merged...

vocab/credentials/v2/template.html

vocab/credentials/v2/vocabulary.yml

TallTed

Modulo the small changes added today, I'm OK with this being merged. I think it represents an overall improvement.

Co-authored-by: Ted Thibodeau Jr <[email protected]>

Co-authored-by: Pierre-Antoine Champin <[email protected]>

Co-authored-by: Ted Thibodeau Jr <[email protected]>

msporny · 2023-07-27T22:00:43Z

Normative, multiple reviews, changes requested and made, no objections, merging.

iherman requested review from msporny, OR13, selfissued, decentralgabe and awoie as code owners July 21, 2023 09:59

iherman requested review from pchampin and TallTed July 21, 2023 09:59

iherman mentioned this pull request Jul 21, 2023

Vocabulary pruning and improvement phase 1 w3c/vc-data-integrity#127

Merged

OR13 approved these changes Jul 21, 2023

View reviewed changes

TallTed requested changes Jul 21, 2023

View reviewed changes

This was referenced Jul 23, 2023

(Editorial) systematically adding an anchor to each property #1080

Closed

Add references in vocabulary that link back to the VCDM document #1061

Closed

msporny approved these changes Jul 23, 2023

View reviewed changes

msporny requested review from dlongley, peacekeeper, dmitrizagidulin, philarcher, brentzundel, Sakurann, KDean-GS1 and seabass-labrax July 23, 2023 15:07

dlongley approved these changes Jul 23, 2023

View reviewed changes

pchampin requested changes Jul 24, 2023

View reviewed changes

vocab/credentials/v2/vocabulary.yml Outdated Show resolved Hide resolved

decentralgabe approved these changes Jul 24, 2023

View reviewed changes

TallTed requested changes Jul 25, 2023

View reviewed changes

vocab/credentials/v2/template.html Outdated Show resolved Hide resolved

vocab/credentials/v2/template.html Outdated Show resolved Hide resolved

decentralgabe mentioned this pull request Jul 26, 2023

Update term definition for vc json schemas as creds #1215

Merged

This was referenced Jul 26, 2023

Update language around the defined types and their usages w3c/vc-json-schema#186

Merged

Missing term in the vcdm spec #1216

Closed

TallTed reviewed Jul 26, 2023

View reviewed changes

vocab/credentials/v2/template.html Show resolved Hide resolved

TallTed reviewed Jul 26, 2023

View reviewed changes

vocab/credentials/v2/vocabulary.yml Show resolved Hide resolved

TallTed reviewed Jul 26, 2023

View reviewed changes

vocab/credentials/v2/vocabulary.yml Outdated Show resolved Hide resolved

TallTed reviewed Jul 26, 2023

View reviewed changes

iherman mentioned this pull request Jul 27, 2023

chore: update title and urls to contexts w3c/vc-bitstring-status-list#69

Merged

msporny force-pushed the vocab/improve-phase1 branch 6 times, most recently from a129740 to a60bb4a Compare July 27, 2023 21:46

msporny force-pushed the main branch from b1d3e02 to 7cac20d Compare July 27, 2023 21:52

msporny force-pushed the vocab/improve-phase1 branch from 2d2d8c3 to a60bb4a Compare July 27, 2023 21:54

iherman and others added 9 commits July 27, 2023 17:59

Refreshed vocabulary, using back links to the main doc.

031f07d

Update the domain of validFrom/validUntil.

9c7c0b0

Update entries in vocabulary to match spec.

e81155d

Fix editorial issues with v2 vocabulary.

1134b55

Co-authored-by: Ted Thibodeau Jr <[email protected]>

Fix missing prefix in TermsOfUse.

c885cfe

Co-authored-by: Pierre-Antoine Champin <[email protected]>

Add section on specification of terms.

4f48b5d

Fix grammar in specification of terms.

45cabb7

Co-authored-by: Ted Thibodeau Jr <[email protected]>

Fix more grammar issues in template and vocabulary.

bc5c957

Co-authored-by: Ted Thibodeau Jr <[email protected]>

Remove trailing space, fix grammar in vocabulary.

ee9a7ff

msporny force-pushed the vocab/improve-phase1 branch from a60bb4a to ee9a7ff Compare July 27, 2023 21:59

msporny merged commit 748a9f9 into main Jul 27, 2023

msporny deleted the vocab/improve-phase1 branch July 27, 2023 22:00

iherman mentioned this pull request Jul 28, 2023

Vocabulary definitions w3c/vc-bitstring-status-list#81

Closed

		comment: \|
		A Presentation is data derived from one or more Credentials, issued by one or more `issuers`, that is shared with a specific `verifier`. A Verifiable Presentation is a tamper-evident Presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. Certain types of verifiable presentations might contain data that is synthesized from, but do not contain, the original verifiable credentials (for example, zero-knowledge proofs).

Vocabulary improvement Phase 1 #1209

Vocabulary improvement Phase 1 #1209

Uh oh!

Conversation

iherman commented Jul 21, 2023 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

For reviewers

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TallTed left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

msporny left a comment

Choose a reason for hiding this comment

Uh oh!

iherman commented Jul 24, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TallTed commented Jul 24, 2023

Uh oh!

pchampin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

iherman commented Jul 25, 2023

Uh oh!

iherman commented Jul 25, 2023

Uh oh!

TallTed left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

iherman commented Jul 26, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TallTed left a comment

Choose a reason for hiding this comment

Uh oh!

msporny commented Jul 27, 2023

Uh oh!

Uh oh!

iherman commented Jul 21, 2023 •

edited by pr-preview bot

Loading

iherman commented Jul 24, 2023 •

edited

Loading