Verifiable Credentials JSON Schema Specification

Draft Community Group Report,

This version:
https://w3c-ccg.github.io/vc-json-schemas/
Latest published version:
https://w3c-ccg.github.io/vc-json-schemas/
Issue Tracking:
GitHub
Editors:
(Transmute)
CG-DRAFT:
https://w3c-ccg.github.io/vc-json-schemas/
Tests:
vc json schema spec tests (ongoing work)

Abstract

The [VC_DATA_MODEL] specifies the models used for Verifiable Credentials and Verifiable Presentations, and explains the relationships between three parties: issuer, holder, and verifier. A critical piece of infrastructure out of the scope of those specifications is the Credential Schema. This specification provides a mechanism to express a Credential Schema and the protocols for evolving the schema.

Status of this document

1. Introduction

This specification provides a mechanism for the use of verifiable credentials in a highly scalable, secure, and verifiable way. A large part of the integrity of a verifiable credential is how to structure the credential so that all three parties — issuer, holder, verifier — may have a singular mechanism of trust into what they are using. We call that document a Credential Schema.

This specification provides a standardized way of creating Credential Schemas to be used in credentialing platforms, how to version them, and how to read them. 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.

2. Terminology

id

A locally unique identifier to locate the schema on a given data storage medium (e.g. a database, ledger, distributed file store). Each credential schema has its own unique identifier, and each version of a schema is required to have its own unique identifier.

This identifier is a Uniform Resource Identifier that may contain information pertaining to the author and version of the schema. For example, if the author had a DID like

did:example:abcdefghi
a possible schema ID the author created would have an identifier such as:
did:example:abcdefghi;id=17de181feb67447da4e78259d92d0240;version=1.0

Version and authorship may be useful to include in a schema identifier as they provide crucial information about the schema without forcing a lookup. Resovling the schema, however, is the recommended approach to gaining an authoritative information about a schema and its metadata.

Credential Schema

The data template for a credential. Refers to the entirety of a Credential Schema, including both the Metadata and JSON Schema. The term may refer to a document either with, or without a proof.

{
  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
  "version": "1.0",
  "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
  "name": "Email",
  "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2021-01-01T00:00:00+00:00",
  "schema": {
    "$id": "email-schema-1.0",
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "description": "Email",
    "type": "object",
    "properties": {
      "emailAddress": {
        "type": "string",
        "format": "email"
      }
    },
    "required": ["emailAddress"],
    "additionalProperties": false
  }
}
Metadata

Top-level information on a Credential Schema. Pieces of data wrapping the JSON Schema to provide further context about the schema.

{
  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
  "version": "1.0",
  "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db",
  "name": "Email",
  "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2021-01-01T00:00:00+00:00"
}
proof

A digital signature over the Credential Schema for the sake of claiming authorship. A piece of Metadata. Most often done using [Linked_Data_Proofs].

type

It is important in software systems for machines to understand the context of what a document is. In credential schemas this is declared in the type field. This field resolves to a JSON schema with details about the schema metadata that applies to the schema. A piece of Metadata.

version

Denotes the revision of a given Credential Schema.

name

A human-readable name for the schema. A piece of Metadata.

author

[DID] of the identity which authored the credential schema. A piece of Metadata.

authored

[RFC-3339] date on which the schema was created. A piece of Metadata.

JSON Schema

schema

schema

This is where the Credential Schema data fields are defined as a valid [JSON_SCHEMA]. A piece of Metadata.

{
    "$id": "email-schema-1.0",
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "description": "Email",
    "type": "object",
    "properties": {
        "emailAddress": {
            "type": "string",
            "format": "email"
        }
    },
    "required": ["emailAddress"],
    "additionalProperties": false
}
credential

Verifiable Credential

Verifiable Credential

See [VC_DATA_MODEL]

3. Standards & Compliance

The [VC_DATA_MODEL] specifies the models used for Verifiable Credentials and Verifiable Presentations, and while this spec attempts to align closely to the W3C model, it should NOT be assumed this specification is fully compliant at the time of this writing. Ultimately, we would like to comply with the W3C specification; however, due to the fact that the W3C specification is under active development and is subject to change, we have diverged from that model with several "forks" that are fully outlined in this specification.

4. Formatting

The [VC_DATA_MODEL] provides examples in the JSON Linked Data interchange format. The specification allows for other formats, such as standard JSON with JSON Schema but provides limited examples. In the credentialSchema section, JSON-SCHEMA-2018 validation is noted explicitly. This specification does not use [JSON-LD]. If it becomes evident that it would be useful to include [JSON-LD] or another format that decision would be made in a revisal draft at a later date.

