This document provides implementation guidance for Verifiable Credentials.

Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-vc-comments@w3.org (subscribe, archives).

Introduction

This section is non-normative.

Welcome dear implementer of Verifiable Credentials! We understand that reading and nagivating technical specifications can be confusing at times. For this reason, we would like to offer you a few resources to get you started.

First, you should probably become familiarized with the official Use Cases document, which offers a concise but limited collection of use cases readers should review before undestanding how Verifiable Claims can best help them.

The data model specification is the most important result of two years of hard work done by the Verifiable Claims Working Group. However, the data model itself is not sufficient if you plan to use Verifiable Claims today. Additional works needs to be done on identifiers as well as on proofs, as you will be able to find out in the sections below.

Identifiers

This section is non-normative.

When expressing statements about a specific entity, such as a person, product, or organization, it is often useful to use some kind of identifier so that others can express statements about the same thing. You may have noticed that the VC Data Model specification contains numerous examples where the choice of identifier for the subject of the credential (the thing the claims are about) has been a decentralized identifier, also known as a DID. An example of a DID is did:example:123456abcdef.

As of the publication of the VC Data Model specification, DIDs are a new type of identifier that are not necessary for verifiable credentials to be useful. Specifically, verifiable credentials do not depend on DIDs and DIDs do not depend on verifiable credentials. However, it is expected that many verifiable credentials will use DIDs and that software libraries implementing the Data Model specification will probably need to resolve DIDs. DID-based URLs are used for expressing identifiers associated with subjects, issuers, holders, credential status lists, cryptographic keys, and other machine-readable information that is associated with a verifiable credential.

There is currently a proposed charter for a new Decentralized Identifier Working Group that has been submitted to the W3C, aiming to officially put DIDs on the standards track.

Proofs

This section is non-normative.

The VC Data Model is designed to be proof format agnostic. At the time of publication, at least two proof formats are being actively utilized by implementers -- JSON Web Token (JWT) and Linked Data Proofs. The Working Group felt that documenting in the spec what these proof formats are and how they are being used would be beneficial to implementers.

The table below compares three syntax and proof format ecosystems; JSON+JWTs, JSON-LD+JWTs, and JSON-LD+LD-Proofs. Implementers should be aware that Zero-Knowledge Proofs are currently proposed as a sub-type of LD-Proofs and thus fall into the final column below.

Feature JSON
+
JWTs
JSON‑LD
+
JWTs
JSON‑LD
+
LD‑Proofs
PF1. Support for open world data modelling.
PF2. Universal identifier mechanism for JSON objects via the use of URIs.
PF3. A way to disambiguate properties shared among different JSON documents by mapping them to IRIs via a context.
PF4. A mechanism to refer to data in an external document, where the data may be merged with the local document without a merge conflict in semantics or structure.
PF5. The ability to annotate strings with their language.
PF6. A way to associate arbitrary datatypes, such as dates and times, with arbitrary property values.
PF7. A facility to express one or more directed graphs, such as a social network, in a single document.
PF8. Supports signature sets.
PF9. Embeddable in HTML such that search crawlers will index the machine-readable content.
PF10. Data on the wire is easy to debug and serialize to database systems.
PF11. Nesting signed data does not cause data size to double for every embedding.
PF12. Proof format supports Zero-Knowledge Proofs.
PF13. Proof format supports arbitrary proofs such as Proof of Work, Timestamp Proofs, and Proof of Stake.
PF14. Proofs can be expressed unmodified in other data syntaxes such as YAML, N-Quads, and CBOR.
PF15. Signature is not invalidated by changes in whitespace or in the ordering of property-values.
PF16. Designed to easily support experimental signature systems.
PF17. Supports signature chaining.
PF18. Does not require pre-processing or post-processing.
PF19. Canonicalization does not require more than base-64 encoding.

Some of the features listed in the table above are debateable since a feature can always be added to a particular syntax or digital proof format. The table is intended to identify native features of each combination such that no additional language design or extension is required to achieve the identified feature. Features that all languages provide, such as the ability to express numbers, have not been included for the purposes of brevity.

