diff --git a/PR/2025/index.html b/PR/2025/index.html new file mode 100644 index 0000000..fba2bd5 --- /dev/null +++ b/PR/2025/index.html @@ -0,0 +1,3733 @@ + + + + + + + + + +Verifiable Credentials JSON Schema Specification + + + + + + + + + + + + + + + + + +
+

+

Verifiable Credentials JSON Schema Specification

JSON Schemas for Verifiable Credentials

+

W3C Proposed Recommendation

+
+ More details about this document +
+
This version:
+ https://www.w3.org/TR/2024/PR-vc-json-schema-20240320/ +
+
Latest published version:
+ https://www.w3.org/TR/vc-json-schema/ +
+
Latest editor's draft:
https://w3c.github.io/vc-json-schema/
+
History:
+ https://www.w3.org/standards/history/vc-json-schema/ +
+ Commit history +
+
Test suite:
https://github.com/w3c/vc-json-schema-test-suite
+
Implementation report:
+ https://w3c.github.io/vc-json-schema-test-suite/ +
+ + + +
Editors:
+ Gabe Cohen (Block) +
+ Mike Prorock (mesur.io) +
+ Mahmoud Alkhraishi (Mavennet) +
+
+ Former editors: +
+ Andres Uribe (Block) +
+ Orie Steele (Transmute) +
+
Author:
+ Gabe Cohen (Block) +
+
Feedback:
+ GitHub w3c/vc-json-schema + (pull requests, + new issue, + open issues) +
+ +
Related Documents
+ Verifiable Credentials Data Model +
+
+
+ + +

+ Copyright + © + 2024 + + World Wide Web Consortium. + W3C® + liability, + trademark and + permissive document license rules apply. +

+
+
+

Abstract

+ +

+ 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: + issuers, holders, and verifiers. Verifiability, extensibility, and semantic + interoperability are critical pieces of functionality referenced throughout + the [VC-DATA-MODEL-2.0]. This specification provides a mechanism to make use of a Credential Schema in + Verifiable Credential, leveraging the existing + Data Schemas concept. +

+
+

Status of This Document

This section describes the status of this + document at the time of its publication. A list of current W3C + publications and the latest revision of this technical report can be found + in the W3C technical reports index at + https://www.w3.org/TR/.

+

Status of This Document

+

+ The Working Group is actively seeking implementation feedback for this + specification. In order to exit the Candidate Recommendation phase, the + Working Group has set the requirement of at least two independent + implementations for each mandatory feature in the specification. For details + on the conformance testing process, see the test suites listed in the + + implementation report. +

+

+ This document was published by the Verifiable Credentials Working Group as + a Proposed Recommendation using the + Recommendation track. +

Publication as a Proposed Recommendation does not + imply endorsement by W3C and its Members.

+ This is a draft document and may be updated, replaced or obsoleted by other + documents at any time. It is inappropriate to cite this document as other + than work in progress. + +

+ The W3C Membership and other interested parties are invited to review + the document and send comments through 17 April 2025. + Advisory Committee Representatives should consult their + WBS questionnaires. Note that substantive technical comments were expected during the + Candidate Recommendation review period that ended + 17 January 2024. +

+ + This document was produced by a group + operating under the + W3C Patent + Policy. + + + W3C maintains a + public list of any patent disclosures + made in connection with the deliverables of + the group; that page also includes + instructions for disclosing a patent. An individual who has actual + knowledge of a patent which the individual believes contains + Essential Claim(s) + must disclose the information in accordance with + section 6 of the W3C Patent Policy. + +

+ This document is governed by the + 03 November 2023 W3C Process Document. +

+

1. Introduction

This section is non-normative.

+ +

+ This specification provides a mechanism for the use of JSON Schemas with + Verifiable Credentials. A significant part of the integrity of a Verifiable Credential + comes from the ability to structure its contents so that all three parties — + issuer, holder, verifier — may have a consistent mechanism of trust in + interpreting the data that they are provided with. We introducing a new data + model for an object to facilitate backing Credentials with JSON Schemas + that we call a Credential Schema. +

+

+ This specification provides a standardized way of creating Credential Schemas + to be used in credentialing systems. Credential Schemas may apply to any portion + of a Verifiable Credential. Multiple JSON Schemas may back a single Verifiable Credential, + e.g. a schema for the credentialSubject and another for other credential properties. +

+

1.1 Terminology

This section is non-normative.

+ +

+The following terms are used to describe concepts in this specification. +

+ +
+
claim
+
+An assertion made about a subject. +
+
verifiable credential schema
+
+The data model that this specification defines. +
+
json schema
+
+A declarative language that allows you to annotate and validate JSON documents. +
+
credential
+
+A set of one or more claims made by an issuer. +The claims in a credential can be about different subjects. +
+
data minimization
+
+The act of limiting the amount of shared data strictly to the minimum +necessary to successfully accomplish a task or goal. +
+
decentralized identifier
+
+A portable URL-based identifier, also known as a DID, +associated with an entity. These identifiers are most often used in a +verifiable credential and are associated with subjects such that a +verifiable credential itself can be easily ported from one +repository to another without the need to reissue the credential. +An example of a DID is did:example:123456abcdef. +
+
decentralized identifier document
+
+Also referred to as a DID document, this is a document +that is accessible using a verifiable data registry and contains +information related to a specific decentralized identifier, such as the +associated repository and public key information. +
+
digital signature
+
+A mathematical scheme for demonstrating the authenticity of a digital message. +
+
entity
+
+A thing with distinct and independent existence, such as a person, +organization, or device that performs one or more roles in the ecosystem. +
+
holder
+
+A role an entity might perform by possessing one or more +verifiable credentials and generating presentations from them. +A holder is usually, but not always, a subject of the verifiable +credentials they are holding. Holders store their credentials in +credential repositories. +
+
identity
+
+The means for keeping track of entities across contexts. Digital +identities enable tracking and customization of entity interactions +across digital contexts, typically using identifiers and attributes. Unintended +distribution or use of identity information can compromise privacy. Collection +and use of such information should follow the principle of +data minimization. +
+
issuer
+
+A role an entity can perform by asserting claims about one or +more subjects, creating a verifiable credential from these +claims, and transmitting the verifiable credential to a +holder. +
+
presentation
+
+Data derived from one or more verifiable credentials, issued by one or +more issuers, that is shared with a specific verifier. +
+
repository
+
+A program, such as a storage vault or personal verifiable credential +wallet, that stores and protects access to holders' +verifiable credentials. +
+
selective disclosure
+
+The ability of a holder to make fine-grained decisions about what +information to share. +
+
subject
+
+A thing about which claims are made. +
+
validation
+
+The assurance that a verifiable credential or a +verifiable presentation meets the needs of a verifier and other +dependent stakeholders. This specification is constrained to verifying +verifiable credentials and verifiable presentations regardless of +their usage. Validating verifiable credentials or +verifiable presentations is outside the scope of this specification. +
+
verifiable credential
+
+A verifiable credential is a tamper-evident credential that has authorship that +can be cryptographically verified. Verifiable credentials can be used to build +verifiable presentations, which can also be cryptographically verified. +
+
verifiable data registry
+
+A role a system might perform by mediating the creation and verification +of identifiers, keys, and other relevant data, such as +verifiable credential schemas, revocation registries, issuer public keys, +and so on, which might be required to use verifiable credentials. Some +configurations might require correlatable identifiers for subjects. Some +registries, such as ones for UUIDs and public keys, might just act as namespaces +for identifiers. +
+
verifiable presentation
+
+A verifiable presentation is a tamper-evident presentation encoded in such a way +that authorship of the data can be trusted after a process of cryptographic +verification. Certain types of verifiable presentations might contain data that +is synthesized from, but do not contain, the original verifiable credentials +(for example, zero-knowledge proofs). +
+
verification
+
+The evaluation of whether a verifiable credential or verifiable presentation +is an authentic and timely statement of the issuer or presenter, respectively. + This includes checking that: the credential (or presentation) conforms to the specification; the proof method is +satisfied; and, if present, the status check succeeds. +Verification of a credential does not imply evaluation of the truth +of claims encoded in the credential.. + +
+
verifier
+
+A role an entity performs by receiving one or more +verifiable credentials, optionally inside a +verifiable presentation for processing. Other specifications might refer +to this concept as a relying party. +
+
URL
+
+A Uniform Resource Locator, as defined by [URL]. URLs can be dereferenced such +that they result in a resource, such as a document. The rules for dereferencing, +or fetching, a URL are defined by the URL scheme. This specification +does not use the term URI or IRI because those terms have been deemed to be +confusing to Web developers. +
+
schema resolution
+
+The process that takes as its input a URL and returns a credential schema. +
+
+
+

