Skip to content

Add links to static copies of vocabulary files and hashes #1279

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

Merged
merged 6 commits into from
Nov 1, 2023
Merged

Add links to static copies of vocabulary files and hashes #1279

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f23198a
Add cryptographic hashes for vocabulary files.
msporny Sep 13, 2023
6306961
Fix table layout for vocabulary hashes.
msporny Sep 13, 2023
bd46c72
Make hash values for vocab files use CODE blocks.
msporny Sep 26, 2023
dc65a84
Remove cryptographic hashes for schema.org vocabulary.
msporny Oct 18, 2023
8658ca9
Add note about schema.org terms being considered stable by the WG.
msporny Oct 18, 2023
1a88c3c
Fix grammar related to schema.org vocab hash.
msporny Oct 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 36 additions & 73 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5849,107 +5849,70 @@ <h3>Vocabularies</h3>

<p class="issue" title="(AT RISK) URL values might change during Candidate Recommendation">
This section lists URL values that might change during the Candidate
Recommendation phase based on migration of documents to the W3C Technical
Reports namespace and implementer feedback that requires the referenced URLs to
be modified.
Recommendation phase based on migration of documents to time-stamped locations,
migration of documents to the W3C Technical Reports namespace, and/or
implementer feedback that requires the referenced URLs to be modified.
</p>

<p>
Implementations MUST ensure that the following vocabulary URLs used in the base
context ultimately resolve to the following files, which are normative:
Implementations that depend on RDF vocabulary processing MUST ensure that the
Copy link
Member

@BigBlueHat BigBlueHat Sep 13, 2023

Choose a reason for hiding this comment

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

Can we rephrase "that depend on RDF vocabulary processing" to "that depend on vocabulary consistency"?

JSON processors and even storage/indexing providers should (must?) care about the definitions and constraints made of the contained terms as used within the VCDM.

It is not a unique requirement of RDF based tooling, though that audience has tooling to get "mechanical" benefit from these files which JSON processors miss out on. Developers working at the JSON layer will need to do additional work / write additional code to maintain consistent use, indexing, parsing, etc. of the terms described in the spec and these context files, so they are broadly applicable.

I realize JSON processors won't want the extra normative requirement to keep the actual context files on hand, but there still needs to be text that requires them to conform with terminology use defined within them.

Copy link
Member

@BigBlueHat BigBlueHat Sep 13, 2023

Choose a reason for hiding this comment

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

Here's the existing requirement from the JSON Processing section:

Ensure that all values associated with a @context property are in the expected order, the contents of the context files match known good cryptographic hashes for each file, and domain experts have deemed that the contents are appropriate for the intended use case.

Copy link
Member Author

@msporny msporny Sep 26, 2023

Choose a reason for hiding this comment

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

@BigBlueHat can you please provide a concrete change suggestion via "Add a suggestion" (CTRL-g)?

following vocabulary URLs used in the base context ultimately resolve to the
following files, which are normative. Other semantically equivalent
serializations of the vocabulary files MAY be used by implementations.
Cryptographic hashes are provided for all content to ensure that developers can
verify that the contents of each file are correct.
</p>

<table class="simple">
<thead>
<tr>
<th>URL</th>
<th>Media Type</th>
<th>Content</th>
<th>URL and Media Type</th>
<th>Content and Hashes</th>
</tr>
</thead>
<tbody>
<tr>
<td>
https://www.w3.org/2018/credentials#
https://www.w3.org/2018/credentials#<br>
`application/ld+json`
</td>
<td>
text/html
</td>
<td>
https://www.w3.org/2018/credentials/index.html
https://www.w3.org/2018/credentials/index.jsonld<br><br>
sha256: `z52TgKqh2nqTCuACI8lCvhRdjwxQjeVmuOMCDCEijq4=`<br><br>
sha3-512: <code>m8Ss+jgZiyL2Ws/ICJcWjHFd9PccJWsXPvMatBOhrH<wbr>
h0qCBrzfgO2zO1OQQbTL7zoPgLseIbcxJJpunD2bkoRA==</code>
</td>
</tr>
<tr>
<td>
https://www.w3.org/2018/credentials#
https://w3id.org/security#<br>
`application/ld+json`
</td>
<td>
application/ld+json
</td>
<td>
https://www.w3.org/2018/credentials/index.jsonld
</td>
</tr>
<tr>
<td>
https://schema.org/
</td>
<td>
text/html
</td>
<td>
https://schema.org/
</td>
</tr>
<tr>
<td>
https://schema.org/
</td>
<td>
application/ld+json
</td>
<td>
https://schema.org/version/latest/schemaorg-current-https.jsonld
</td>
</tr>
<tr>
<td>
https://w3id.org/security#
</td>
<td>
text/html
</td>
<td>
https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.html
</td>
</tr>
<tr>
<td>
https://w3id.org/security#
</td>
<td>
application/ld+json
</td>
<td>
https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.jsonld
https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.jsonld<br><br>
Copy link
Contributor