PF1: Support for open world data modelling
An open world data model is one where any entity can make any statement about anything while simultaneously ensuring that the semantics of the statement are unambiguous. This specification is enabled by an open world data model called Linked Data. One defining characteristic of supporting an open world data model is the ability to specify the semantic context in which data is being expressed. JSON-LD provides this mechanism via the @context property. JSON has no such feature.
PF2: Universal identifier mechanism for JSON objects via the use of URIs.
All entities in a JSON-LD document are identified either via an automatic URI, or via an explicit URI. This enables all entities in a document to be unambiguously referenced. JSON does not have a native URI type nor does it require objects to have one, making it difficult to impossible to unambiguously identify an entity expressed in JSON.
PF3: A way to disambiguate properties shared among different JSON documents by mapping them to IRIs via a context.
JSON object properties are not mapped to IRIs, which result in ambiguities with respect to the semantic meaning of the property. For example, one JSON document can use "title" (meaning "book title") in a way that is semantically incompatible with another JSON document using "title" (meaning "job title"). In contrast, each object property in a JSON-LD document, such as the property "homepage", is either a keyword, an IRI, or a literal mapped to an IRI via a context. This feature enables open world systems to identify the semantic meaning of the property in an unambiguous way, which enables seamless merging of data between disparate systems.
PF4: A mechanism to refer to data in an external document, whereby the external data may be merged with the local document without a merge conflict in semantics or structure.
JSON-LD provides a mechanism that enables a data value to use a URL to refer to data outside of the local document. This external data may then be automatically merged with the local document without a merge conflict in semantics or structure. This feature enables a system to apply the "follow your nose" principle to discover a richer set of data that is associated with the local document. While a JSON document can contain pointers to external data, interpreting the pointer is often application specific and usually does not support merging the external data to construct a richer data set.
PF5: The ability to annotate strings with their language.
JSON-LD enables a developer to specify the language, such as English, French, or Japanese, in which a text string is expressed via the use of language tags. JSON does not provide such a feature.
PF6: A way to associate arbitrary datatypes, such as dates and times, with arbitrary property values.
JSON-LD enables a developer to specify the data type of a property value, such as Date, unsigned integer, or Temperature by specifying it in the JSON-LD Context. JSON does not provide such a feature.
PF7: A facility to express one or more directed graphs, such as a social network, in a single document.
JSON-LD's abstract data model supports the expression of information as a directed graph of labeled nodes and edges, which enables an open world data model to be supported. JSON's abstract data model only supports the expression of information as a tree of unlabeled nodes and edges, which restricts the types of relationships and structures that can be natively expressed in the language.
PF8: Supports signature sets.
A signature set is an unordered set of signatures over a data payload. Use cases, such as cryptographic signatures applied to a legal contract, typically require more than one signature to be associated with the contract in order to legally bind two or more parties under the terms of the contract. LD-Proofs, including LD-Signatures, natively support sets of signatures. JWTs only enable a single signature over a single payload.
PF9: Embeddable in HTML such that search crawlers will index the machine-readable content.
All major search crawlers natively parse and index information expressed as JSON-LD in HTML pages. LD-Proofs enable the current data format that search engines use to be extended to support digital signatures. JWTs have no mechanism to express data in HTML pages and are currently not indexed by search crawlers.
PF10: Data on the wire is easy to debug and serialize to database systems.
When developers are debugging software systems, it is beneficial for them to be able to see the data that they are operating on using common debugging tools. Similarly, it is useful to be able to serialize data from the network to a database and then from the database back out to the network using a minimal number of pre- and post-processing steps. LD-Proofs enable developers to use common JSON tooling without having to convert the format into a different format or structure. Payload information in JWTs is base-64 encoded, and requires complicated pre- and post-processing steps to convert the data into JSON data while not destroying the digital signature. Similarly, schema-less databases, which are typically used to index JSON data, cannot index information that is expressed in an opaque base-64 encoded wrapper.
PF11: Nesting signed data does not cause data size to double for every embedding.
When a JWT is encapsulated by another JWT, the entire payload must be base-64 encoded in the initial JWT, and then base-64 encoded again in the encapsulating JWT. This is often necessary when a cryptographic signature is required on a document that contains a cryptographic signature, such as when a Notary signs a document that has been signed by someone else seeking the Notary's services. LD-Proofs use an equally secure canonicalization process that requires only the cryptographic signature to be base-64 encoded; i.e., LD-Proofs do not require that the signed portion of a document also be base-64 encoded.
PF12: Proof format supports Zero-Knowledge Proofs.
The LD-Proof format is capable of specifying the algorithm (including as-yet-undefined algorithms) used to generate the hash or hashes that are cryptographically signed. This cryptographic agility enables digital signature systems, such as Zero-Knowledge Proofs, to be layered on top of LD-Proofs without requiring creation of an entirely new digital signature container format. Because of the way that JWTs are designed, an entirely new digital signature container format will be required for JWTs to support Zero-Knowledge Proofs.
PF13: Proof format supports arbitrary proofs such as Proof of Work, Timestamp Proofs, and Proof of Stake.
The LD-Proof format was designed with a broad range of proof types in mind and supports cryptographic proofs beyond simple cryptographic signatures. These proof types are in common use in systems such as decentralized ledgers and provide additional guarantees to verifiable credentials, such as the ability to prove that a particular claim was made at a particular time or that a certain amount of energy was expended to generate a particular credential. The JWT format does not support arbitrary proof formats.
PF14: Proofs can be expressed unmodified in other data syntaxes such as XML, YAML, N-Quads, and CBOR.
The LD-Proof format utilizes a canonicalization algorithm to generate a cryptographic hash that is used as an input to the cryptographic proof algorithm. This enables the bytes generated as the cryptographic proof to be compact and expressible in a variety of other syntaxes such as XML, YAML, N-Quads, and CBOR. JWTs are inextricably tied to the JSON syntax, because JWT generation requires the use of JSON.
PF15: Signature is not invalidated by changes in whitespace or in the ordering of property-values.
Since LD-Proofs utilize a canonicalization algorithm, changes in whitespace that does not change the meaning of the information being expressed has no effect on the final cryptographic hash over the information. This means that simple changes in whitespace formatting, such as those changes made when writing data to a schema-less database and then retrieving the same information from the same database do not cause the digital signature to fail. JWT payloads use base-64 encoding, which is changed by whitespace formatting though it has no effect on the information expressed. This makes it challenging to use JWTs to, for example, express signed data in web pages meant to be indexed by search engine crawlers.
PF16: Designed to easily support experimental signature systems.
The JWT format requires entries in a centralized registry through a formal international standards working group in order to avoid naming collisions, so it does not easily support experimental extensions. The LD-Proof format is naturally extensible, through the decentralized publication of cryptographic suites that are guaranteed to not conflict with other LD-Proof extensions. This approach enables LD-Proof developers to easily experiment with new cryptographic signature mechanisms that support selective disclosure, zero-knowledge proofs, post-quantum algorithms, and other innovations.
PF17: Supports signature chaining.
A signature chain is an ordered set of signatures over a data payload. Use cases, such as cryptographic signatures applied to a notarized document, typically require a signature by the signing party and then an additional one by a notary to be made after the original signing party has made their signature. LD-Proofs, including LD-Signatures, natively support chains of signatures. JWTs only enable a single signature over a single payload.
PF18: Does not require pre-processing or post-processing.
In order to encode a verifiable credential or a verifiable presentation in a JWT, an extra set of steps is required to convert the data to and from the JWT format. Such extra conversion steps are not required for verifiable credentials and verifiable presentations protected by LD-Proofs.
PF19: Canonicalization does not require more than base-64 encoding.
JWTs use a simple base-64 encoding to generate the cryptographic hash of the data. LD-Proofs require a more complex canonicalization algorithm to generate the cryptographic hash. The JWT approach simplifies implementation but reduces encoding flexibility. The LD-Proof approach increases encoding flexibility but complicates implementation.

