Add formal vocabulary definitions. #105

msporny · 2023-12-28T18:19:44Z

This PR is a first pass at attempting to address issue #17 by formally defining the vocabulary for BitstringStatusList.

dlongley · 2023-12-28T19:50:41Z

index.html

@@ -529,7 +529,7 @@ <h3>BitstringStatusListCredential</h3>
              </td>
            </tr>
            <tr>
-              <td>credentialSubject.ttl</td>
+              <td id="ttl">credentialSubject.ttl</td>


I flagged this elsewhere -- but don't think ttl works as specified and we don't need it here. I won't object to it being added here, but we'll then just need to remove it later unless it can be shown that it works properly.

Please raise an issue if you haven't done so already noting why TTL doesn't work.

Nevermind, I found it: #73 (comment)

iherman · 2023-12-29T15:44:02Z

I will check the vocabulary generation file soonish (probably on the week-end), but one immediate remark that should be handled somehow.

in contrast to the two other vocabularies, you chose to call the vocabulary file index.yml instead of vocabulary.yml
the yml2vocab script's default name for the vocabulary file is vocabulary.yml
the action script to include the vocabulary generation does not have an explicit name for the vocabulary file.
the generation of the ttl and jsonld file is such that the 'base name' of the vocabulary file is used, i.e., if index is used then it will be index.ttl and index.jsonld. The vocabulary template file, that refers to these formats, should reflect that.

All this means that the current setup will lead to a problem. I would suggest, to stay in line with the other vocabulary generation cases, to use vocabulary.yml file in instead of index.yml.

msporny · 2023-12-30T00:03:07Z

@iherman wrote:

All this means that the current setup will lead to a problem.

Yes, I've been meaning to chat with you about the defaults. One of the downsides to having all the files generated say "vocabulary.html" is that browsing to the directory doesn't load the vocabulary file. On Github, you're just given a 404 (without directory contents).

I can change it back if it's a pain (simple rename), but I'm wondering if we should consider using whatever name the individual that wrote the file has chosen instead of forcing a naming convention on the people that use the yml2vocab tool. You are, of course, the final arbiter in that decision since you wrote the tool. :)

iherman · 2023-12-30T07:55:53Z

I can change it back if it's a pain (simple rename), but I'm wondering if we should consider using whatever name the individual that wrote the file has chosen instead of forcing a naming convention on the people that use the yml2vocab tool. You are, of course, the final arbiter in that decision since you wrote the tool. :)

I would propose to leave this as a vocabulary.yml for now. Any change would involve (1) make a (very simple) change in the yml2vocab package (2) update the package on npm (3) make all the changes in the DI and VCDM vocabularies as well, because the package taken from npm would not work for them anymore. Nothing complicated, but with the avalanche of PR-s and issues for CR, it is just a distraction for now. This is the typical issue that we can handle when we get to more peaceful times with CRs all around.

iherman · 2023-12-30T08:03:35Z

@msporny while we are looking at those annoying minor issues... Is the namespace for this vocabulary (ie, https://www.w3.org/ns/credentials/status-list#) cast in concrete? The reason I am asking this is that we have now the following URL-s for the VC related vocabularies:

Credentials namespace: https://www.w3.org/2018/credentials#
DI namespace: https://w3id.org/security#
Bitstring status namespace: https://www.w3.org/ns/credentials/status-list#

Three different vocabularies with three totally different namespace URL-s: that is a real reason for confusion. We had some discussions before regarding (1) and (2), and there is a general agreement that, well, this is what we inherited, and it would lead to more problems changing those that it would solve. Ie, we are stuck with (1) and (2). But if so, wouldn't it be less confusing to the community if the bitstring status namespece was https://www.w3.org/2018/status-list#?

Using /ns/credentials/... would clearly be, in theory, nicer and cleaner. But isn't this the case where practical and user considerations should win over theoretical purity?

CC @dlongley

msporny · 2023-12-30T16:32:46Z

@iherman wrote:

I would propose to leave this as a vocabulary.yml for now.

Done in eb561c1.

Is the namespace for this vocabulary (ie, https://www.w3.org/ns/credentials/status-list#) cast in concrete?

No, it's just a proposal for now. :)

It's based on our decision to do this in VCDM v2.0:

  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],

We didn't change the vocabulary URLs because we had deployed systems for VCDM v1.0 and v1.1 in production. The StatusList2021 specification used https://w3id.org/vc/status-list# as its vocabulary URL base.

However, when the group decided to rename from StatusList2021 we broke all backwards compatibility with all existing systems, and we had no systems that we knew of in production. So, this vocabulary URL is a bit of a green field exercise -- we are not held back by previous production deployments.

wouldn't it be less confusing to the community if the bitstring status namespece was https://www.w3.org/2018/status-list#?

Maybe? I wouldn't be opposed to that base URL. The only argument against it is that the status list vocabulary didn't exist in 2018. :)

