Skip to content
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

Jump to bottom

Finalize the context URL for the spec to address #206. #258

Merged
merged 6 commits into from
Nov 1, 2018
Merged

Finalize the context URL for the spec to address #206. #258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a2972fe
Fix all VC JSON-LD Context URLs. See #206.
msporny Oct 27, 2018
b4d88ff
Add note about static VC JSON-LD Context and vocab. See #206.
msporny Oct 27, 2018
a635f00
Add section on Contexts. See #206.
msporny Nov 1, 2018
27269e0
Refer to Extensibility section from Contexts section.
msporny Oct 27, 2018
2399114
Add note about example context. See #245.
msporny Oct 27, 2018
7d66396
Fix namespace documents as requested by @gkellogg.
msporny Nov 1, 2018
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
136 changes: 115 additions & 21 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,6 @@
company: "Spec-Ops", companyURL: "https://spec-ops.io/",
w3cid: "44770" }
],

// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.
Expand All @@ -66,7 +65,6 @@
{ name: "Dave Longley", url: "http://digitalbazaar.com/",
company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/"}
],

// name of the WG
wg: "Verifiable Claims Working Group",

Expand Down Expand Up @@ -653,6 +651,70 @@ <h1>Basic Concepts</h1>
toward the end of the document.
</p>

<section>
<h2>Contexts</h2>

<p>
When two software systems need to exchange data, they must use terminology
that both systems understand. A useful analogy is to think about how two
people communicate; both people must use the same language and the words
that each of them use must mean the same thing to the other party. This
specification uses the <code>@context</code> property to express the context
of the conversation.
</p>

<dl>
<dt><dfn>@context</dfn></dt>
<dd>
The value of this property MUST be one or more URIs where first URI is the
Copy link
Member

@brentzundel brentzundel Oct 31, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

The meaning of a verifiable credential could change if its context changes. I'm concerned that requiring only a URI (which by its nature is a mutable reference), we are not requiring any sort of guarantee that the context pointed to by the URI won't change over time.

Copy link
Contributor

Choose a reason for hiding this comment

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

This is also my concern, especially since it is proposed to move Issuer Terms of Use to the @context from the VC itself. The advantage of this move is that the holder of a ZPK credentials cannot hide the terms of use, which he could if it were an assertion in the VC. The disadvantage is that the verifier has to rely on the contents of URLs being immutable. Can we propose some crypto to guarantee that if the contents change, the verifier can detect this.

Copy link
Member Author

@msporny msporny Nov 1, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

We can't solve this issue in this PR. As @gkellogg mentioned, it's a separate broader Web/JSON-LD ecosystem issue. There are options, but we are unlikely to settle on a standard before the VCWG is done. I know that @dmitrizagidulin is going to document all the options over in the JSON-LD WG's issue repository.

value <code>https://w3.org/2018/credentials/v1</code>.
If more than one URI is provided, the URIs MUST be interpreted as an
ordered set. It is RECOMMENDED that dereferencing the URI results in a
document containing machine-readable information about the context.
</dd>
</dl>

<pre class="example nohighlight" title="Usage of the @context property">
{
<span class="highlight">"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
]</span>,
"id": "http://dmv.example.gov/credentials/3732",
"type": ["VerifiableCredential", "ProofOfAgeCredential"],
"claim": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"ageOver": 21
},
"proof": { ... }
}
</pre>

