Skip to content

Add hashes for context and vocab files. #116

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 7 commits into from
Jul 28, 2023
Merged

Add hashes for context and vocab files. #116

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
6b4eda6
Add section on Contexts with hashes.
msporny Jul 15, 2023
f96f347
Add section on vocabulary hashes.
msporny Jul 15, 2023
67ebcf5
Add instructions on generating digests for contexts and vocabs.
msporny Jul 15, 2023
84535fe
Refer to section on using cached contexts/vocabs in VCDM v2.0.
msporny Jul 15, 2023
d4bd6c7
Ensure references to VC-DATA-MODEL-2.0 are informative.
msporny Jul 15, 2023
a9bdac0
Fix grammar in section on context and vocabularies.
msporny Jul 21, 2023
b24a862
Update security vocab hash statements as requested by @iherman.
msporny Jul 28, 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
131 changes: 129 additions & 2 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -616,7 +616,7 @@ <h3>Proofs</h3>
and local calendar preferences of the individual [[?LTLI]]. Conversion of
timestamps to local time values are expected to consider the time zone
expectations of the individual. See
<a data-cite="VC-DATA-MODEL-2.0#representing-time"></a> for more details about
<a data-cite="?VC-DATA-MODEL-2.0#representing-time"></a> for more details about
Copy link
Member

@jyasskin jyasskin Jul 16, 2023

Choose a reason for hiding this comment

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

I haven't checked, but Respec should be smart enough to notice that this is inside a Note and so put it in the informative references section even if you don't add the ?. If it's not doing that, we should file a bug.

Copy link
Member Author

@msporny msporny Jul 16, 2023

Choose a reason for hiding this comment

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

Yes, I thought the same and was surprised when the informative reference jumped to the normative references in the appendix. At that point, I scanned through the document and manually set all references to informative (that were supposed to be informative references)... and the problem went away.

I didn't then go back and try to reproduce it by removing the "?" characters from data-cite. I guess I'll try that now as I have the spec up in another window...

Hmm, so, it worked... I tried two things:

  1. Set the above manually in data-cite and it moved it from normative to informative.
  2. Set the section as class="informative" and it moved it from normative to informative.

So, ReSpec seems to be operating as expected. I think the issue might be that the appendix is marked as normative, when it should be informative... so, I'll fix that when I go back through and clean up this PR.

Thanks for the nudge to track down the issue @jyasskin.

representing time values to individuals.
</p>

Expand Down Expand Up @@ -1475,6 +1475,133 @@ <h2>Relationship to Linked Data</h2>

</section>

<section>
<h2>Contexts and Vocabularies</h2>

<p class="issue" title="(AT RISK) Hash values might change during Candidate Recommendation">
This section lists cryptographic hash values that might change during the
Candidate Recommendation phase based on implementer feedback that requires
the referenced files to be modified.
</p>
<p>
Implementations that perform JSON-LD processing MUST treat the following
JSON-LD context URLs as already resolved, where the resolved document matches
the corresponding hash values below:
Copy link
Member

@jyasskin jyasskin Jul 16, 2023

Choose a reason for hiding this comment

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

IIUC, these hashes are here to defend against the possibility that the URL starts resolving to a different document during the lifetime of the standard. But if it does that, implementers should still be able to implement based on the contents of this document, and having only a hash will make that difficult. Can you embed the expected document into this spec, maybe as a set of appendices?

Copy link
Member Author

@msporny msporny Jul 16, 2023

Choose a reason for hiding this comment

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

Yes, your understanding is correct. It's even less of a problem w/ the HTML files as those are the human-readable versions of the machine-readable JSON-LD documents. For this specific section, it's the JSON-LD ones that matter, but only if you're doing some advanced RDF processing. So, @iherman is arguing that we should just not list the HTML files and only include the JSON-LD ones.

We could include these files in the specification, but these documents are BIG, and they're going to be archived at W3C at date-stamped URLs, and in the spec repositories on Github, and in the Arctic code vault. The likelihood of them going away completely is exceedingly small, so putting them in the spec feels a bit like overkill. We could do it, but people are already complaining about the length of the spec (which shouldn't matter, but people seem to associate a negative outlook with the technology when the spec gets big). @iherman has suggested that maybe we could hide everything in a details element (which we could).