So, if https://www.w3.org/ns/credentials/status-list# is "nicer and cleaner", then we can do that for this particular vocabulary URL.

iherman · 2023-12-30T16:56:41Z

@iherman wrote:

I would propose to leave this as a vocabulary.yml for now.

Done in eb561c1.

Thanks. Let us come back to these when the CR storm settles :-)

Is the namespace for this vocabulary (ie, https://www.w3.org/ns/credentials/status-list#) cast in concrete?

No, it's just a proposal for now. :)

[…]

wouldn't it be less confusing to the community if the bitstring status namespece was https://www.w3.org/2018/status-list#?

Maybe? I wouldn't be opposed to that base URL. The only argument against it is that the status list vocabulary didn't exist in 2018. :)

So, if https://www.w3.org/ns/credentials/status-list# is "nicer and cleaner", then we can do that for this particular vocabulary URL.

This would be o.k. only if we decided to use /ns/credentials/core# or something like that for the credential vocabulary. That is a big no-no I believe it is even more clean and nice if these two vocabularies live side by side, so to say.

Actually, in #81, I considered these terms to be simply added to the VCDM credential vocabulary... Would that be out of the question? Does it have a real value of keeping these two apart? (Just asking, I do not have strong feelings on that aspect.)

msporny · 2023-12-30T20:32:26Z

@iherman wrote:

Actually, in #81, I considered these terms to be simply added to the VCDM credential vocabulary... Would that be out of the question? Does it have a real value of keeping these two apart? (Just asking, I do not have strong feelings on that aspect.)

I'd be fine w/ this path as well, though, we might not want to get into a situation where the VC vocabulary becomes a massive vocabulary for all extensions to VCs as well. That would be a path towards centralization -- not everything important in VCs needs to go through the VCWG (or the VC vocabulary).

It would be good for us to provide an example of how to extend the core data model, which is what this PR does. But, as I said above, I don't have strong feelings about this. I prefer that we provide a good example of an extension that we can point to in the future when others want to extend VCs in some way.

iherman · 2023-12-31T11:47:00Z

Actually, in #81, I considered these terms to be simply added to the VCDM credential vocabulary... Would that be out of the question? Does it have a real value of keeping these two apart? (Just asking, I do not have strong feelings on that aspect.)

I'd be fine w/ this path as well, though, we might not want to get into a situation where the VC vocabulary becomes a massive vocabulary for all extensions to VCs as well. That would be a path towards centralization -- not everything important in VCs needs to go through the VCWG (or the VC vocabulary).

Just for the sake of argument: moving these vocabulary items into the VCDM vocabulary does not mean that this is for all extensions. It only means that we use it for extensions defined by this Working Group.

We already do something like that elsewhere: the few extra terms needed for the VC JSON Schema spec have been added to the VCDM vocabulary, instead of defining a separate vocabulary for those. I acknowledge that the comparison is not entirely ok, because this proposed vocabulary is a factor larger than the Schema spec's.