<p>
The example above uses the base context
(<code>https://w3.org/2018/credentials/v1</code>) to establish that the
conversation is about a Verififiable Credential. It then adds an additional
context (<code>https://example.com/examples/v1</code>) to establish that the
conversation will also be about examples.
</p>

<p class="note">
This document uses the Example Context
(<code>https://example.com/examples/v1</code>) for the purposes of
demonstrating examples. The Example Context MUST NOT be used for any other
purpose such as in pilot or production systems.
</p>

<p>
The data available at <code>https://w3.org/2018/credentials/v1</code>
is a static document that is never updated and MAY be downloaded and
cached. The associated human-readable vocabulary document for the
Verifiable Credentials Data Model can be found at the following URL:
<a href="https://w3.org/2018/credentials">https://w3.org/2018/credentials</a>.
This concept is expanded upon in Section <a href="#extensibility"></a>.
</p>
</section>

<section>
<h2>Identifiers</h2>

Expand Down Expand Up @@ -682,7 +744,7 @@ <h2>Identifiers</h2>

<pre class="example nohighlight" title="Usage of the 'id' property">
{
"@context": "https://w3id.org/credentials/v1",
"@context": "https://w3.org/2018/credentials/v1",
<span class="highlight">"id": "http://dmv.example.gov/credentials/3732"</span>,
"type": ["VerifiableCredential", "ProofOfAgeCredential"],
"claim": {
Expand Down Expand Up @@ -740,7 +802,10 @@ <h2>Types</h2>

<pre class="example nohighlight" title="Usage of the type property">
{
"@context": "https://w3id.org/credentials/v1",
"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "http://dmv.example.gov/credentials/3732",
<span class="highlight">"type": ["VerifiableCredential", "ProofOfAgeCredential"]</span>,
"claim": {
Expand Down Expand Up @@ -882,7 +947,10 @@ <h2>Issuer</h2>
</dl>
<pre class="example nohighlight" title="Usage of issuer properties">
{
"@context": "https://w3id.org/credentials/v1",
"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "http://dmv.example.gov/credentials/3732",
"type": ["VerifiableCredential", "ProofOfAgeCredential"],
<span class="highlight">"issuer": "https://dmv.example.gov/issuers/14"</span>,
Expand Down Expand Up @@ -915,7 +983,10 @@ <h2>Proofs (e.g., Signatures)</h2>
<pre class="example nohighlight"
title="Usage of proof property on a verifiable credential">
{
"@context": "https://w3id.org/credentials/v1",
"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "http://example.gov/credentials/3732",
"type": ["VerifiableCredential", "ProofOfAgeCredential"],
"issuer": "https://dmv.example.gov",
Expand Down Expand Up @@ -963,7 +1034,10 @@ <h2>Expiration</h2>

<pre class="example nohighlight" title="Usage of expirationDate property">
{
"@context": "https://w3id.org/credentials/v1",
"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "http://dmv.example.gov/credentials/3732",
"type": ["VerifiableCredential", "ProofOfAgeCredential"],
"issuer": "https://dmv.example.gov/issuers/14",
Expand Down Expand Up @@ -1018,7 +1092,10 @@ <h2>Status</h2>

<pre class="example nohighlight" title="Usage of status property">
{
"@context": "https://w3id.org/credentials/v1",
"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "http://dmv.example.gov/credentials/3732",
"type": ["VerifiableCredential", "ProofOfAgeCredential"],
"issuer": "https://dmv.example.gov/issuers/14",
Expand Down Expand Up @@ -1059,7 +1136,10 @@ <h2>Presentations</h2>

<pre class="example nohighlight" title="Basic structure of a presentation">
{
"@context": "https://w3id.org/credentials/v1",
"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
"type": ["VerifiablePresentation"],
<span class="highlight">"verifiableCredential": [{ ... }],
Expand Down Expand Up @@ -1165,7 +1245,10 @@ <h2>Extensibility</h2>

<pre class="example nohighlight" title="A simple credential">
{
"@context": "https://w3id.org/credentials/v1",
"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "http://example.com/credentials/4643",
"type": ["VerifiableCredential"],
"issuer": "https://example.com/issuers/14",
Expand Down Expand Up @@ -1215,7 +1298,7 @@ <h2>Extensibility</h2>
title="A verifiable credential with a custom extension">
{
"@context": <span class="highlight">[
</span>"https://w3id.org/credentials/v1",
</span>"https://w3.org/2018/credentials/v1",
<span class="highlight">"https://example.com/contexts/mycontext.jsonld"
]</span>,
"id": "http://example.com/credentials/4643",
Expand Down Expand Up @@ -1298,7 +1381,7 @@ <h3>Semantic Interoperability</h3>
"@context": {
"referenceNumber": "https://example.com/vocab#referenceNumber",
<span class="highlight">"claim": {
"@id": "https://w3id.org/credentials#claim",
"@id": "https://w3.org/2018/credentials#claim",
"@context": {
"favoriteFood": "https://example.com/vocab#favoriteFood"
}
Expand Down Expand Up @@ -1351,7 +1434,7 @@ <h2>Refreshing</h2>
<pre class="example nohighlight" title="Usage of termsOfUse property by an Issuer">
{
"@context": [
"https://w3id.org/credentials/v1",
"https://w3.org/2018/credentials/v1",
"https://example.org/motorlicense/v1"
],
"id": "http://dmv.example.gov/credentials/3732",
Expand Down Expand Up @@ -1424,7 +1507,7 @@ <h2>Terms of Use</h2>
<pre class="example nohighlight" title="Usage of termsOfUse property by an Issuer">
{
"@context": [
"https://w3id.org/credentials/v1",
"https://w3.org/2018/credentials/v1",
"https://example.org/motorlicense/v1"
],
"id": "http://dmv.example.gov/credentials/3732",
Expand Down Expand Up @@ -1458,7 +1541,7 @@ <h2>Terms of Use</h2>
<pre class="example nohighlight" title="Usage of termsOfUse property by a Holder">
{
"@context": [
"https://w3id.org/credentials/v1",
"https://w3.org/2018/credentials/v1",
"https://example.org/motorlicense/v1"
],
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
Expand Down Expand Up @@ -1548,7 +1631,7 @@ <h2>Evidence</h2>
<pre class="example nohighlight" title="Usage of evidence property">
{
"@context": [
"https://w3id.org/credentials/v1",
"https://w3.org/2018/credentials/v1",
"https://example.org/motorlicense/v1"
],
"id": "http://dmv.example.gov/credentials/3732",
Expand Down Expand Up @@ -1642,7 +1725,7 @@ <h2>Credential Uniquely Identifies Subject</h2>
<pre class="example nohighlight" title="An example of a credential
that uniquely identifies a subject">
{
"@context": ["https://w3id.org/credentials/v1", "https://schema.org/"]
"@context": ["https://w3.org/2018/credentials/v1", "https://schema.org/"]
"id": "http://dmv.example.gov/credentials/332",
"type": ["VerifiableCredential", "IdentityCredential"],
"issuer": "https://dmv.example.gov/issuers/4",
Expand Down Expand Up @@ -2004,7 +2087,10 @@ <h2>Disputes</h2>
<pre class="example nohighlight"
title="Expressing a disputed credential">
{
"@context": "https://w3id.org/credentials/v1",
"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "http://example.com/credentials/245",
"type": ["VerifiableCredential", "DisputeCredential"],
<span class="highlight">"claim": {
Expand Down Expand Up @@ -2180,7 +2266,7 @@ <h3>JSON Web Token</h3>
"aud": "www.example.com",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"verifiableCredential": {
"@context": "https://w3id.org/security/v1",
"@context": "https://w3.org/2018/security/v1",
"id": "http://example.gov/credentials/3732",
"type": ["VerifiableCredential", "ProofOfAgeCredential"],
"issuer": "https://dmv.example.gov",
Expand Down Expand Up @@ -2226,7 +2312,12 @@ <h2>JSON-LD</h2>
processing a <a>verifiable credential</a> or <a>verifiable presentation</a>,
and a <code>@context</code> property is not present at the top-level of the
JSON-LD document, then a <code>@context</code> property with a value of
<code>https://w3id.org/credentials/v1</code> MUST be assumed.
<code>https://w3.org/2018/credentials/v1</code> MUST be assumed. The
JSON-LD Context available at <code>https://w3.org/2018/credentials/v1</code>
is a static document that is never updated and may thus be downloaded and
cached client side. The associated vocabulary document for the
Verifiable Credentials Data Model can be found at the following URL:
<code>https://w3.org/2018/credentials</code>.
</p>

</section>
Expand Down Expand Up @@ -2706,7 +2797,10 @@ <h3>Bearer Credentials</h3>

<pre class="example nohighlight" title="Usage of issuer properties">
{
"@context": "https://w3id.org/credentials/v1",
"@context": [
"https://w3.org/2018/credentials/v1",
"https://example.com/examples/v1"
],
"id": "http://dmv.example.gov/credentials/temporary/28934792387492384",
"type": ["VerifiableCredential", "ProofOfAgeCredential"],
"issuer": "https://dmv.example.gov/issuers/14",
Expand Down
4 changes: 2 additions & 2 deletions vocab/context.jsonld
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
{
"@version": 1.1
},
"https://w3id.org/security/v1",
"https://w3.org/2018/security/v1",
{
"id": "@id",
"type": "@type",
"cred": "https://w3id.org/credentials#",
"cred": "https://w3.org/2018/credentials#",
"dc": "http://purl.org/dc/terms/",
"schema": "http://schema.org/",
"xsd": "http://www.w3.org/2001/XMLSchema#",
Expand Down
12 changes: 6 additions & 6 deletions vocab/credentials.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
specStatus: "base",
shortName: "vc-vocab",
publishDate: "2018-07-25",
thisVersion: "http://w3id.org/credentials",
thisVersion: "http://w3.org/2018/credentials",
Copy link
Contributor

Choose a reason for hiding this comment

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

Should this be https?

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, it should.

doJsonLd: true,
//edDraftURI: "https://w3c.github.io/vc-vocab/",
// lcEnd: "3000-01-01",
Expand Down Expand Up @@ -72,7 +72,7 @@
.bold {font-weight: bold;}
</style>
</head>
<body resource="https://w3id.org/credentials#" typeof="owl:Ontology" prefix="cred: https://w3id.org/credentials#">
<body resource="https://w3.org/2018/credentials#" typeof="owl:Ontology" prefix="cred: https://w3.org/2018/credentials#">
<section id="abstract">
<p>This document describes the
<span property="dc:title">Verifiable Claims Vocabulary</span>
Expand All @@ -89,7 +89,7 @@
<dt>Published:</dt><dd><time property="dc:date">2018-07-25</time></dd>
<dt>Imports:</dt>
<dd><a href="http://purl.org/dc/terms/" property="owl:imports">http://purl.org/dc/terms/</a></dd>
<dd><a href="https://w3id.org/security" property="owl:imports">https://w3id.org/security</a></dd>
<dd><a href="https://w3.org/2018/security" property="owl:imports">https://w3.org/2018/security</a></dd>
<dt>Version Info:</dt>
<dd><a href="" property="owl:versionInfo"></a></dd>
<dt>See Also:</dt>
Expand All @@ -107,11 +107,11 @@ <h2>Introduction</h2>
<p>This specification makes use of the following namespaces:</p>
<dl class="terms">
<dt><code>cred</code>:</dt>
<dd><code>https://w3id.org/credentials#</code></dd>
<dd><code>https://w3.org/2018/credentials#</code></dd>
<dt><code>dc</code>:</dt>
<dd><code>http://purl.org/dc/terms/</code></dd>
<dt><code>sec</code>:</dt>
<dd><code>https://w3id.org/security#</code></dd>
<dd><code>https://w3.org/2018/security#</code></dd>
<dt><code>xsd</code>:</dt>
<dd><code>http://www.w3.org/2001/XMLSchema#</code></dd>
</dl>
Expand Down Expand Up @@ -291,7 +291,7 @@ <h2>Term Definitions</h2>
</dd>
<dt>cred</dt>
<dd>
https://w3id.org/credentials#
https://w3.org/2018/credentials#
</dd>
<dt>credentialStatus</dt>
<dd>
Expand Down
8 changes: 4 additions & 4 deletions vocab/credentials.jsonld
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
{
"@version": 1.1
},
"https://w3id.org/security/v1",
"https://w3.org/2018/security/v1",
{
"id": "@id",
"type": "@type",
"cred": "https://w3id.org/credentials#",
"cred": "https://w3.org/2018/credentials#",
"dc": "http://purl.org/dc/terms/",
"schema": "http://schema.org/",
"xsd": "http://www.w3.org/2001/XMLSchema#",
Expand Down Expand Up @@ -140,7 +140,7 @@
"@type": "@id"
}
},
"@id": "https://w3id.org/credentials#",
"@id": "https://w3.org/2018/credentials#",
"@type": "owl:Ontology",
"dc:title": {
"en": "Verifiable Claims Vocabulary"
Expand All @@ -151,7 +151,7 @@
"dc:date": "2018-07-25",
"owl:imports": [
"http://purl.org/dc/terms/",
"https://w3id.org/security"
"https://w3.org/2018/security"
],
"rdfs:seeAlso": [
"https://www.w3.org/TR/verifiable-claims-data-model/"
Expand Down
Loading