Skip to content

Make the vocabulary URLs and values normative #1159

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 4 commits into from
Jun 30, 2023
Merged

Make the vocabulary URLs and values normative #1159

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e4a9644
Make referenced vocabulary values normative.
msporny Jun 19, 2023
73d775d
Add issue marker noting Vocabulary URLs might change.
msporny Jun 30, 2023
b214247
Add issue marker noting impending change away from w3c.github.io.
msporny Jun 30, 2023
f3d32dd
Add issue marker for normative references for vocabulary files.
msporny Jun 30, 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
111 changes: 110 additions & 1 deletion index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5052,7 +5052,7 @@ <h3>Fitness for Purpose</h3>
</section>

<section class="appendix informative">
<h2>Contexts, Types, and Credential Schemas</h2>
<h2>Contexts, Vocabularies, Types, and Credential Schemas</h2>

<section class="normative">
<h3>Base Context</h3>
Expand Down Expand Up @@ -5116,6 +5116,115 @@ <h3>Base Context</h3>
</p>
</section>

<section class="normative">
<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.
</p>

<p>
Implementations MUST ensure that the following vocabulary URLs used in the base
context ultimately resolve to the following files, which are normative:
</p>

<table class="simple">
<thead>
<tr>
<th>URL</th>
<th>Media Type</th>
<th>Content</th>
</tr>
</thead>
<tbody>
<tr>
<td>
https://www.w3.org/2018/credentials#
</td>
<td>
text/html
</td>
<td>
https://www.w3.org/2018/credentials/index.html
Copy link
Contributor

Choose a reason for hiding this comment

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

Is it expected for the section 3. Term definitions to be empty in this doc? See image below.
image

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 is not... There seems to be a bug in the generation process.

I will look into it. That being said (1) this should not hold up this PR if it is voted to be merged and (2) at some point we agreed that the vocabulary definitions should happen when things get to an equilibrium point; it is impossible to keep the vocabulary in sync with so many things pending...

Thanks for notifying this.

Copy link
Member

Choose a reason for hiding this comment

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

@msporny I have contacted you in a separate mail on this possible bug. There is some mystery surrounding the github.io behavior that leads to the disappearance of a full section content...

Copy link
Member Author

Choose a reason for hiding this comment

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

There is probably some race condition when it comes to publishing the file, or the build process isn't getting executed before publishing for gh-pages, or some other strange thing like that. Usually when something like this happens, I look in the gh-pages build logs to see if I can see what's going wrong... or I look for something that could be a race condition.

Copy link
Member

Choose a reason for hiding this comment

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

Can I trust you on looking at that? I am pretty much lost when it comes to these github magic...

</td>
</tr>
<tr>
<td>
https://www.w3.org/2018/credentials#
</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#
Copy link
Contributor

Choose a reason for hiding this comment

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

Are we sure we want to make this one normative like this? or should we move this to a w3c origin before taking a normative dependency on it?

Copy link
Member Author

Choose a reason for hiding this comment

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

This PR makes it such that it doesn't matter what URL the group decides to make normative, because it explicitly states what vocabulary is the normative one (the W3C published one). This means that the W3C VCWG is effectively taking over how the URL resolves and stating that the only correct resolution is to the W3C Vocabulary (or, whatever vocabulary the W3C VCWG deems is the one it wants to point to, like schema.org).

The benefit here is that we don't have to go around renaming all of the URLs in the ecosystem. What some in the VCWG wanted was to have control over the vocabulary URL and content, this PR does that without introducing any backwards incompatible changes.

</td>
<td>
text/html
</td>
<td>
https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.html
Copy link
Contributor

Choose a reason for hiding this comment

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

This should be to a w3c origin, not github.

Copy link
Member Author

Choose a reason for hiding this comment

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

I agree, but the appropriate URL doesn't exist at this time.

I would expect that this URL will end up being https://www.w3.org/ns/security, but the VCWG hasn't set up that URL yet. I'll add an issue marker to that effect to the PR.

</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
Copy link
Contributor

Choose a reason for hiding this comment

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

this should be to a w3c origin

Copy link
Member Author

Choose a reason for hiding this comment

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

I agree, but the appropriate URL doesn't exist at this time.

I would expect that this URL will end up being https://www.w3.org/ns/security, but the VCWG hasn't set up that URL yet. I'll add an issue marker to that effect to the PR.

</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>

<p class="issue" title="How to normatively refer to vocabulary files">
Copy link
Contributor

Choose a reason for hiding this comment

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

Since there is issue to leave this comment on, I will leave it here.

hash for vocab seems a bit odd, given we are trusting w3c to maintain both the hash, and the vocab.... an attacker with control of the origin can change both.

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes, I agree... which is one of the reasons why I didn't want to use hash or the vocab content in the spec in the first place. Feels like overkill.

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>

</section>
<section class="informative">
<h3>Differences between Contexts, Types, and CredentialSchemas</h3>

Expand Down