Verifiable Credentials Implementation Guidelines 1.0

4.1 Core Data Model

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

4.2 Specific Verifiable Credentials

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

4.3 Content Integrity

Protecting the integrity of content is an important component of verification. Verifiers need to have confidence that the content they rely on to verify credentials doesn't change without their knowledge. This content may include data schemas, identifiers, public keys, etc.

There are a number of ways to provide content integrity protection. A few of these are described in greater detail below.

7.1 Creating New Credential Types

We expect the most common extensions to the Verifiable Credentials Data Model to be new credential types. Whenever someone has something to say about one or more entities and they want their authorship to be verifiable, they should use a Verifiable Credential. Sometimes there may be an existing credential type, that someone else has created, that can be reused to make the statements they want to make. However, there are often cases where new credential types are needed.

New credential types can be created by following a few steps. This guide will also walk you through creating an example new credential type. At a high level, the steps to follow are:

1. Design the data model.
2. Create a new JSON-LD context.
3. Select a publishing location.
4. Use the new JSON-LD context when issuing new credentials.

So, let's walk through creating a new credential type which we will call ExampleAddressCredential . The purpose of this credential will be to express a person's postal address.

Design the data model

First, we must design a data model for our new credential type. We know that we will need to be able to express the basics of a postal address, things like a person's city, state, and zipcode. Of course, those items are quite US centric, so we should consider internationalizing those terms. But before we go further, since we're using [LINKED-DATA] vocabularies, there is a good chance that commonly known concepts may already have a vocabulary that someone else has created that we can leverage.

If we are going to use someone else's vocabulary, we will want to make sure it is stable and unlikely to change in any significant way. There may even be technologies that we can make use of that store immutable vocabularies that we can reference, but those are not the focus of this example. Here we will rely on the inertia that comes from a very popularly used vocabulary on the Web, schema.org. It turns out that this vocabulary has just what we need; it has already modeled a postal address and even has examples for how to express it using JSON-LD.

Using the schema.org vocabulary and JSON-LD we can express a person's address like so:

{
  
  "@context": [
    "http://schema.org"
  ],
  "type": "Person",
  "address": {
    "type": "PostalAddress",
    "streetAddress": "123 Main St."
    "addressLocality": "Blacksburg",
    "addressRegion": "VA",
    "postalCode": "24060",
    "addressCountry": "US"
  }
}

Note the above @context key in the JSON. This @context refers to a machine-readable file (also expressed in JSON) that provides term definitions [JSON-LD]. A term definition maps a key or type used in the JSON, such as address or PostalAddress , to a globally unique identifier: a URL.

This ensures that when software sees the @context http://schema.org , that it will interpret the the keys and types in the JSON in a globally consistent way, without requiring developers to use full URLs in the JSON or in the code that may traverse it. As long as the software is aware of the specific @context used (or if it uses JSON-LD processing to transform it to some other known @context ), then it will understand the context in which the JSON was written and meant to be understood. The use of @context also allows [JSON-LD] keywords such as @type to be aliased to the simpler type as is done in the above example.

Note that we could also express the JSON using full URLs, if we want to avoid using @context . Here is what the example would look like if we did that:

{
  "@type": "http://schema.org/Person",
  "http://schema.org/address": {
    "@type": "http://schema.org/PostalAddress",
    "http://schema.org/streetAddress": "123 Main St."
    "http://schema.org/addressLocality": "Blacksburg",
    "http://schema.org/addressRegion": "VA",
    "http://schema.org/postalCode": "24060",
    "http://schema.org/addressCountry": "US"
  }
}

While this form is an acceptable way to express the information such that it is unambiguous, many software developers would prefer to use more idiomatic JSON. The use of @context enables idiomatic JSON without losing global consistency and without the need for a centralized registry or authority for creating extensions. Note that @context can also have more than one value. In this case, a JSON array is used to express multiple values, where each value references another context that defines terms. Using this mechanism we can first bring in the terms defined in the Verifiable Credentials Data Model specification and then bring in the terms defined by schema.org:

{
  
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "http://schema.org"
  ],
  ...
  "credentialSubject": {
    "type": "Person",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "123 Main St."
      "addressLocality": "Blacksburg",
      "addressRegion": "VA",
      "postalCode": "24060",
      "addressCountry": "US"
    }
  },
  ...
}

