Verifiable Credentials JSON Schema Specification 2023

JSON Schemas for Verifiable Credentials

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2023/WD-vc-json-schema-20230530/
Latest published version:
https://www.w3.org/TR/vc-json-schema/
Latest editor's draft:
https://w3c.github.io/vc-json-schema/
History:
https://www.w3.org/standards/history/vc-json-schema
Commit history
Editors:
Gabe Cohen (Block)
Orie Steele (Transmute)
Andres Uribe (Block)
Authors:
Gabe Cohen (Block)
Orie Steele (Transmute)
Feedback:
GitHub w3c/vc-json-schema (pull requests, new issue, open issues)
Related Documents
Verifiable Credentials Data Model

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.

Status of This Document

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

Status of This Document

This document is experimental and is undergoing heavy development. It is inadvisable to implement the specification in its current form. An experimental implementation is available.

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

Publication as a Working Draft does not imply endorsement by W3C and its Members.

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

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

This document is governed by the 2 November 2021 W3C Process Document.

1. Introduction

This section is non-normative.

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

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

1.1 Terminology

This section is non-normative.

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

claim
An assertion made about a subject.
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.
user agent
A program, such as a browser or other Web client, that mediates the communication between holders, issuers, and verifiers.
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.

1.2 Conformance

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

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

2. Data Model

The following sections outline the data models for this document, of which there are two: 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.

2.1 JsonSchema2023

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

2.2 CredentialSchema2023

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 enhancementdiscuss

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

3. JSON Schema Specifications

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

JSON Schema Specification Date of Publication References
draft-bhutton-json-schema-01 10 June 2022 JSON Schema: A Media Type for Describing JSON Documents
JSON Schema Validation: A Vocabulary for Structural Validation of JSON
Relative JSON Pointers
Draft 2020-12, draft-bhutton-json-schema-00 11 June 2021 JSON Schema: A Media Type for Describing JSON Documents
JSON Schema Validation: A Vocabulary for Structural Validation of JSON
Relative JSON Pointers
Draft 2019-09, Draft 8 19 March 2020 JSON Schema: A Media Type for Describing JSON Documents
JSON Schema Validation: A Vocabulary for Structural Validation of JSON
JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON
Issue 133: Being able to normatively reference JSON Schema planningprocess

Write considerations for normatively referencing JSON Schema.

Issue 142: Support YAML schema representations

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

Issue 146: Add section on warning for reserved words in JSON schema versions enhancement

Write section on implementation considerations, such as using name, description and reserved keywords such as $id and $schema.

4. Processing

This section details instructions on how to process Credential Schemas.

4.1 Integrity Validation

Credential Schemas MAY be packaged as verifiable credentials as defined by usage of the CredentialSchema2023 type. The credential containing a credential schema may include a proof, either embedded according to [VC-DATA-INTEGRITY] or packaged as a [VC-JWT].

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

Provide examples for Data Integrity and VC-JWT Credential Schemas

4.2 Evaluation

Validation of a given Credential against its schema is to be performed according to its associated [JSON-SCHEMA] specification. If validation succeeds the credential is considered to be valid against its credential schema.

5. Implementation Considerations

This section is non-normative.

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

5.1 Validation of Specific Properties in a Credential

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",
  "description": "Schema requiring validUntil and evidence properties",
  "type": "object",
  "properties": {
    "validUntil": {
      "type": "object"
    },
    "evidence": {
      "type": "object"
    }
  },
  "required": ["validUntil", "evidence"]
}

5.2 Additional Properties

This section is non-normative.

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",
  "description": "Name",
  "type": "object",
  "properties": {
    "credentialSubject": {
      "type": "object",
      "properties": {
        "name": {
          "type": "object",
          "properties": {
            "firstName": {
              "type": "string"
            },
            "lastName": {
              "type": "string"
            },
            "additionalProperties": false
          },
          "required": [
            "firstName",
            "lastName"
          ]
        }
      }
    }
  }
}

5.3 Versioning

This section is non-normative.

Versioning is not provided as an explicit feature of this specification. 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.

5.4 Storage

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.

5.5 Resolution

This section is non-normative.

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

Add section on schema resolution.

5.6 Multiple Schemas

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

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.

5.7 Validity of a Verifiable Credential

This section is non-normative.

Validation against a [JSON-SCHEMA] may be confused with validation or verification of a Verifiable Credential. A valid credential according to a [JSON-SCHEMA] refers only to the structure of the claims comprising a Verifiable Credential. This idea of validity does not imply anything about the validity of the Verifiable Credential itself. It's possible for a Verifiable Credential to be considered valid by one verifier, while another verifier would not consider it valid.

5.8 Relationship to Verifiable Credential Type Property

This section is non-normative.

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

The example below illustrates this for EmailCredential:

Example 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": "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.

6. Privacy Considerations

This section is non-normative.

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

6.1 Verifier Caching

This section is non-normative.

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

6.2 Content Distribution Networks

This section is non-normative.

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.

7. Security Considerations

This section is non-normative.

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

7.1 Issuer Impersonation

This section is non-normative.

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.

8. Accessibility Considerations

This section is non-normative.

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

This section details the general accessibility considerations to take into account when utilizing this data model.

Issue 147: Add section on accessibility considerations enhancement

Write accessibility considerations.

9. Internationalization Considerations

This section is non-normative.

There are a number of internationalization considerations implementers should be aware of when publishing data described in this specification. As with any web standards or protocols implementation, ignoring internationalization makes it difficult for data to be produced and consumed across a disparate set of languages and societies, which would limit the applicability of the specification and significantly diminish its value as a standard.

This section outlines general internationalization considerations to take into account when utilizing this data model.

Issue 148: Add section on i18n considerations enhancement

Write i18n considerations.

A. References

A.1 Normative references

[JSON-Schema]
JSON Schema: A Media Type for Describing JSON Documents. OpenJS Foundation. URL: https://json-schema.org/specification.html
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[VC-DATA-INTEGRITY]
Verifiable Credential Data Integrity 1.0. David Longley; Manu Sporny. W3C Verifiable Credentials Working Group. Working Draft. URL: https://www.w3.org/TR/vc-data-integrity/
[VC-DATA-MODEL-2]
Verifiable Credentials Data Model v2.0. Manu Sporny; Dave Longley; Grant Noble; Dan Burnett; Ted Thibodeau; Brent Zundel; David Chadwick; Kyle Den Hartog. W3C Verifiable Credentials Working Group. Working Draft. URL: https://www.w3.org/TR/vc-data-model-2.0/
[VC-JWT]
Securing Verifiable Credentials using JSON Web Tokens. Orie Steele; Michael Jones; Michael Prorock. W3C. URL: https://www.w3.org/TR/vc-jwt/

A.2 Informative references

[URL]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[WCAG21]
Web Content Accessibility Guidelines (WCAG) 2.1. Andrew Kirkpatrick; Joshue O'Connor; Alastair Campbell; Michael Cooper. W3C. 5 June 2018. W3C Recommendation. URL: https://www.w3.org/TR/WCAG21/