The Verifiable Credentials data model relies heavily upon standard JSON with validation provided by [JSON_SCHEMA]. The data model embeds [JSON_SCHEMA] documents inside a larger document that contains useful metadata about a given credential schema.

5. Specification

5.1. Overview

The Credential Schema is a document that is used to guarantee the structure, and by extension the semantics, of the set of claims comprising a Verifiable Credential. A shared Credential Schema allows all parties to reference data in a known way.

A schema can be viewed from four perspectives: the author, issuer, verifier and holder.

Author: An author creates a schema as a blueprint for a verifiable credential, specifying the shape and format of the data in such a credential.

Issuer: Issuers utilize schemas to provide structure and meaning to the data they issue as verifiable credentials. By using schemas, issuers contribute to a credentialing ecosystem, and promote the use and adoption of data standards.

Verifier: A verifier requesting data needs to do so with knowledge of the credential shapes. Credential Schemas allow a Verifier to request data knowing that an issuer has generated a Credential in a well-known format, and that a holder can accurately respond to such a request.

Holder: Holders, or those who are the subject of credential issuance, can make sense of the data they own – values – by viewing it against a schema—keys. When data is requested from them by referencing a Credential Schema, this known structure allows the holder to return the data specifically requested by the verifier.

5.1.1. Guarantees

With adherance to the specification, the following guarantees can be made about a schema:

5.1.2. Storage

Credential Schemas are created and made available as immutable objects on any number of storage mediums such as a distributed ledger, traditional database, or decentralized file storage. The same schema may be replicated across multiple file stores with the same identifier. Immutability is key to enable consistent sources of truth for credential issuance. Schemas can evolve by creating new versions.

5.1.3. Versioning

Schemas are versioned via a version property. The version denotes the revision of a particular schema for a given storage medium.

Authors and Issuers care about versioning to track advancements and changes over time both for formatting changes (e.g. supporting [JSON_SCHEMA] draft-bhutton-json-schema-00 as opposed to Draft 7) as well as field changes (e.g. adding a new required field) as a schema evolves to its latest form. Holders care about versioning to know where and how their credential can be used. Similarly, Verifiers care about versioning to know which data, or schema versions they should accept in their systems.

Gudelines for versioning can be found in the Versioning Guidelines section of this document.

5.1.4. Processing

There is wide support for JSON Schema processing and [JSON_SCHEMA_IMPLMENTATIONS] can be found in many programming languages.

5.1.4.1. Acceptance

A system may choose to accept schemas based on multiple different criteria: storage location, authorship, identifier, version, etc.

The language by which a schema, or set of schemas are accepted by Credentialing Systems is out of scope of this document. It is advisable that such a language is flexible to accomodate important criterion of a schema, such as supporting version ranges with a common property, or enforcing authorship from a known author with a valid authentication mechanism (i.e. proof).

5.1.4.2. Validation

What determines the validity of a Credential is up to the verifier for that given Credential. Validity could mean a a valid proof, a valid proof and validation against a given schema, or other set of conditions.

Validation of a given Credential against its schema is to be performed according to the [JSON_SCHEMA_VALIDATION] specification.

5.2. Credential Schema Definition

This section provides the [JSON_SCHEMA] definition for Credential Schema along with an example of a Credential Schema for an Email Verifiable Credential.

JSON Schema

{
  "$id": "credential-schema-2.0",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "description": "JSON Schema for W3C Verifiable Credential JSON Schema",
  "type": "object",
  "properties": {
    "type": {
      "type": "string"
    },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+$"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "author": {
      "type": "string"
    },
    "authored": {
      "type": "string"
    },
    "schema": {
      "type": "object",
      "properties": {
        "$id": {
          "type": "string"
        },
        "$schema": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "properties": {
          "type": "object"
        },
        "required": {
          "type": "array",
          "items": [
            {
              "type": "string"
            }
          ]
        },
        "additionalProperties": {
          "type": "boolean"
        }
      },
      "required": [
        "$id",
        "$schema",
        "description",
        "type",
        "properties",
        "required",
        "additionalProperties"
      ]
    },
    "proof": {
      "type": "object"
    }
  },
  "required": [
    "type",
    "version",
    "id",
    "name",
    "author",
    "authored",
    "schema"
  ]
}

5.2.1. Metadata

The properties, in order, before the JSON Schema document, embedded into the JSON Schema are as follows:

  1. type

  2. version

  3. id

  4. name

  5. author

  6. authored

{
  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
  "version": "1.0",
  "id": "06e126d1-fa44-4882-a243-1e326fbe21db",
  "name": "Email",
  "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2021-01-01T00:00:00+00:00"
}

5.2.2. Schema

This is where the Credential Schema data fields are defined as a valid JSON Schema document.