1.2 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

+ The key words MAY, MUST, MUST NOT, RECOMMENDED, SHOULD, and SHOULD NOT in this document + are to be interpreted as described in + BCP 14 + [RFC2119] [RFC8174] + when, and only when, they appear in all capitals, as shown here. +

+
+
+

2. Data Model

+ +

+ The following sections outline the data models for this document, of which there are two: + JsonSchema for usage of a [JSON-SCHEMA] directly in a credentialSchema + property, and JsonSchemaCredential for usage of a [JSON-SCHEMA] represented as a + verifiable credential. +

+

+ Implementers MAY package a [JSON-SCHEMA] as a verifiable credential when they wish to + leverage features of the [VC-DATA-MODEL-2.0], answering questions such as: +

+ +

2.1 JsonSchema

+ +

+ This term is part of the + Verifiable Credentials Vocabulary v2.0. +

+

+ JsonSchema is used for the validation of W3C Verifiable Credentials using + JSON Schema. When dereferencing the id property associated with the + JsonSchema type value the result is a valid JSON + Schema document according to its specification version. +

+ The specification version of [JSON-SCHEMA] can be any version noted in the section + on JSON Schema Specifications. +

+ + + + + + + + + + + + + + + + + +
PropertyDescription
idThe constraints on the id property are listed in the Verifiable Credentials + Data Model specification [VC-DATA-MODEL-2.0]. The value MUST be a URL that identifies + the schema associated with the verifiable credential.
typeThe type property MUST be JsonSchema.
+
Note: Restriction on the use of the jsonSchema property

+ The jsonSchema property is only to be used + when the JsonSchema class instance is the object of the credentialSubject + property within a JsonSchemaCredential instance. +

+

+ An example of utilizing the VC Data Model's credentialSchema + is provided below: +

+
+
+ Example 1: Example JsonSchema +
+ 
{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3732",
+  "type": ["VerifiableCredential", "EmailCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "subject@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema"
+  }
+}
graph LR + +0("VerifiableCredential") +1{{"id"}} +2("https://example.com/credentials/3732") +3(("type")) +4("EmailCredential") +5("issuer") +6("https://example.com/issuers/14") +7("issuanceDate") +8("2010-01-01T19:23:24Z") +9("credentialSubject") +10{{"id"}} +11("did:example:ebfeb1f712ebc6f1c276e12ec21") +12("emailAddress") +13("subject@example.com") +14("credentialSchema") +15{{"id"}} +16("https://example.com/schemas/email.json") +17(("type")) +18("JsonSchema") + +0 --- 1 +1 --- 2 +0 --- 3 +3 --- 4 +0 --- 5 +5 --- 6 +0 --- 7 +7 --- 8 +0 --- 9 +9 --- 10 +10 --- 11 +9 --- 12 +12 --- 13 +0 --- 14 +14 --- 15 +15 --- 16 +14 --- 17 +17 --- 18
---------------- Decoded Protected Header ----------------
+{
+  "alg": "ES384"
+}
+---------------- Decoded Protected Claimset ----------------
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3732",
+  "type": [
+    "VerifiableCredential",
+    "EmailCredential"
+  ],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "subject@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema"
+  }
+}
+---------------- Compact Encoded JSON Web Token ----------------
+eyJhbGciOiJFUzM4NCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL2NyZWRlbnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiRW1haWxDcmVkZW50aWFsIl0sImlzc3VlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy8xNCIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMTk6MjM6MjRaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJlbWFpbEFkZHJlc3MiOiJzdWJqZWN0QGV4YW1wbGUuY29tIn0sImNyZWRlbnRpYWxTY2hlbWEiOnsiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL3NjaGVtYXMvZW1haWwuanNvbiIsInR5cGUiOiJKc29uU2NoZW1hIn19.paii7pMn5_XiPZnf3wtkaAf1Oy_l42qt7URoyGqZN6GMaVcZhRyZogu4swUbwou4QdYQ7eX_mYqANPfVk7A0Zyryc5L2U2xBWwxPN3bhLOIlgTKZna4D_HdXwJt2Ktxy
+

+ Upon dereferencing the value of the id https://example.com/schemas/email.json, + a process also be referred to as schema resolution, the following JSON Schema + document is returned: +

+
+
+ Example 2: Example Email JSON Schema + 
{
+  "$id": "https://example.com/schemas/email.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "EmailCredential",
+  "description": "EmailCredential using JsonSchema",
+  "type": "object",
+  "properties": {
+    "credentialSubject": {
+      "type": "object",
+      "properties": {
+        "emailAddress": {
+          "type": "string",
+          "format": "email"
+        }
+      },
+      "required": [
+        "emailAddress"
+      ]
+    }
+  }
+}
+
+
+

2.2 JsonSchemaCredential

+ +

+ This term is part of the + Verifiable Credentials Vocabulary v2.0. +

+

+ JsonSchemaCredential is used for the validation of W3C Verifiable Credentials using + JSON Schema, where the JSON Schema is contained with a verifiable credential. + When dereferencing the id property associated with the + credentialSchema type value, the result is a valid + verifiable credential. For the resulting verifiable credential: +

+

+

+ Any version of [JSON-SCHEMA] in the section on + JSON Schema Specifications + can be used. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyDescription
idThe constraints on the id property are listed in the Verifiable Credentials + Data Model specification [VC-DATA-MODEL-2.0]. The value MUST be a URL that identifies + the verifiable credential which contains a credential schema.
typeThe type property MUST be JsonSchemaCredential.
credentialSubject.idThe credentialSubject's id property MUST follow the guidance + provided for identifiers in the [VC-DATA-MODEL-2.0] + specification.
credentialSubject.typeThe credentialSubject's type property MUST be + JsonSchema.
credentialSubject.jsonSchemaThe credentialSubject MUST use the jsonSchema property to + represent a valid [JSON-SCHEMA].
+

+ An example of utilizing the VC Data Model's credentialSchema + is provided below: +

+
+
+ Example 3: Example JsonSchemaCredential +
+ 
{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3733",
+  "type": ["VerifiableCredential", "ExampleEmailCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "subject@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/credentials/3734",
+    "type": "JsonSchemaCredential"
+  }
+}
graph LR + +19("VerifiableCredential") +20{{"id"}} +21("https://example.com/credentials/3733") +22(("type")) +23("ExampleEmailCredential") +24("issuer") +25("https://example.com/issuers/14") +26("issuanceDate") +27("2010-01-01T19:23:24Z") +28("credentialSubject") +29{{"id"}} +30("did:example:ebfeb1f712ebc6f1c276e12ec21") +31("emailAddress") +32("subject@example.com") +33("credentialSchema") +34{{"id"}} +35("https://example.com/credentials/3734") +36(("type")) +37("JsonSchemaCredential") + +19 --- 20 +20 --- 21 +19 --- 22 +22 --- 23 +19 --- 24 +24 --- 25 +19 --- 26 +26 --- 27 +19 --- 28 +28 --- 29 +29 --- 30 +28 --- 31 +31 --- 32 +19 --- 33 +33 --- 34 +34 --- 35 +33 --- 36 +36 --- 37
---------------- Decoded Protected Header ----------------
+{
+  "alg": "ES384"
+}
+---------------- Decoded Protected Claimset ----------------
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3733",
+  "type": [
+    "VerifiableCredential",
+    "ExampleEmailCredential"
+  ],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "subject@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/credentials/3734",
+    "type": "JsonSchemaCredential"
+  }
+}
+---------------- Compact Encoded JSON Web Token ----------------
+eyJhbGciOiJFUzM4NCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL2NyZWRlbnRpYWxzLzM3MzMiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiRXhhbXBsZUVtYWlsQ3JlZGVudGlhbCJdLCJpc3N1ZXIiOiJodHRwczovL2V4YW1wbGUuY29tL2lzc3VlcnMvMTQiLCJpc3N1YW5jZURhdGUiOiIyMDEwLTAxLTAxVDE5OjIzOjI0WiIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmV4YW1wbGU6ZWJmZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIiwiZW1haWxBZGRyZXNzIjoic3ViamVjdEBleGFtcGxlLmNvbSJ9LCJjcmVkZW50aWFsU2NoZW1hIjp7ImlkIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9jcmVkZW50aWFscy8zNzM0IiwidHlwZSI6Ikpzb25TY2hlbWFDcmVkZW50aWFsIn19.rTwc641kBDRoVXkhHpXfv_htDS99UT1WNL53UO3UL3FWpNNlcGzB963lYuiX99CDha6HKZvOeo3YnCYYUiFd6Wz5fSYRMBdYVCjBf79Aq8qL4LNgKUNJvZBhSN54EZJM
+

