Verifiable Credentials JSON Schema Specification 2023

Abstract

Among other things, the [ VC-DATA-MODEL-2 ] 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 ]. This specification provides a mechanism to make use of a Credential Schema in Verifiable Credential , leveraging the existing Data Schemas concept.

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

This term definition is https://www.w3.org/ns/credentials#JsonSchema2023.

JsonSchema2023 is for the validation of W3C Verifiable Credentials, based on JSON Schema. The version of [ JSON-Schema ] can be any version noted in the section 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 ]. The value MUST be a URL that identifies the schema associated with the verifiable credential .
type	The `type` property MUST be JsonSchema2023.

An example of utilizing the VC Data Model's


credentialSchema

is provided below:

Example 1 : Example JsonSchema2023

{
  "@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": "JsonSchema2023"
  }
}

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

This term definition is https://www.w3.org/ns/credentials#CredentialSchema2023.

CredentialSchema2023 is used for the validation of W3C Verifiable Credentials, based on representing JSON Schema in a verifiable credential . The 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 ]. The value MUST be a URL that identifies the verifiable credential which contains a credential schema.
type	The `type` property MUST be CredentialSchema2023

An example of utilizing the VC Data Model's


credentialSchema

is provided below:

Example 3 : Example CredentialSchema2023

{
  "@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/credentials/3734",
    "type": "CredentialSchema2023"
  }
}

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", "CredentialSchema2023"],
  "issuer": "https://example.com/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "$id": "https://example.com/schemas/email-credential-schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "name": "EmailCredential",
    "description": "EmailCredential using CredentialSchema2023",
    "type": "object",
    "properties": {
      "credentialSubject": {
        "type": "object",
        "properties": {
          "emailAddress": {
            "type": "string",
            "format": "email"
          }
        },
        "required": ["emailAddress"]
      }
    }
  }
}

Issue 159 : Language on nesting of credential schemas when using CredentialSchema2023 enhancement discuss

Add language about CredentialSchema2023 credentials having a credentialSchema property and the risks of nesting.

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

JSON Schema Specification	Date of Publication	~~References~~ $schema URI
[ ~~draft-bhutton-json-schema-01~~ JSON-SCHEMA-2020-12 ]	10 June 2022	~~• JSON Schema: A Media Type for Describing JSON Documents~~ ~~• JSON Schema Validation: A Vocabulary for Structural Validation of JSON~~ https://json-schema.org/draft/2020-12/schema ~~• Relative JSON Pointers~~
[ ~~Draft 2020-12, draft-bhutton-json-schema-00~~ JSON-SCHEMA-2019-09 ]	~~11 June 2021~~ 19 March 2020	~~• JSON Schema: A Media Type for Describing JSON Documents~~ ~~• JSON Schema Validation: A Vocabulary for Structural Validation of JSON~~ https://json-schema.org/draft/2019-09/schema ~~• Relative JSON Pointers~~
[ ~~Draft 2019-09, Draft 8~~ JSON-SCHEMA-DRAFT-7 ]	~~19 March 2020~~ 20 September 2018	~~• JSON Schema: A Media Type for Describing JSON Documents~~ ~~• JSON Schema Validation: A Vocabulary for Structural Validation of JSON~~ http://json-schema.org/draft-07/schema# ~~• JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON~~

~~Issue 133 : Being able to normatively reference JSON Schema planning process Write considerations for normatively referencing JSON Schema.~~

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 and should not be used in conflicting ways.

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 [ RFC-6596 ] URI. The $id MUST be present and its value MUST represent a valid URI-reference [ RFC-3986 ].

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

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.

Issue 142 : Support YAML schema representations

Write section on using different representations of JSON Schema, such as YAML.

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 sections of a verifiable credential . To do this, credential schemas can be constructed to specify application to subsets of a given credential.

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 5 : 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.

In 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 6 : 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. It is advised to make backwards compatabile changes to schemas, should they be adjusted. Otherwise, it is advised that a new credential schema is created with a unique identifier.

Issue 120 : Consider adding language on schema immutability v2

Add language on enabling schema immutability/versioning, such as making use of hashlinks.

This section is non-normative.

Credential schemas MAY be created and made available as immutable objects. They can be stored on any number of storage mediums such as a distributed ledger, traditional database, or decentralized file storage. The same schema could be replicated across multiple file stores with the same identifier.

Immutability is key to enabling a consistent source of truth for usage with verifiable credentials which are tamper-evident by design.

This section is non-normative.

Issue 19 : Example of the credentialSchema.id resolution to schema v2

Add section on schema resolution.

This section is non-normative.

A common use case is to include multiple schemas to validate against which a single verifiable Credential . One such use case is to utilize the JSON Schema defined by the [ VC-DATA-MODEL-2 ] 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 utilizing 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 7 : 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 8 : 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": "CredentialSchema2023"
    },
    "proof": { ... }
}

Issue 136 : Add warning for improperly formed schemes using multiple schemas enhancement

Add warning for improperly formed schemas and risks associated with using multiple schemas.

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 9 : 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": "JsonSchema2023"
  }
}

Example 10 : 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 JsonSchema2023",
  "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 2023

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 JsonSchema2023

2.2 CredentialSchema2023

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

5. Implementation Considerations

5.1 Validation of Specific Properties in a Credential

5.2 Additional Properties

5.3 Versioning

5.4 Storage

5.5 Resolution

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 Content Distribution Networks

7. Security Considerations

7.1 Issuer Impersonation

8. Accessibility Considerations

9. Internationalization Considerations

A. References

A.1 Normative references

A.2 Informative references