All this to say, it's an active area of discussion (do we embed stuff in the spec, or refer to an external file (that's archived at W3C) and use a cryptographic hash and URL to refer to it).

Interested in your thoughts, @jyasskin, given the above.

Copy link
Member

@jyasskin jyasskin Jul 17, 2023

Choose a reason for hiding this comment

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

I don't know JSON-LD or RDF well, so this could be wrong, but I think that we can make a distinction between the contexts and the documents with RDFa data in them. To process JSON-LD at all—to get the IDs right—you have to process the context. The RDFa information, on the other hand, is only for if you want to situate the credential into a wider semantic web, right? That seems to imply that this specification should include the contexts but omit the RDFa. The contexts seem short enough to embed without making the spec overly long?

Copy link
Member

@iherman iherman Jul 18, 2023

Choose a reason for hiding this comment

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

I don't know JSON-LD or RDF well, so this could be wrong, but I think that we can make a distinction between the contexts and the documents with RDFa data in them. To process JSON-LD at all—to get the IDs right—you have to process the context. The RDFa information, on the other hand, is only for if you want to situate the credential into a wider semantic web, right? That seems to imply that this specification should include the contexts but omit the RDFa. The contexts seem short enough to embed without making the spec overly long?

I do not think we were ever considering including the RDFa. Instead, we were considering the JSON-LD representation of the vocabulary; in this respect, it is more akin to the context file. And, actually, they are of more or less equal length.

(Maybe you misspelled, and you meant RDF and not RDFa, @jyasskin?)

Copy link
Member Author

@msporny msporny Jul 18, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

The contexts seem short enough to embed without making the spec overly long?

Yes, we can also do this, but I question whether we need to... it presumes that w3.org goes away and, simultaneously, the entire development ecosystem goes away, or that people don't also have this information (the JSON-LD Contexts) copied statically in a variety of different software libraries (because we tell them to do just that in the spec).

The reality is that w3.org is maintained and isn't going away any time soon. If it /does/ go away, we have the Github repo. If Github goes away we have the Arctic Code Vault and the Library of Congress as backups... and if all of those things go away, we have all the developers that have backed up the context in their libraries. I guess the cost isn't much to place it in our spec, and we can include it in a collapsed details element... but that presumes such a catastrophic series of events that I question adding yet another redundancy for the many we already have in place.

All this to say, are we really that worried about the w3.org going away, and all the software repositories that have a backup for the context file going away, in such a way that makes it impossible to re-create the JSON-LD context? Feels like we're preparing for an extremely unlikely event.

</p>

<table class="simple">
<thead>
<tr>
<th>URL and Media Type</th>
<th>Content</th>
</tr>
</thead>
<tbody>
<tr>
<td style="white-space: nowrap;">
https://www.w3.org/ns/data-integrity/v1<br>
application/ld+json
</td>
<td>
sha256: v/POI0jhSjPansxhJAP1fwepCBZ2HK77fRZfCCyBDs0=<br><br>
sha3-512: Sg1PLFxKyEYQns9Zr0BoYXtFeDNfrHUDNMkyq4QEWv<wbr>wGIaX1v5xovnCG+dfceZEzr7BhBjm396noZF1HEeCM8g==
</td>
</tr>
<tr>
<td style="white-space: nowrap;">
https://www.w3.org/ns/multikey/v1<br>
application/ld+json
</td>
Copy link
Member

@iherman iherman Jul 16, 2023

Choose a reason for hiding this comment

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

First time I see this URL... AFAIK, multikey is not a W3C specification, so what would this file contain?

Copy link
Member Author

@msporny msporny Jul 16, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

First time I see this URL... AFAIK, multikey is not a W3C specification, so what would this file contain?

Multikey is defined here:

https://w3c.github.io/vc-data-integrity/#multikey

and is in the Security vocabulary here:

https://w3id.org/security#Multikey

It would contain the contents of this file (for anyone that would want to just include Multikey):

https://w3id.org/security/multikey/v1

Copy link
Member

@iherman iherman Jul 18, 2023

Choose a reason for hiding this comment

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

I missed it, sorry. Not sure if we need a separate context for this or whether we can simply merge this with the security context, but that is a separate discussion.

Copy link
Member Author

@msporny msporny Jul 21, 2023

Choose a reason for hiding this comment

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