+ Upon dereferencing the value of the id https://example.com/credentials/3734, + a process also be referred to as schema resolution, the following verifiable credential, + representing a JSON Schema, is returned: +

+
+
+ Example 4: 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", "JsonSchemaCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSchema": {
+    "id": "https://www.w3.org/ns/credentials/json-schema/v2.json",
+    "type": "JsonSchema",
+    "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
+  },
+  "credentialSubject": {
+    "id": "https://example.com/schemas/email-credential-schema.json",
+    "type": "JsonSchema",
+    "jsonSchema": {
+        "$id": "https://example.com/schemas/email-credential-schema.json",
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "EmailCredential",
+        "description": "EmailCredential using JsonSchemaCredential",
+        "type": "object",
+        "properties": {
+          "credentialSubject": {
+            "type": "object",
+            "properties": {
+              "emailAddress": {
+                "type": "string",
+                "format": "email"
+              }
+            },
+            "required": ["emailAddress"]
+          }
+        }
+    }
+  }
+}
graph LR + +38("VerifiableCredential") +39{{"id"}} +40("https://example.com/credentials/3734") +41(("type")) +42("JsonSchemaCredential") +43("issuer") +44("https://example.com/issuers/14") +45("issuanceDate") +46("2010-01-01T19:23:24Z") +47("credentialSchema") +48{{"id"}} +49("https://www.w3.org/ns/credentials/json-schema/v2.json") +50(("type")) +51("JsonSchema") +52("digestSRI") +53("sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW") +54("credentialSubject") +55{{"id"}} +56("https://example.com/schemas/email-credential-schema.json") +57(("type")) +58("JsonSchema") +59("jsonSchema") +60("$id") +61("https://example.com/schemas/email-credential-schema.json") +62("$schema") +63("https://json-schema.org/draft/2020-12/schema") +64("title") +65("EmailCredential") +66("description") +67("EmailCredential using JsonSchemaCredential") +68(("type")) +69("object") +70("properties") +71("credentialSubject") +72(("type")) +73("object") +74("properties") +75("emailAddress") +76(("type")) +77("string") +78("format") +79("email") +80("required") +81("emailAddress") + +38 --- 39 +39 --- 40 +38 --- 41 +41 --- 42 +38 --- 43 +43 --- 44 +38 --- 45 +45 --- 46 +38 --- 47 +47 --- 48 +48 --- 49 +47 --- 50 +50 --- 51 +47 --- 52 +52 --- 53 +38 --- 54 +54 --- 55 +55 --- 56 +54 --- 57 +57 --- 58 +54 --- 59 +59 --- 60 +60 --- 61 +59 --- 62 +62 --- 63 +59 --- 64 +64 --- 65 +59 --- 66 +66 --- 67 +59 --- 68 +68 --- 69 +59 --- 70 +70 --- 71 +71 --- 72 +72 --- 73 +71 --- 74 +74 --- 75 +75 --- 76 +76 --- 77 +75 --- 78 +78 --- 79 +71 --- 80 +80 --- 81
---------------- Decoded Protected Header ----------------
+{
+  "alg": "ES384"
+}
+---------------- Decoded Protected Claimset ----------------
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3734",
+  "type": [
+    "VerifiableCredential",
+    "JsonSchemaCredential"
+  ],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSchema": {
+    "id": "https://www.w3.org/ns/credentials/json-schema/v2.json",
+    "type": "JsonSchema",
+    "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
+  },
+  "credentialSubject": {
+    "id": "https://example.com/schemas/email-credential-schema.json",
+    "type": "JsonSchema",
+    "jsonSchema": {
+      "$id": "https://example.com/schemas/email-credential-schema.json",
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "EmailCredential",
+      "description": "EmailCredential using JsonSchemaCredential",
+      "type": "object",
+      "properties": {
+        "credentialSubject": {
+          "type": "object",
+          "properties": {
+            "emailAddress": {
+              "type": "string",
+              "format": "email"
+            }
+          },
+          "required": [
+            "emailAddress"
+          ]
+        }
+      }
+    }
+  }
+}
+---------------- Compact Encoded JSON Web Token ----------------
+eyJhbGciOiJFUzM4NCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL2NyZWRlbnRpYWxzLzM3MzQiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiSnNvblNjaGVtYUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9pc3N1ZXJzLzE0IiwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQxOToyMzoyNFoiLCJjcmVkZW50aWFsU2NoZW1hIjp7ImlkIjoiaHR0cHM6Ly93d3cudzMub3JnL25zL2NyZWRlbnRpYWxzL2pzb24tc2NoZW1hL3YyLmpzb24iLCJ0eXBlIjoiSnNvblNjaGVtYSIsImRpZ2VzdFNSSSI6InNoYTM4NC1TNTd5UURnMU1UekY1Nk9pOURiU1ExNHU3akJ5MFJEZHgwWWJlVjdzaHdoQ1M4OEc4U0NYZUZxODJQYWZoQ3JXIn0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9zY2hlbWFzL2VtYWlsLWNyZWRlbnRpYWwtc2NoZW1hLmpzb24iLCJ0eXBlIjoiSnNvblNjaGVtYSIsImpzb25TY2hlbWEiOnsiJGlkIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9zY2hlbWFzL2VtYWlsLWNyZWRlbnRpYWwtc2NoZW1hLmpzb24iLCIkc2NoZW1hIjoiaHR0cHM6Ly9qc29uLXNjaGVtYS5vcmcvZHJhZnQvMjAyMC0xMi9zY2hlbWEiLCJ0aXRsZSI6IkVtYWlsQ3JlZGVudGlhbCIsImRlc2NyaXB0aW9uIjoiRW1haWxDcmVkZW50aWFsIHVzaW5nIEpzb25TY2hlbWFDcmVkZW50aWFsIiwidHlwZSI6Im9iamVjdCIsInByb3BlcnRpZXMiOnsiY3JlZGVudGlhbFN1YmplY3QiOnsidHlwZSI6Im9iamVjdCIsInByb3BlcnRpZXMiOnsiZW1haWxBZGRyZXNzIjp7InR5cGUiOiJzdHJpbmciLCJmb3JtYXQiOiJlbWFpbCJ9fSwicmVxdWlyZWQiOlsiZW1haWxBZGRyZXNzIl19fX19fQ.da8kzcUFZ6UmQYdJFT23OVI6woaywTt8kLImFcyEWhXg_1CJkJwpSxZz57WVuK-o7uSA4v1uL4IWw29TB44fI3dxnHWiY7zgp-KBNQztJLVG7RNfe1rSNoUmytnAQold
+

2.2.1 jsonSchema

+ +

+ This term is part of the + Verifiable Credentials Vocabulary v2.0. +

+

jsonSchema enables the use of the jsonSchema property + within the credentialSubject of a verifiable credential. The term is + intended to be used with the 2.2 JsonSchemaCredential type only. The value of + the jsonSchema property MUST be a valid [JSON-SCHEMA]. +