{
 "$schema": "https://json-schema.org/draft/2019-09/schema",
 "description": "Email",
 "type": "object",
 "properties": {
   "emailAddress": {
       "type": "string",
       "format": "email"
   }
 },
 "required": ["emailAddress"],
 "additionalProperties": false
}

5.2.3. Proof

Any Credential Schema may be authenticated using [Linked_Data_Proofs].

Example and more detail needed.

6. Versioning Guidelines

This section applies to version properties of the metadata.

Versioning is defined as MODEL.REVISION where MODEL is a breaking change and REVISION is non-breaking. The version is contained within the schema identifier.

With schemas we are concerned with a new schema and backwards compatibility of existing data on an older schema.

MODEL Updating this number tells the end user that this version breaks the schema for ANY interaction with an older schema. For processing, if a holder presents a credential built from a schema with version 1.0, and the platform is looking for version 2.0, it is not able to parse ANY information.

REVISION Updating this number tells the end user that this version may prevent interactions with parts of the schema. For processing, if a holder presents a credential built from a schema with version 1.0 and the platform is looking for version 1.5, there are likely to be SOME fields incompatible with the expected credential.

6.1. Revision

The addition or removal of an optional field is what constitutes a REVISION. Adding or removing an optional field does not break historical data in a schema, and in a claims exchange protocol, missing optional fields can be ignored.

{
 "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
 "version": "1.0",
 "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
 "name": "Email",
 "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
 "authored": "2018-01-01T00:00:00+00:00",
 "schema": {
   "$id": "email-schema-1.0",
   "$schema": "https://json-schema.org/draft/2019-09/schema",
   "description": "Email",
   "type": "object",
   "properties": {
      "emailAddress": {
      "type": "string",
      "format": "email"
    }
   },
   "required": ["emailAddress"],
   "additionalProperties": false
 }
}

In this example we once again reference the email schema, but this time we add an optional field backupEmailAddress. Notice how this would not break the claims exchange because the field is optional.

{
 "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
 "version": "1.1",
 "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
 "name": "Email",
 "author": "did:example:abc123",
 "authored": "2018-01-01T00:00:00+00:00",
 "schema": {
   "$id": "email-schema-1.1",
   "$schema": "https://json-schema.org/draft/2019-09/schema",
   "description": "Email",
   "type": "object",
   "properties": {
    "emailAddress": {
      "type": "string",
      "format": "email"
    },
    "backupEmailAddress": {
      "type": "string",
      "format": "email"
    }
   },
   "required": ["emailAddress"],
   "additionalProperties": false
 }
}

6.2. Model

When a schema breaks backwards compatiblity it is considered a model change. The most common case of a MODEL change is the addition or subtraction of a required field. It is important to note that for the change of a key name on a required field constitutes a MODEL change as this introduces a breaking change, adding a required field.

An example of this rule is when the additionalProperties field’s value changes. Changing additionalProperties from false to true OR from true to false constitutes a breaking change, necessitating a MODEL increment.

{
 "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
 "version": "1.1",
 "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
 "name": "Email",
 "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
 "authored": "2018-01-01T00:00:00+00:00",
 "schema": {
   "$id": "email-schema-1.1",
   "$schema": "https://json-schema.org/draft/2019-09/schema",
   "description": "Email",
   "type": "object",
   "properties": {
    "emailAddress": {
      "type": "string",
      "format": "email"
    },
    "backupEmailAddress": {
      "type": "string",
      "format": "email"
    }
   },
   "required": ["emailAddress"],
   "additionalProperties": false
 }
}

This time our credentialing requirements for our email schema have changed and we need to attach a firstName for verification. This is a required field, so we know it is a MODEL change.

{
 "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
 "version": "2.0",
 "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=2.0",
 "name": "Email",
 "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
 "authored": "2018-01-01T00:00:00+00:00",
 "schema": {
   "$id": "email-schema-2.0",
   "$schema": "https://json-schema.org/draft/2019-09/schema",
   "description": "Email",
   "type": "object",
   "properties": {
    "emailAddress": {
      "type": "string",
      "format": "email"
    },
    "firstName": {
      "type": "string"
    },
    "backupEmailAddress": {
      "type": "string",
      "format": "email"
    }
   },
   "required": ["emailAddress", "firstName"],
   "additionalProperties": false
 }
}

7. Extensibility

By introducing a version field we allow the credential schema to become extensible. Properties such as derivedFrom could reference a schema that a new schema is built on top of. Similarly, platform-utility features such as searchability could be provided by adding a tags array that contains categorization and classification information for a schema.

These are just a few examples that illustrate the flexibility of the proposed model. It can be extended to support a wide variety of use-cases and make the burden on issuance and verification simpler by facilitating the development of higher-level tooling.