We need a separate context for those that just want to pull the key format into their JSON-LD file. That doesn't mean we can't /also/ put the definitions in the data-integrity context, but we should break just the key context out for those that just want to import the key definitions.

Copy link
Member

@iherman iherman Jul 21, 2023

Choose a reason for hiding this comment

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

I am fine with the "also" :-).

<td>
sha256: SA+P0RxXl8ZH6xdPcmX71crzeGkCYMPfYjdVT46SF0o=<br><br>
sha3-512: BgQBN00t6vj1T4uYt5SwdPOhe2BVNY11UEvkVo/rbBv<wbr>fBd+Z09isxhGhf2HkVqMT
SANah1u7rLk6Uw6GeQGH1w==
</td>
</tr>
</tbody>
</table>

<p>
The security vocabulary terms that the JSON-LD contexts listed above resolve
to are in the <a href="https://w3id.org/security">https://w3id.org/security#</a>
namespace. That is, all security terms in this vocabulary are of the form
`https://w3id.org/security#TERM`, where `TERM` is the name of a term.
</p>

<p>
Implementations that perform RDF processing MUST treat the following
JSON-LD vocabulary URL as already resolved, where the resolved document matches
the corresponding hash values below.
</p>

<p>
When dereferencing the
<a href="https://w3id.org/security">https://w3id.org/security#</a> URL,
the data returned depends on HTTP content negotiation. These are as follows:
</p>

<table class="simple">
<thead>
<tr>
<th>Media Type</th>
<th>Description and Cryptographic Hashes</th>
</tr>
</thead>
<tbody>
<tr>
<td>
application/ld+json
</td>
<td>
The vocabulary in JSON-LD format [[?JSON-LD]].<br><br>

sha256: LEaoTyf796eTaSlYWjfPe3Yb+poCW9TjWYTbFDmC0tc=<br><br>

sha3-512: f4DhJ3xhT8nT+GZ8UUZi4QC+HT//wXE2fRTgUP4UNw<wbr>e4kvel2PFfd6jcofHBm9BjwEiGzVFGv4K+fFTKXRD2NA==
</td>
</tr>
<tr>
<td>
text/turtle
</td>
<td>
The vocabulary in Turtle format [[?TURTLE]].<br><br>
sha256: McnhLyt7+/A/0iLb3CUXD0itNw+7bwwjtzOww/zwoyI=<br><br>
sha3-512: jZtZsqgPPPo+jphAcN8/St4VdRLLAmN3nEQhzs0twE<wbr>MTmCY45euQ01Z4Zo7VlJMYNTf0KC6BMpogpSTAi/1J7Q==
</td>
<td>
</td>
</tr>
<tr>
<td>
text/html
</td>
<td>
The vocabulary in HTML+RDFa Format [[?HTML-RDFA]].<br><br>
sha256: eUHP1xiSC157iTPDydZmxg/hvmX3g/nnCn+FO25d4dc=<br><br>
sha3-512: z53j8ryjVeX16Z/dby//ujhw37degwi09+LAZCTUB8<wbr>WJZjjzW1AydhdEWmgHM0P5KUcPMmSe7edMlGr7G9rmcA==
</td>
<td>
</td>
</tr>
</tbody>
</table>

<p>
It is possible to confirm the 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>
For further information regarding processing of JSON-LD Contexts and
Vocabularies, see <a data-cite="?VC-DATA-MODEL-2.0#base-context">Verifiable
Credentials v2.0: Base Context</a> and <a data-cite="?VC-DATA-MODEL-2.0#vocabularies">
Verifiable Credentials v2.0: Vocabularies</a>.
</p>

</section>

</section>

</section>
Expand Down Expand Up @@ -2450,7 +2577,7 @@ <h2>Presenting Time Values</h2>
exposed to an individual if a proof is processed and is detected to be outside
an allowable time range. When exposing these dates and times to an individual,
implementers are urged to take into account
<a data-cite="VC-DATA-MODEL-2.0#representing-time">cultural norms when
<a data-cite="?VC-DATA-MODEL-2.0#representing-time">cultural norms when
representing dates and times</a>, as well as ensuring that the value is
<a href="#representing-time">displayed according to provided locale settings</a>
in display software. In addition to these considerations, presenting time
Expand Down