@OR13 OR13 Sep 13, 2023

Choose a reason for hiding this comment

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

Is it possible to make this a W3C origin based URL?

Copy link
Member Author

@msporny msporny Sep 13, 2023

Choose a reason for hiding this comment

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

It will eventually be a date-stamped W3C URL. Since that URL doesn't exist today, this is all I have to work with.

The text at the top of the section highlights that this URL will be changing during CR.

Copy link
Contributor

@OR13 OR13 Sep 13, 2023

Choose a reason for hiding this comment

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

What will the eventual URL be?

https://www.w3.org/2023/data-integrity/vocabulary.jsonld ?

Copy link
Member Author

@msporny msporny Sep 13, 2023

Choose a reason for hiding this comment

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

yeah, something like that. I don't know, @iherman will probably end up deciding based on W3C policy when it comes to these sorts of things.

Copy link
Contributor

@OR13 OR13 Sep 13, 2023

Choose a reason for hiding this comment

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

The only reason I raise it now, is we saw objections to github hosted documents in the DID WG, so if its possible to do a redirect soon, its one less thing that might come up later.

Copy link
Member Author

@msporny msporny Sep 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

The timing of this is largely up to @iherman and how quickly we get down the CR road. I don't think we'd go into Proposed Rec without this updated and there is text saying we're going to change it. IOW, I don't know how someone would defend a position on an objection that we're not going to change something that we have clearly said, in the spec, that we're going to change.

Copy link
Member

@iherman iherman Sep 14, 2023

Choose a reason for hiding this comment

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

Using github gives us the flexibility for easy changes. My preference would be to make a big cleanup on the URL-s when we are closing up to Proposed Rec, and not to complicate our life with this at this point.

sha256: `LEaoTyf796eTaSlYWjfPe3Yb+poCW9TjWYTbFDmC0tc=`<br><br>
sha3-512: <code>f4DhJ3xhT8nT+GZ8UUZi4QC+HT//wXE2fRTgUP4UNw<wbr>
e4kvel2PFfd6jcofHBm9BjwEiGzVFGv4K+fFTKXRD2NA==</code>
</td>
</tr>
</tbody>
</table>

<p class="issue" title="w3c.github.io links expected to change">
The URLs listed above that start with
`https://w3c.github.io/vc-data-integrity/vocab/security/` are expected to change
to `https://www.w3.org/ns/security/` or an equally normative and archived
location under W3C control.
<p>
It is possible to confirm the cryptographic digests listed above by running the
following command from a modern Unix command interface line:
`curl -sL -H "Accept: &lt;MEDIA_TYPE>" &lt;DOCUMENT_URL> | openssl dgst -&ltDIGEST_ALGORITHM> -binary | openssl base64 -nopad -a`
</p>

<p class="issue" title="How to normatively refer to vocabulary files">
The Working Group is currently discussing how it might want to normatively
refer to the vocabulary files that are under the control of the Working Group.
Current options are: inclusion of the files directly into the specification or
publishing the files in W3C TR space and referring to them by using a
cryptographic hash.
<p class="note"
title="schema.org changes regularly, but is considered stable">
Implementers and document authors might note that cryptographic digests for
`schema.org` are not provided. This is because the `schema.org` vocabulary
undergoes regular changes; any digest provided would be out of date within
weeks of publication. The Working Group discussed this concern and concluded
that the vocabulary terms from `schema.org`, that are used by this
specification, have been stable for years and are highly unlikely to change in
their semantic meaning.
</p>

<p>
Expand Down