8. Examples

8.1. Verifiable Credentials

We define an Email schema as the basis for a credential.

{
  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json",
  "version": "1.0",
  "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
  "name": "Email",
  "author": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2021-01-01T00:00:00+00:00",
  "schema": {
    "$id": "email-schema-1.0",
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "description": "Email",
    "type": "object",
    "properties": {
      "emailAddress": {
        "type": "string",
        "format": "email"
      }
    },
    "required": ["emailAddress"],
    "additionalProperties": false
  }
}

The example references a Credential Schema with an identifier did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0 inside of a Verifiable Credential following the [VC_DATA_MODEL]. The example is adapted from Example 18 in the specification.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/1872",
  "type": ["VerifiableCredential", "EmailCredential"],
  "issuer": "https://example.com/issuers/565049",
  "issuanceDate": "2021-01-01T00:00:00Z",
  "credentialSchema": {
    "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
    "type": "JsonSchemaValidator2018"
  },
  "credentialSubject": {
    "id": "did:example:MDP8AsFhHzhwUvGNuYkX7T",
    "emailAddress": "first.last@example.com"
    }
  },
  "proof": { ... }
}

The ID of the Credential Schema is visible in the credentialSchema section of the credential, and provides information about the schema’s author and version. The type of JsonSchemaValidator2018 refers to a [JSON-LD] type providing information on how the data in the credentialSubject should be validated against the provided schema.

9. Drawbacks

Within a credentialing ecosystem, relying heavily upon [JSON_SCHEMA] makes data shapes for credentials consistent, and could enable an ecosystem with many similar schemas with slight changes (naming, capitalization). Without proper oversight or authoritative schemas to limit duplication or misuse, utilization of [JSON_SCHEMA] could lead to a poor user experience. At a higher, platform level tooling can be provided to minimize confusion and promote reuse.

Within the broader Credentialing Ecosystem, interoperability could be more difficult if the wider community adopts [JSON-LD] without advocating for pairing with [JSON_SCHEMA] based schemas or credentials. This issue can mainly be side-stepped with the metadata we include –– the Credential Schema –– since this model is flexible to change. A new version could be introduced that supports [JSON-LD] and removes support for [JSON_SCHEMA]. A drawback here is the requirement that all schemas have this piece of metadata, which itself is versioned and evolvable.

A flip side to drawbacks of the usage of [JSON_SCHEMA] is that there is a plethora of documentation, libraries, and usage of [JSON_SCHEMA] across programming languages and the web.

10. Alternatives

[JSON-LD] is the most prominent alternative, though it does not provide the same functionality in regards to strict data validation. It has been suggested that both [JSON_SCHEMA] and [JSON-LD] can work symbiotically in the credentialing ecosystem: [JSON-LD] providing semantic interoparability, and [JSON_SCHEMA] providing static validation.

11. Security & Privacy Considerations

Privacy & security considerations mainly revolve around Personally Identifiable Information (PII) leaks in schemas. Any field which a user could enter data is a potential area for personally identifiable information. When implementing systems that support the storage and querying of schemas relevant data privacy laws and regulations must be taken into account.

12. Interoperability

The primary concern of this specification is to facilitate an ecosystem in which Verifiable Credentials can be issued and used. To be interoperable, additional schema types may need to be supported. Given the investment into a robust versioning strategy of Credential Schema Metadata interoperability with the current design is less of a concern.

A goal of publishing this document is to promote others to adopt this schema philosophy. It also opens the door for providing feedback and collaborative contribution to developing primitives that would lead to a successful verifiable ecosystem.

Index

Terms defined by this specification

References

Informative References

[DID]
Decentralized Identifiers (DIDs) v1.0. URL: https://w3c.github.io/did-core/
[JSON-LD]
JSON-LD 1.1: A JSON-based Serialization for Linked Data. URL: https://w3c.github.io/json-ld-syntax/
[JSON_SCHEMA]
JSON Schema Bhutton Draft 00. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00
[JSON_SCHEMA_IMPLMENTATIONS]
JSON Schema Implementations. URL: https://json-schema.org/implementations.html
[JSON_SCHEMA_VALIDATION]
JSON Schema Validation: A Vocabulary for Structural Validation of JSON draft-bhutton-json-schema-validation-00. URL: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00
[Linked_Data_Proofs]
Linked Data Proofs 1.0. URL: https://w3c-ccg.github.io/ld-proofs/
[RFC-3339]
Date and Time on the Internet: Timestamps. URL: https://tools.ietf.org/html/rfc3339
[VC_DATA_MODEL]
Verifiable Credentials Data Model 1.0. URL: https://www.w3.org/TR/vc-data-model/