I would think this should be raised on the next WG call (I won't be there), and let the WG decide. I accept any decision done by the WG.

vocab/README.md

iherman · 2023-12-31T12:10:57Z

vocab/template.html

+        shortName:   "ns/credentials/status-list",
+        thisVersion: "https://www.w3.org/ns/credentials/status-list/",


Just flagging this, so that we should not forget: these entries may have to change if the decision is to choose a different namespace URL.

Fixed in aa07c21.

vocab/template.html

iherman · 2023-12-31T12:13:51Z

vocab/template.html

+the definition found in an external specification. For instance, this is so when
+the term is needed to provide a consistent structure to the RDFS vocabulary,
+such as when the term defines a common supertype for class instances that are
+used as objects of specific properties, or when
+<a href="https://www.w3.org/TR/rdf12-concepts/#section-rdf-graph">RDF Graphs</a>
+are involved. For such cases, the extra definition is included in the current
+document (and the `rdfs:comment` property is used to include them in the RDFS
+representations).


Is this relevant? I.e., will this vocabulary ever deal with RDF Graphs? If not (which is probably the case) the whole section may be removed.

Correct, this vocabulary will probably never deal w/ RDF Graphs. We can remove the statement about RDF Graphs.

Mentions of RDF Graphs have been removed in the PR.

iherman · 2023-12-31T12:14:19Z

vocab/vocabulary.yml

@@ -0,0 +1,91 @@
+vocab:
+  - id: sl
+    value: https://www.w3.org/ns/credentials/status-list#


Same comment as above: this may have to change.

What about https://www.w3.org/ns/credentials/status# ?

See my answer below

Per WG meeting /ns/credentials/status# should be o.k.

Fixed in 636451d

iherman · 2023-12-31T12:15:39Z

vocab/vocabulary.yml

@@ -0,0 +1,91 @@
+vocab:
+  - id: sl


Would it be user friendly to chose a different prefix, say, slist? The problem is that it is difficult to differentiate between s1 and sl in many fonts, and this may be the source of stupid bugs...

(I made the mistake reviewing this file in github: I was wondering why on earth do we use the prefix s1, ie, "sh one"...)

Now for the important question... if not sl, then what? :P

Would sv be better? For "Status Vocabulary"? and then perhaps shorten the URL to: https://www.w3.org/ns/credentials/status# ?

I think sv is really better.

As for the URL, for the reasons I started this discussions with, my personal preference is to put it into /2018/, alongside the VCDM vocabulary.

(but shorten it to .../status is indeed a good idea imho.)

Just to be precise, because I made a mistake in the original comment, what about https://www.w3.org/2018/credentials/status#

(Noting that we will have to update the .htaccess file in /2018/credentials/)

Per WG meeting this issue is getting closed. But I think using "sv" instead of "sl" would still be better, and that means that URL would be /ns/credentials/status#.

Once this is merged, the .htaccess in /ns/credentials will need some magic...

Updated in 636451d

vocab/vocabulary.yml

vocab/template.html

iherman · 2024-01-03T07:35:21Z

Just flagging this: before merging (if there is an approval to do so) some name changes that happened in other PR-s should be added here. See 35860ac (but there may be more).

iherman · 2024-01-10T17:14:35Z

The issue was discussed in a meeting on 2024-01-10

no resolutions were taken

View the transcript

3.1. Rename "status" to "message" for `statusPurpose` feature. (pr vc-bitstring-status-list#100)

See github pull request vc-bitstring-status-list#100.

Manu Sporny: we had 3 status purpose values: revocation, suspension and status.
… we have changed status to message.
… we have pre-pended the word status to some of the property names.

See github pull request vc-bitstring-status-list#105.

iherman · 2024-01-10T17:14:35Z

The issue was discussed in a meeting on 2024-01-10

no resolutions were taken

View the transcript

3.8. Add formal vocabulary definitions. (pr vc-bitstring-status-list#105)

See github pull request vc-bitstring-status-list#105.

Manu Sporny: what is the vocabulary URL for the status list?
… several proposals for this.

Manu Sporny: This could be one of the vocabulary URL prefixes: https://www.w3.org/ns/credentials/status-list#.

Manu Sporny: This could be one of the vocabulary URL prefixes: https://www.w3.org/2018/credentials/status#.

Manu Sporny: we need to pick one and go with it.

Manu Sporny: This could be one of the vocabulary URL prefixes: https://www.w3.org/ns/credentials/status#

Manu Sporny: but does not align with 2018 existing terms.
… should there be a date in the terms or not?

Brent Zundel: do we want to have a poll on the name?

POLL: What should the status list vocabulary URL be Choice A) https://www.w3.org/ns/credentials/status# and Choice B) https://www.w3.org/2018/credentials/status# ?

Ivan Herman: B.

Manu Sporny: A.

Andres Uribe: A.

Brent Zundel: A.

Phillip Long: A.

David Chadwick: B.

Paul Dietrich: A.

Joe Andrieu: B.

Kevin-Dean-GS1: A.

David Chadwick: The reason I wanted the date is if you want to change a definition, if you have date in there, change in definition could have a new date. I see how you can append/remove, but changing them is not possible.

Ted Thibodeau Jr.: I don't fully grok the pros and cons. A ns vs B 2018 (which is when the original VCWG started).

Ivan Herman: There might be a version in the vocabulary, but URL does not change.

msporny · 2024-01-13T16:21:54Z

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

Co-authored-by: Ivan Herman <[email protected]>

msporny requested review from dlongley, longpd, iherman, dmitrizagidulin, andresuribe87, TallTed, David-Chadwick, brianorwhatever and decentralgabe December 28, 2023 18:19

msporny requested a review from mprorock as a code owner December 28, 2023 18:19

msporny mentioned this pull request Dec 28, 2023

Add vocabulary document #17

Closed

dlongley approved these changes Dec 28, 2023

View reviewed changes

iherman mentioned this pull request Dec 29, 2023

Vocabulary definitions #81

Closed

msporny mentioned this pull request Dec 29, 2023

Credential Type Mismatch between the Spec and the Schema #96

Closed

iherman requested changes Dec 31, 2023

View reviewed changes

TallTed approved these changes Jan 2, 2024

View reviewed changes

msporny commented Jan 2, 2024

View reviewed changes

vocab/template.html Outdated Show resolved Hide resolved

iherman mentioned this pull request Jan 10, 2024

Rename "status" to "message" for statusPurpose feature. #100

Merged

David-Chadwick approved these changes Jan 12, 2024

View reviewed changes

msporny and others added 9 commits January 13, 2024 11:22

Add vocabulary README.md.

544cb1a

Add template for vocabulary documentation.

29d83f8

Add vocabulary definition file.

3cb5818

Add Github pages build commands for vocabulary files.

b0bfc43

Add and fix anchors from vocabulary document to specification.

becd62c

Rename index.yml back to vocabulary.yml.

0bcf241

Fix vocabulary based on feedback from @iherman.

25b437c

Co-authored-by: Ivan Herman <[email protected]>

Update vocabulary prefix to one agreed to by VCWG.

e514656

Update vocabulary URL in template.

b54d651

msporny force-pushed the msporny-add-vocab branch from aa07c21 to b54d651 Compare January 13, 2024 16:23

msporny merged commit 2e20e10 into main Jan 13, 2024
1 of 2 checks passed

msporny deleted the msporny-add-vocab branch January 13, 2024 16:24

		shortName: "ns/credentials/status-list",
		thisVersion: "https://www.w3.org/ns/credentials/status-list/",

Add formal vocabulary definitions. #105

Add formal vocabulary definitions. #105

Conversation

msporny commented Dec 28, 2023 • edited by pr-preview bot Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iherman commented Dec 29, 2023 • edited Loading

msporny commented Dec 30, 2023

iherman commented Dec 30, 2023

iherman commented Dec 30, 2023

msporny commented Dec 30, 2023 • edited Loading

iherman commented Dec 30, 2023

msporny commented Dec 30, 2023

iherman commented Dec 31, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iherman commented Jan 3, 2024

iherman commented Jan 10, 2024

3.1. Rename "status" to "message" for statusPurpose feature. (pr vc-bitstring-status-list#100)

iherman commented Jan 10, 2024

3.8. Add formal vocabulary definitions. (pr vc-bitstring-status-list#105)

msporny commented Jan 13, 2024

msporny commented Dec 28, 2023 •

edited by pr-preview bot

Loading

iherman commented Dec 29, 2023 •

edited

Loading

msporny commented Dec 30, 2023 •

edited

Loading

3.1. Rename "status" to "message" for `statusPurpose` feature. (pr vc-bitstring-status-list#100)