Verifiable Credentials JSON Schema Specification

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.

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.

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.

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.

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:

Who is the author of this schema? (provided by the issuer property)
Is it schema still valid? (provided by the validFrom, validUntil, and credentialStatus properties)
Has the schema been tampered with? (provided by Securing Verifiable Credentials)

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.

Property	Description
id	The 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.
type	The `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

application/vc+ld+json
text/vnd.mermaid
application/vc+ld+json+jwt

{
  "@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.q1q8mz_7E74fE8gWlVUhbKiyZGwH-fZP5LRXMJ0slLaw4dJdMBFStO4vaoUQIIu9hIIRWHY_o_XAOj9slRgcB2zRzl8i-0BACAvLnZ9ybRchAEANaOS9jcXbs8nftxhA

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",
  "name": "EmailCredential",
  "description": "EmailCredential using JsonSchema",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "emailAddress": {
          "type": "string",
          "format": "email"
        }
      },
      "required": [
        "emailAddress"
      ]
    }
  }
}

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:

The credentialSubject property MUST contain two properties:
- type – the value of which MUST be JsonSchema
- jsonSchema – an object which contains a valid JSON Schema
The value of the credentialSchema property MUST always be set to:
```
{
  "id": "https://www.w3.org/2022/credentials/v2/json-schema-credential-schema.json",
  "type": "JsonSchema",
  "digestSRI": "sha384-S57yQDg1MTzF56Oi9DbSQ14u7jBy0RDdx0YbeV7shwhCS88G8SCXeFq82PafhCrW"
}
```
Issue: Hash values might change during Candidate Recommendation
The hash value of the digestSRI property might change during the Candidate Recommendation phase based on implementer feedback that requires the referenced files to be modified.

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

Property	Description
id	The 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.
type	The `type` property MUST be `JsonSchemaCredential`.
credentialSubject.id	The `credentialSubject`'s `id` property MUST follow the guidance provided for identifiers in the [VC-DATA-MODEL-2.0] specification.
credentialSubject.type	The `credentialSubject`'s `type` property MUST be JsonSchema.
credentialSubject.jsonSchema	The `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

application/vc+ld+json
text/vnd.mermaid
application/vc+ld+json+jwt

