Terminology

Validation of Specific Properties in a Credential

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.

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

Additional Properties

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.

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

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

Storage

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.

Resolution

Add section on schema resolution.

Multiple Schemas

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:

            {
              "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",
                  "description": "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",
                  "description": "Email",
                  "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": "CredentialSchema2023"
                },
                "proof": { ... }
            }
            

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

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

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

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.

Content Distribution Networks

The use of content distribution networks by issuers can increase the privacy of holders by reducing or eliminating requests for the schemas lists from the issuer. Often, a request for a schema list 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.

Issuer Impersonation

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