+
+
+ Example 5: Example JsonSchema Credential with jsonSchema + 
{
+  "@context": [
+      "https://www.w3.org/ns/credentials/v2",
+      "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3734",
+  "type": ["VerifiableCredential", "JsonSchemaCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSchema": {
+    "id": "https://www.w3.org/ns/credentials/json-schema/v2.json",
+    "type": "JsonSchema",
+  },
+  "credentialSubject": {
+    "id": "https://example.com/schemas/favorite-color-schema.json",
+    "type": "JsonSchema",
+     "jsonSchema": {
+      "$id": "https://example.com/schemas/favorite-color-schema.json",
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "Favorite Color Schema",
+      "description": "Favorite Color using JsonSchemaCredential",
+      "type": "object",
+      "properties": {
+        "credentialSubject": {
+          "type": "object",
+          "properties": {
+            "favoriteColor": {
+              "type": "string"
+              "enum": ["red", "orange", "green", "blue", "yellow", "purple"]
+            }
+          },
+          "required": ["favoriteColor"]
+        }
+      }
+    }
+    
+  }
+}
+
+

+ The $ref property can be used to reference another jsonSchema without redefining the JSON structure. +

+
+
+ Example 6: Example JsonSchema Credential with ref + 
{
+  "@context": [
+      "https://www.w3.org/ns/credentials/v2",
+      "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3734",
+  "type": ["VerifiableCredential", "JsonSchemaCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSchema": {
+    "id": "https://www.w3.org/ns/credentials/json-schema/v2.json",
+    "type": "JsonSchema",
+  },
+  "credentialSubject": {
+    "id": "https://example.com/schemas/favorite-color-schema.json",
+    "type": "JsonSchema",
+     "jsonSchema": {
+      "$ref": "https://example.com/schemas/favorite-color-schema.json"
+    }
+    
+  }
+}
+
+
+
+
+

3. JSON Schema Specifications

+ +

+ The following section describes the allowed specifications for + using a [JSON-SCHEMA] with a credential schema. +

+

+ To promote conformance and enable interoperability, implementers MUST + provide support for JSON Schema specifications where, in the following table, + the required column's value is yes. +

+ + + + + + + + + + + + + + + + + +
JSON Schema SpecificationDate of Publication$schema URIRequired
[JSON-SCHEMA-2020-12]10 June 2022https://json-schema.org/draft/2020-12/schemaYes
+ +
Note: A stable JSON Schema specification is coming

+ A stable JSON Schema specification + is in the works. When it's released, we intend to update this table to require the stable version. +

+ +

3.1 Reserved Keywords

+ +

+ JSON Schema specifications reserve certain keywords that hold specific meanings and + functions during the processing of JSON Schemas. It is crucial to avoid using conflicting + keys when creating JSON Schemas. The specification document for each version of JSON Schema + lists these reserved keywords, which can be found in the table provided above. +

+

+ In the upcoming sections we list some keywords that possess unique significance in + [JSON-SCHEMA] documents and SHOULD NOT be used in conflicting ways, such as redefining + these keywords, or using them in a manner other than as noted by [JSON-SCHEMA] specifications. +

+

+ Furthermore, we identify specific keywords, that are not explicitly defined by JSON Schema, + but are emphasized in this specification to support widespread usage. +

+

3.1.1 $id

+ +

+ Across JSON Schema specifications, the $id keyword identifies a schema resource + with its canonical URI. The $id MUST be present, and its value MUST represent + a valid URI-reference as specified by the associated [JSON-SCHEMA] version. +

+

+ It is RECOMMENDED that the value of the $id property match the id + value in the credentialSchema object of a verifiable credential, and + that the value of the $id is a dereferenceable URL. +

+
+

3.1.2 $schema

+ +

+ Across JSON Schema specifications, the $schema keyword identifies a JSON Schema + providing the feature set for a given JSON Schema specification. This property MUST be present + in each schema. For example, when constructing a schema for Draft 2020-12 the value of + the $schema identifier MUST be https://json-schema.org/draft/2020-12/schema. +

+
+

3.1.3 title

+ +

+ It is RECOMMENDED that all JSON Schemas include the optional title property as defined in + [JSON-SCHEMA]. +

+
+

3.1.4 description

+ +

+ It is RECOMMENDED that all JSON Schemas include the optional description property as + defined in [JSON-SCHEMA]. +

+
+

3.1.5 lang

+ +

+ JSON Schemas SHOULD choose to include an optional lang property that indicates the + language tag for the values of the title and + description properties defined in the JSON Schema. The value of this field MUST be a + canonical unicode locale identifier. + When absent, implementers MUST assume that the value of this property is und. +

+
+

3.1.6 dir

+ +

+ JSON Schemas SHOULD choose to include an optional dir property that indicates the + base direction for the values of the title and description properties defined in + the JSON Schema. The value of this property MUST be a text-direction. When absent, implementers + MUST assume that the value of this property is "auto". +

+

+ The text-directions are the following: +

+
+
+ "ltr" +
+
+ Left-to-right text. +
+
+ "rtl" +
+
+ Right-to-left text. +
+
+ "auto" (default) +
+
+ No explicit directionality. +
+
+
+
+

3.2 Representations of JSON Schema

+ +

+ The standard representation of [JSON-SCHEMA] uses the [RFC8259] JSON data interchange + syntax with .json as the file extension. +

+

+ Implementers MAY use OpenAPI Specification's OpenAPI Specification - version 3.1.0 [YAML] representation + of a [JSON-SCHEMA] with .yaml as the file extension. +

+
Note

+ YAML representations of JSON Schemas can only be used with credential schemas whose type is JsonSchema. +

+ + An example [JSON-SCHEMA] using [YAML] is provided below. +
+
+ Example 7 + 
---
+"$id": https://example.com/schemas/email.json
+"$schema": https://json-schema.org/draft/2020-12/schema
+title: Email Credential Schema
+description: Email Credential JSON Schema using YAML
+type: object
+properties:
+  credentialSubject:
+    type: object
+    properties:
+      emailAddress:
+        type: string
+        format: email
+    required:
+      - emailAddress
+example: |-
+  {
+    "$id": "https://example.com/schemas/email.json",
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "EmailCredential",
+    "description": "Email Credential JSON Schema",
+    "type": "object",
+    "properties": {
+      "credentialSubject": {
+        "type": "object",
+        "properties": {
+          "emailAddress": {
+            "type": "string",
+            "format": "email"
+          }
+        },
+        "required": ["emailAddress"]
+      }
+    }
+  }
+
+
+
+

4. Processing

+ +

+ This section details how to process Credential Schemas, which is commonly referred to + as JSON schema validation. +

+

+ There are many open source implementations of [JSON-SCHEMA] validators across many common programming + languages. The OpenJS Foundation maintains a list of implementations + as a part of the JSON Schema official documentation. +

+

+ A common feature of a JSON Schema validator is the ability to detect the version of a JSON Schema document + and select the validator for that specific version of [JSON-SCHEMA]. This is done by switching on the + schema's $schema property and picking the corresponding validator. Schemas without a + $schema property are not considered valid and MUST NOT be processed. Implementers + SHOULD choose validators which possess this capability and are able to limit validation to the + JSON Schema specifications supported by this document. +

+

+ Conformant implementers MUST support JSON Schema specification versions marked as required + in the table defined in the JSON Schema specifications section + of this document. Implementers MAY support JSON Schema specification versions not marked as + required. +

+

4.1 Integrity Validation

+ +

+ Credential Schemas MAY be packaged as verifiable credentials as defined + by usage of the JsonSchemaCredential type. + The credential containing a credential schema MAY be secured by using either an + embedded or external proof as defined in + Securing Verifiable Credentials. +

+

+ 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. +

+
Issue 143: Add examples of validating VC-JWT and Linked Data Proof credentials post-cr

+ Provide examples for secured credential schemas. +

+

+ Credential Schemas of type JsonSchema 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 + Integrity of Related Resources. + It is RECOMMENDED that validation of the integrity of the schema be done before evaluation. +

+

+ An example of such usage is provided below: +

+
+
+ Example 8: Example Verifiable Credential JsonSchema with Integrity Information +
+ 
{
+  "@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"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "subject@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema",
+    "digestSRI": "sha384-dNwyy/Zs/YjPor8aoOgnaCqb+PH24QcNFxbxM1XoBOxdbgnpQcVaGYH8QunXww2U"
+  }
+}
graph LR + +82("VerifiableCredential") +83{{"id"}} +84("https://example.com/credentials/3733") +85(("type")) +86("EmailCredential") +87("issuer") +88("https://example.com/issuers/14") +89("issuanceDate") +90("2010-01-01T19:23:24Z") +91("credentialSubject") +92{{"id"}} +93("did:example:ebfeb1f712ebc6f1c276e12ec21") +94("emailAddress") +95("subject@example.com") +96("credentialSchema") +97{{"id"}} +98("https://example.com/schemas/email.json") +99(("type")) +100("JsonSchema") +101("digestSRI") +102("sha384-dNwyy/Zs/YjPor8aoOgnaCqb+PH24QcNFxbxM1XoBOxdbgnpQcVaGYH8QunXww2U") + +82 --- 83 +83 --- 84 +82 --- 85 +85 --- 86 +82 --- 87 +87 --- 88 +82 --- 89 +89 --- 90 +82 --- 91 +91 --- 92 +92 --- 93 +91 --- 94 +94 --- 95 +82 --- 96 +96 --- 97 +97 --- 98 +96 --- 99 +99 --- 100 +96 --- 101 +101 --- 102
---------------- Decoded Protected Header ----------------
+{
+  "alg": "ES384"
+}
+---------------- Decoded Protected Claimset ----------------
+{
+  "@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"
+  ],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "subject@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema",
+    "digestSRI": "sha384-dNwyy/Zs/YjPor8aoOgnaCqb+PH24QcNFxbxM1XoBOxdbgnpQcVaGYH8QunXww2U"
+  }
+}
+---------------- Compact Encoded JSON Web Token ----------------
+eyJhbGciOiJFUzM4NCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL2NyZWRlbnRpYWxzLzM3MzMiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiRW1haWxDcmVkZW50aWFsIl0sImlzc3VlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy8xNCIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMTk6MjM6MjRaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJlbWFpbEFkZHJlc3MiOiJzdWJqZWN0QGV4YW1wbGUuY29tIn0sImNyZWRlbnRpYWxTY2hlbWEiOnsiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL3NjaGVtYXMvZW1haWwuanNvbiIsInR5cGUiOiJKc29uU2NoZW1hIiwiZGlnZXN0U1JJIjoic2hhMzg0LWROd3l5L1pzL1lqUG9yOGFvT2duYUNxYitQSDI0UWNORnhieE0xWG9CT3hkYmducFFjVmFHWUg4UXVuWHd3MlUifX0.MvULnHQNRLvrrPHOceoplBzCLQefVuoIUhIOuLbpK-DcpwKfDysknw0Ag7vIGd1TG8gu7bYrVaRKVkizBfYPSr2vBC4GaoB9YEGriEAUp_EhzbQI_F7AHirglh-JOQ0a
+
+

4.2 Evaluation

+ +

+ Validation of a given credential against a schema is to be performed according + to its associated [JSON-SCHEMA] specification. Validation MUST result in one of the following three possible + outcomes: +

+ +

+ Examples for the Success and Failure possible outcomes are provided below. +

+

4.2.1 Success Result

+ +
+
+ Example 9: Example Email JSON Schema + 
{
+  "$id": "https://example.com/schemas/email.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "EmailCredential",
+  "description": "EmailCredential using JsonSchema",
+  "type": "object",
+  "properties": {
+    "credentialSubject": {
+      "type": "object",
+      "properties": {
+        "emailAddress": {
+          "type": "string",
+          "format": "email"
+        }
+      },
+      "required": ["emailAddress"]
+    }
+  }
+}
+
+

+ Validation according to the spec [JSON-SCHEMA-2020-12] yields a Success result + when applying it to the VC below. +

+
+
+ Example 10: Example Verifiable Credential - validation Success +
+ 
{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3732",
+  "type": ["VerifiableCredential", "EmailCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "subject@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema"
+  }
+}
graph LR + +103("VerifiableCredential") +104{{"id"}} +105("https://example.com/credentials/3732") +106(("type")) +107("EmailCredential") +108("issuer") +109("https://example.com/issuers/14") +110("issuanceDate") +111("2010-01-01T19:23:24Z") +112("credentialSubject") +113{{"id"}} +114("did:example:ebfeb1f712ebc6f1c276e12ec21") +115("emailAddress") +116("subject@example.com") +117("credentialSchema") +118{{"id"}} +119("https://example.com/schemas/email.json") +120(("type")) +121("JsonSchema") + +103 --- 104 +104 --- 105 +103 --- 106 +106 --- 107 +103 --- 108 +108 --- 109 +103 --- 110 +110 --- 111 +103 --- 112 +112 --- 113 +113 --- 114 +112 --- 115 +115 --- 116 +103 --- 117 +117 --- 118 +118 --- 119 +117 --- 120 +120 --- 121
---------------- Decoded Protected Header ----------------
+{
+  "alg": "ES384"
+}
+---------------- Decoded Protected Claimset ----------------
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3732",
+  "type": [
+    "VerifiableCredential",
+    "EmailCredential"
+  ],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "subject@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema"
+  }
+}
+---------------- Compact Encoded JSON Web Token ----------------
+eyJhbGciOiJFUzM4NCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL2NyZWRlbnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiRW1haWxDcmVkZW50aWFsIl0sImlzc3VlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy8xNCIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMTk6MjM6MjRaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJlbWFpbEFkZHJlc3MiOiJzdWJqZWN0QGV4YW1wbGUuY29tIn0sImNyZWRlbnRpYWxTY2hlbWEiOnsiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL3NjaGVtYXMvZW1haWwuanNvbiIsInR5cGUiOiJKc29uU2NoZW1hIn19.fdKIVZ0BowV_18yvO5JE6Hnxtbg83ksTDUp1yw8tajseN1-OEYIOQvYu5_gmONZLyvl5t1Qh3pmTMuGsJ9SarsaKYq2TZoOwFCK2xsiyZB8ADNvbeojPZUOB3nZ0CHg7
+
+

