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.

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 for an entity wanting 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

  • Design the Data Model.
  • Create the JSON-LD Context.
  • Select a publishing location.
  • Use the new JSON-LD Context.
  • 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 can 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.

    Cryptographic Suites

    COSE Signature Expression

    Use COSE to express signature values.

    COSE Key Expression

    Use COSE Web Keys to express key material.

    Hashlinks

    Use Hashlink URLs to provide content integrity for links to external resources.