{
  "@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.64b2YKT4_TX5DH69HGfjGcGvkEVBsBOAy5Nyhn6F13bg8m-e51h3B3BOpPqLiGWYgR3qN7rdkWiix2sPsCRytlcuERag2Bobl6lRIaoGDG07vFmQPmakfYJr8CouxZym

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

application/vc+ld+json
text/vnd.mermaid
application/vc+ld+json+jwt

{
  "@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/2022/credentials/v2/json-schema-credential-schema.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",
       "name": "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/2022/credentials/v2/json-schema-credential-schema.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("name")
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/2022/credentials/v2/json-schema-credential-schema.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",
      "name": "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.eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvdjIiLCJodHRwczovL3d3dy53My5vcmcvbnMvY3JlZGVudGlhbHMvZXhhbXBsZXMvdjIiXSwiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL2NyZWRlbnRpYWxzLzM3MzQiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiSnNvblNjaGVtYUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9pc3N1ZXJzLzE0IiwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQxOToyMzoyNFoiLCJjcmVkZW50aWFsU2NoZW1hIjp7ImlkIjoiaHR0cHM6Ly93d3cudzMub3JnLzIwMjIvY3JlZGVudGlhbHMvdjIvanNvbi1zY2hlbWEtY3JlZGVudGlhbC1zY2hlbWEuanNvbiIsInR5cGUiOiJKc29uU2NoZW1hIiwiZGlnZXN0U1JJIjoic2hhMzg0LVM1N3lRRGcxTVR6RjU2T2k5RGJTUTE0dTdqQnkwUkRkeDBZYmVWN3Nod2hDUzg4RzhTQ1hlRnE4MlBhZmhDclcifSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJodHRwczovL2V4YW1wbGUuY29tL3NjaGVtYXMvZW1haWwtY3JlZGVudGlhbC1zY2hlbWEuanNvbiIsInR5cGUiOiJKc29uU2NoZW1hIiwianNvblNjaGVtYSI6eyIkaWQiOiJodHRwczovL2V4YW1wbGUuY29tL3NjaGVtYXMvZW1haWwtY3JlZGVudGlhbC1zY2hlbWEuanNvbiIsIiRzY2hlbWEiOiJodHRwczovL2pzb24tc2NoZW1hLm9yZy9kcmFmdC8yMDIwLTEyL3NjaGVtYSIsIm5hbWUiOiJFbWFpbENyZWRlbnRpYWwiLCJkZXNjcmlwdGlvbiI6IkVtYWlsQ3JlZGVudGlhbCB1c2luZyBKc29uU2NoZW1hQ3JlZGVudGlhbCIsInR5cGUiOiJvYmplY3QiLCJwcm9wZXJ0aWVzIjp7ImNyZWRlbnRpYWxTdWJqZWN0Ijp7InR5cGUiOiJvYmplY3QiLCJwcm9wZXJ0aWVzIjp7ImVtYWlsQWRkcmVzcyI6eyJ0eXBlIjoic3RyaW5nIiwiZm9ybWF0IjoiZW1haWwifX0sInJlcXVpcmVkIjpbImVtYWlsQWRkcmVzcyJdfX19fX0.7RtNs3ftLll4IHFqN2knYMmrU5KNY72yUFoR0hco8CziWtsuLi_oLzUchl12RdD9Or8bSvjIJ93cxlTKgXmC7J-LbfK-INEL51u-yf_ZbcyEM6FK9Hi-M6-rm2VWrnIb

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/2022/credentials/v2/json-schema-credential-schema.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",
       "name": "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 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 Specification	Date of Publication	$schema URI	Required
[JSON-SCHEMA-2020-12]	10 June 2022	https://json-schema.org/draft/2020-12/schema	Yes
[JSON-SCHEMA-2019-09]	19 March 2020	https://json-schema.org/draft/2019-09/schema	No
[JSON-SCHEMA-DRAFT-7]	20 September 2018	http://json-schema.org/draft-07/schema#	No

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.

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.

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.

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.

It is RECOMMENDED that all JSON Schemas include a name property which provides a human-readable name that describes the schema.

JSON Schemas MAY choose to include an optional description property which provides a human-readable sentence describing the 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 6

---
"$id": https://example.com/schemas/email.json
"$schema": https://json-schema.org/draft/2020-12/schema
name: 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/2019-09/schema",
    "name": "EmailCredential",
    "description": "Email Credential JSON Schema",
    "type": "object",
    "properties": {
      "credentialSubject": {
        "type": "object",
        "properties": {
          "emailAddress": {
            "type": "string",
            "format": "email"
          }
        },
        "required": ["emailAddress"]
      }
    }
  }

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.

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 7: Example Verifiable Credential JsonSchema with Integrity Information

application/vc+ld+json
text/vnd.mermaid
application/vc+ld+json+jwt

{
  "@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.Fp1aVpV2f_dRwx5r8-NeGm8OdvIA0FCC0kTnVPPIUwFlPrr83voXyjrPzgv4lh9ffiq7rYQCvNVyE3880NaSiNQc1VizldBR6LzE3DFdDCE0vEcuilCDheznEAGSsiov

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:

Success – The credential is considered to be valid against the given credential schema.
Failure – The credential is not considedred to be valid against the given credential schema.
Indeterminate – The credential could not be validated. Implementers MUST return this outcome when they encounter a schema whose version they do not support.

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

Example 8: Example Email JSON Schema

{
  "$id": "https://example.com/schemas/email.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "name": "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 9: Example Verifiable Credential - validation Success

application/vc+ld+json
text/vnd.mermaid
application/vc+ld+json+jwt

{
  "@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.uaTHbrbQcDLWe3J-5YH_9kJz0BIRAHrURVn7DX41oXpnbQvweSFua7uavvVHc5K5SBoYnY4QJvmot5zvvPlMXHLeUgtNVGZKzQQrmtROaIl24Ou0RLjOVr73IHgOgfip

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

Example 10: Example Verifiable Credential - validation Failure

application/vc+ld+json
text/vnd.mermaid
application/vc+ld+json+jwt

{
  "@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.9QlOSYi2SvupSjLDyHXM5bOBB-a9OaGt4yLFgiXMmPU5jGUF4Xr7n_EdzGmbFN2ECh-qq5q-2M16K4xwSqCWchXV_qqBF5vzg0gWVl-yMWiCoOerEQyzztbiVsJNCtV5

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

Example 11: 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",
  "name": "EmailCredential",
  "description": "EmailCredential using JsonSchema",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "emailAddress": {
          "type": "string",
          "format": "email"
        }
      },
      "required": [
        "emailAddress"
      ]
    }
  }
}

Example 12: Example Verifiable Credential - validation Indeterminate

application/vc+ld+json
text/vnd.mermaid
application/vc+ld+json+jwt

{
  "@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.CEwanqw5DcA4FEfDmuL6GLtgPegMQX-N2pK6Pi7jGq4DyOnDNUReF14R_YsUFACzQSfxuKW7w9C7rZgLNYsCPmdA6WvnSlU42W9IMDOXf1rad5JPoyKSQjQ3RFsdSyD2

This section is non-normative.

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

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 13: ValidUntil and Evidence Credential Schema

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

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 14: Example Name Credential Schema

{
  "$id": "name-schema",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "name": "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"
          ]
        }
      }
    }
  }
}

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.

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.

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.

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 15: 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",
      "name": "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",
      "name": "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 16: Multiple Schema Verifiable Credential Example

