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

Update language around the defined types and their usages #186

Merged
merged 7 commits into from
Jul 31, 2023
Merged

Update language around the defined types and their usages #186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b0a1bc3
update term definitions
Jul 25, 2023
c3e402e
update usage of credential schema and surrounding text
Jul 25, 2023
b010e6d
Revert term defs
Jul 25, 2023
7eaf768
changes from review comments
Jul 26, 2023
f7f8739
add type
Jul 26, 2023
5cba68f
use ul
Jul 26, 2023
21ff4f1
Update index.html
decentralgabe Jul 26, 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
100 changes: 67 additions & 33 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,18 +148,22 @@ <h2>Data Model</h2>
<p>
The following sections outline the data models for this document, of which there are two:
<code>JsonSchema2023</code> for usage of a [[JSON-Schema]] directly in a <code>credentialSchema</code>
property, and <code>VerifiableCredentialSchema2023</code> for usage of a [[JSON-Schema]] represented as a
property, and <code>JsonSchemaCredential2023</code> for usage of a [[JSON-Schema]] represented as a
<a>verifiable credential</a>.
</p>
<section>
<h3>JsonSchema2023</h3>
<p>
This <a href="https://www.w3.org/TR/json-ld/#dfn-term-definition">term definition</a>
is <code>https://www.w3.org/ns/credentials#JsonSchema2023</code>.
is <code>https://www.w3.org/ns/credentials/#JsonSchema2023</code>.
</p>
<p>
<b>JsonSchema2023</b> is for the validation of W3C Verifiable Credentials, based
on JSON Schema. The version of [[JSON-Schema]] can be any version noted in the section
<b>JsonSchema2023</b> is used for the validation of W3C Verifiable Credentials using
JSON Schema. When dereferencing the <code>id</code> property associated with the
<code>JsonSchema2023</code> <code>type</code> value the result is a valid JSON
Schema document according to its specification version.
<p>
The specification version of [[JSON-Schema]] can be any version noted in the section
on <a href="#json-schema-specifications">JSON Schema Specifications</a>.
</p>
<p>
Expand Down Expand Up @@ -209,6 +213,11 @@ <h3>JsonSchema2023</h3>
</pre>
</p>
<p>
<p>
Upon dereferencing the value of the <code>id</code> <code>https://example.com/schemas/email.json</code>,
a process also be referred to as <a>schema resolution</a>, the following JSON Schema
document is returned:
</p>
<pre class="example" title="Example Email JSON Schema">
{
"$id": "https://example.com/schemas/email.json",
Expand All @@ -235,15 +244,31 @@ <h3>JsonSchema2023</h3>
</p>
</section>
<section>
<h3>VerifiableCredentialSchema2023</h3>
<h3>JsonSchemaCredential2023</h3>
<p>
This <a href="https://www.w3.org/TR/json-ld/#dfn-term-definition">term definition</a>
is <code>https://www.w3.org/ns/credentials#VerifiableCredentialSchema2023</code>.
is <code>https://www.w3.org/ns/credentials#JsonSchemaCredential2023</code>.
</p>
<p>
<b>JsonSchemaCredential2023</b> is used for the validation of W3C Verifiable Credentials using
JSON Schema, where the JSON Schema is contained with a <a>verifiable credential</a>.
When dereferencing the <code>id</code> property associated with the
<code>JsonSchemaCredential2023</code> <code>type</code> value the result is a valid
<a>verifiable credential</a>. The resulting <a>verifiable credential</a>'s
<code>credentialSubject</code> property MUST contain a two properties:
<ul>
<li><code>type</code> – the value of which MUST be <code>JsonSchema2023</code></li>
<li><code>jsonSchema</code> – an object which contains a valid JSON Schema</li>
</ul>
</p>
<p>
The <a href="https://www.w3.org/TR/json-ld/#dfn-term-definition">term definition</a>
for using the <code>jsonSchema</code> property within the <code>credentialSubject</code>
of a verifiable credential is <code>https://www.w3.org/ns/credentials#JsonSchema</code>.
</p>
<p>
<b>VerifiableCredentialSchema2023</b> is used for the validation of W3C Verifiable Credentials, based
on representing JSON Schema in a <a>verifiable credential</a>. The version of [[JSON-Schema]]
can be any version noted in the section on <a href="#json-schema-specifications">JSON Schema Specifications</a>.
The specification version of [[JSON-Schema]] can be any version noted in the section
on <a href="#json-schema-specifications">JSON Schema Specifications</a>.
</p>
<p>
<table class="simple">
Expand All @@ -262,21 +287,21 @@ <h3>VerifiableCredentialSchema2023</h3>
</tr>
<tr>
<td>type</td>
<td>The <code>type</code> property MUST be VerifiableCredentialSchema2023</td>
<td>The <code>type</code> property MUST be JsonSchemaCredential2023</td>
</tr>
</tbody>
</table>
</p>
An example of utilizing the VC Data Model's <code>credentialSchema</code>
is provided below:
<pre class="example" title="Example VerifiableCredentialSchema2023">
<pre class="example" title="Example JsonSchemaCredential2023">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3733",
"type": ["VerifiableCredential", "EmailCredential"],
"type": ["VerifiableCredential", "ExampleEmailCredential"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
Expand All @@ -285,46 +310,55 @@ <h3>VerifiableCredentialSchema2023</h3>
},
"credentialSchema": {
"id": "https://example.com/credentials/3734",
"type": "VerifiableCredentialSchema2023"
"type": "JsonSchemaCredential2023"
}
}
</pre>
</p>
<p>
<p>
Upon dereferencing the value of the <code>id</code> <code>https://example.com/credentials/3734</code>,
a process also be referred to as <a>schema resolution</a>, the following verifiable credential,
Copy link
Collaborator