4.2.2 Failure Result

+ +

+ Validation according to the spec [JSON-SCHEMA-2020-12] yields a Failure result when + applying it to the VC below. +

+
+
+ Example 11: Example Verifiable Credential - validation Failure +
+ 
{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3732",
+  "type": ["VerifiableCredential", "EmailCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "not an email"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema"
+  }
+}
graph LR + +122("VerifiableCredential") +123{{"id"}} +124("https://example.com/credentials/3732") +125(("type")) +126("EmailCredential") +127("issuer") +128("https://example.com/issuers/14") +129("issuanceDate") +130("2010-01-01T19:23:24Z") +131("credentialSubject") +132{{"id"}} +133("did:example:ebfeb1f712ebc6f1c276e12ec21") +134("emailAddress") +135("not an email") +136("credentialSchema") +137{{"id"}} +138("https://example.com/schemas/email.json") +139(("type")) +140("JsonSchema") + +122 --- 123 +123 --- 124 +122 --- 125 +125 --- 126 +122 --- 127 +127 --- 128 +122 --- 129 +129 --- 130 +122 --- 131 +131 --- 132 +132 --- 133 +131 --- 134 +134 --- 135 +122 --- 136 +136 --- 137 +137 --- 138 +136 --- 139 +139 --- 140
---------------- Decoded Protected Header ----------------
+{
+  "alg": "ES384"
+}
+---------------- Decoded Protected Claimset ----------------
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3732",
+  "type": [
+    "VerifiableCredential",
+    "EmailCredential"
+  ],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "not an email"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema"
+  }
+}
+---------------- Compact Encoded JSON Web Token ----------------
+eyJhbGciOiJFUzM4NCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL2NyZWRlbnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiRW1haWxDcmVkZW50aWFsIl0sImlzc3VlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy8xNCIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMTk6MjM6MjRaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJlbWFpbEFkZHJlc3MiOiJub3QgYW4gZW1haWwifSwiY3JlZGVudGlhbFNjaGVtYSI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vc2NoZW1hcy9lbWFpbC5qc29uIiwidHlwZSI6Ikpzb25TY2hlbWEifX0.4wl_r2wBPKQ92tQLPFgHAq6nWRVC-3ZD0tUhfnuhS1qJBhqklISapNt5vqG5WsiRDpn3GO17qDk5jDcoE9bj43coYmtsQoKPGAXL_cxWXzXuogptrrjEhClT24AEgED8
+
+