Note, however, that each context might have a different definition for the same term, e.g., the JSON key address might map to a different URL in each context . By default, [JSON-LD] allows terms in a @context to be redefined using a last term wins order. While these changes can be safely dealt with by using JSON-LD processing, we want to lower the burden on consumers of Verifiable Credentials. We want consumer software to be able to make assumptions about the meaning of terms by only having to read and understand the string value associated with the @context key. We don't want them to have to worry about terms being redefined in unexpected ways. That way their software can inspect only the @context values and then be hard coded to understand the meaning of the terms.

In order to prevent term redefinition, the [JSON-LD] @protected feature must be applied to term definitions in the @context . All terms in the core Verifiable Credentials @context are already protected in this way. The only time that an existing term is allowed to be redefined is if the new definition is scoped underneath another new term that is defined in a context . This matches developer expectations and ensures that consumer software has strong guarantees about the semantics of the data it is processing; it can be written such that it is never confused about the definition of a term. Note that consumers must determine their own risk profile for how to handle any credentials their software processes that include terms that it does not understand.

Create a new JSON-LD context

Given the above, there is at least one reason why we don't want to use the schema.org context : it is designed to be very flexible and thus does not use the @protected feature. There are a few additional reasons we want to create our own [JSON-LD] context though. First, the schema.org context does not define our new credential type: ExampleAddressCredential . Second, it is not served via a secure protocol (e.g., https ); rather, it uses http . Note that this is less of a concern than it may seem, as it is recommended that all Verifiable Credential consumer software hard code the @context values it understands and not reach out to the Web to fetch them. Lastly, it is a very large context, containing many more term definitions than are necessary for our purposes.

So, we will create our own [JSON-LD] context that expresses just those term definitions that we need for our new credential type. Note that this does not mean that we must mint new URLs; we can still reuse the schema.org vocabulary terms. All we are doing is creating a more concise and targeted context. Here's what we'll need in our context:

{
  "@version": 1.1,
  "@protected": true,
  "ExampleAddressCredential":
    "https://example.org/ExampleAddressCredential",
  "Person": {
    "@id": "http://schema.org/Person",
    "@context": {
      "@version": 1.1,
      "@protected": true,
      "address": "http://schema.org/address"
    }
  },
  "PostalAddress": {
    "@id": "http://schema.org/PostalAddress",
    "@context": {
      "@version": 1.1,
      "@protected": true,
      "streetAddress": "http://schema.org/streetAddress",
      "addressLocality": "http://schema.org/addressLocality",
      "addressRegion": "http://schema.org/addressRegion",
      "postalCode": "http://schema.org/postalCode",
      "addressCountry": "http://schema.org/addressCountry"
    }
  }
}

The above context defines a term for our new credential type ExampleAddressCredential , mapping it to the URL https://example.org/ExampleAddressCredential . We could have also chosen a URI like urn:private-example:ExampleAddressCredential , but this approach would not allow us to serve up a Web page to describe it, if we so desire. The context also defines the terms for types Person and PostalAddress , mapping them to their schema.org vocabulary URLs. Furthermore, when those types are used, it also defines protected terms for each of them via a scoped context , mapping terms like address and streetAddress to their schema.org vocabulary URLs. For more information on how to write a JSON-LD context or scoped contexts , see the [JSON-LD] specification.

Select a publishing location

Now that we have a [JSON-LD] context, we must give it a URL. Technically speaking, we could just use a URI, for example, a private URN such as urn:private-example:my-extension . However, if we want people to be able to read and discover it on the Web, we should give it a URL like https://example.org/example-address-credential-context/v1 .

When this URL is dereferenced, it should return application/ld+json by default, to allow JSON-LD processors to process the context. However, if a user agent requests HTML , it should return human readable text that explains, to humans, what the term definitions are and what they map to. Since we're reusing an existing vocabulary, schema.org, we can also simply link to the definitions of the meaning of our types and terms via their website. If we had created our own new vocabulary terms, we would describe them on our own site, ideally including machine readable Information as well.

Use the new JSON-LD context when issuing new credentials

Now we're ready for our context to be used by anyone who wishes to issue an ExampleAddressCredential !

{
  
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://example.org/example-address-credential-context/v1"
  ],
  "id": "https://example.org/credentials/1234",
  "type": "ExampleAddressCredential",
  "issuer": "https://example.org/people#me",
  "issuanceDate": "2017-12-05T14:27:42Z",
  "credentialSubject": {
    "id": "did:example:1234",
    "type": "Person",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "123 Main St."
      "addressLocality": "Blacksburg",
      "addressRegion": "VA",
      "postalCode": "24060",
      "addressCountry": "US"
    }
  },
  "proof": { ... }
}

Note that writing this new credential type requires permission from no one, you must only adhere to the above referenced standards.

7.2 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.

8.1 Benefits of JWTs

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.

