Skip to content

Commit 6806113

Browse files
decentralgabeTallTed
decentralgabe
and
TallTed
authored
Address part of 210 (#212)
* cleanup normative refs * one more * tmp * Apply suggestions from code review Co-authored-by: Ted Thibodeau Jr <[email protected]> --------- Co-authored-by: Ted Thibodeau Jr <[email protected]>
1 parent d488099 commit 6806113

File tree

2 files changed

+35
-108
lines changed

2 files changed

+35
-108
lines changed

‎common.js

Lines changed: 1 addition & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -5,38 +5,6 @@ var vcwg = {
55
// Add as the respecConfig localBiblio variable
66
// Extend or override global respec references
77
localBiblio: {
8-
"RFC-6596": {
9-
title: "The Canonical Link Relation",
10-
date:" April 2012",
11-
href: "https://www.rfc-editor.org/rfc/rfc6596",
12-
authors: [
13-
"M. Ohye",
14-
"J. Kupke"
15-
]
16-
},
17-
"RFC-3986": {
18-
title: "Uniform Resource Identifier (URI): Generic Syntax",
19-
date:" January 2005",
20-
href: "https://www.rfc-editor.org/rfc/rfc3986",
21-
authors: [
22-
"T. Berners-Lee",
23-
"R. Fielding",
24-
"L. Masinter"
25-
]
26-
},
27-
"VC-DATA-MODEL-2": {
28-
title: "Verifiable Credentials Data Model v2.0",
29-
href: "https://www.w3.org/TR/vc-data-model-2.0/",
30-
authors: [
31-
"Manu Sporny",
32-
"Orie Steele",
33-
"Michael B. Jones",
34-
"Gabe Cohen",
35-
"Oliver Terbu"
36-
],
37-
status: "Working Draft",
38-
publisher: "W3C Verifiable Credentials Working Group"
39-
},
408
"JSON-SCHEMA": {
419
href: "https://json-schema.org/specification.html",
4210
title: "JSON Schema: A Media Type for Describing JSON Documents",
@@ -57,63 +25,18 @@ var vcwg = {
5725
title: "JSON Schema Draft-07 Release Notes",
5826
publisher: "OpenJS Foundation"
5927
},
60-
"DID-CORE": {
61-
href: "https://w3c.github.io/did-core/",
62-
title: "Decentralized Identifiers (DIDs) v1.0",
63-
publisher: "W3C"
64-
},
65-
"JSON-LD": {
66-
href: "https://w3c.github.io/json-ld-syntax/",
67-
title: "JSON-LD 1.1: A JSON-based Serialization for Linked Data",
68-
publisher: "W3C"
69-
},
7028
"VC-JOSE-COSE": {
7129
href: "https://www.w3.org/TR/vc-jose-cose/",
7230
title: "Securing Verifiable Credentials using JOSE and COSE",
7331
authors: ["Orie Steele", "Michael Jones", "Michael Prorock"],
7432
publisher: "W3C"
7533
},
76-
"VC-DATA-INTEGRITY": {
77-
title: "Verifiable Credential Data Integrity 1.0",
78-
href: "https://www.w3.org/TR/vc-data-integrity/",
79-
authors: ["David Longley", "Manu Sporny"],
80-
status: "Working Draft",
81-
publisher: "W3C Verifiable Credentials Working Group"
82-
},
83-
"JOSE": {
84-
href: "https://jose.readthedocs.io/en/latest/",
85-
title: "Javascript Object Signing and Encryption (JOSE)",
86-
publisher: "IETF"
87-
},
88-
"JSON-SCHEMA-IMPLMENTATIONS": {
89-
href: "https://json-schema.org/implementations.html",
90-
title: "JSON Schema Implementations",
91-
publisher: "json-schema-org"
92-
},
9334
"SD-JWT": {
9435
title: "Selective Disclosure for JWTs (SD-JWT)",
9536
href: "https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-05",
96-
authors: [ "Daniel Fett" , "Kristina Yasuda" , "Brian Campbell"],
37+
authors: ["Daniel Fett", "Kristina Yasuda", "Brian Campbell"],
9738
status: "Internet-Draft",
9839
publisher: "IETF"
99-
},
100-
"OAS": {
101-
title: "OpenAPI Specification Version 3.1.0",
102-
href: "https://swagger.io/specification/",
103-
authors: [
104-
"Darrel Miller",
105-
"Jeremy Whitlock",
106-
"Marsh Gardiner ",
107-
"Mike Ralphson",
108-
"Ron Ratovsky",
109-
"Uri Sarid",
110-
],
111-
publisher: "OpenAPI Initiative",
112-
},
113-
"YAML": {
114-
href: "https://yaml.org/spec/1.2.2/",
115-
title: "YAML Ain’t Markup Language (YAML™) version 1.2",
116-
publisher:"YAML Language Development Team"
11740
}
11841
}
11942
};

‎index.html

Lines changed: 34 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
previousPublishDate: "2022-04-05",
2222
localBiblio: vcwg.localBiblio,
2323
doJsonLd: true,
24+
xref: true,
2425
github: "https://github.com/w3c/vc-json-schema/",
2526
includePermalinks: false,
2627
edDraftURI: "https://w3c.github.io/vc-json-schema/",
@@ -105,13 +106,13 @@
105106
<section id='abstract'>
106107
<h2>Abstract</h2>
107108
<p>
108-
Among other things, the [[VC-DATA-MODEL-2]] specifies the models used for Verifiable Credentials,
109+
Among other things, the [[VC-DATA-MODEL-2.0]] specifies the models used for Verifiable Credentials,
109110
Verifiable Presentations, and explains the relationships between three parties:
110111
<i>issuers</i>, <i>holders</i>, and <i>verifiers</i>. Verifiability, extensibility, and semantic
111112
interoperability are critical pieces of functionality referenced throughout
112-
the [[VC-DATA-MODEL-2]]. This specification provides a mechanism to make use of a Credential Schema in
113+
the [[VC-DATA-MODEL-2.0]]. This specification provides a mechanism to make use of a Credential Schema in
113114
<a>Verifiable Credential</a>, leveraging the existing
114-
<a data-cite="vc-data-model/#data-schemas">Data Schemas</a> concept.
115+
<a data-cite="VC-DATA-MODEL-2.0/#data-schemas">Data Schemas</a> concept.
115116
</p>
116117
</section>
117118
<section id='sotd'>
@@ -151,17 +152,18 @@ <h3>Terminology</h3>
151152
<h2>Data Model</h2>
152153
<p>
153154
The following sections outline the data models for this document, of which there are two:
154-
<code>JsonSchema</code> for usage of a [[JSON-Schema]] directly in a <code>credentialSchema</code>
155-
property, and <code>JsonSchemaCredential</code> for usage of a [[JSON-Schema]] represented as a
155+
<code>JsonSchema</code> for usage of a [[JSON-SCHEMA]] directly in a <code>credentialSchema</code>
156+
property, and <code>JsonSchemaCredential</code> for usage of a [[JSON-SCHEMA]] represented as a
156157
<a>verifiable credential</a>.
157158
</p>
158159
<p>
159160
Implementers may find use in packaging a JSON Schema as a verifiable credential when they wish to
160-
leverage features of the [[VC-DATA-MODEL-2]], answering questions such as:
161+
leverage features of the [[VC-DATA-MODEL-2.0]], answering questions such as:
161162
<ul>
162163
<li>Who is the author of this schema? (provided by the <code>issuer</code> property)</li>
163164
<li>Is it schema still valid? (provided by the <code>validFrom</code>, <code>validUntil</code>, and <code>credentialStatus</code> properties)</li>
164-
<li>Has the schema been tampered with? (provided by [[VC-DATA-INTEGRITY]] or [[VC-JOSE-COSE]])</li>
165+
<li>Has the schema been tampered with? (provided by <a data-cite="VC-DATA-MODEL-2.0/#securing-verifiable-credentials">
166+
Securing Verifiable Credentials</a>)</li>
165167
</ul>
166168
</p>
167169
<section class="normative">
@@ -176,7 +178,7 @@ <h3>JsonSchema</h3>
176178
<code>JsonSchema</code> <code>type</code> value the result is a valid JSON
177179
Schema document according to its specification version.
178180
<p>
179-
The specification version of [[JSON-Schema]] can be any version noted in the section
181+
The specification version of [[JSON-SCHEMA]] can be any version noted in the section
180182
on <a href="#json-schema-specifications">JSON Schema Specifications</a>.
181183
</p>
182184
<p>
@@ -191,7 +193,7 @@ <h3>JsonSchema</h3>
191193
<tr>
192194
<td>id</td>
193195
<td>The constraints on the <code>id</code> property are listed in the Verifiable Credentials
194-
Data Model specification [[VC-DATA-MODEL-2]]. The value MUST be a URL that identifies
196+
Data Model specification [[VC-DATA-MODEL-2.0]]. The value MUST be a URL that identifies
195197
the schema associated with the <a>verifiable credential</a>.</td>
196198
</tr>
197199
<tr>
@@ -314,7 +316,7 @@ <h3>JsonSchemaCredential</h3>
314316
<tr>
315317
<td>id</td>
316318
<td>The constraints on the <code>id</code> property are listed in the Verifiable Credentials
317-
Data Model specification [[VC-DATA-MODEL-2]]. The value MUST be a <a>URL</a> that identifies
319+
Data Model specification [[VC-DATA-MODEL-2.0]]. The value MUST be a URL that identifies
318320
the <a>verifiable credential</a> which contains a credential schema.</td>
319321
</tr>
320322
<tr>
@@ -324,7 +326,7 @@ <h3>JsonSchemaCredential</h3>
324326
<tr>
325327
<td>credentialSubject.id</td>
326328
<td>The <code>credentialSubject</code>'s <code>id</code> property MUST follow the guidance
327-
provided for <a data-cite="vc-data-model#identifiers">identifiers</a> in the [[VC-DATA-MODEL-2]]
329+
provided for <a data-cite="VC-DATA-MODEL-2.0/#identifiers">identifiers</a> in the [[VC-DATA-MODEL-2.0]]
328330
specification.</td>
329331
</tr>
330332
<tr>
@@ -470,7 +472,7 @@ <h4>jsonSchema</h4>
470472
<h2>JSON Schema Specifications</h2>
471473
<p>
472474
The following section describes the allowed specifications for
473-
using a [[JSON-Schema]] with a <a>credential schema</a>.
475+
using a [[JSON-SCHEMA]] with a <a>credential schema</a>.
474476
</p>
475477
<p>
476478
To promote conformance and enable interoperability, implementers MUST
@@ -533,8 +535,8 @@ <h3>Reserved Keywords</h3>
533535
<h4>$id</h4>
534536
<p>
535537
Across JSON Schema specifications, the <code>$id</code> keyword identifies a schema resource
536-
with its canonical [[RFC-6596]] URI. The <code>$id</code> MUST be present and its value
537-
MUST represent a valid URI-reference [[RFC-3986]].
538+
with its canonical [[RFC6596]] URI. The <code>$id</code> MUST be present and its value
539+
MUST represent a valid URI-reference [[RFC3986]].
538540
</p>
539541
<p>
540542
It is RECOMMENDED that the value of the <code>$id</code> property match the <code>id</code>
@@ -573,7 +575,7 @@ <h3>Representations of JSON Schema</h3>
573575
syntax</a> with <code>.json</code> as the file extension.
574576
</p>
575577
<p>
576-
Implementers MAY use OpenAPI Specification's [[OAS]] [[YAML]] representation
578+
Implementers MAY use OpenAPI Specification's [[[OPENAPIS-3.1.0]]] [[YAML]] representation
577579
of a [[JSON-SCHEMA]] with <code>.yaml</code> as the file extension.
578580

579581
<p class="note">
@@ -616,21 +618,22 @@ <h3>Integrity Validation</h3>
616618
Credential Schemas MAY be packaged as <a>verifiable credentials</a> as defined
617619
by usage of the <a href="#jsonschemacredential">JsonSchemaCredential</a> type.
618620
The credential containing a <a>credential schema</a> may include a proof, either
619-
embedded according to [[VC-DATA-INTEGRITY]] or packaged as a [[VC-JOSE-COSE]].
621+
embedded according to <a data-cite="VC-DATA-MODEL-2.0/#securing-verifiable-credentials">
622+
Securing Verifiable Credentials</a>.
620623
</p>
621624
<p>
622625
Secured credentials representing credential schemas SHOULD first be validated
623626
according to the rules set out in the aforementioned securing specifications
624627
before proceeding with additional processing.
625628
</p>
626629
<p class="issue" data-number="143">
627-
Provide examples for Data Integrity and VC-JOSE-COSE Credential Schemas
630+
Provide examples for secured credential schemas.
628631
</p>
629632
<p>
630633
Credential Schemas of type <a href="#jsonschema">JsonSchema</a> MAY
631634
be annotated with integrity information by adding the `digestSRI` property to the `credentialSchema` value
632635
in the Verifiable Credential which contains the schema, using the method specified in
633-
<a data-cite="sri/#integrity-metadata">Subresource Integrity</a>.
636+
<a data-cite="VC-DATA-MODEL-2.0/#integrity-of-related-resources">Integrity of Related Resources</a>.
634637
It is RECOMMENDED that validation of the integrity of the schema be done before evaluation.
635638
</p>
636639
<p>
@@ -853,7 +856,7 @@ <h3>Credential Property Validation</h3>
853856
<section class="informative">
854857
<h3>Additional Properties</h3>
855858
<p>
856-
In using [[JSON-Schema]] it is advised that implementers avoid
859+
When using [[JSON-SCHEMA]], it is advised that implementers avoid
857860
setting the <code>additionalProperties</code> to <i>false</i>. Doing
858861
so could inadvertently exclude properties in a credential from passing
859862
validation.
@@ -919,7 +922,8 @@ <h3>Content Integrity Protection</h3>
919922
of a <a>credential schema</a> via its digital signature.
920923
</p>
921924
<p>
922-
As an alternative, the aforementioned [[SRI]] scheme may be used to provide content integrity
925+
As an alternative, the aforementioned <a data-cite="VC-DATA-MODEL-2.0/#integrity-of-related-resources">
926+
Integrity of Related Resources</a> scheme may be used to provide content integrity
923927
protection, ensuring that the underlying <a>credential schema</a> resource has not been tampered with.
924928
</p>
925929
</section>
@@ -935,7 +939,7 @@ <h3>Storage</h3>
935939
<h3>Multiple Schemas</h3>
936940
<p>
937941
A common use case is to include multiple schemas to validate against a single
938-
<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>.
942+
<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>.
939943
</p>
940944
<p>
941945
An example of how to construct such a schema using the [[JSON-SCHEMA]] property
@@ -1037,8 +1041,8 @@ <h3>Multiple Schemas</h3>
10371041
<h3>Validity of a Verifiable Credential</h3>
10381042
<p>
10391043
Validation against a [[JSON-SCHEMA]] may be confused with
1040-
<a data-cite="vc-data-model/#dfn-credential-validation">validation</a>
1041-
or <a data-cite="vc-data-model/#dfn-verify">verification</a>
1044+
<a data-cite="VC-DATA-MODEL-2.0/#dfn-credential-validation">validation</a>
1045+
or <a data-cite="VC-DATA-MODEL-2.0/#dfn-verify">verification</a>
10421046
of a Verifiable Credential. A valid credential according to a [[JSON-SCHEMA]] refers
10431047
only to the structure of the claims comprising a Verifiable Credential. This idea of
10441048
validity does not imply anything about the validity of the Verifiable Credential itself.
@@ -1050,11 +1054,11 @@ <h3>Validity of a Verifiable Credential</h3>
10501054
<h3>Relationship to Verifiable Credential Type Property</h3>
10511055
<p>
10521056
It is common to define a <code>credential schema</code> that will be set for
1053-
Verifiable Credentials whose <a data-cite="vc-data-model/#dfn-type">type</a>
1057+
Verifiable Credentials whose <a data-cite="VC-DATA-MODEL-2.0/#dfn-type">type</a>
10541058
property contains a specific <code>type</code>. In this scenario, it is advised to use the value
10551059
of the specific <code>type</code> in the <code>id</code> or in a <code>name</code> or
10561060
<code>description</code> property.
1057-
of a [[JSON-Schema]].
1061+
of a [[JSON-SCHEMA]].
10581062
</p>
10591063
<p>
10601064
The example below illustrates this for <code>EmailCredential</code>:
@@ -1211,7 +1215,7 @@ <h2>Accessibility Considerations</h2>
12111215
JSON Schemas are designed to be a machine-readable format which provides static
12121216
validation. As such, human readability is a secondary concern. When using a
12131217
<a>verifiable credential</a> to represent a schema, we recommend following the
1214-
guidance in the <a data-cite="vc-data-model/#accessibility-considerations">VC Data Model</a>.
1218+
guidance in the <a data-cite="VC-DATA-MODEL-2.0/#accessibility-considerations">VC Data Model</a>.
12151219
</p>
12161220
</section>
12171221
<section class="informative">
@@ -1232,7 +1236,7 @@ <h2>Internationalization Considerations</h2>
12321236
</p>
12331237
<p>
12341238
When using a <a>verifiable credential</a> to represent a schema, we recommend following the
1235-
guidance in the <a data-cite="vc-data-model/#internationalization-considerations">VC Data Model</a>.
1239+
guidance in the <a data-cite="VC-DATA-MODEL-2.0/#internationalization-considerations">VC Data Model</a>.
12361240
</p>
12371241
</section>
12381242
<section class="normative">
@@ -1248,8 +1252,8 @@ <h2><code>JsonSchema</code></h2>
12481252
<a href="#json-schema-specifications">JSON Schema specifications</a>.
12491253
</p>
12501254
<p>
1251-
When using the <a href="#jsonschema">JsonSchema</a> type with a YAML
1252-
representation of a JSON Schema, defined by [[OAS]], the types <code>application/openapi+yaml</code>
1255+
When using the <a href="#jsonschema">JsonSchema</a> type with a [[YAML]]
1256+
representation of a [[JSON-SCHEMA]], defined by [[[OPENAPIS-3.1.0]]], the types <code>application/openapi+yaml</code>
12531257
or <code>application/yaml</code> may be used.
12541258
</p>
12551259
</section>
@@ -1259,7 +1263,7 @@ <h2><code>JsonSchemaCredential</code></h2>
12591263
This specification acknowledges the use of the <code>application/vc+ld+json</code>,
12601264
<code>application/vc+ld+json+jwt</code>, and <code>application/vc+ld+json+sd-jwt</code> Media Types
12611265
specifically for identifying a [[JSON-SCHEMA]] with usage of the <a href="#jsonschemacredential">
1262-
JsonSchemaCredential</a> type, as registered in the [[VC-DATA-MODEL-2]], [[VC-JOSE-COSE]], and [[SD-JWT]] specifications respectively.
1266+
JsonSchemaCredential</a> type, as registered in the [[VC-DATA-MODEL-2.0]], [[VC-JOSE-COSE]], and [[SD-JWT]] specifications respectively.
12631267
</p>
12641268
</section>
12651269
</section>

0 commit comments

Comments
 (0)