Terminology

Credential Property Validation

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.

            {
              "$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"]
            }
            

Additional Properties

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.

            {
              "$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"
                      ]
                    }
                  }
                }
              }
            }
            

Versioning

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.

Content Integrity Protection

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.

Storage

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.

Multiple Schemas

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:

            {
              "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:

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

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.

Validity of a Verifiable Credential

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.

Relationship to Verifiable Credential Type Property

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:

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

              {
                "$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.

Personally Identifiable Information

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.

Verifier Caching

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.

Schema Resolution

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.

Issuer Impersonation

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.