Terminology

Verification

This section is non-normative.

TBD

Core Data Model

Conformant tooling that processes Verifiable Credentials will ensure that the core data model is verified when processing credentials.

Specific Verifiable Credentials

There are many data verification languages, the following approach is one that should work for most use cases.

Disputes

There are at least two different cases to consider where an entity wants to dispute a credential issued by an issuer:

The mechanism for issuing a DisputeCredential is the same as for a regular credential, except that the credentialSubject identifier in the DisputeCredential property is the identifier of the disputed credential.

For example, if a credential with an identifier of https://example.org/credentials/245 is disputed, an entity can issue one of the credentials shown below. In the first example, the subject might present this to the verifier along with the disputed credential. In the second example, the entity might publish the DisputeCredential in a public venue to make it known that the credential is disputed.

  {
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.com/credentials/123",
  "type": ["VerifiableCredential", "DisputeCredential"],
  "credentialSubject": {
    "id": "http://example.com/credentials/245",
    "currentStatus": "Disputed",
    "statusReason": {
      "@value": "Address is out of date",
      "@language": "en"
    },
  },
  "issuer": "https://example.com/people#me",
  "issuanceDate": "2017-12-05T14:27:42Z",
  "proof": { ... }
  }
        
  {
  "@context": "https://w3id.org/credentials/v1",
  "id": "http://example.com/credentials/321",
  "type": ["VerifiableCredential", "DisputeCredential"],
  "credentialSubject": {
    "id": "http://example.com/credentials/245",
    "currentStatus": "Disputed",
    "statusReason": {
      "@value": "Credential contains disputed statements",
      "@language": "en"
    },
    "disputedClaim": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "address": "Is Wrong"
    }
  },
  "issuer": "https://example.com/people#me",
  "issuanceDate": "2017-12-05T14:27:42Z",
  "proof": { ... }
  }
        