PF1a: Proof format supports Zero-Knowledge Proofs.

JWTs can embed proof attributes for repudiable proofs such as Zero-Knowledge Proofs. In that case, the JWS will not have an signature element.

PF2a: Proof format supports arbitrary proofs such as Proof of Work, Timestamp Proofs, and Proof of Stake.

JWTs can embed proof attributes for any type of proofs such as Proof of Work, Timestamp, Proofs, and Proof Stake.

PF3a: Based on existing official standards.

JSON and JWT are proposed and mature IETF standards. While JSON-LD 1.0 is in REC state in W3C , JSON-LD 1.1 is still in WD state. LD-Proofs are not standardized at all.

PF4a: Designed to be small in size.

JSON was invented as a simple data format to be transmitted on the wire. A verifiable credential can be expressed by its attributes only, without the necessity to introduce additional meta-information such as @context. This makes the resulting JSON+JWT credential typically also smaller in size.

PF5a: Offline support without further processing.

A JWT can fully describe itself without the need to retrieve or verify any external documents. JSON-LD requires the context to be queryable and requires further documents to be accessible to check the prevalent document, e.g., LD-Proof. Additional caching needs to be implemented to support offline use cases.

PF6a: Wide adoption in other existing standards.

JWT founds its application in many other existing standards, e.g., OAuth2, OpenID Connect. This allows for backward compatibility with existing authentication and authorization frameworks without or with only minor modifications to these legacy systems.

PF7a: No type ambiguity.

It is best practice that JSON data structures typically do not expect changing types of their internal attributes. JSON-LD has implicit support for compact form serialization which transforms arrays with a single element only to switch its data type. Developers writing parsers have to implement special handling of these data types, which results in more code, is more error-prone and sometimes does not allow parsers based on code generation, which rely on static types.

PF8a: Broad library support.

JWT and JSON due to its maturity and standardization, have a lot of open-source library support. While JSON-LD 1.0 is a standard and has support for different programming languages, it is still behind JSON which is often part of the native platform toolchain, e.g., JavaScript. For LD-Proofs, on the other hand, only a few scattered libraries exist.

PF9a: Easy to understand what is signed.

JWT makes it visible what is signed in contrast to LD-Proofs, e.g., LD Signatures, that are detached from the actual payload and contain links to external documents which makes it not obvious for a developer to figure out what is part of the signature.

PF10a: Ability to be used as authn/authz token with existing systems.

Many existing applications rely on JWT for authentication and authorization purposes. In theory, developers maintaining these applications could leverage JWT-based verifiable presentations in their current systems with minor or no modifications. LD-Proofs represents a new approach which would require more work to achieve the same result.

PF11a: No additional canonicalization required.

Beyond base64 URL encoding JSON and JWT don't require any canonicalization to be transmitted on the wire. The JWS can be calculated on any data inside of the payload. This results in less computation, less complexity, and light-weight libraries compared to JSON-LD and LD-Proofs where canonicalization is required.

PF12a: No Internet PKI required.

JSON-LD and LD-Proofs rely on resolving external documents, e.g., @context . This means that a verifiable credential system would rely on existing Internet PKI to a certain extend and cannot be fully decentralized. A JWT-based system does not need to introduce this dependency.

PF13a: No resolution of external documents needed.

JSON-LD and LD-Proofs require the resolution of external documents, which leads to an increased network load for the verifier of a verifiable presentation. This needs to be mitigated through caching strategies.

8.2 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.

PF1b: 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.

PF2b: 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.

PF3b: 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").

PF4b: 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.

PF5b: 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.

PF6b: 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.

PF7b: 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.

PF8b: 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.

PF9b: 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.

PF10b: 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.

PF11b: 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.

PF12b: 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.

PF13b: 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.

PF14b: 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.

PF15b: 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.

PF16b: 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.

PF17b: 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.

PF18b: 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.

PF19b: Canonicalization requires only 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 requires 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.

10.1 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.

10.2 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:

• Atomic Credentials - These are verifiable credentials which consist of a single claim. An issuer may provide a set of atomic credentials that duplicates the claims of a standard credential. This atomicity allows a holder to disclose only those claims which need to be revealed to a verifier , rather than requiring all of the claims of a standard credential to be revealed.
• Selective Disclosure Signatures - Certain signature schemes natively support selective disclosure of verifiable credential claims. One example of these is Camenisch-Lysyanskaya signatures . Such Signatures allow a holder to disclose only those claims which need to be revealed to a verifier , rather than requiring all of the credential's claims to be revealed.

10.3 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 .

10.4 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.