Choose a reason for hiding this comment

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

Why call out the schema resolution as a separate process? Isn't it a simple URL fetch?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

it is but it's a necessary step in using the spec, so it can be given a name which would be useful in enumerating the steps to process like

  1. get credential
  2. perform schema resolution
  3. evaluate schema against credential

representing a JSON Schema, is returned:
</p>
<pre class="example" title="Example Email Credential Schema">
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/3734",
"type": ["VerifiableCredential", "VerifiableCredentialSchema2023"],
"type": ["VerifiableCredential", "JsonSchemaCredential2023"],
"issuer": "https://example.com/issuers/14",
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"$id": "https://example.com/schemas/email-credential-schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"name": "EmailCredential",
"description": "EmailCredential using VerifiableCredentialSchema2023",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"emailAddress": {
"type": "string",
"format": "email"
}
},
"required": ["emailAddress"]
}
"id": "https://example.com/schemas/email-credential-schema.json",
"type": "JsonSchema2023",
"jsonSchema": {
"$id": "https://example.com/schemas/email-credential-schema.json",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"name": "EmailCredential",
"description": "EmailCredential using JsonSchemaCredential2023",
"type": "object",
"properties": {
"credentialSubject": {
"type": "object",
"properties": {
"emailAddress": {
"type": "string",
"format": "email"
}
},
"required": ["emailAddress"]
}
}
}
}
}
</pre>
</p>
<p class="issue" data-number="159">
Add language about CredentialSchema2023 credentials having a credentialSchema property
Add language about JsonSchemaCredential2023 credentials having a credentialSchema property
and the risks of nesting.
</p>
</section>
Expand Down Expand Up @@ -444,7 +478,7 @@ <h2>Processing</h2>
<h3>Integrity Validation</h3>
<p>
Credential Schemas MAY be packaged as <a>verifiable credentials</a> as defined
by usage of the <a href="#verifiablecredentialschema2023">VerifiableCredentialSchema2023</a> type.
by usage of the <a href="#jsonschemacredential2023">JsonSchemaCredential2023</a> type.
The credential containing a <a>credential schema</a> may include a proof, either
embedded according to [[VC-DATA-INTEGRITY]] or packaged as a [[VC-JWT]].
</p>
Expand Down Expand Up @@ -714,7 +748,7 @@ <h3>Multiple Schemas</h3>
},
"credentialSchema": {
"id": "multiple-credential-schema-test",
"type": "VerifiableCredentialSchema2023"
"type": "JsonSchemaCredential2023"
},
"proof": { ... }
}
Expand Down
4 changes: 4 additions & 0 deletions terms.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,5 +157,9 @@
or fetching, a URL are defined by the URL [=url/scheme=]. This specification
does not use the term URI or IRI because those terms have been deemed to be
confusing to Web developers.
</dd>
<dt><dfn data-lt="resolution|schema resolution">schema resolution</dfn></dt>
<dd>
The process that takes as its input a <a>URL</a> and returns a <a>credential schema</a>.
</dd>
</dl>