4.2.3 Indeterminate Result

+ +

+ Assuming that the implementer does not support [JSON-SCHEMA-2019-09], an example of an Indeterminate + evaluation is provided below. +

+
+
+ Example 12: Example Email JSON Schema using unsupported JSON Schema version + 
{
+  "$id": "https://example.com/schemas/email.json",
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "title": "EmailCredential",
+  "description": "EmailCredential using JsonSchema",
+  "type": "object",
+  "properties": {
+    "credentialSubject": {
+      "type": "object",
+      "properties": {
+        "emailAddress": {
+          "type": "string",
+          "format": "email"
+        }
+      },
+      "required": [
+        "emailAddress"
+      ]
+    }
+  }
+}
+
+
+
+ Example 13: Example Verifiable Credential - validation Indeterminate +
+ 
{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3732",
+  "type": ["VerifiableCredential", "EmailCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "not an email"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema"
+  }
+}
graph LR + +141("VerifiableCredential") +142{{"id"}} +143("https://example.com/credentials/3732") +144(("type")) +145("EmailCredential") +146("issuer") +147("https://example.com/issuers/14") +148("issuanceDate") +149("2010-01-01T19:23:24Z") +150("credentialSubject") +151{{"id"}} +152("did:example:ebfeb1f712ebc6f1c276e12ec21") +153("emailAddress") +154("not an email") +155("credentialSchema") +156{{"id"}} +157("https://example.com/schemas/email.json") +158(("type")) +159("JsonSchema") + +141 --- 142 +142 --- 143 +141 --- 144 +144 --- 145 +141 --- 146 +146 --- 147 +141 --- 148 +148 --- 149 +141 --- 150 +150 --- 151 +151 --- 152 +150 --- 153 +153 --- 154 +141 --- 155 +155 --- 156 +156 --- 157 +155 --- 158 +158 --- 159
---------------- Decoded Protected Header ----------------
+{
+  "alg": "ES384"
+}
+---------------- Decoded Protected Claimset ----------------
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/3732",
+  "type": [
+    "VerifiableCredential",
+    "EmailCredential"
+  ],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "not an email"
+  },
+  "credentialSchema": {
+    "id": "https://example.com/schemas/email.json",
+    "type": "JsonSchema"
+  }
+}
+---------------- Compact Encoded JSON Web Token ----------------
+eyJhbGciOiJFUzM4NCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL2NyZWRlbnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiRW1haWxDcmVkZW50aWFsIl0sImlzc3VlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy8xNCIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMTk6MjM6MjRaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJlbWFpbEFkZHJlc3MiOiJub3QgYW4gZW1haWwifSwiY3JlZGVudGlhbFNjaGVtYSI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vc2NoZW1hcy9lbWFpbC5qc29uIiwidHlwZSI6Ikpzb25TY2hlbWEifX0.Q-5qlL6GIPC7zyYQ6aA-bk6I9mBHD5QSHA29p-MYa-lfUSLAnlhFx6_Og0DdT4n1rPA9RkGupcRvxsMk_eyyFwIUTd3Fs7OMk1JtGwLrg1dPD3pwFyQB5DKdveP-Z7yJ
+
+
+
+

5. Implementation Considerations

This section is non-normative.

+ +

+ This section details some issues implementers of the specification + may consider. +

+

5.1 Credential Property Validation

This section is non-normative.

+ +

+ Implementers may wish to validate certain properties in a + verifiable credential. To do this, credential schemas can be + constructed to validate subsets of a credential's data. +

+

+ One example of such a construction would be to validate the presence of certain + top-level properties in a verifiable credential. The following example + demonstrates a schema which enforces that a credential issued against it + has an validUntil property and includes evidence. +

+
+
+ Example 14: ValidUntil and Evidence Credential Schema + 
{
+  "$id": "validuntil-and-evidence-schema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Example validUntil and evidence schema",
+  "description": "Schema requiring validUntil and evidence properties",
+  "type": "object",
+  "properties": {
+    "validUntil": {
+      "type": "object"
+    },
+    "evidence": {
+      "type": "object"
+    }
+  },
+  "required": ["validUntil", "evidence"]
+}
+
+
+

5.2 Additional Properties

This section is non-normative.

+ +

+ When using [JSON-SCHEMA], it is advised that implementers avoid + setting the additionalProperties to false. Doing + so could inadvertently exclude properties in a credential from passing + validation. +

+

+ As an example, consider a credential schema that is intended to validate + the credentialSubject property of a credential. It is common + for the credentialSubject property to include an id, + denoting the identifier the subject. Not including this id property + in a given schema would result in validation failure. The simple alternative + is to avoid setting additionalProperties to false. +

+
+
+ Example 15: Example Name Credential Schema + 
{
+  "$id": "name-schema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Name schema",
+  "description": "A schema capturing a human name",
+  "type": "object",
+  "properties": {
+    "credentialSubject": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "object",
+          "properties": {
+            "firstName": {
+              "type": "string"
+            },
+            "lastName": {
+              "type": "string"
+            },
+            "additionalProperties": false
+          },
+          "required": [
+            "firstName",
+            "lastName"
+          ]
+        }
+      }
+    }
+  }
+}
+
+
+

5.3 Versioning

This section is non-normative.

+ +

+ Versioning is not provided as an explicit feature of this specification. + Implementers are advised to make backwards compatabile changes to schemas, should + they be adjusted. Otherwise, it is advised that new credential schemas + be created with unique identifiers to avoid processing conflicts. +

+
+

5.4 Content Integrity Protection

This section is non-normative.

+ +

+ It is important to make sure that credential schemas have not been tampered with + before processing. When making use of the JsonSchemaCredential2023 representation + of a schema, the credential's associated integrity protection mechanism can be used to detect mutations + of a credential schema via its digital signature. +

+

+ As an alternative, the aforementioned + Integrity of Related Resources scheme may be used to provide content integrity + protection, ensuring that the underlying credential schema resource has not been tampered with. +

+
+

5.5 Storage

This section is non-normative.

+ +

+ Credential schemas can be stored on any number of storage media such as a distributed + ledger, traditional database, or decentralized file storage. For more robust availability + guarantees, the same schema could be replicated across multiple file stores. +

+
+

5.6 Multiple Schemas

This section is non-normative.

+ +

+ A common use case is to include multiple schemas to validate against a single + verifiable Credential. One such use case is to use the JSON Schema defined by the [VC-DATA-MODEL-2.0] in addition to a schema to validate a specific property in the credential, such as the credentialSubject. Multiple schemas MAY be combined using native constructs from the [JSON-SCHEMA] specification, through use of properties such as oneOf, anyOf, or allOf. +

+

+ An example of how to construct such a schema using the [JSON-SCHEMA] property + allOf is provided below, combining schemas for a verifiable credential, + name, and email address: +

+
+
+ Example 16: Multiple Schema Credential Schema Example + 
{
+  "allOf": [
+    {
+      "$ref": "https://raw.githubusercontent.com/w3c/vc-data-model/main/schema/verifiable-credential/verifiable-credential-schema.json"
+    },
+    {
+      "$id": "name-schema",
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "Name schema",
+      "description": "A schema capturing a human name",
+      "type": "object",
+      "properties": {
+        "credentialSubject": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "object",
+              "properties": {
+                "firstName": {
+                  "type": "string"
+                },
+                "lastName": {
+                  "type": "string"
+                },
+                "additionalProperties": false
+              },
+              "required": [
+                "firstName",
+                "lastName"
+              ]
+            }
+          }
+        }
+      }
+    },
+    {
+      "$id": "email-schema-1.0",
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "Email schema",
+      "description": "A schema requiring an email address.",
+      "type": "object",
+      "properties": {
+        "credentialSubject": {
+          "type": "object",
+          "properties": {
+            "email": {
+              "type": "object",
+              "properties": {
+                "emailAddress": {
+                  "type": "string",
+                  "format": "email"
+                }
+              },
+              "required": ["emailAddress"]
+            }
+          }
+        }
+      }
+    }
+  ]
+}
+
+

+ The example above is used to validate every property in the following + verifiable credential: +

