Skip to content

Address part of 210 #212

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 5 commits into from
Sep 12, 2023
Merged

Address part of 210 #212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8ed05d3
cleanup normative refs
Sep 5, 2023
709c460
one more
Sep 5, 2023
c3ac35e
tmp
Sep 6, 2023
e18f598
Merge branch 'main' into address-210
decentralgabe Sep 7, 2023
0eb6dc0
Apply suggestions from code review
decentralgabe Sep 7, 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
79 changes: 1 addition & 78 deletions common.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,38 +5,6 @@ var vcwg = {
// Add as the respecConfig localBiblio variable
// Extend or override global respec references
localBiblio: {
"RFC-6596": {
title: "The Canonical Link Relation",
date:" April 2012",
href: "https://www.rfc-editor.org/rfc/rfc6596",
authors: [
"M. Ohye",
"J. Kupke"
]
},
"RFC-3986": {
title: "Uniform Resource Identifier (URI): Generic Syntax",
date:" January 2005",
href: "https://www.rfc-editor.org/rfc/rfc3986",
authors: [
"T. Berners-Lee",
"R. Fielding",
"L. Masinter"
]
},
"VC-DATA-MODEL-2": {
title: "Verifiable Credentials Data Model v2.0",
href: "https://www.w3.org/TR/vc-data-model-2.0/",
authors: [
"Manu Sporny",
"Orie Steele",
"Michael B. Jones",
"Gabe Cohen",
"Oliver Terbu"
],
status: "Working Draft",
publisher: "W3C Verifiable Credentials Working Group"
},
"JSON-SCHEMA": {
href: "https://json-schema.org/specification.html",
title: "JSON Schema: A Media Type for Describing JSON Documents",
Expand All @@ -57,63 +25,18 @@ var vcwg = {
title: "JSON Schema Draft-07 Release Notes",
publisher: "OpenJS Foundation"
},
"DID-CORE": {
href: "https://w3c.github.io/did-core/",
title: "Decentralized Identifiers (DIDs) v1.0",
publisher: "W3C"
},
"JSON-LD": {
href: "https://w3c.github.io/json-ld-syntax/",
title: "JSON-LD 1.1: A JSON-based Serialization for Linked Data",
publisher: "W3C"
},
"VC-JOSE-COSE": {
href: "https://www.w3.org/TR/vc-jose-cose/",
title: "Securing Verifiable Credentials using JOSE and COSE",
authors: ["Orie Steele", "Michael Jones", "Michael Prorock"],
publisher: "W3C"
},
"VC-DATA-INTEGRITY": {
title: "Verifiable Credential Data Integrity 1.0",
href: "https://www.w3.org/TR/vc-data-integrity/",
authors: ["David Longley", "Manu Sporny"],
status: "Working Draft",
publisher: "W3C Verifiable Credentials Working Group"
},
"JOSE": {
href: "https://jose.readthedocs.io/en/latest/",
title: "Javascript Object Signing and Encryption (JOSE)",
publisher: "IETF"
},
"JSON-SCHEMA-IMPLMENTATIONS": {
href: "https://json-schema.org/implementations.html",
title: "JSON Schema Implementations",
publisher: "json-schema-org"
},
"SD-JWT": {
title: "Selective Disclosure for JWTs (SD-JWT)",
href: "https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-05",
authors: [ "Daniel Fett" , "Kristina Yasuda" , "Brian Campbell"],
authors: ["Daniel Fett", "Kristina Yasuda", "Brian Campbell"],
status: "Internet-Draft",
publisher: "IETF"
},
"OAS": {
title: "OpenAPI Specification Version 3.1.0",
href: "https://swagger.io/specification/",
authors: [
"Darrel Miller",
"Jeremy Whitlock",
"Marsh Gardiner ",
"Mike Ralphson",
"Ron Ratovsky",
"Uri Sarid",
],
publisher: "OpenAPI Initiative",
},
"YAML": {
href: "https://yaml.org/spec/1.2.2/",
title: "YAML Ain’t Markup Language (YAML™) version 1.2",
publisher:"YAML Language Development Team"
}
}
};
Expand Down
64 changes: 34 additions & 30 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
previousPublishDate: "2022-04-05",
localBiblio: vcwg.localBiblio,
doJsonLd: true,
xref: true,
github: "https://github.com/w3c/vc-json-schema/",
includePermalinks: false,
edDraftURI: "https://w3c.github.io/vc-json-schema/",
Expand Down Expand Up @@ -105,13 +106,13 @@
<section id='abstract'>
<h2>Abstract</h2>
<p>
Among other things, the [[VC-DATA-MODEL-2]] specifies the models used for Verifiable Credentials,
Among other things, the [[VC-DATA-MODEL-2.0]] specifies the models used for Verifiable Credentials,
Verifiable Presentations, and explains the relationships between three parties:
<i>issuers</i>, <i>holders</i>, and <i>verifiers</i>. Verifiability, extensibility, and semantic
interoperability are critical pieces of functionality referenced throughout
the [[VC-DATA-MODEL-2]]. This specification provides a mechanism to make use of a Credential Schema in
the [[VC-DATA-MODEL-2.0]]. This specification provides a mechanism to make use of a Credential Schema in
<a>Verifiable Credential</a>, leveraging the existing
<a data-cite="vc-data-model/#data-schemas">Data Schemas</a> concept.
<a data-cite="VC-DATA-MODEL-2.0/#data-schemas">Data Schemas</a> concept.
</p>
</section>
<section id='sotd'>
Expand Down Expand Up @@ -151,17 +152,18 @@ <h3>Terminology</h3>
<h2>Data Model</h2>
<p>
The following sections outline the data models for this document, of which there are two:
<code>JsonSchema</code> for usage of a [[JSON-Schema]] directly in a <code>credentialSchema</code>
property, and <code>JsonSchemaCredential</code> for usage of a [[JSON-Schema]] represented as a
<code>JsonSchema</code> for usage of a [[JSON-SCHEMA]] directly in a <code>credentialSchema</code>
property, and <code>JsonSchemaCredential</code> for usage of a [[JSON-SCHEMA]] represented as a
<a>verifiable credential</a>.
</p>
<p>
Implementers may find use in packaging a JSON Schema as a verifiable credential when they wish to
leverage features of the [[VC-DATA-MODEL-2]], answering questions such as:
leverage features of the [[VC-DATA-MODEL-2.0]], answering questions such as:
<ul>
<li>Who is the author of this schema? (provided by the <code>issuer</code> property)</li>
<li>Is it schema still valid? (provided by the <code>validFrom</code>, <code>validUntil</code>, and <code>credentialStatus</code> properties)</li>
<li>Has the schema been tampered with? (provided by [[VC-DATA-INTEGRITY]] or [[VC-JOSE-COSE]])</li>
<li>Has the schema been tampered with? (provided by <a data-cite="VC-DATA-MODEL-2.0/#securing-verifiable-credentials">
Securing Verifiable Credentials</a>)</li>
</ul>
</p>
<section class="normative">
Expand All @@ -176,7 +178,7 @@ <h3>JsonSchema</h3>
<code>JsonSchema</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
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 All @@ -191,7 +193,7 @@ <h3>JsonSchema</h3>
<tr>
<td>id</td>
<td>The constraints on the <code>id</code> property are listed in the Verifiable Credentials
Data Model specification [[VC-DATA-MODEL-2]]. The value MUST be a URL that identifies
Data Model specification [[VC-DATA-MODEL-2.0]]. The value MUST be a URL that identifies
the schema associated with the <a>verifiable credential</a>.</td>
</tr>
<tr>
Expand Down Expand Up @@ -314,7 +316,7 @@ <h3>JsonSchemaCredential</h3>
<tr>
<td>id</td>
<td>The constraints on the <code>id</code> property are listed in the Verifiable Credentials
Data Model specification [[VC-DATA-MODEL-2]]. The value MUST be a <a>URL</a> that identifies
Data Model specification [[VC-DATA-MODEL-2.0]]. The value MUST be a URL that identifies
the <a>verifiable credential</a> which contains a credential schema.</td>
</tr>
<tr>
Expand All @@ -324,7 +326,7 @@ <h3>JsonSchemaCredential</h3>
<tr>
<td>credentialSubject.id</td>
<td>The <code>credentialSubject</code>'s <code>id</code> property MUST follow the guidance
provided for <a data-cite="vc-data-model#identifiers">identifiers</a> in the [[VC-DATA-MODEL-2]]
provided for <a data-cite="VC-DATA-MODEL-2.0/#identifiers">identifiers</a> in the [[VC-DATA-MODEL-2.0]]
specification.</td>
</tr>
<tr>
Expand Down Expand Up @@ -470,7 +472,7 @@ <h4>jsonSchema</h4>
<h2>JSON Schema Specifications</h2>
<p>
The following section describes the allowed specifications for
using a [[JSON-Schema]] with a <a>credential schema</a>.
using a [[JSON-SCHEMA]] with a <a>credential schema</a>.
</p>
<p>
To promote conformance and enable interoperability, implementers MUST
Expand Down Expand Up @@ -533,8 +535,8 @@ <h3>Reserved Keywords</h3>
<h4>$id</h4>
<p>
Across JSON Schema specifications, the <code>$id</code> keyword identifies a schema resource
with its canonical [[RFC-6596]] URI. The <code>$id</code> MUST be present and its value
MUST represent a valid URI-reference [[RFC-3986]].
with its canonical [[RFC6596]] URI. The <code>$id</code> MUST be present and its value
MUST represent a valid URI-reference [[RFC3986]].
</p>
<p>
It is RECOMMENDED that the value of the <code>$id</code> property match the <code>id</code>
Expand Down Expand Up @@ -573,7 +575,7 @@ <h3>Representations of JSON Schema</h3>
syntax</a> with <code>.json</code> as the file extension.
</p>
<p>
Implementers MAY use OpenAPI Specification's [[OAS]] [[YAML]] representation
Implementers MAY use OpenAPI Specification's [[[OPENAPIS-3.1.0]]] [[YAML]] representation
of a [[JSON-SCHEMA]] with <code>.yaml</code> as the file extension.

<p class="note">
Expand Down Expand Up @@ -616,21 +618,22 @@ <h3>Integrity Validation</h3>
Credential Schemas MAY be packaged as <a>verifiable credentials</a> as defined
by usage of the <a href="#jsonschemacredential">JsonSchemaCredential</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-JOSE-COSE]].
embedded according to <a data-cite="VC-DATA-MODEL-2.0/#securing-verifiable-credentials">
Securing Verifiable Credentials</a>.
</p>
<p>
Secured credentials representing credential schemas SHOULD first be validated
according to the rules set out in the aforementioned securing specifications
before proceeding with additional processing.
</p>
<p class="issue" data-number="143">
Provide examples for Data Integrity and VC-JOSE-COSE Credential Schemas
Provide examples for secured credential schemas.
</p>
<p>
Credential Schemas of type <a href="#jsonschema">JsonSchema</a> MAY
be annotated with integrity information by adding the `digestSRI` property to the `credentialSchema` value
in the Verifiable Credential which contains the schema, using the method specified in
<a data-cite="sri/#integrity-metadata">Subresource Integrity</a>.
<a data-cite="VC-DATA-MODEL-2.0/#integrity-of-related-resources">Integrity of Related Resources</a>.
It is RECOMMENDED that validation of the integrity of the schema be done before evaluation.
</p>
<p>
Expand Down Expand Up @@ -853,7 +856,7 @@ <h3>Credential Property Validation</h3>
<section class="informative">
<h3>Additional Properties</h3>
<p>
In using [[JSON-Schema]] it is advised that implementers avoid
When using [[JSON-SCHEMA]], it is advised that implementers avoid
setting the <code>additionalProperties</code> to <i>false</i>. Doing
so could inadvertently exclude properties in a credential from passing
validation.
Expand Down Expand Up @@ -919,7 +922,8 @@ <h3>Content Integrity Protection</h3>
of a <a>credential schema</a> via its digital signature.
</p>
<p>
As an alternative, the aforementioned [[SRI]] scheme may be used to provide content integrity
As an alternative, the aforementioned <a data-cite="VC-DATA-MODEL-2.0/#integrity-of-related-resources">
Integrity of Related Resources</a> scheme may be used to provide content integrity
protection, ensuring that the underlying <a>credential schema</a> resource has not been tampered with.
</p>
</section>
Expand All @@ -935,7 +939,7 @@ <h3>Storage</h3>
<h3>Multiple Schemas</h3>
<p>
A common use case is to include multiple schemas to validate against a single
<a>verifiable Credential</a>. One such use case is to utilize <a href="https://github.com/w3c/vc-data-model/blob/main/schema/verifiable-credential/verifiable-credential-schema.json">the JSON Schema defined by the</a> [[VC-DATA-MODEL-2]] in addition to a schema to validate a specific property in the credential, such as the <code>credentialSubject</code>. Multiple schemas MAY be combined using native constructs from the [[JSON-SCHEMA]] specification, through utilizing properties such as <code>oneOf</code>, <code>anyOf</code>, or <code>allOf</code>.
<a>verifiable Credential</a>. One such use case is to use <a href="https://github.com/w3c/vc-data-model/blob/main/schema/verifiable-credential/verifiable-credential-schema.json">the JSON Schema defined by the</a> [[VC-DATA-MODEL-2.0]] in addition to a schema to validate a specific property in the credential, such as the <code>credentialSubject</code>. Multiple schemas MAY be combined using native constructs from the [[JSON-SCHEMA]] specification, through use of properties such as <code>oneOf</code>, <code>anyOf</code>, or <code>allOf</code>.
</p>
<p>
An example of how to construct such a schema using the [[JSON-SCHEMA]] property
Expand Down Expand Up @@ -1037,8 +1041,8 @@ <h3>Multiple Schemas</h3>
<h3>Validity of a Verifiable Credential</h3>
<p>
Validation against a [[JSON-SCHEMA]] may be confused with
<a data-cite="vc-data-model/#dfn-credential-validation">validation</a>
or <a data-cite="vc-data-model/#dfn-verify">verification</a>
<a data-cite="VC-DATA-MODEL-2.0/#dfn-credential-validation">validation</a>
or <a data-cite="VC-DATA-MODEL-2.0/#dfn-verify">verification</a>
of a Verifiable Credential. A valid credential according to a [[JSON-SCHEMA]] refers
only to the structure of the claims comprising a Verifiable Credential. This idea of
validity does not imply anything about the validity of the Verifiable Credential itself.
Expand All @@ -1050,11 +1054,11 @@ <h3>Validity of a Verifiable Credential</h3>
<h3>Relationship to Verifiable Credential Type Property</h3>
<p>
It is common to define a <code>credential schema</code> that will be set for
Verifiable Credentials whose <a data-cite="vc-data-model/#dfn-type">type</a>
Verifiable Credentials whose <a data-cite="VC-DATA-MODEL-2.0/#dfn-type">type</a>
property contains a specific <code>type</code>. In this scenario, it is advised to use the value
of the specific <code>type</code> in the <code>id</code> or in a <code>name</code> or
<code>description</code> property.
of a [[JSON-Schema]].
of a [[JSON-SCHEMA]].
</p>
<p>
The example below illustrates this for <code>EmailCredential</code>:
Expand Down Expand Up @@ -1211,7 +1215,7 @@ <h2>Accessibility Considerations</h2>
JSON Schemas are designed to be a machine-readable format which provides static
validation. As such, human readability is a secondary concern. When using a
<a>verifiable credential</a> to represent a schema, we recommend following the
guidance in the <a data-cite="vc-data-model/#accessibility-considerations">VC Data Model</a>.
guidance in the <a data-cite="VC-DATA-MODEL-2.0/#accessibility-considerations">VC Data Model</a>.
</p>
</section>
<section class="informative">
Expand All @@ -1232,7 +1236,7 @@ <h2>Internationalization Considerations</h2>
</p>
<p>
When using a <a>verifiable credential</a> to represent a schema, we recommend following the
guidance in the <a data-cite="vc-data-model/#internationalization-considerations">VC Data Model</a>.
guidance in the <a data-cite="VC-DATA-MODEL-2.0/#internationalization-considerations">VC Data Model</a>.
</p>
</section>
<section class="normative">
Expand All @@ -1248,8 +1252,8 @@ <h2><code>JsonSchema</code></h2>
<a href="#json-schema-specifications">JSON Schema specifications</a>.
</p>
<p>
When using the <a href="#jsonschema">JsonSchema</a> type with a YAML
representation of a JSON Schema, defined by [[OAS]], the types <code>application/openapi+yaml</code>
When using the <a href="#jsonschema">JsonSchema</a> type with a [[YAML]]
representation of a [[JSON-SCHEMA]], defined by [[[OPENAPIS-3.1.0]]], the types <code>application/openapi+yaml</code>
or <code>application/yaml</code> may be used.
</p>
</section>
Expand All @@ -1259,7 +1263,7 @@ <h2><code>JsonSchemaCredential</code></h2>
This specification acknowledges the use of the <code>application/vc+ld+json</code>,
<code>application/vc+ld+json+jwt</code>, and <code>application/vc+ld+json+sd-jwt</code> Media Types
specifically for identifying a [[JSON-SCHEMA]] with usage of the <a href="#jsonschemacredential">
JsonSchemaCredential</a> type, as registered in the [[VC-DATA-MODEL-2]], [[VC-JOSE-COSE]], and [[SD-JWT]] specifications respectively.
JsonSchemaCredential</a> type, as registered in the [[VC-DATA-MODEL-2.0]], [[VC-JOSE-COSE]], and [[SD-JWT]] specifications respectively.
</p>
</section>
</section>
Expand Down