Verifiable Credentials JSON Schema Specification

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.

2. Terminology

id

A globally unique identifier to locate the schema on a distributed ledger. Each credential schema has its own unique identifier, and each version of a credential schema is required to have its own unique identifier.

This identifier is a Generic DID Parameter Name based upon the author of the schema. For example, if the author had a did like

did:work:abcdefghi

a possible schema ID the author created would have an identifier such as:

did:work:abcdefghi;id=17de181feb67447da4e78259d92d0240;version=1.0

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/1.0/schema.json",
  "modelVersion": "1.0",
  "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
  "name": "Email",
  "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2018-01-01T00:00:00+00:00"
}

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

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

proof: A digital signature over the Credential Schema for the sake of claiming authorship. A piece of Metadata.
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.
modelVersion: After a machine has parsed the type property it should know that the document it is reading is a Credential Schema. The next field is the version, which denotes what version of the schema metadata this is. A piece of Metadata.
schemaVersion: A version that applies to both the JSON Schema and Metadata. A piece of Metadata.
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.

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

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 its examples in the JSON Linked Data interchange format. The specification allows for other formats, such as standard JSON with JSON Schema but provides only limited examples. In the credentialSchema section, JSON-SCHEMA-2018 validation is explicitly called out. 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] Draft 7. 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 ask for data knowing that an issuer has issued in an understood way and that a holder’s wallet can find data matching that requested.

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’s wallet 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:

A schema is versionable and new versions can evolve it over time
A schema is available for any issuer to use and any verifier, or other platform member to read
A schema always guarantees the structure of a credential. The described structure can be used by the Verifier to understand what data the Holder holds. There is no requirement for the Verifier to validate sent data against the schema since this sent data may only be partial, for example in event of a proof request only requiring a single field from a credential with multiple fields defined in the schema.

5.1.2. Storage

Credential Schemas are created and made available as immutable objects on a distributed ledger. Among other benefits, this makes tie-in easier with [DID] authors.

5.1.3. Versioning

Schemas are versioned in two ways: modelVersion and schemaVersion properties. Versioning provides benefits for schema authors, issuers, and verifiers to make sense of their data.

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

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

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string"
    },
    "modelVersion": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "author": {
      "type": "string"
    },
    "authored": {
      "type": "string"
    },
    "schema": {
      "type": "object",
      "properties": {
        "$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": [
        "$schema",
        "description",
        "type",
        "properties",
        "required",
        "additionalProperties"
      ]
    },
    "proof": {
      "type": "object",
      "properties": {
        "created": {
          "type": "string"
        },
        "creator": {
          "type": "string"
        },
        "nonce": {
          "type": "string"
        },
        "signatureValue": {
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "required": [
        "created",
        "creator",
        "nonce",
        "signatureValue",
        "type"
      ]
    }
  },
  "required": [
    "type",
    "modelVersion",
    "name",
    "author",
    "authored",
    "schema",
    "proof"
  ]
}

Example

{
  "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
  "modelVersion": "1.0",
  "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
  "name": "EmailCredentialSchema",
  "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2018-01-01T00:00:00+00:00",
  "schema": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "description": "Email",
    "type": "object",
    "properties": {
      "emailAddress": {
        "type": "string",
        "format": "email"
      }
    },
    "required": ["emailAddress"],
    "additionalProperties": false
  },
  "proof": {
      "created": "2019-09-27T06:26:11Z",
      "creator": "did:work:MDP8AsFhHzhwUvGNuYkX7T#key-1",
      "nonce": "0efba23d-2987-4441-998e-23a9d9af79f0",
      "signatureValue": "2A7ZF9f9TWMdtgn57Y6dP6RQGs52xg2QdjUESZUuf4J9BUnwwWFNL8vFshQAEQF6ZFBXjYLYNU4hzXNKc3R6y6re",
      "type": "Ed25519VerificationKey2018"
  }
}

5.2.1. Metadata

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

type
modelVersion
id
schemaVersion
name
author
authored

5.2.2. Schema

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

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

5.2.3. Proof

Under construction.

6. Versioning Guidelines

This section applies to both schemaVersion and modelVersion 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 verification if a holder presents a credential built from a schema of version 1.0 and the platform is only looking for > 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 verification if a holder presents a credential built from a schema of version 1.0 and the platform is looking for > 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 the claims exchange protocol fields that are returned negative in the optional field can be ignored as they are optional by default.

{
 "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
 "modelVersion": "1.0",
 "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
 "name": "EmailCredentialSchema",
 "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
 "authored": "2018-01-01T00:00:00+00:00",
 "schema": {
   "$schema": "http://json-schema.org/draft-07/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/1.0/schema.json",
 "modelVersion": "1.0",
 "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
 "name": "EmailCredentialSchema",
 "author": "did:work:abc123",
 "authored": "2018-01-01T00:00:00+00:00",
 "schema": {
   "$schema": "http://json-schema.org/draft-07/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 historical data we call it a model change. This is the major differentiating point between other schema versioning protocols which allow for some breaking changes because as we learned in the problem section, even breaking one area can lead to very difficult issues for verifiers through the credential exchange protocol. The most common case of a MODEL change is the addition or subtraction of a required field. It is also important to note that for the change of a key name on a required field constitutes a MODEL change. Why? Because technically that introduces a breaking change and adds 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/1.0/schema.json",
 "modelVersion": "1.0",
 "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.1",
 "name": "EmailCredentialSchema",
 "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
 "authored": "2018-01-01T00:00:00+00:00",
 "schema": {
   "$schema": "http://json-schema.org/draft-07/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 email have changed and email address is no longer enough information on a credential, and we need to attach a name for verification as well to our schema. This is a required field, so we know it is a MODEL change.

{
 "type": "https://w3c-ccg.github.io/vc-json-schemas/schema/1.0/schema.json",
 "modelVersion": "1.0",
 "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=2.0",
 "name": "EmailCredentialSchema",
 "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
 "authored": "2018-01-01T00:00:00+00:00",
 "schema": {
   "$schema": "http://json-schema.org/draft-07/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 modelVersion 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/1.0/schema.json",
  "modelVersion": "1.0",
  "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
  "name": "Email",
  "author": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
  "authored": "2018-01-01T00:00:00+00:00"
}

The example references a Credential Schema with the Credential Schema identifier did:work: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": "2010-01-01T19:73:24Z",
  "credentialSchema": {
    "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T;id=06e126d1-fa44-4882-a243-1e326fbe21db;version=1.0",
    "type": "JsonSchemaValidator2018"
  },
  "credentialSubject": {
    "id": "did:work:MDP8AsFhHzhwUvGNuYkX7T",
    "emailAddress": "first.last@example.com"
    }
  },
  "proof": { ... }
}

The ID of the Credential Schema is visible in the credentialSchema section of the credential, and describes the shape of the email schema. 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 modelVersion 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 has been suggested that both [[JSON Schema]] and [JSON-LD] can work symbiotically in the credentialing ecosystem.

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 our 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 our schema philosophy. It also opens the door for providing feedback and collaborative contribution to developing primitives that would lead to a successful verifiable ecosystem.