+
+
+ Example 17: Multiple Schema Verifiable Credential Example +
+ 
{
+    "@context": ["https://www.w3.org/ns/credentials/v2"],
+    "id": "4995c86c-851f-43a6-9dd2-03dc891091fd",
+    "type": ["VerifiableCredential"],
+    "issuer": "did:example:1234",
+    "validFrom": "2023-01-01T05:05:05Z",
+    "credentialSubject": {
+        "firstName": "Alice",
+        "lastName": "Bobertson",
+        "emailAddress": "alice@bobertson.com"
+    },
+    "credentialSchema": {
+        "id": "multiple-credential-schema-test",
+        "type": "JsonSchemaCredential"
+    }
+}
graph LR + +160("VerifiableCredential") +161{{"id"}} +162("4995c86c-851f-43a6-9dd2-03dc891091fd") +163("issuer") +164("did:example:1234") +165("validFrom") +166("2023-01-01T05:05:05Z") +167("credentialSubject") +168("firstName") +169("Alice") +170("lastName") +171("Bobertson") +172("emailAddress") +173("alice@bobertson.com") +174("credentialSchema") +175{{"id"}} +176("multiple-credential-schema-test") +177(("type")) +178("JsonSchemaCredential") + +160 --- 161 +161 --- 162 +160 --- 163 +163 --- 164 +160 --- 165 +165 --- 166 +160 --- 167 +167 --- 168 +168 --- 169 +167 --- 170 +170 --- 171 +167 --- 172 +172 --- 173 +160 --- 174 +174 --- 175 +175 --- 176 +174 --- 177 +177 --- 178
---------------- Decoded Protected Header ----------------
+{
+  "alg": "ES384"
+}
+---------------- Decoded Protected Claimset ----------------
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2"
+  ],
+  "id": "4995c86c-851f-43a6-9dd2-03dc891091fd",
+  "type": [
+    "VerifiableCredential"
+  ],
+  "issuer": "did:example:1234",
+  "validFrom": "2023-01-01T05:05:05Z",
+  "credentialSubject": {
+    "firstName": "Alice",
+    "lastName": "Bobertson",
+    "emailAddress": "alice@bobertson.com"
+  },
+  "credentialSchema": {
+    "id": "multiple-credential-schema-test",
+    "type": "JsonSchemaCredential"
+  }
+}
+---------------- Compact Encoded JSON Web Token ----------------
+eyJhbGciOiJFUzM4NCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiXSwiaWQiOiI0OTk1Yzg2Yy04NTFmLTQzYTYtOWRkMi0wM2RjODkxMDkxZmQiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlzc3VlciI6ImRpZDpleGFtcGxlOjEyMzQiLCJ2YWxpZEZyb20iOiIyMDIzLTAxLTAxVDA1OjA1OjA1WiIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImZpcnN0TmFtZSI6IkFsaWNlIiwibGFzdE5hbWUiOiJCb2JlcnRzb24iLCJlbWFpbEFkZHJlc3MiOiJhbGljZUBib2JlcnRzb24uY29tIn0sImNyZWRlbnRpYWxTY2hlbWEiOnsiaWQiOiJtdWx0aXBsZS1jcmVkZW50aWFsLXNjaGVtYS10ZXN0IiwidHlwZSI6Ikpzb25TY2hlbWFDcmVkZW50aWFsIn19.pqyEI8Ex9wMnkUN72IzHaETja_t4r7u7rgSs9Idw-cGzeSL7_9sSUFIKbLwunHophXwDbhX1jmG2rR6YHrTqwGzySt2TvKjacjjQTXtXAvEFKWfc4aNdDE4r_hmFA7bX
+

+ Using allOf when composing a JSON Schema can easily result in a schema for which all JSON documents will fail to validate. Such a situation may happen when multiple schemas reference the same property. Implementers are advised to test their schemas against a set of sample input documents before introducing any real world usage. Including sample input that suceeds and fails is considered a good practice. +

+
+

5.7 Validity of a Verifiable Credential

This section is non-normative.

+ +

+ Validation against a [JSON-SCHEMA] may be confused with + validation + or verification + 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. + It's possible for a Verifiable Credential to be considered valid by one verifier, + while another verifier would not consider it valid. +

+
+

5.8 Relationship to Verifiable Credential Type Property

This section is non-normative.

+ +

+ It is common to define a credential schema that will be set for + Verifiable Credentials whose type + property contains a specific type. In this scenario, it is advised to use the value + of the specific type in the id or in a name or + description property. + of a [JSON-SCHEMA]. +

+

+ The example below illustrates this for EmailCredential: +

+
+
+ Example 18: Verifiable Credential with Schema Type +
+ 
{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/email-credential",
+  "type": ["VerifiableCredential", "EmailCredential"],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "tester@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.org/examples/email.json",
+    "type": "JsonSchema"
+  }
+}
graph LR + +179("VerifiableCredential") +180{{"id"}} +181("https://example.com/credentials/email-credential") +182(("type")) +183("EmailCredential") +184("issuer") +185("https://example.com/issuers/14") +186("issuanceDate") +187("2010-01-01T19:23:24Z") +188("credentialSubject") +189{{"id"}} +190("did:example:ebfeb1f712ebc6f1c276e12ec21") +191("emailAddress") +192("tester@example.com") +193("credentialSchema") +194{{"id"}} +195("https://example.org/examples/email.json") +196(("type")) +197("JsonSchema") + +179 --- 180 +180 --- 181 +179 --- 182 +182 --- 183 +179 --- 184 +184 --- 185 +179 --- 186 +186 --- 187 +179 --- 188 +188 --- 189 +189 --- 190 +188 --- 191 +191 --- 192 +179 --- 193 +193 --- 194 +194 --- 195 +193 --- 196 +196 --- 197
---------------- Decoded Protected Header ----------------
+{
+  "alg": "ES384"
+}
+---------------- Decoded Protected Claimset ----------------
+{
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
+  "id": "https://example.com/credentials/email-credential",
+  "type": [
+    "VerifiableCredential",
+    "EmailCredential"
+  ],
+  "issuer": "https://example.com/issuers/14",
+  "issuanceDate": "2010-01-01T19:23:24Z",
+  "credentialSubject": {
+    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
+    "emailAddress": "tester@example.com"
+  },
+  "credentialSchema": {
+    "id": "https://example.org/examples/email.json",
+    "type": "JsonSchema"
+  }
+}
+---------------- Compact Encoded JSON Web Token ----------------
+eyJhbGciOiJFUzM4NCJ9.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL2NyZWRlbnRpYWxzL2VtYWlsLWNyZWRlbnRpYWwiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiRW1haWxDcmVkZW50aWFsIl0sImlzc3VlciI6Imh0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy8xNCIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMTk6MjM6MjRaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJlbWFpbEFkZHJlc3MiOiJ0ZXN0ZXJAZXhhbXBsZS5jb20ifSwiY3JlZGVudGlhbFNjaGVtYSI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS5vcmcvZXhhbXBsZXMvZW1haWwuanNvbiIsInR5cGUiOiJKc29uU2NoZW1hIn19.8_6UwVBFXKZ4EfvHe0L45iZzjFmaOdGw0dzQrXejHXdl65Dg3lwvsXeskNUr5k4LTJpE-EQonZDlmfLs-hLGKDOpJTywSUFI8ZQrg8WFSKIPoH3xFOuPgfgdUtpOmSr9
+
+
+ Example 19: Schema with Matching Type Name + 
{
+  "$id": "https://example.com/schemas/email.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Email Credential",
+  "description": "Email Credential Schema for usage in JsonSchema",
+  "type": "object",
+  "properties": {
+    "credentialSubject": {
+      "type": "object",
+      "properties": {
+        "emailAddress": {
+          "type": "string",
+          "format": "email"
+        }
+      },
+      "required": [
+        "emailAddress"
+      ]
+    }
+  }
+}
+
+

+ It is important to note that a credential schema enables issuers to communicate how to process + the structure of data inside a verifiable credential, whereas the type property of a verifiable credential + lets issuers communicate the semantics of the data. It is advised to associate all properties + that have a semantic mapping with a property in a credential schema. +

+
+
+

6. Privacy Considerations

This section is non-normative.

+ +

+ This section details the general privacy considerations and specific privacy + implications of deploying this specification into production environments. +