In the above verifiable credential, the issuer is claiming that the address in the disputed verifiable credential is wrong. For example, the subject might wrongly be claiming to have the same address as that of the issuer.

If a credential does not have an identifier, a content-addressed identifier can be used to identify the disputed credential. Similarly, content-addressed identifiers can be used to uniquely identify individual claims.

Extensions

This section is non-normative.

TBD

Creating New Credential Types

Human Readability

The JSON-LD Context declaration mechanism is used by implementations to signal the context in which the data transmission is happening to consuming applications:

          {
            
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "id": "http://example.edu/credentials/1872",
            ...
        

Extension authors are urged to publish two types of information at the context URLs. The first type of information is for machines, and is the machine-readable JSON-LD Context. The second type of information is for humans, and should be an HTML document. It is suggested that the default mode of operation is to serve the machine-readable JSON-LD Context as that is the primary intended use of the URL. If content-negotiation is supported, requests for text/html should result in a human readable document. The human readable document should at least contain usage information for the extension, such as the expected order of URLs associated with the @context property, specifications that elaborate on the extension, and examples of typical usage of the extension.

Cryptography

This section is non-normative.

Benefits of JWTs

This section will explain the benefits of using only JSON and JWTs as well as JSON-LD and JWTs.

Benefits of JSON-LD and LD-Proofs

The Verifiable Credentials Data Model is designed to be compatible with a variety of existing and emerging syntaxes and digital proof formats. Each approach has benefits and drawbacks. The following table is intended to summarize a number of these native trade-offs.

The table below compares three syntax and proof format ecosystems; JSON+JWTs, JSON-LD+JWTs, and JSON-LD+LD-Proofs. Readers should be aware that Zero-Knowledge Proofs are currently proposed as a sub-type of LD-Proofs and thus fall into the final column below.

Feature JSON
+
JWTs
JSON‑LD
+
JWTs
JSON‑LD
+
LD‑Proofs
PF1. Support for open world data modelling.
PF2. Universal identifier mechanism for JSON objects via the use of URIs.
PF3. A way to disambiguate properties shared among different JSON documents by mapping them to IRIs via a context.
PF4. A mechanism to refer to data in an external document, where the data may be merged with the local document without a merge conflict in semantics or structure.
PF5. The ability to annotate strings with their language.
PF6. A way to associate arbitrary datatypes, such as dates and times, with arbitrary property values.
PF7. A facility to express one or more directed graphs, such as a social network, in a single document.
PF8. Supports signature sets.
PF9. Embeddable in HTML such that search crawlers will index the machine-readable content.
PF10. Data on the wire is easy to debug and serialize to database systems.
PF11. Nesting signed data does not cause data size to double for every embedding.
PF12. Proof format supports Zero-Knowledge Proofs.
PF13. Proof format supports arbitrary proofs such as Proof of Work, Timestamp Proofs, and Proof of Stake.
PF14. Proofs can be expressed unmodified in other data syntaxes such as YAML, N-Quads, and CBOR.
PF15. Changing property-value ordering, or introducing whitespace does not invalidate signature.
PF16. Designed to easily support experimental signature systems.
PF17. Supports signature chaining.
PF18. Does not require pre-processing or post-processing.
PF19. Canonicalization requires more than base-64 encoding.

Some of the features listed in the table above are debateable, since a feature can always be added to a particular syntax or digital proof format. The table is intended to identify native features of each combination such that no additional language design or extension is required to achieve the identified feature. Features that all languages provide, such as the ability to express numbers, have not been included for the purposes of brevity.

PF1: Support for open world data modelling
An open world data model is one where any entity can make any statement about anything while simultaneously ensuring that the semantics of the statement are unambiguous. This specification is enabled by an open world data model called Linked Data. One defining characteristic of supporting an open world data model is the ability to specify the semantic context in which data is being expressed. JSON-LD provides this mechanism via the @context property. JSON has no such feature.
PF2: Universal identifier mechanism for JSON objects via the use of URIs.
All entities in a JSON-LD document are identified either via an automatic URI, or via an explicit URI. This enables all entities in a document to be unambiguously referenced. JSON does not have a native URI type nor does it require objects to have one, making it difficult to impossible to unambiguously identify an entity expressed in JSON.
PF3: A way to disambiguate properties shared among different JSON documents by mapping them to IRIs via a context.
All object properties in a JSON-LD document, such as the property "homepage", are either keywords or they are mapped to an IRI. This feature enables open world systems to identify the semantic meaning of the property in an unambiguous way, which enables seamless merging of data between disparate systems. JSON object properties are not mapped to IRIs, which result in ambiguities with respect to the semantic meaning of the property. For example, one JSON document might use "title" (meaning "book title") in a way that is semantically incompatible with another JSON document using "title" (meaning "job title").
PF4: A mechanism to refer to data in an external document, where the data may be merged with the local document without a merge conflict in semantics or structure.
JSON-LD provides a mechanism that enables a data value to use a URL to refer to data outside of the local document. This external data may then be automatically merged with the local document without a merge conflict in semantics or structure. This feature enables a system to apply the "follow your nose" principle to discover a richer set of data that is associated with the local document. While a JSON document can contain pointers to external data, interpreting the pointer is often application specific and usually does not support merging the external data to construct a richer data set.
PF5: The ability to annotate strings with their language.
JSON-LD enables a developer to specify the language, such as English, French, or Japanese, in which a text string is expressed via the use of language tags. JSON does not provide such a feature.
PF6: A way to associate arbitrary datatypes, such as dates and times, with arbitrary property values.
JSON-LD enables a developer to specify the data type of a property value, such as Date, unsigned integer, or Temperature by specifying it in the JSON-LD Context. JSON does not provide such a feature.
PF7: A facility to express one or more directed graphs, such as a social network, in a single document.
JSON-LD's abstract data model supports the expression of information as a directed graph of labeled nodes and edges, which enables an open world data model to be supported. JSON's abstract data model only supports the expression of information as a tree of unlabeled nodes and edges, which restricts the types of relationships and structures that can be natively expressed in the language.
PF8: Supports signature sets.
A signature set is an unordered set of signatures over a data payload. Use cases, such as cryptographic signatures applied to a legal contract, typically require more than one signature to be associated with the contract in order to legally bind two or more parties under the terms of the contract. Linked Data Proofs, including Linked Data Signatures, natively support sets of signatures. JWTs only enable a single signature over a single payload.
PF9: Embeddable in HTML such that search crawlers will index the machine-readable content.
All major search crawlers natively parse and index information expressed as JSON-LD in HTML pages. LD-Proofs enable the current data format that search engines use to be extended to support digital signatures. JWTs have no mechanism to express data in HTML pages and are currently not indexed by search crawlers.
PF10: Data on the wire is easy to debug and serialize to database systems.
When developers are debugging software systems, it is beneficial for them to be able to see the data that they are operating on using common debugging tools. Similarly, it is useful to be able to serialize data from the network to a database and then from the database back out to the network using a minimal number of pre and post processing steps. LD-Proofs enable developers to use common JSON tooling without having to convert the format into a different format or structure. JWTs base-64 encode payload information, resulting in complicated pre and post processing steps to convert the data into JSON data while not destroying the digital signature. Similarly, schema-less databases, which are typically used to index JSON data, cannot index information that is expressed in an opaque base-64 encoded wrapper.
PF11: Nesting signed data does not cause data size to double for every embedding.
When a JWT is encapsulated by another JWT, the entire payload must be base-64 encoded in the initial JWT, and then base-64 encoded again in the encapsulating JWT. This is often necessary when a cryptographic signature is required on a document that contains a cryptographic signature, such as when a Notary signs a document that has been signed by someone else seeking the Notary's services. LD-Proofs do not require base-64 encoding the signed portion of a document and instead rely on a canonicalization process that is just as secure, and that only requires the cryptographic signature to be encoded instead of the entire payload.
PF12: Proof format supports Zero-Knowledge Proofs.
The LD-Proof format is capable of modifying the algorithm that generates the hash or hashes that are cryptographically signed. This cryptographic agility enables digital signature systems, such as Zero-Knowledge Proofs, to be layered on top of LD-Proofs instead of an entirely new digital signature container format to be created. JWTs are designed such that an entirely new digital signature container format will be required to support Zero-Knowledge Proofs.
PF13: Proof format supports arbitrary proofs such as Proof of Work, Timestamp Proofs, and Proof of Stake.
The LD-Proof format was designed with a broader range of proof types in mind and supports cryptographic proofs beyond simple cryptographic signatures. These proof types are in common usage in systems such as decentralized ledgers and provide additional guarantees to verifiable credentials, such as the ability to prove that a particular claim was made at a particular time or that a certain amount of energy was expended to generate a particular credential. The JWT format does not support arbitrary proof formats.
PF14: Proofs can be expressed unmodified in other data syntaxes such as XML, YAML, N-Quads, and CBOR.
The LD-Proof format utilizes a canonicalization algorithm to generate a cryptographic hash that is used as an input to the cryptographic proof algorithm. This enables the bytes generated as the cryptographic proof to be compact and expressible in a variety of other syntaxes such as XML, YAML, N-Quads, and CBOR. Since JWTs require the use of JSON to be generated, they are inextricably tied to the JSON syntax.
PF15: Changing property-value ordering, or introducing whitespace does not invalidate signature.
Since LD-Proofs utilize a canonicalization algorithm, the introduction of whitespace that does not change the meaning of the information being expressed has no effect on the final cryptographic hash over the information. This means that simple changes in whitespace formatting, such as those changes made when writing data to a schema-less database and then retrieving the same information from the same database do not cause the digital signature to fail. JWTs encode the payload using the base-64 format which is not resistant to whitespace formatting that has no effect on the information expressed. This shortcoming of JWTs make it challenging to, for example, express signed data in web pages that search crawlers index.
PF16: Designed to easily support experimental signature systems.
The LD-Proof format is naturally extensible, not requiring the format to be extended in a formal international standards working group in order to prevent namespace collisions. The JWT format requires entries in a centralized registry in order to avoid naming collisions and does not support experimentation as easily as the LD-Proof format does. LD-Proof format extension is done through the decentralized publication of cryptographic suites that are guaranteed to not conflict with other LD-Proof extensions. This approach enables developers to easily experiment with new cryptographic signature mechanisms that support selective disclosure, zero-knowledge proofs, and post-quantum algorithms.
PF17: Supports signature chaining.
A signature chain is an ordered set of signatures over a data payload. Use cases, such as cryptographic signatures applied to a notarized document, typically require a signature by the signing party and then an additional one by a notary to be made after the original signing party has made their signature. Linked Data Proofs, including Linked Data Signatures, natively support chains of signatures. JWTs only enable a single signature over a single payload.
PF18: Does not require pre-processing or post-processing.
In order to encode a verifiable credential or a verifiable presentation in a JWT, an extra set of steps are required to convert the data to and from the JWT format. No such extra converstion step are required for verifiable credentials and verifiable presentations protected by LD-Proofs.
PF19: Canonicalization requires more than base-64 encoding.
The JWT format utilizes a simple base-64 encoding format to generate the cryptographic hash of the data. The encoding format for LD-Proofs require a more complex canonicalization algorithm to generate the cryptographic hash. The benefits of the JWT approach are simplicity at the cost of encoding flexibility. The benefits of the LD-Proof approach are flexibility at the cost of implementation complexity.

The Verifiable Credentials Data Model is designed to be compatible with a variety of existing and emerging digital proof formats. Each proof format has benefits and drawbacks. For instance, many proof formats cannot reveal selected attribute values in a verifiable credential; they can only reveal all (or none).

Zero-Knowledge Proofs (ZKPs) are a proof format that enables privacy-preserving and data-minimization features in verifiable presentations, such as selective disclosure and predicate proofs.

Selective disclosure is the ability of a holder to reveal a subset of the attributes of a verifiable credential in a verifiable presentation. A presentation based on zero-knowledge proof mechanisms only contains those attributes and associated values that are required to satisfy the presentation requirements.

Zero-knowledge predicate proofs are a type of proof associated with an attribute. Predicate proofs include comparisons, such as "greater than", "less than", "not equal", "range", "set membership", and "set non-membership". Predicate proofs can be constructed without requiring the issuer to create special fields, such as "age-under-18", "age-over-21", or "age-over-60", in the verifiable credential at the time the credential was issued. For example, if a holder has a credential with a "birth-date" claim, the holder can create a predicate proof based on "birth-date" in the verifiable presentation. A predicate value derived from "birth-date" in the verifiable credential can cryptographically prove to the verifier that the holder's age is greater (or less) than a specified number, without revealing the holder's "birth-date".

Verifiable credentials based on zero-knowledge proof mechanisms are also quantum-resistant after presentation.

A drawback of zero-knowledge proof mechanisms is that they are more complex and larger than some older signature schemes.

Cryptographic Suites

COSE Signature Expression

Use COSE to express signature values.

COSE Key Expression

Use COSE Web Keys to express key material.

Hashlinks

Hashlink URLs can be used to provide content integrity for links to external resources.

Progressive Trust

This section is non-normative.

Entities that use verifiable credentials and verifiable presentations should follow protocols that enable progressive trust. Progressive trust refers to enabling individuals to share information about themselves only on an as needed basis, slowing building up more trust as more information is shared with another party.

Progressive trust is strongly related to the principle of data minimization, and enabled by technologies such as selective disclosure and predicate proofs. We encourage the use of progressive trust as a guiding principle for implementers as they develop protocols for issuers, holders, and verifiers.

Data Minimization

Data minimization is a principle that encourages verifiers to request the minimum amount of data necessary from holders, and for holders to only provide the minimum amount of data to verifiers. This "minimum amount of data" depends on the situation and may change over the course of a holder's interaction with a verifier.

For example, a holder may apply for a loan, with a bank acting as the verifier. There are several points at which the bank may want to determine whether the holder is qualified to continue in the process of applying for the loan; for instance, the bank may have a policy of only providing loans to existing account holders. A protocol that follows the principle of data minimization would allow the holder to reveal to the verifier only that they are an existing account holder, before the bank requests any additional information, such as account balances or employment status. In this way, the applicant may progressively entrust the bank with more information, as the data needed by the bank to make its determinations is requested a piece at a time, as needed, rather than as a complete set, up front.

Selective Disclosure

Selective disclosure is the ability of a holder to select some elements of a verifiable credential to share with a verifier, without revealing the rest. There are several different methods which support selective disclosure, we provide two examples:

Predicates

Another technique which may be used to support progressive trust is to use predicates as the values of revealed claims. Predicates allow a holder to provide True/False values to a verifier rather than revealing claim values.

Predicate proofs may be enabled by verifiable credential issuers as claims, e.g., the credentialSubject may include an ageOver18 property rather than a birthdate property. This would allow holders to provide proof that they are over 18 without revealing their birthdates.

Certain signature types enable predicate proofs by allowing claims from a standard verifiable credential to be presented as predicates. For example, a Camenisch-Lysyanskaya signed verifiable credential that contains a credentialSubject with a birthdate property may be included in a verifiable presentation as a derived credential that contains an ageOver18 property.

Further Techniques

The examples provided in this section are intended to illustrate some possible mechanisms for supporting progressive trust, not provide an exhaustive or comprehensive list of all the ways progressive trust may be supported. Research in this area continues with the use of cutting-edge proof techniques such as zk-SNARKS and Bulletproofs, as well as different signature protocols.

A draft report by the Credentials Community Group on data minimization may also be useful reading for implementers looking to enable progressive trust.