application/vc+ld+json
text/vnd.mermaid
application/vc+ld+json+jwt

{
    "@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.fT_aq7H_nmMYQdOEM8WPXCYHNOHUzG4Jj0SiQB2-MeSz-BdUE9hnG1YcotnubUyQTh4EwH7qHajrmkIDXuMxcfAJP0IBTG5HK2pjtI1-KkV9_VFp7eH_6hRiwkPLZwPm

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.

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.

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 17: Verifiable Credential with Schema Type

application/vc+ld+json
text/vnd.mermaid
application/vc+ld+json+jwt

{
  "@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.S1IeknhBg6fOqRyEY3f_yMdNEqWoolgqUU6fGmuMYCgEeyikZ1TbBeA1v40CqhV_eiXR2RUOLiPnIa0h9c1oMjcJ2-c9hK9qaWog7hX4cMRIDDZWIB6Wlb6hs3t5pqLB

Example 18: Schema with Matching Type Name

{
  "$id": "https://example.com/schemas/email.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "name": "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.

Verifiable Credentials JSON Schema Specification

JSON Schemas for Verifiable Credentials

Abstract

Status of This Document

Status of This Document

1. Introduction

1.1 Terminology

1.2 Conformance

2. Data Model

2.1 JsonSchema

2.2 JsonSchemaCredential

2.2.1 jsonSchema

3. JSON Schema Specifications

3.1 Reserved Keywords

3.1.1 $id

3.1.2 $schema

3.1.3 name

3.1.4 description

3.2 Representations of JSON Schema

4. Processing

4.1 Integrity Validation

4.2 Evaluation

4.2.1 Success Result

4.2.2 Failure Result

4.2.3 Indeterminate Result

5. Implementation Considerations

5.1 Credential Property Validation

5.2 Additional Properties

5.3 Versioning

5.4 Content Integrity Protection

5.5 Storage

5.6 Multiple Schemas

5.7 Validity of a Verifiable Credential

5.8 Relationship to Verifiable Credential Type Property

6. Privacy Considerations

6.1 Personally Identifiable Information

6.2 Verifier Caching

6.3 Schema Resolution

6.4 Data Minimization

7. Security Considerations

7.1 Issuer Impersonation

8. Accessibility Considerations

9. Internationalization Considerations

10. IANA Considerations

10.1 Media Types

10.1.1 JsonSchema

10.1.2 JsonSchemaCredential

11. Revision History

11.1 Changes since the First Public Working Draft:

A. References

A.1 Normative references

A.2 Informative references

10.1.1 `JsonSchema`

10.1.2 `JsonSchemaCredential`