+

+ When using the JsonSchemaCredential + type, implementers are advised to review the + Privacy Considerations outlined in the [VC-DATA-MODEL-2.0]. +

+

6.1 Personally Identifiable Information

This section is non-normative.

+ +

+ Data associated with schemas and verifiable credentials are susceptible + to privacy violations when shared. Personally identifying data, such as a + government-issued identifier, address, or name, can be used to track and correlate + entities. Even less overt personal data such as a birthdate or postal code has + the ability to result in correlation and de-anonymization. +

+

+ Implementers are strongly advised to avoid constructing schemas with any personally + identifiable information (PII). +

+

+ If such personally identifiable information is necessary in a schema, or a credential + schema, implementers are strongly advised to use mechanisms while storing and + transporting verifiable credentials that protect the data from those who should + not access it such as Transportation Layer Security (TLS) or other means of encrypting + the data whether in transit or at rest. +

+
+

6.2 Verifier Caching

This section is non-normative.

+ +

+ Since schemas are immutable, they are highly cachable. + It is possible for verifiers to increase the privacy of the + holder whose verifiable credential is being checked by caching + schemas that have been fetched from remote servers. By caching the + content locally, less correlatable information can be inferred from + verifier-based access patterns on the schema. +

+
+

6.3 Schema Resolution

This section is non-normative.

+ +

+ Schema resolution is the process of dereferencing a credential schema's identifier in order to fetch a + credential schema. +

+

+ Issuers can increase the privacy of holders by using + content distribution networks to reduce or eliminate requests for the + schemas from the issuer. Often, a request for a schema + will be served by an edge device and thus be faster and reduce the load + on the server as well as cloaking verifiers and holders + from issuers. +

+

+ Furthermore, the use of Oblivious HTTP + can prevent linkage of schema requests made by holders. Implementers are encouraged to allow configuration + of an Oblivious Relay Resource + for use during schema resolution. +

+

+ When using credential schema identifiers that are unique to the issued credential, it is possible + to correlate schema resolution of a credential with an IP address. Implementers are encouraged to prevent such + correlation by selecting identifiers which are shared among a class of credentials. +

+
+

6.4 Data Minimization

+ +

+ Data minimization refers to the principle of sharing the minimum necessary data for any given data request, such + as a verifier requesting one or more verifiable credentials from + a holder. +

+

+ When using a credential schema with a credential that supports selective disclosure, it may be + possible for a verifier to deduce additional attributes that would be available but were not presented + when verifying a credential from a holder. To mitigate data leakage, holders may + choose to reject verification requests that could disclose such additional attributes, or, if the capability is + available, to selectively disclose properties in the associated credential schema. To enable this functionality, + issuers can use selective disclosure schemes when creating credential schemas using + the JsonCredentialSchema type. +

+
+
+

7. Security Considerations

This section is non-normative.

+ +

+ There are a number of security considerations that implementers should be + aware of when processing data described by this specification. Ignoring or + not understanding the implications of this section can result in + security vulnerabilities. +

+

+ When using the JsonSchemaCredential + type, implementers are advised to review the + Security Considerations outlined in the [VC-DATA-MODEL-2.0]. +

+

7.1 Issuer Impersonation

This section is non-normative.

+ +

+ It is possible for a schema to become authoritative, such as a schema + provided by a recognized industry group like a consortium of financial + companies. To avoid confusion as to the authorship of credential schemas, + it is advised that they be packaged as verifiable credentials using the + JsonSchemaCredential type. +

+
+
+

8. Accessibility Considerations

This section is non-normative.

+ +

+ There are a number of accessibility considerations implementers should be + aware of when processing data described in this specification. As with any web + standards or protocols implementation, ignoring accessibility issues makes + this information unusable to a large subset of the population. It is important + to follow accessibility guidelines and standards, such as [WCAG21], to ensure + all people, regardless of ability, can make use of this data. This is + especially important when establishing systems utilizing cryptography, which + have historically created problems for assistive technologies. +

+

+ 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 + verifiable credential to represent a schema, we recommend following the + guidance in the VC Data Model. +

+
+

9. Internationalization Considerations

This section is non-normative.

+ +

+ JSON Schemas are JSON text intended primarily for machines to read, since they + are used for strict static validation of data. Language and text direction concerns + are addressed by the noted specification documents + for JSON Schema itself. +

+

+ When using a verifiable credential to represent a schema, we recommend following the + guidance in the VC Data Model. +

+
+

10. IANA Considerations

+ +

10.1 Media Types

+ +

10.1.1 JsonSchema

+ +

+ The media type application/schema+json, as defined in + [JSON-SCHEMA], SHOULD be used when transmitting a [JSON-SCHEMA] expressed + as JSON over HTTP. Clients receiving [JSON-SCHEMA] files over HTTP MAY accept content + using either the application/schema+json media type or the + application/json media type as defined in [JSON]. +

+

+ When using the JsonSchema type with a [YAML] + representation of a [JSON-SCHEMA], defined by OpenAPI Specification - version 3.1.0, the types + application/openapi+yaml or application/yaml MAY be used. +

+
+

10.1.2 JsonSchemaCredential

+ +

+ The media types application/vc, application/vc+jwt, or + application/vc+sd-jwt, as defined in the [VC-DATA-MODEL-2.0], + [VC-JOSE-COSE], or [SD-JWT] specification, respectively, SHOULD be used when + transmitting a [JSON-SCHEMA] represented as a verifiable credential with the + JsonSchemaCredential type. Clients receiving credential schemas + files over HTTP MAY accept content using any of these types. +

+
+
+
+

11. Revision History

This section is non-normative.

+ +

+ This section contains the substantive changes that have been made to + this specification over time. +

+

11.1 + Changes since the + + First Public Working Draft: +

+ + +
+
+ + +

A. References

A.1 Normative references

+ +
[i18n-glossary]
+ Internationalization Glossary. Richard Ishida; Addison Phillips. W3C. 17 October 2024. W3C Working Group Note. URL: https://www.w3.org/TR/i18n-glossary/ +
[JSON-SCHEMA]
+ JSON Schema: A Media Type for Describing JSON Documents. OpenJS Foundation. URL: https://json-schema.org/specification.html +
[JSON-SCHEMA-2020-12]
+ JSON Schema 2020-12 Release Notes. OpenJS Foundation. URL: https://json-schema.org/draft/2020-12/release-notes.html +
[OPENAPIS-3.1.0]
+ OpenAPI Specification - version 3.1.0. Darrell Miller; Jeremy Whitlock; Marsh Gardiner; Mike Ralphson; Ron Ratovsky; Uri Sarid. OpenAPI Initiative. 15 February 2021. URL: https://spec.openapis.org/oas/v3.1.0 +
[RFC2119]
+ Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119 +
[RFC8174]
+ Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
[RFC8259]
+ The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed. IETF. December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259 +
[SD-JWT]
+ Selective Disclosure for JWTs (SD-JWT). Daniel Fett; Kristina Yasuda; Brian Campbell. IETF. Internet-Draft. URL: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-05 +
[VC-DATA-MODEL-2.0]
+ Verifiable Credentials Data Model v2.0. Manu Sporny; Ted Thibodeau Jr; Ivan Herman; Gabe Cohen; Michael Jones. W3C. 27 January 2025. CRD. URL: https://www.w3.org/TR/vc-data-model-2.0/ +
[VC-JOSE-COSE]
+ Securing Verifiable Credentials using JOSE and COSE. Orie Steele; Michael Jones; Michael Prorock. W3C. URL: https://www.w3.org/TR/vc-jose-cose/ +
[YAML]
+ YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html +
+

A.2 Informative references

+ +
[JSON-SCHEMA-2019-09]
+ JSON Schema 2019-09 Release Notes. OpenJS Foundation. URL: https://json-schema.org/draft/2019-09/release-notes.html +
[URL]
+ URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/ +
[WCAG21]
+ Web Content Accessibility Guidelines (WCAG) 2.1. Michael Cooper; Andrew Kirkpatrick; Joshue O'Connor; Alastair Campbell. W3C. 12 December 2024. W3C Recommendation. URL: https://www.w3.org/TR/WCAG21/ +
+
\ No newline at end of file