Verifiable Credentials Data Model 1.0

Expressing verifiable information on the Web

W3C Candidate Recommendation

This version:
https://www.w3.org/TR/2019/CR-verifiable-claims-data-model-20190407/
Latest published version:
https://www.w3.org/TR/verifiable-claims-data-model/
Latest editor's draft:
https://w3c.github.io/vc-data-model/
Implementation report:
https://w3c.github.io/vc-test-suite/implementations/
Previous version:
https://www.w3.org/TR/2019/WD-verifiable-claims-data-model-20190208/
Editors:
Manu Sporny (Digital Bazaar)
Grant Noble (ConsenSys)
Daniel C. Burnett (ConsenSys)
Dave Longley (Digital Bazaar)
Authors:
Manu Sporny (Digital Bazaar)
Dave Longley (Digital Bazaar)
David Chadwick (University of Kent)
Participate:
GitHub w3c/vc-data-model
File a bug
Commit history
Pull requests

Abstract

Credentials are a part of our daily lives; driver's licenses are used to assert that we are capable of operating a motor vehicle, university degrees can be used to assert our level of education, and government-issued passports enable us to travel between countries. This specification provides a mechanism to express these sorts of credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable.

Status of This Document

This is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://w3c.github.io/vc-data-model/ for the Editor's draft.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

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

The Working Group seeks implementation feedback, having set the requirement of at least two implementations of each feature as the exit criteria for the Candidate Recommendation phase. The group aims to obtain reports from two producers and two consumers for each feature if possible. For details, see the test suite and sample implementation report.

The following features are considered at risk of removal due to potentially insufficient implementation experience (reports): credentialSchema property, refreshService property, evidence property, zero-knowledge proof support, disputedClaim property, JWT support, nonTransferable property.

Changes since the last publication of this document include:

This document was published by the Verifiable Claims Working Group as a Candidate Recommendation. This document is intended to become a W3C Recommendation.

GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-vc-comments@w3.org (archives).

W3C publishes a Candidate Recommendation to indicate that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than 23 April 2019.

Please see the Working Group's implementation report.

Publication as a Candidate Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

1. Introduction

This section is non-normative.

Credentials are a part of our daily lives; driver's licenses are used to assert that we are capable of operating a motor vehicle, university degrees can be used to assert our level of education, and government-issued passports enable us to travel between countries. These credentials provide benefits to us when used in the physical world, but their use on the Web continues to be elusive.

Currently it is difficult to express education qualifications, healthcare data, financial account details, and other sorts of third-party verified machine-readable personal information on the Web. The difficulty of expressing digital credentials on the Web makes it challenging to receive the same benefits through the Web that physical credentials provide us in the physical world.

This specification provides a standard way to express credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable.

For those unfamiliar with the concepts related to verifiable credentials, the following sections provide an overview of:

1.1 What is a Verifiable Credential?

This section is non-normative.

In the physical world, a credential might consist of:

A verifiable credential can represent all of the same information that a physical credential represents. The addition of technologies, such as digital signatures, makes verifiable credentials more tamper-evident and more trustworthy than their physical counterparts. Holders of verifiable credentials can generate presentations and then share these presentations with verifiers to prove they possess verifiable credentials with certain characteristics. Both verifiable credentials and verifiable presentations can be transmitted rapidly, making them more convenient than their physical counterparts when trying to establish trust at a distance.

While this specification attempts to improve the ease of expressing digital credentials, it also attempts to balance this goal with a number of privacy-preserving goals. The persistence of digital information, and the ease with which disparate sources of digital data can be collected and correlated, comprise a privacy concern that the use of verifiable and easily machine-readable credentials threatens to make worse. This document outlines and attempts to address a number of these issues in Section § 7. Privacy Considerations. Examples of how to use this data model using privacy-enhancing technologies, such as zero-knowledge proofs, are also provided throughout this document.

1.2 Ecosystem Overview

This section is non-normative.

This section describes the roles of the core actors and the relationships between them in an ecosystem where verifiable credentials are expected to be useful. A role is an abstraction that might be implemented in many different ways. The separation of roles suggests likely interfaces and protocols for standardization. The following roles are introduced in this specification:

holder
A role an entity might perform by possessing one or more verifiable credentials and generating presentations from them. Example holders include students, employees, and customers.
issuer
A role an entity might perform by creating a verifiable credential, associating it with a specific subject, and transmitting it to a holder. Example issuers include corporations, non-profit organizations, trade associations, governments, and individuals.
subject
A role an entity might perform by having one or more verifiable credentials asserted about it. Example subjects include human beings, animals, and things. While in many cases the holder of a verifiable credential is the subject, in certain cases it is not. For example, a parent (the holder) might hold the verifiable credentials of a child (the subject), or a pet owner (the holder) might hold the verifiable credentials of their pet (the subject). For more information about these special cases, see Appendix § B. Subject-Holder Relationships
verifier
A role an entity might perform by requesting and receiving a verifiable presentation that proves the holder possesses the required verifiable credentials with certain characteristics. Example verifiers include employers, security personnel, and websites.
verifiable data registry
A role a system might perform by mediating the creation and verification of identifiers, keys, and other relevant data, such as verifiable credential schemas and revocation registries, which might be required to use verifiable credentials. Some configurations might require correlatable identifiers for subjects. Example verifiable data registries include trusted databases, decentralized databases, government ID databases, and distributed ledgers. Often there is more than one type of verifiable data registry utilized in an ecosystem.
diagram showing how
	       credentials flow from issuer to holder and
	       presentations flow from holder to verifier where all
	       three parties can use information from a logical
	       verifiable data registry
Figure 1 The roles and information flows forming the basis for this specification.
Note

The ecosystem above is provided as an example to ground the rest of the concepts in this specification. Other ecosystems exist, such as protected environments or proprietary systems, where verifiable credentials also provide benefit.

1.3 Use Cases and Requirements

This section is non-normative.

The Verifiable Credentials Use Cases [VC-USECASES] document outlines a number of key topics that readers might find useful, including:

As a result of documenting and analyzing the use cases document, the following desirable ecosystem characteristics were identified for this specification:

1.4 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, RECOMMENDED, and SHOULD are to be interpreted as described in [RFC2119].

A conforming document is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections § 4. Basic Concepts, § 5. Advanced Concepts, and § 6. Syntaxes of this document MUST be enforced.

A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming document. Conforming processors MUST produce errors when non-conforming documents are consumed.

This specification makes no normative statements with regard to the conformance of roles in the ecosystem, such as issuers, holders, or verifiers, because the conformance of ecosystem roles are highly application, use case, and market vertical specific.

2. Terminology

This section is non-normative.

The following terms are used to describe concepts in this specification.

claim
An assertion made about a subject.
credential
A set of one or more claims made by an issuer. A verifiable credential is a tamper-evident credential that has authorship that can be cryptographically verified. Verifiable credentials can be used to build verifiable presentations, which can also be cryptographically verified. The claims in a credential can be about different subjects.
data minimization
The act of limiting the amount of shared data strictly to the minimum necessary in order to successfully accomplish a task or goal.
decentralized identifier
A portable URL-based identifier, also known as a DID, associated with an entity. These identifiers are most often used in a credential and are associated with subjects such that a credential itself can be easily ported from one repository to another without the need to reissue the credential. An example of a DID is did:example:123456abcdef.
decentralized identifier document
A document that is accessible using an verifiable data registry and contains information related to a specific decentralized identifier, such as the associated repository and public key information.
derived predicate
A verifiable, boolean assertion about the value of another attribute in a verifiable credential. These are useful in zero-knowledge-proof-style presentations because they can limit information disclosure. For example, if a verifiable credential contains an attribute for expressing a specific height in centimeters, a derived predicate might reference the height attribute in the credential demonstrating that the issuer attests to a height value meeting the minimum height requirement, without actually disclosing the specific height value. For example, the subject is taller than 150 centimeters.
digital signature
A mathematical scheme for demonstrating the authenticity of a digital message.
entity
A thing with distinct and independent existence, such as a person, organization, concept, or device. An entity can perform one or more roles in the ecosystem.
graph
A network of information composed of subjects and their relationship to other subjects or data.
holder
A role an entity can perform by possessing one or more verifiable credentials. A holder is usually, but not always, the subject of the verifiable credentials they are holding. Holders store their credentials in credential repositories.
identity
The means for keeping track of entities across contexts. Digital identities enable tracking and customization of entity interactions across digital contexts, typically using identifiers and attributes. Unintended distribution or use of identity information can compromise privacy. Collection and use of such information should follow the principle of data minimization.
identity provider
An identity provider, sometimes abbreviated as IdP, is a system for creating, maintaining, and managing identity information for holders, while providing authentication services to relying party applications within a federation or distributed network. In this case the holder is always the subject. Even if the credentials are bearer credentials, it is assumed the credentials remain with the subject, and if they are not, they were stolen by an attacker. This specification does not use this term unless comparing or mapping the concepts in this document to other specifications. This specification decouples the identity provider concept into two distinct concepts: the issuer and the holder.
issuer
A role an entity might perform by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder.
presentation
Data derived from one or more credentials, issued by one or more issuers, that is shared with a specific verifier. A verifiable presentation is a tamper-evident presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. Certain types of verifiable presentations might contain data that is synthesized from, but do not contain, the original verifiable credentials (for example, zero-knowledge proofs).
repository
A program, such as a storage vault or personal verifiable credential wallet, that stores and protects access to holder credentials.
selective disclosure
The ability enabling a holder to decide what information to share with fine-grained precision.
subject
An entity about which claims are made.
user agent
A program, such as a browser or other Web client, that mediates the communication between holders, issuers, and verifiers.
validation
The assurance that a verifiable credential or a verifiable presentation meets the needs of a verifier and other dependent stakeholders. This specification is constrained to verifying verifiable credentials and verifiable presentations regardless of their usage. Validating verifiable credentials or verifiable presentations is outside the scope of this specification.
verifiable data registry
A role a system might perform by mediating the creation and verification of subject identifiers, verifiable credential schemas, revocation registries, issuer public keys, and so on. Some registries, such as ones for UUIDs and public keys, just act as namespaces for identifiers.
verification
The evaluation of whether or not a verifiable credential or verifiable presentation complies with this specification.
verifier
A role an entity might perform by receiving one or more verifiable presentations for processing. Other specifications might refer to this concept as a relying party.
URI
An identifier as defined by [RFC3986].

3. Core Data Model

This section is non-normative.

The following sections outline core data model concepts, such as claims, credentials, and presentations, which form the foundation of this specification.

3.1 Claims

This section is non-normative.

A claim is a statement about a subject. A subject is an entity about which claims can be made. Claims are expressed using subject-property-value relationships.

subject has a property which
            has a value
Figure 2 The basic structure of a claim.

The data model for claims described above is powerful and can be used to express a large variety of statements. For example, whether someone graduated from a particular university can be expressed as shown below.

Pat has an alumniOf
            property whose value is Example University
Figure 3 A basic claim expressing that Pat is an alumni of "Example University".

Individual claims can be merged together to express a graph of information about a subject. The example below extends the previous claim by adding the claims that Pat knows Sam and that Sam is employed as a professor.

extends previous
            diagram with another property called knows whose value is
            Sam, and Sam has a property jobTitle whose value is Professor
Figure 4 Multiple claims can be combined to express a graph of information.

To this point, the concepts of a claim and a graph of information are introduced. To be able to trust claims, more information must be added.

3.2 Credentials

This section is non-normative.

A credential is a set of one or more claims made by the same entity. Credentials might also include an identifier and metadata to describe properties of the credential, such as the issuer, the expiry date and time, a representative image, a public key to use for verification purposes, the revocation mechanism, and so on. The metadata might be signed by the issuer. A verifiable credential is a set of tamper-evident claims and metadata that cryptographically prove who issued it.

a Verifible
	       Credential contains Credential Metadata, Claim(s), and
	       Proof(s)
Figure 5 Basic components of a verifiable credential.

Examples of verifiable credentials include digital employee identification cards, digital birth certificates, and digital educational certificates.

Note

Credential identifiers are often used to identify specific instances of a credential. These identifiers can also be used for correlation. A holder wanting to minimize correlation is advised to use a selective disclosure scheme that does not reveal the credential identifier.

Figure 5 above shows the basic components of a verifiable credential, but abstracts the details about how claims are organized into information graphs, which are then organized into verifiable credentials. Figure 6 below shows a more complete depiction of a verifiable credential, which is normally composed of at least two information graphs. The first graph expresses the credential itself, which contains credential metadata and claims. The second graph expresses the digital proof, which is usually a digital signature.

diagram with a
	       Credential Graph on top connected via a proof to a
	       Proof Graph on the bottom.  The Credental Graph has
	       Credential 123 with 4 properties: 'type' of value
	       AlumniCredential, 'issuer' of Example University,
	       'issuanceDate' of 2010-01-01T19:73:24Z, and
	       credentialSubject of Pat, who has an alumniOf property
	       with value of Example University.  The Proof Graph has
	       Signature 456 with 5 properties: 'type' of
	       RsaSignature2018, 'creator' of Example University
	       Public Key 7, 'created' of 2017-06-18T21:19:10Z,
	       'nonce' of 348dj239dsj328, and 'signatureValue' of
	       BavEll0...3JT24=
Figure 6 Information graphs associated with a basic verifiable credential.
Note

It is possible to have a credential, such as a marriage certificate, containing multiple claims about different subjects that are not required to be related.

3.3 Presentations

This section is non-normative.

Enhancing privacy is a key design feature of this specification. Therefore, it is important for entities using this technology to be able to express only the portions of their persona that are appropriate for a given situation. The expression of a subset of one's persona is called a verifiable presentation. Examples of different personas include a person's professional persona, their online gaming persona, their family persona, or an incognito persona.

A verifiable presentation expresses data from one or more verifiable credentials, and is packaged in such a way that the authorship of the data is verifiable. If credentials are directly presented, they become a presentation. Data formats derived from credentials that are cryptographically verifiable but do not of themselves contain credentials, might also be presentations.

The data in a presentation is often about the same subject, but was issued by multiple issuers. The aggregation of this information typically expresses an aspect of a person, organization, or entity.

A Verifiable
            Presentation contains Presentation Metadata, Verifiable
            Credential(s), and Proof(s)
Figure 7 Basic components of a verifiable presentation.

Figure 7 above shows the components of a verifiable presentation, but abstracts the details about how verifiable credentials are organized into information graphs, which are then organized into verifiable presentations. Figure 8 below shows a more complete depiction of a verifiable presentation, which is normally composed of at least four information graphs. The first graph expresses the presentation itself, which contains presentation metadata. The verifiablePresentation property in the graph refers to one or more verifiable credentials (each a self-contained graph), which in turn contains credential metadata and claims. The third graph expresses the credential graph proof, which is usually a digital signature. The fourth graph expresses the presentation graph proof, which is usually a digital signature.

diagram with
	       a Presentation Graph on top connected via a proof to a
	       Presentation Proof Graph on the bottom.  The
	       Presentation Graph has Presentation ABC with 3
	       properties: 'type' of value VerifiablePresentation,
	       'termsOfUse' of value Do Not Archive, and
	       'verifiableCredential' whose value is Figure 6.  The
	       Presentation Proof Graph has Signature 8910 with 5
	       properties: 'type' of RsaSignature2018, 'creator' of
	       Example Presenter Public Key 11, 'created' of
	       2018-01-15T12:43:56Z, 'nonce' of d28348djsj3239, and
	       'signatureValue' of p2KaZ...8Fj3K=
Figure 8 Information graphs associated with a basic verifiable presentation.
Note

It is possible to have a presentation, such as a business persona, which draws on multiple credentials about different subjects that are often, but not required to be, related.

3.4 Concrete Lifecycle Example

This section is non-normative.

The previous sections introduced the concepts of claims, credentials, and presentations using graphical depictions. This section provides a concrete set of simple but complete lifecycle examples of the data model expressed in one of the concrete syntaxes supported by this specification. The lifecycle of credentials and presentations in the Verifiable Credentials Ecosystem often take a common path:

  1. Issuance of one or more verifiable credentials.
  2. Storage of verifiable credentials in a credential repository (such as a digital wallet).
  3. Composition of verifiable credentials into a verifiable presentation for verifiers.
  4. Verification of the verifiable presentation by the verifier.

We will use concrete examples to illustrate the lifecycle above by demonstrating how to redeem an alumni discount from a university. In the example below, Pat receives an alumni credential from a university that will be stored in Pat's digital wallet.

Example 1: A simple example of a verifiable credential
{
  // set the context, which establishes the special terms we will be using
  // such as 'issuer' and 'alumniOf'.
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  // specify the identifier for the credential
  "id": "http://example.edu/credentials/1872",
  // the credential types, which declare what data to expect in the credential
  "type": ["VerifiableCredential", "AlumniCredential"],
  // the entity that issued the credential
  "issuer": "https://example.edu/issuers/565049",
  // when the credential was issued
  "issuanceDate": "2010-01-01T19:73:24Z",
  // claims about the subject of the credential
  "credentialSubject": {
    // identifier for the subject of the credential
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    // assertion about the subject of the credential
    "alumniOf": "<span lang='en'>Example University</span>"
  },
  // digital proof that makes the credential tamper-evident
  "proof": {
    // the cryptographic signature suite that was used to generate the signature
    "type": "RsaSignature2018",
    // the date the signature was created
    "created": "2017-06-18T21:19:10Z",
    // the public key identifier that created the signature
    "creator": "https://example.edu/issuers/keys/1",
    // the digital signature value
    "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
      sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
      X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
      PAYuNzVBAh4vGHSrQyHUdBBPM"
  }
}

Pat then presents the alumni credential above in order to receive a discount. The verifier, a ticket sales system, states that any alumni of "Example University" receives a discount on season tickets to sporting events. Using a mobile device, Pat starts the process of purchasing a season ticket. A step in the process requests an alumni credential and the request is routed to Pat's digital wallet. The digital wallet asks Pat if they would like to provide the previously issued verifiable credential. Pat selects the verifiable credential, which is then composed into a verifiable presentation. The verifiable presentation is then sent to the verifier and verified.

Example 2: A simple example of a verifiable presentation
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "type": "VerifiablePresentation",
  // the verifiable credential issued in the previous example
  "verifiableCredential": [{
    "id": "http://example.edu/credentials/1872",
    "type": ["VerifiableCredential", "AlumniCredential"],
    "issuer": "https://example.edu/issuers/565049",
    "issuanceDate": "2010-01-01T19:73:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "alumniOf": "<span lang='en'>Example University</span>"
    },
    "proof": {
      "type": "RsaSignature2018",
      "created": "2017-06-18T21:19:10Z",
      "creator": "https://example.edu/issuers/keys/1",
      "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
        sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
        X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
        PAYuNzVBAh4vGHSrQyHUdBBPM"
    }
  }],
  // digital signature by Pat on the presentation establishes consent and
  // protects against replay attacks
  "proof": {
    "type": "RsaSignature2018",
    "created": "2018-09-14T21:19:10Z",
    "creator": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1",
    // 'nonce' and 'domain' protect against replay attacks
    "nonce": "1f44d55f-f161-4938-a659-f8026467f126",
    "domain": "4jt78h47fh47",
    "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..kTCYt5
      XsITJX1CxPCT8yAV-TVIw5WEuts01mq-pQy7UJiN5mgREEMGlv50aqzpqh4Qq_PbChOMqs
      LfRoPsnsgxD-WUcX16dUOqV0G_zS245-kronKb78cPktb3rk-BuQy72IFLN25DYuNzVBAh
      4vGHSrQyHUGlcTwLtjPAnKb78"
  }
}

4. Basic Concepts

This section introduces some basic concepts for the specification, in preparation for Section § 5. Advanced Concepts later in the document.

4.1 Contexts

When two software systems need to exchange data, they must use terminology and a protocol that both systems understand. As an analogy, consider how two people communicate. Both people must use the same language and the words they use must mean the same thing to each other. This is often referred to as "the context in which a conversation happens". This specification defines the use of the @context property when communicating information related to specific verifiable credentials or verifiable presentations. Verifiable credentials and verifiable presentations MUST include a @context property.

@context
The value of the @context property MUST be an ordered set where the first item is a URI with the value https://www.w3.org/2018/credentials/v1. Subsequent items in the array MUST be composed of any combination of URIs or objects that express context information. It is RECOMMENDED that dereferencing the URIs results in a document containing machine-readable information about the context.
Example 3: Usage of the @context property
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/58473",
  "type": ["VerifiableCredential", "AlumniCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "alumniOf": "<span lang='en'>Example University</span>"
  },
  "proof": { ... }
}

The example above uses the base context URI (https://www.w3.org/2018/credentials/v1) to establish that the conversation is about a verifiable credential. The second URI (https://www.w3.org/2018/credentials/examples/v1) establishes that the conversation is about examples.

Note

This document uses the examples context URI (https://www.w3.org/2018/credentials/examples/v1) for the purposes of demonstrating examples. The examples context URI MUST NOT be used for any other purpose, such as in pilot or production systems.

The data available at https://www.w3.org/2018/credentials/v1 is a static document that is never updated and SHOULD be downloaded and cached. The associated human-readable vocabulary document for the Verifiable Credentials Data Model is available at https://www.w3.org/2018/credentials. This concept is further expanded on in Section § 5.3 Extensibility.

Issue 1

The specific location and content in the JSON-LD Context URLs used throughout this document may change during the W3C Candidate Recommendation phase based on implementer feedback. The test suite will reflect any changes to the URLs or content located at the URLs.

4.2 Identifiers

When expressing statements about a specific thing, 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. Identifiers that others are expected to use when expressing statements about a specific thing MUST be expressed using the id property.

Note

Developers should remember that identifiers might be harmful in scenarios where pseudonymity is required. Developers are encouraged to read Section § 7. Privacy Considerations carefully when considering such scenarios. Where privacy is a strong consideration, the id property MAY be omitted.

id
The value of the id property MUST be a single URI. It is RECOMMENDED that dereferencing the URI results in a document containing machine-readable information about the identifier.
Example 4: Usage of the id property
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "proof": { ... }
}

The example above uses two types of identifiers. The first identifier is for the credential and uses an HTTP-based URL. The second identifier is for the subject of the credential (the thing the claims are about) and uses a decentralized identifier, also known as a DID.

Note

As of this publication, 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 this 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.

4.3 Types

Software systems that process the kinds of objects specified in this document use type information to determine whether or not a provided credential or presentation is appropriate. This specification defines a type property for the expression of type information. Verifiable credentials and verifiable presentations MUST have a type property.

type
The value of the type property MUST be, or map to, one or more URIs. If more than one URI is provided, the URIs MUST be interpreted as an unordered set. Syntactic conveniences, such as JSON-LD terms, SHOULD be used to ease developer usage. It is RECOMMENDED that dereferencing the URIs results in a document containing machine-readable information about the type.
Example 5: Usage of the type property
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "proof": { ... }
}

With respect to this specification, the following table lists examples of objects that MUST have a type specified.

Object Type
Credential object VerifiableCredential and a more specific credential type. For example,
"type": ["VerifiableCredential", "UniversityDegreeCredential"]
Presentation object VerifiablePresentation and a more specific presentation type. For example,
"type": ["VerifiablePresentation", "CredentialManagerPresentation"]
proof object A valid proof type. For example,
"type": "RsaSignature2018"
credentialStatus object A valid credential status type. For example,
"type": "CredentialStatusList2017"
termsOfUse object A valid terms of use type. For example,
"type": "OdrlPolicy2017")
evidence object A valid evidence type. For example,
"type": "DocumentVerification2018"

All credentials, presentations, and encapsulated objects MUST specify, or be associated with, additional more narrow types (like UniversityDegreeCredential, for example) so software systems can process this additional information.

When processing encapsulated objects defined in this specification, (for example, objects associated with the credentialSubject object or deeply nested therein), software systems SHOULD use the type information specified in encapsulating objects higher in the hierarchy. Specifically, an encapsulating object, such as credential, SHOULD convey the associated object types so that verifiers can quickly determine the contents of an associated object based on the encapsulating object type.

For example, a credential object with the type of UniversityDegreeCredential, signals to a verifier that the object associated with the credentialSubject property contains the identifier for the:

This enables implementers to rely on values associated with the type property for verification purposes. The expectation of types and their associated properties should be documented in at least a human-readable specification, and preferably, in an additional machine-readable representation.

Note

The type system for the Verifiable Credentials Data Model is the same as for [JSON-LD] and is detailed in Section 5.4: Specifying the Type and Section 8: JSON-LD Grammar. When using a JSON-LD context (see Section § 5.3 Extensibility), this specification aliases the @type keyword to type to make the JSON-LD documents more easily understood. While application developers and document authors do not need to understand the specifics of the JSON-LD type system, implementers of this specification who want to support interoperable extensibility, do.

4.4 Credential Subject

A verifiable credential contains claims about one or more subjects. This specification defines a credentialSubject property for the expression of claims about one or more subjects. A verifiable credential MUST have a credentialSubject property.

credentialSubject
The value of the credentialSubject property is defined as a set of objects that contain one or more properties that are each related to a subject of the verifiable credential. Each object MAY contain an id as described in Section § 4.2 Identifiers.
Example 6: Usage of the credentialSubject property
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "proof": { ... }
}

4.5 Issuer

This specification defines a property for expressing the issuer of a verifiable credential. A verifiable credential MUST contain the following property:

issuer
The value of the issuer property MUST either be a URI or an object containing a id property. It is RECOMMENDED that dereferencing the URI, or the id property, results in a document containing machine-readable information about the issuer that can be used to verify the information expressed in the credential.
Example 7: Usage of issuer property
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "proof": { ... }
}

4.6 Issuance Date

This specification defines the following property for expressing the date and time when the credential was issued:

issuanceDate
A verifiable credential MUST have an issuanceDate property. The value of the issuanceDate property MUST be a string value of an [RFC3339] combined date and time string representing the date and time the credential was issued. Note that this date represents the earliest date when the information associated with the credentialSubject property became valid.
Example 8: Usage of issuanceDate property
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "proof": { ... }
}

4.7 Proofs (Signatures)

For a credential or presentation to be verifiable, at least one proof mechanism MUST be expressed. This specification identifies two classes of proof mechanisms: external proofs and embedded proofs. An external proof is one that wraps an expression of this data model, such as a JSON Web Token, which is elaborated upon in Section § 6.3.1 JSON Web Token. An embedded proof is a mechanism where the proof is included in the data, such as a Linked Data Signature, which is elaborated upon in Section § 6.3.2 Linked Data Proofs. When embedding a proof, the following property MUST be used:

proof
One or more cryptographic proofs that can be used to detect tampering and verify the authorship of a credential or presentation. The specific method used for an embedded proof MUST be included using the type property.

Because the method used for a mathematical proof varies by representation language and the technology used, the set of name-value pairs that is expected as the value of the proof property will vary accordingly. For example, if digital signatures are used for the proof mechanism, the proof property is expected to have name-value pairs that include a signature, a reference to the signing entity, and a representation of the signing date. The example below uses RSA digital signatures.

Example 9: Usage of the proof property on a verifiable credential
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "proof": {
    "type": "RsaSignature2018",
    "created": "2018-06-18T21:19:10Z",
    "verificationMethod": "https://example.com/jdoe/keys/1",
    "signatureValue": "BavEll0/I1zpYw8XNi1bgVg/sCneO4Jugez8RwDg/+
      MCRVpjOboDoe4SxxKjkCOvKiCHGDvc4krqi6Z1n0UfqzxGfmatCuFibcC1wps
      PRdW+gGsutPTLzvueMWmFhwYmfIFpbBu95t501+rSLHIEuujM/+PXr9Cky6Ed
      +W3JT24="
  }
}
Note

No single proof mechanism is currently standardised or recommended for verifiable credentials.

4.8 Expiration

This specification defines the following property for the expression of credential expiration information:

expirationDate
The value of the expirationDate property MUST be a string value of an [RFC3339] combined date and time string representing the date and time the credential ceases to be valid.
Example 10: Usage of the expirationDate property
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "expirationDate": "2020-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "proof": { ... }
}

4.9 Status

This specification defines the following property for the discovery of information about the current status of a verifiable credential, such as whether it is suspended or revoked:

credentialStatus
The value of the credentialStatus property MUST include the:
  • id property, which MUST be a URL.
  • type property, which expresses the credential status type (also referred to as the credential status method). It is expected that the value will provide enough information to determine the current status of the credential. For example, the object could contain a link to an external document noting whether or not the verifiable credential is suspended or revoked.

The precise contents of the credential status information is determined by the specific credentialStatus type definition, and varies depending on factors such as whether it is simple to implement or if it is privacy-enhancing.

Example 11: Usage of the status property
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "credentialStatus": {
    "id": "https://example.edu/status/24",
    "type": "CredentialStatusList2017"
  },
  "proof": { ... }
}

Defining the data model, formats, and protocols for status schemes are out of scope for this specification. A status scheme registry [VC-STATUS-REGISTRY] exists for implementers who want to implement credential status checking.

4.10 Presentations

Verifiable presentations MAY be used to combine and present verifiable credentials.

If verifiable presentations are used, they MUST be constructed from verifiable credentials themselves, or of data derived from verifiable credentials in a cryptographically verifiable format.

The example below shows a verifiable presentation that embeds verifiable credentials.

Example 12: Basic structure of a presentation
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [{ ... }],
  "proof": [{ ... }]
}

The contents of the verifiableCredential property shown above are verifiable credentials, as described by this specification. The contents of the proof property are proofs, as described by the Linked Data Proofs [LD-PROOFS] specification. The id property is optional and MAY be used to provide a unique identifier for the presentation. The value associated with the id property MUST be a URI.

Some zero-knowledge cryptography schemes might enable holders to indirectly prove they hold a credential without revealing the credential itself. In these schemes, the original attribute, such as date of birth, might be translated into another value, such as "over the age of 15", which is cryptographically asserted such that a verifier can trust the value if they trust the issuer.

Note

For an example of a ZKP-style verifiable presentation that contains derived data instead of directly embedded verifiable credentials, please see Section § 5.8 Zero-Knowledge Proofs.

If a presentation supports derived predicates, a claim about birthdate in a credential can become the basis of proof that at a given point in time, the age of a subject did or will fall within a specified range. Selective disclosure schemes using zero-knowledge proofs can use claims expressed in this model to prove additional statements about those claims. For example, a claim specifying a subject's date of birth can be used as a predicate to prove the subject's age is within a given range, and therefore prove the subject qualifies for age-related discounts, without actually revealing the subject's birthdate. The holder has the flexibility to use the claim in any way that is applicable to the desired presentation.

Pat has a property
            dateOfBirth whose value is 2010-01-01T19:73:24Z
Figure 9 A basic claim expressing that Pat's date of birth is 2010-01-01T19:23:24Z. Date encoding would be determined by the schema.

5. Advanced Concepts

Building on the concepts introduced in Section § 4. Basic Concepts, this section explores more complex topics about verifiable credentials.

5.1 Lifecycle Details

This section is non-normative.

Section § 1.2 Ecosystem Overview provided an overview of the verifiable credential ecosystem. This section provides more detail about how the ecosystem is envisaged to operate, as follows:

  1. The verifier defines its policies for accepting verifiable credentials from holders for its supported actions.
  2. The issuer issues a verifiable credential to the holder.
  3. The holder might pass on its verifiable credentials to another holder.
  4. The final holder presents its verifiable credentials to the verifier in a verifiable presentation, requesting a supported action.
  5. The verifier verifies the authenticity of the verifiable presentation and verifiable credentials.
  6. The verifier verifies that the holder possesses the verifiable credentials.
  7. The verifier decides whether to accept the verifiable credentials for the requested action, taking into account its policy, the holder, and the contents of the verifiable credentials.
  8. The verifier either performs the requested action or rejects the request.
Note

The order of the steps above are not fixed and some steps might be repeated.

This specification does not define any protocol for transfering verifiable credentials or verifiable presentations, but assuming other specifications do specify how they are transferred between entities, then this Verifiable Credential Data Model is:

In particular, Sections § 5.6 Terms of Use and § B. Subject-Holder Relationships specify how a verifier can determine:

5.2 Trust Model

This section is non-normative.

The verifiable credentials trust model is as follows:

This trust model differentiates itself from other trust models by ensuring the:

By decoupling the trust between the identity provider and the relying party a more flexible and dynamic trust model is created such that market competition and customer choice is increased.

For more information about how this trust model interacts with various threat models studied by the Working Group, see the Verifiable Credentials Use Cases [VC-USECASES] document.

Note

The data model detailed in this specification does not imply a transitive trust model, such as that provided by more traditional Certificate Authority trust models. In the Verifiable Credentials Data Model, a verifier either directly trusts or does not trust an issuer. While it is possible to build transitive trust models using the Verifiable Credentials Data Model, implementers are urged to learn about the security weaknesses introduced by broadly delegating trust in the manner adopted by Certificate Authority systems.

5.3 Extensibility

One of the goals of the Verifiable Credentials Data Model is to enable permissionless innovation. To achieve this, the data model needs to be extensible in a number of different ways. The data model is required to:

This approach to data modelling is often called an open world assumption, meaning that any entity can say anything about any other entity. While this approach seems to conflict with building simple and predictable software systems, balancing extensibility with program correctness is always more challenging with an open world assumption than with closed software systems.

The rest of this section describes, through a series of examples, how both extensibility and program correctness are achieved.

Let us assume we start with the verifiable credential shown below.

Example 13: A simple credential
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.com/credentials/4643",
  "type": ["VerifiableCredential"],
  "issuer": "https://example.com/issuers/14",
  "issuanceDate": "2018-02-24T05:28:04Z",
  "credentialSubject": {
    "id": "did:example:abcdef1234567",
    "name": "Jane Doe"
  },
  "proof": { ... }
}

This verifiable credential states that the entity associated with did:example:abcdef1234567 has a name with a value of Jane Doe.

Now let us assume a developer wants to extend the verifiable credential to store two additional pieces of information: an internal corporate reference number, and Jane's favorite food.

The first thing to do is to create a JSON-LD context containing two new terms, as shown below.

Example 14: A JSON-LD context
{
  "@context": {
    "referenceNumber": "https://example.com/vocab#referenceNumber",
    "favoriteFood": "https://example.com/vocab#favoriteFood"
  }
}

After this JSON-LD context is created, the developer publishes it somewhere so it is accessible to verifiers who will be processing the verifiable credential. Assuming the above JSON-LD context is published at https://example.com/contexts/mycontext.jsonld, we can extend this example by including the context and adding the new properties and credential type to the verifiable credential.

Example 15: A verifiable credential with a custom extension
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://example.com/contexts/mycontext.jsonld"
  ],
  "id": "http://example.com/credentials/4643",
  "type": ["VerifiableCredential", "CustomExt12"],
  "issuer": "https://example.com/issuers/14",
  "issuanceDate": "2018-02-24T05:28:04Z",
  "referenceNumber": 83294847,
  "credentialSubject": {
    "id": "did:example:abcdef1234567",
    "name": "Jane Doe",
    "favoriteFood": "Papaya"
  },
  "proof": { ... }
}

This example demonstrates extending the Verifiable Credentials Data Model in a permissionless and decentralized way. The mechanism shown also ensures that verifiable credentials created in this way provide a mechanism to prevent namespace conflicts and semantic ambiguity.

A dynamic extensibility model such as this does increase the implementation burden. Software written for such a system has to determine whether verifiable credentials with extensions are acceptable based on the risk profile of the application. Some applications might accept only certain extensions while highly secure environments might not accept any extensions. These decisions are up to the developers of these applications and are specifically not the domain of this specification.

Developers are urged to ensure that extension JSON-LD contexts are highly available. Implementations that cannot fetch a context will produce an error. Strategies for ensuring that extension JSON-LD contexts are always available include using content-addressed URLs for contexts, bundling context documents with implementations, or enabling aggressive caching of contexts.

5.3.1 Semantic Interoperability

This specification endeavors to enable both the JSON and JSON-LD syntaxes to be semantically compatible with one another without the JSON implementations needing to process the documents as JSON-LD. To achieve this, the specification imposes the following additional restrictions on both syntaxes:

  • JSON-based processors MUST process the @context property, ensuring the expected values exist in the expected order for the credential type being processed. It is advised that the expected order of values of the @context property should be defined by at least a human-readable extension specification and preferably by a machine-readable specification as well.
  • JSON-LD-based processors MUST produce an error when a JSON-LD context redefines any term in the active context. The only way to change the definition of existing terms is to introduce a new term that clears the active context within the scope of that new term. Authors that are interested in this feature should read about the @protected feature in the JSON-LD 1.1 specification.

5.4 Data Schemas

Data schemas are useful when enforcing a specific structure on a given collection of data. There are at least two types of data schemas that this specification considers:

This specification defines the following property for the expression of a data schema:

credentialSchema
The value of the credentialSchema property MUST be one or more data schemas that provide verifiers with enough information to determine if the provided data conforms to the provided schema. Each credentialSchema MUST specify its type (for example, JsonSchemaValidator2018), and an id property that MUST be a URI identifying the schema file. The precise contents of each data schema is determined by the specific type definition.
Example 16: Usage of the credentialSchema property to perform JSON schema validation
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "credentialSchema": {
    "id": "https://example.org/examples/degree.json",
    "type": "JsonSchemaValidator2018"
  },
  "proof": { ... }
}

In the example above, the issuer is specifying a credentialSchema, which points to a [JSON-SCHEMA] file that can be used by a verifier to determine if the verifiable credential is well formed.

Note

For information about linkages to JSON Schema or other optional verification mechanisms, please refer to the Verifiable Credentials Implementation Guidelines.

Data schemas can also be used to specify mappings to other binary formats, such as those used to perform zero-knowledge proofs. For more information on using the credentialSchema property with zero-knowledge proofs, see Section § 5.8 Zero-Knowledge Proofs.

Example 17: Usage of the credentialSchema property to perform zero-knowledge validation
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "credentialSchema": {
    "id": "https://example.org/examples/degree.zkp",
    "type": "ZkpExampleSchema2018"
  },
  "proof": { ... }
}

In the example above, the issuer is specifying a credentialSchema pointing to a zero-knowledge packed binary data format that is capable of transforming the input data into a format, which can then be used by a verifier to determine if the proof provided with the verifiable credential is valid.

(Feature at Risk) Issue 2

The usage of the Data Schemas property may change during the W3C Candidate Recommendation process based on implementer feedback. Specifically, the location of its usage may be expanded. It may also be removed if there is not enough implementation support.

5.5 Refreshing

It is useful for systems to enable the manual or automatic refresh of a expired verifiable credential. This specification enables an issuer to include a link to a refresh service.

The issuer can include the refresh service as an element inside the verifiable credential if it is intended for either the verifier or the holder (or both), or inside the verifiable presentation if it is intended for the holder only. In the latter case, this enables the holder to refresh the verifiable credential before creating a verifiable presentation to share with a verifier. In the former case, including the refresh service inside the verifiable credential enables both the holder and the verifier to perform future updates of the credential.

This specification defines the following property for expressing a refresh service:

refreshService
The value of the refreshService property MUST be one or more refresh services that provides enough information to the recipient's software such that the recipient can refresh the credential. Each refreshService value MUST specify its type (for example, ManualRefreshService2018) and its id, which is the URL of the service. The precise content of each refresh service is determined by the specific refreshService type definition.
Example 18: Usage of the refreshService property by an issuer
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "refreshService": {
    "id": "https://example.edu/refresh/3732"
    "type": "ManualRefreshService2018",
  },
  "proof": { ... }
}

In the example above, the issuer specifies a manual refreshService that can be used by directing the holder or the verifier to https://example.edu/refresh/3732.

(Feature at Risk) Issue 3

The refresh service may change based on implementer feedback, including being removed from the specification if there is not enough implementer support for the feature.

5.6 Terms of Use

Terms of use can be utilized by an issuer or a holder to communicate the terms under which a verifiable credential or verifiable presentation was issued. The issuer places their terms of use inside the credential. The holder places their terms of use inside a presentation. The value of this property tells the verifier what actions it must perform (an obligation), must not perform (a prohibition), or may perform (a permission) if it is to accept the verifiable credential or verifiable presentation.

Note

Further study is required to determine how a subject who is not a holder places terms of use on their verifiable credentials. One way could be for the subject to request the issuer to place the terms of use inside the issued verifiable credentials. Another way could be for the subject to delegate a verifiable credential to a holder and placing terms of use restrictions on the delegated verifiable credential.

This specification defines the following property for expressing terms of use:

termsOfUse
The value of the termsOfUse property MUST specify one or more terms of use policies under which the creator issued the credential or presentation. If the recipient (a holder or verifier) is not willing to adhere to the specified terms of use, then they do so on their own responsibility and might incur legal liability if they violate the stated terms of use. Each termsOfUse value MUST specify its type, for example, IssuerPolicy, and MAY specify its instance id. The precise contents of each term of use is determined by the specific termsOfUse type definition.
Example 19: Usage of the termsOfUse property by an issuer
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "termsOfUse": [{
    "type": "IssuerPolicy",
    "id": "http://example.com/policies/credential/4",
    "profile": "http://example.com/profiles/credential",
    "prohibition": [{
      "assigner": "https://example.edu/issuers/14",
      "assignee": "AllVerifiers",
      "target": "http://example.edu/credentials/3732",
      "action": ["Archival"]
    }]
  },
  "proof": { ... }
}

In the example above, the issuer (the assigner) is prohibiting verifiers (the assignee) from storing the data in an archive.

Example 20: Usage of the termsOfUse property by a holder
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "type": "VerifiablePresentation",
  "verifiableCredential": [{
    "id": "http://example.edu/credentials/3732",
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "issuer": "https://example.edu/issuers/14",
    "issuanceDate": "2010-01-01T19:23:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
    },
    "proof": { ... }
  }],
  "termsOfUse": [{
    "type": "HolderPolicy",
    "id": "http://example.com/policies/credential/6",
    "profile": "http://example.com/profiles/credential",
    "prohibition": [{
      "assigner": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "assignee": "https://wineonline.example.org/",
      "target": "http://example.edu/credentials/3732",
      "action": ["3rdPartyCorrelation"]
    }]
  },
  "proof": [ ... ]
}

In the example above, the holder (the assigner), who is also the subject, expressed a term of use prohibiting the verifier (the assignee, https://wineonline.example.org) from using the information provided to correlate the holder or subject using a third-party service. If the verifier were to use a third-party service for correlation, they would violate the terms under which the holder created the presentation.

(Feature at Risk) Issue 4

The terms of use feature may change during the W3C Candidate Recommendation phase including being removed entirely if there is not enough implementer support for the feature.

5.7 Evidence

Evidence can be included by an issuer to provide the verifier with additional supporting information in a verifiable credential. This could be used by the verifier to establish the confidence with which it relies on the claims in the verifiable credential.

For example, an issuer could check physical documentation provided by the subject or perform a set of background checks before issuing the credential. In certain scenarios, this information is useful to the verifier when determining the risk associated with relying on a given credential.

This specification defines the following property for expressing evidence information:

evidence
The value of the evidence property MUST be one or more evidence schemes providing enough information for a verifier to determine whether the evidence gathered by the issuer meets its confidence requirements for relying on the credential. Each evidence scheme is identified by its type. The id property is optional, but if present, SHOULD contain a URL that points to where more information about this instance of evidence can be found. The precise content of each evidence scheme is determined by the specific evidence type definition.
Note

For information on how attachments and references to credentials and non-credential data may be supported by the specification, please refer to the Verifiable Credentials Implementation Guidelines.

Example 21: Usage of the evidence property
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "evidence": [{
    "id": "https://example.edu/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231",
    "type": ["DocumentVerification"],
    "verifier": "https://example.edu/issuers/14",
    "evidenceDocument": "DriversLicense",
    "subjectPresence": "Physical",
    "documentPresence": "Physical"
  },{
    "id": "https://example.edu/evidence/f2aeec97-fc0d-42bf-8ca7-0548192dxyzab",
    "type": ["SupportingActivity"],
    "verifier": "https://example.edu/issuers/14",
    "evidenceDocument": "Fluid Dynamics Focus",
    "subjectPresence": "Digital",
    "documentPresence": "Digital"
  }],
  "proof": { ... }
}
Note

The evidence property provides different and complimentary information to the proof property. The evidence property is used to express supporting information, such as documentary evidence, related to the integrity of the credential. In contrast, the proof property is used to express machine-verifiable mathematical proofs related to the authenticity of the issuer and integrity of the credential.

(Feature at Risk) Issue 5

The evidence feature may change during the W3C Candidate Recommendation phase based on implementer feedback, or be removed entirely due to lack of support by implementers.

5.8 Zero-Knowledge Proofs

A zero-knowledge proof is a cryptographic method where an entity can prove to another entity that they know a certain value without disclosing the actual value. A real world example is proving that an accredited university has granted a degree to you without revealing your identity or any other personally identifiable information contained on the degree.

The key capabilities introduced by zero-knowledge proof mechanisms are:

  1. The ability of a holder to combine multiple verifiable credentials from multiple issuers into a single presentation without revealing credential or subject identifiers to the verifier. This makes it more difficult for the verifier to collude with any of the issuers regarding the issued credentials.
  2. The ability of a holder to selectively disclose the claims in a credential to a verifier without requiring the issuance of multiple atomic credentials. This allows a holder to provide a verifier with precisely the information they need and nothing more.
  3. The ability of a holder to produce a derived credential that is formatted according to the verifier's data schema rather than the issuer's, without needing to involve the issuer after credential issuance. This provides a great deal of flexibility for holders to use the credentials they have been issued.

This specification describes a data model that supports zero-knowledge proof mechanisms. The examples below highlight how the data model may be used to issue, present, and verify zero-knowledge verifiable credentials.

To use zero-knowledge verifiable credentials the issuer must issue a verifiable credential in a manner that enables the holder to present the information to a verifier in a privacy-enhancing manner. This implies that the holder will be able to prove the validity of the issuer's signature without revealing the values that were signed, or when only revealing certain selected values. The standard practice is to do so by proving knowledge of the signature, without revealing the signature itself. There are two requirements for verifiable credentials when they are to be used in zero-knowledge proof systems:

The following example shows one method of using verifiable credentials in zero-knowledge. It makes use of a CL Signature, which allows the presentation of the verifiable credential in a way that supports the privacy of the holder and subject through the use of selective disclosure of the credential values.

Example 22: A verifiable credential that supports CL Signatures
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "credentialSchema": {
    "id": "did:example:cdf:35LB7w9ueWbagPL94T9bMLtyXDj9pX5o",
    "type": "did:example:schema:22KpkXgecryx9k7N6XN1QoN3gXwBkSU8SfyyYQG"
  },
  "issuer": "did:example:Wz4eUg7SetGfaUVCn8U9d62oDYrUJLuUtcy619",
  "credentialSubject": {
    "givenName": "Jane",
    "familyName": "Doe",
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>",
      "college": "College of Engineering"
    }
  },
  "proof": {
    "type": "AnonCredv1",
    "issuerData": "5NQ4TgzNfSQxoLzf2d5AV3JNiCdMaTgm...BXiX5UggB381QU7ZCgqWivUmy4D",
    "attributes": "pPYmqDvwwWBDPNykXVrBtKdsJDeZUGFA...tTERiLqsZ5oxCoCSodPQaggkDJy",
    "signature": "8eGWSiTiWtEA8WnBwX4T259STpxpRKuk...kpFnikqqSP3GMW7mVxC4chxFhVs",
    "signatureCorrectnessProof": "SNQbW3u1QV5q89qhxA1xyVqFa6jCrKwv...dsRypyuGGK3RhhBUvH1tPEL8orH"
  }
}

The example above provides the credential definition by using the credentialSchema property and a specific proof that is usable in the Camenisch-Lysyanskaya Zero-Knowledge Proof system.

The next example utilizes the verifiable credential above to generate a new derived verifiable credential with a privacy-preserving proof. The derived verifiable credential is then placed in a verifiable presentation that further proves that the entire assertion is valid. There are three requirements of most verifiable presentations when they are to be used in zero-knowledge systems:

Example 23: A verifiable presentation that supports CL Signatures
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "type": "VerifiablePresentation",
  "verifiableCredential": [{
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "credentialSchema": {
      "id": "did:example:cdf:35LB7w9ueWbagPL94T9bMLtyXDj9pX5o",
      "type": "did:example:schema:22KpkXgecryx9k7N6XN1QoN3gXwBkSU8SfyyYQG"
    },
    "issuer": "did:example:Wz4eUg7SetGfaUVCn8U9d62oDYrUJLuUtcy619",
    "credentialSubject": {
      "degreeType": "BachelorDegree",
      "degreeSchool": "College of Engineering"
      }
    },
    "proof": {
      "type": "AnonCredDerivedCredentialv1",
      "primaryProof": "cg7wLNSi48K5qNyAVMwdYqVHSMv1Ur8i...Fg2ZvWF6zGvcSAsym2sgSk737",
      "nonRevocationProof": "mu6fg24MfJPU1HvSXsf3ybzKARib4WxG...RSce53M6UwQCxYshCuS3d2h"
    }
  }],
  "proof": {
    "type": "AnonCredPresentationProofv1",
    "proofValue": "DgYdYMUYHURJLD7xdnWRinqWCEY5u5fK...j915Lt3hMzLHoPiPQ9sSVfRrs1D"
  }
}
Verifiable
            Credential 1 and Verifiable Credential 2 on the left map
            to Derived Credential 1 and Derived Credential 2 inside a
            Presentation on the right.  Verifiable Credential 1
            contains Context, Type, ID, Issuer, Issue Date, Expiration
            Date, CredentialSubject, and Proof, where
            CredentialSubject contains GivenName, FamilyName, and
            Birthdate and Proof contains Signature, Proof of
            Correctness, and Attributes.  Verifiable Credential 2
            contains Context, Type, ID, Issuer, Issue Date, Expiration
            Date, CredentialSubject, and Proof, where
            CredentialSubject contains University, which contains
            Department, which contains DegreeAwarded, and Proof contains Signature, Proof of
            Correctness, and Attributes.  The Presentation diagram on
            the right contains Context, Type, ID,
            VerifiableCredential, and Proof, where
            VerifiableCredential contains Derived Credential 1 and
            Derived Credential 2 and Proof contains Common Link
            Secret.  Derived Credential 1 contains Context, Type, ID,
            Issuer, Issue Date, CredentialSubject, and Proof, where
            CredentialSubject contains AgeOver18 and Proof contains
            Knowledge of Signature.  Derived Credential 2 contains
            Context, Type, ID, Issuer, Issue Date, CredentialSubject,
            and Proof, where CredentialSubject contains Degree and
            Proof contains Knowledge of Signature.  A line links
            Birthdate in Verifiable Credential 1 to AgeOver18 in
            Derived Credential 1.  A line links DegreeAwarded in
            Verifiable Credential 2 to Degree in Derived Credential 2.
Figure 10 A visual example of the relationship between credentials and derived credentials in a ZKP presentation.
Note

Important details regarding the format for the credential definition and of the proofs are omitted on purpose because they are outside of the scope of this document. The purpose of this section is to guide implementers wanting to extend verifiable credentials and verifiable presentations to support zero-knowledge proof systems.

(Feature at Risk) Issue 6

Zero Knowledge Proofs are a feature at risk. The Working Group is looking for multiple implementers to support the feature during the W3C Candidate Recommendation phase.

5.9 Disputes

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

Only the subject of a verifiable credential is entitled to issue a DisputeCredential. A DisputeCredential issued by anyone other than the subject should be disregarded by the verifier, unless the verifier has some other way of determining the truth of the dispute. This is to prevent denial of service attacks whereby an attacker falsely disputes a true claim.

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.

Example 24: A subject disputes a credential
{
  "@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": { ... }
}
Example 25: Another entity disputes a credential
{
  "@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 credential the issuer is claiming that the address in the disputed credential is wrong. For example, the subject might wrongly be claiming to have the same address as that of the issuer.

Note

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.

(Feature at Risk) Issue 7

The dispute feature may change significantly during the W3C Candidate Recommendation process including possibly being removed if there is not enough support from implementations for the feature.

5.10 Authorization

This section is non-normative.

Verifiable credentials are intended as a means of reliably identifying subjects. While it is recognized that Role Based Access Controls (RBACs) and Attribute Based Access Controls (ABACs) rely on this identification as a means of authorizing subjects to access resources, this specification does not provide a complete solution for RBAC or ABAC. Authorization is not an appropriate use for this specification without an accompanying authorization framework.

The Working Group did consider authorization use cases during the creation of this specification and is pursuing that work as an architectural layer built on top of this specification.

6. Syntaxes

Many of the concepts in this document were introduced by example using the JSON syntax. This section formalizes how the data model (described in Sections § 3. Core Data Model, § 4. Basic Concepts, and § 5. Advanced Concepts) is realized in JSON and JSON-LD. Although syntactic mappings are provided for these two syntaxes only, applications and services can use any other data representation syntax, such as XML, YAML, or CBOR, that is capable of expressing the data model.

6.1 JSON

The data model as described in Section § 3. Core Data Model can be encoded in Javascript Object Notation (JSON) [RFC8259] by mapping property values to JSON types as follows:

6.2 JSON-LD

[JSON-LD] is a JSON-based format used to serialize Linked Data. The syntax is designed to easily integrate into deployed systems already using JSON, and provides a smooth upgrade path from JSON to JSON-LD. It is primarily intended to be a way to use Linked Data in Web-based programming environments, to build interoperable Web services, and to store Linked Data in JSON-based storage engines.

JSON-LD is useful when extending the data model described in this specification. Instances of the data model are encoded in JSON-LD in the same way they are encoded in JSON (Section § 6.1 JSON), with the addition of the @context property. The JSON-LD Context is described in detail in the [JSON-LD] specification and its use is elaborated on in Section § 5.3 Extensibility.

Multiple contexts MAY be used or combined to express any arbitrary information about credentials in idiomatic JSON. The JSON-LD Context available at https://www.w3.org/2018/credentials/v1 is a static document that is never updated and can therefore be downloaded and cached client side. The associated vocabulary document for the Verifiable Credentials Data Model is available at https://www.w3.org/2018/credentials.

6.2.1 Syntactic Sugar

In general, the data model and syntaxes described in this document are designed such that developers can copy and paste examples to incorporate verifiable credentials into their software systems. The design goal of this approach is to provide a low barrier to entry while still ensuring global interoperability between a heterogeneous set of software systems. This section describes some of these approaches, which will likely go unnoticed by most developers, but whose details will be of interest to implementers. The most noteworthy syntactic sugars provided by JSON-LD are:

  • The @id and @type keywords are aliased to id and type respectively, enabling developers to use this specification as idiomatic JSON.
  • Data types, such as integers, dates, units of measure, and URLs, are automatically typed to provide stronger type guarantees for use cases that require them.
  • The verifiableCredential and proof properties are treated as graph containers. That is, mechanisms used to isolate sets of data asserted by different entities. This ensures, for example, proper cryptographic separation between the data graph provided by each issuer and the one provided by the holder presenting the verifiable credential to ensure the provenance of the information for each graph is preserved.
  • The @protected properties feature of JSON-LD 1.1 is used to ensure that terms defined by this specification cannot be overridden. This means that as long as the same @context declaration is made at the top of a verifiable credential or verifiable presentation, interoperability is guaranteed for all terms understood by users of the data model whether or not they use a JSON-LD processor.

6.3 Proof Formats

The data model described in this specification is designed to be proof format agnostic. This specification does not make any normative statements related to the use of any particular digital proof or signature format. At the time of publication, at least two proof formats are being actively utilized by implementers and the Working Group felt that documenting what these proof formats are and how they are being used would be beneficial to implementers. The sections detailing the current proof formats being actively utilized to issue verifiable credentials are:

6.3.1 JSON Web Token

JSON Web Token (JWT) [RFC7519] is still a widely used means to express claims to be transferred between two parties. Providing a representation of the Verifiable Credentials Data Model for JWT allows existing systems and libraries to participate in the ecosystem described in Section § 1.2 Ecosystem Overview. A JWT encodes a set of claims as a JSON object that is contained in a JSON Web Signature (JWS) [RFC7515] or JWE [RFC7516]. For this specification, the use of JWE is out of scope.

(Feature at Risk) Issue 8

JWT support is a feature at risk and may be removed during the W3C Candidate Recommendation phase if there is not enough implementer support for the feature.

Relation to the Verifiable Credentials Data Model

This specification defines encoding rules of the Verifiable Credential Data Model onto JWT and JWS. It further defines processing rules how and when to make use of specific JWT registered claim names and specific JWS registered header parameter names to allow systems based on JWT to comply with this specification. If these specific claim names and header parameters are present, their respective counterpart in the standard verifiable credential and verifiable presentation MAY be omitted to avoid duplication.

IANA Considerations

This specification introduces two new registered claim names, which contain those parts of the standard verifiable credentials and verifiable presentation where no explicit encoding rules for JWT exist. These objects are enclosed in the JWT payload as follows:

JWT and JWS Considerations
JWT Encoding

To encode a verifiable credential as a JWT, specific properties introduced by this specification MUST be encoded as standard JOSE header parameters, JWT registered claim names, or contained in the JWS signature part. If no explicit rule is specified, properties are encoded in the same way as with a standard verifiable credential, and are added to the vc property of the JWT. The following paragraphs describe these encoding rules.

If the JWS is present, the digital signature either refers to the issuer of the verifiable credential, or in the case of a verifiable presentation, the holder of the verifiable credential. The JWS proves that the issuer of the JWT signed the contained JWT payload and therefore, the proof property can be omitted.

If no JWS is present, a proof property MUST be provided. The proof property can be used to represent more complex proofs, for example if the creator is different from the issuer, or a proof not based on digital signatures, such as Proof of Work. The issuer MAY include both a JWS and a proof property. For backward compatibility reasons, the issuer MUST use JWS to represent proofs based on a digital signature.

The following defines rules for JOSE headers in the context of this specification:

  • alg MUST be used for RSA and ECDSA-based digital signatures. If only the proof attribute is used, the alg header MUST be set to none.
  • kid MAY be used if there are multiple keys associated with the issuer of the JWT. The key discovery is out of the scope of this specification. For example, the kid can refer to a key in a DID document, or can be the identifier of a key inside a JWKS.
  • typ, if present, MUST be set to JWT.

For backward compatibility with JWT processors, the following JWT registered claim names MUST be used instead of, or in addition to, their respective standard verifiable credential counterparts:

Other JOSE header parameters and claim names not specified herein can be used if their use is not explicitly discouraged. Additional claims MUST be added to the credentialSubject property of the JWT.

This version of the specification defines no JWT specific encoding rules for the concepts outlined in Section Advanced Concepts (for example, refreshService, termsOfUse, and evidence). These concepts can be encoded as they are without any transformation, and can be added to the vc property of the JWT.

JWT Decoding

To decode a JWT to a standard verifiable credential, the following transformation MUST be performed:

  1. Create a JSON object.
  2. Add the content from the vc property to the new JSON object.
  3. Transform the remaining JWT specific headers and claims, and add the results to the new JSON object.

To transform the JWT specific headers and claims, the following MUST be done. If:

  • exp is present, the UNIX timestamp MUST be converted to an [RFC3339] date-time, and MUST be used to set the value of the expirationDate property of credentialSubject of the new JSON object.
  • iss is present, the value MUST be used to set the issuer property of the new JSON object.
  • iat is present, the UNIX timestamp MUST be converted to an [RFC3339] date-time, and MUST be used to set the value of the issuanceDate property of the new JSON object.
  • jti is present, the value MUST be used to set the value of the id property of credentialSubject of the new JSON object.
  • sub is present, the value MUST be used to set the value of the id property of the new JSON object.
Example 26: JWT header of a JWT-based verifiable credential using JWS as a proof (non-normative)
{
    "alg": "RS256",
    "typ": "JWT",
    "kid": "did:example:abfe13f712120431c276e12ecab#keys-1"
}

In the example above, the verifiable credential uses a proof based on JWS digital signatures, and the corresponding verification key can be obtained using the kid header parameter.

Example 27: JWT payload of a JWT-based verifiable credential using JWS as a proof (non-normative)
{
  "sub": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "jti": "http://example.edu/credentials/3732",
  "iss": "did:example:abfe13f712120431c276e12ecab",
  "iat": "1541493724",
  "exp": "1573029723",
  "nonce": "660!6345FSer",
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": ["VerifiableCredential", "UniversityDegreeCredential"],
    "credentialSubject": {
      "degree": {
        "type": "BachelorDegree",
        "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
      }
    }
  }
}

In the example above, vc does not contain the id property because the JWT encoding uses the jti attribute to represent a unique identifier. The sub attribute encodes the information represented by the id property of credentialSubject.

Example 28: Verifiable credential using JWT compact serialization (non-normative)
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0
MzFjMjc2ZTEyZWNhYiNrZXlzLTEifQ.eyJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxY
zI3NmUxMmVjMjEiLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsImlzc
yI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0MzFjMjc2ZTEyZWNhYiIsImlhdCI6IjE1NDE0OTM3M
jQiLCJleHAiOiIxNTczMDI5NzIzIiwibm9uY2UiOiI2NjAhNjM0NUZTZXIiLCJ2YyI6eyJAY29udGV4d
CI6WyJodHRwczovL3czLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwiaHR0cHM6Ly9leGFtcGxlLmNvb
S9leGFtcGxlcy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eURlZ
3JlZUNyZWRlbnRpYWwiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiZGVncmVlIjp7InR5cGUiOiJCYWNoZ
WxvckRlZ3JlZSIsIm5hbWUiOiJCYWNoZWxvciBvZiBTY2llbmNlIGluIE1lY2hhbmljYWwgRW5naW5lZ
XJpbmcifX19fQ.VTotLRYblDOtJBTlOYbvibqC_uu8RXdvv6m_lR6cdEdFcGf4oNKiFZ_WJr07n1A-_E
jTLzjD5XwmDPzb8lxDlEkCLJ5WQS4_jwzCZAeetNG7YO2slTCFRiE_2xBM2R01ssI8bEPnqLBnc-Lu88
DmO21wL8-Yud1eL45N_pEE5DqTF5DJ-IesmVkWvC8159GUHKShFIpgHiE1EDDEjUzjYA5ZyzS2_ZmSTj
5NDLOt8muVlORpO7xJ6aWRdtibkmSTKykUzh75-4Rklz2H9-AWBXEh5ajkyB8yINh_y4jK3g7ypVACRI
Z9DZhdw2K39KCilAPVJsmejiKlxNhQAOlgcYUlhCzphLsqo-FA90fFGrsg-3JuQihnNw6RSPImjVt_yV
appfjilEzhyfWT-Smm_KN8LRbFdNtU-awwhKbjDNW-7fNVrnsWHKvLsd_zlch8YlHZ6g0tHJnxo_yOTM
BSSpt0jzyl1ByqjumgBFNpTR-NTVog4B7vLEvq58RuShraL5VNr7bjNzq2gisp3jq3LpfUmiwc7rQXw6
AlQuattLRolXx3EtPysrZe-wU7yrEtNPvpGs-OyJAczfJPzza9lGTbx6IWS-0pTmNq6hwNd0ODMiB3uL
3TeBN1xLoue9Hdc3toUvmdyXecSvltPcaiRoN-uQo8RRAvfK7GALAzaHw
Example 29: JWT header of a JWT based verifiable presentation (non-normative)
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1"
}

In the example above, the verifiable presentation uses a proof based on JWS digital signatures, and the corresponding verification key can be obtained using the kid header parameter.

Example 30: JWT payload of a JWT based verifiable presentation (non-normative)
{
  "iss": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "aud": "did:example:4a57546973436f6f6c4a4a57573",
  "iat": "1541493724",
  "exp": "1573029723",
  "nonce": "343s$FSFDa-",
  "vp": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": ["VerifiablePresentation"],
    // base64url-encoded JWT as string
    "verifiableCredential": ["..."]
  }
}

In the example above, vp does not contain the id property because the JWT encoding uses the jti attribute to represent a unique identifier. verifiableCredential contains an string array of verifiable credentials using JWT compact serialization.

Example 31: Verifiable presentation using JWT compact serialization (non-normative)
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2
ZjFjMjc2ZTEyZWMyMSNrZXlzLTEifQ.eyJpc3MiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxY
zI3NmUxMmVjMjEiLCJqdGkiOiJ1cm46dXVpZDozOTc4MzQ0Zi04NTk2LTRjM2EtYTk3OC04ZmNhYmEzO
TAzYzUiLCJhdWQiOiJkaWQ6ZXhhbXBsZTo0YTU3NTQ2OTczNDM2ZjZmNmM0YTRhNTc1NzMiLCJpYXQiO
iIxNTQxNDkzNzI0IiwiZXhwIjoiMTU3MzAyOTcyMyIsIm5vbmNlIjoiMzQzcyRGU0ZEYS0iLCJ2cCI6e
yJAY29udGV4dCI6WyJodHRwczovL3czLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIiwiaHR0cHM6Ly9le
GFtcGxlLmNvbS9leGFtcGxlcy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50YXRpb24iXSwid
mVyaWZpYWJsZUNyZWRlbnRpYWwiOlsiZXlKaGJHY2lPaUpTVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0lzS
W10cFpDSTZJbVJwWkRwbGVHRnRjR3hsT21GaVptVXhNMlkzTVRJeE1qQTBNekZqTWpjMlpURXlaV05oW
WlOclpYbHpMVEVpZlEuZXlKemRXSWlPaUprYVdRNlpYaGhiWEJzWlRwbFltWmxZakZtTnpFeVpXSmpOb
Vl4WXpJM05tVXhNbVZqTWpFaUxDSnFkR2tpT2lKb2RIUndPaTh2WlhoaGJYQnNaUzVsWkhVdlkzSmxaR
1Z1ZEdsaGJITXZNemN6TWlJc0ltbHpjeUk2SW1ScFpEcGxlR0Z0Y0d4bE9tRmlabVV4TTJZM01USXhNa
kEwTXpGak1qYzJaVEV5WldOaFlpSXNJbWxoZENJNklqRTFOREUwT1RNM01qUWlMQ0psZUhBaU9pSXhOV
GN6TURJNU56SXpJaXdpYm05dVkyVWlPaUkyTmpBaE5qTTBOVVpUWlhJaUxDSjJZeUk2ZXlKQVkyOXVkR
1Y0ZENJNld5Sm9kSFJ3Y3pvdkwzY3pMbTl5Wnk4eU1ERTRMMk55WldSbGJuUnBZV3h6TDNZeElpd2lhS
FIwY0hNNkx5OWxlR0Z0Y0d4bExtTnZiUzlsZUdGdGNHeGxjeTkyTVNKZExDSjBlWEJsSWpwYklsWmxjb
WxtYVdGaWJHVkRjbVZrWlc1MGFXRnNJaXdpVlc1cGRtVnljMmwwZVVSbFozSmxaVU55WldSbGJuUnBZV
3dpWFN3aVkzSmxaR1Z1ZEdsaGJGTjFZbXBsWTNRaU9uc2laR1ZuY21WbElqcDdJblI1Y0dVaU9pSkNZV
05vWld4dmNrUmxaM0psWlNJc0ltNWhiV1VpT2lKQ1lXTm9aV3h2Y2lCdlppQlRZMmxsYm1ObElHbHVJR
TFsWTJoaGJtbGpZV3dnUlc1bmFXNWxaWEpwYm1jaWZYMTlmUS5WVG90TFJZYmxET3RKQlRsT1lidmlic
UNfdXU4UlhkdnY2bV9sUjZjZEVkRmNHZjRvTktpRlpfV0pyMDduMUEtX0VqVEx6akQ1WHdtRFB6Yjhse
ERsRWtDTEo1V1FTNF9qd3pDWkFlZXRORzdZTzJzbFRDRlJpRV8yeEJNMlIwMXNzSThiRVBucUxCbmMtT
HU4OERtTzIxd0w4LVl1ZDFlTDQ1Tl9wRUU1RHFURjVESi1JZXNtVmtXdkM4MTU5R1VIS1NoRklwZ0hpR
TFFRERFalV6allBNVp5elMyX1ptU1RqNU5ETE90OG11VmxPUnBPN3hKNmFXUmR0aWJrbVNUS3lrVXpoN
zUtNFJrbHoySDktQVdCWEVoNWFqa3lCOHlJTmhfeTRqSzNnN3lwVkFDUklaOURaaGR3MkszOUtDaWxBU
FZKc21lamlLbHhOaFFBT2xnY1lVbGhDenBoTHNxby1GQTkwZkZHcnNnLTNKdVFpaG5OdzZSU1BJbWpWd
F95VmFwcGZqaWxFemh5ZldULVNtbV9LTjhMUmJGZE50VS1hd3doS2JqRE5XLTdmTlZybnNXSEt2THNkX
3psY2g4WWxIWjZnMHRISm54b195T1RNQlNTcHQwanp5bDFCeXFqdW1nQkZOcFRSLU5UVm9nNEI3dkxFd
nE1OFJ1U2hyYUw1Vk5yN2JqTnpxMmdpc3AzanEzTHBmVW1pd2M3clFYdzZBbFF1YXR0TFJvbFh4M0V0U
HlzclplLXdVN3lyRXROUHZwR3MtT3lKQWN6ZkpQenphOWxHVGJ4NklXUy0wcFRtTnE2aHdOZDBPRE1pQ
jN1TDNUZUJOMXhMb3VlOUhkYzN0b1V2bWR5WGVjU3ZsdFBjYWlSb04tdVFvOFJSQXZmSzdHQUxBemFId
yJdfX0.hqDdoQrayDldi2RjdzACjgdPkp3eKQczJtkecHHlQgUs7533SoOPgG96cLPsDMb-0VKcRDw33
CgkuSIXHbxhmR23DpU0OR2lLtCI18qmtgBC9-bqvundES1p4U4cFQrUbbuMWYYpIxoHkh4KZGBAszRaF
U9OiCgOPQSpJFfr75IVYlIpgl0LwBh3Ac9-P0623BOEzOE4V-X-oYAro7on2lv6eukEb7BDpCE_DZbyT
bLLJJ5TWLUNf13CQKpza4cyVl0LtBwfBoj1IXQzdODYx2V-AAabI5H3vNSSPWZHHrm_nmnU7ZP2H8tpT
Uec3a094lZLHP3Ktz5zMLQwQwtrU7nJ4iDTW6ExIK6IxhQ250yzV4kaABbziynd5GmCrJ9IIYtMy-cK4
TPQHxlPvq9Zcxh7XEWquhc9UWFvdpx6zGtWYuDkB8q0NXwUZHrFHkqseYuiKsK7sd75ajeMCANxKw164
K4cUyX9v3w60xz3gFivd2W6A0mFRCqUkFUGfMpe4j-hsf6FyPzyXM6m1JNkNHsD86HHT_Xu9xTGHuaLp
3kn3l_wwQ687VuPnCPLGlV92lZOHIo-QSMm-WBTo4m5q5X8sr9gior_NI39OH3RfzBPA0iN1JDi8EkOA
dwapkZcYgpuhxHrzNbofYYS0nIIkZ7dIEHiyGhfLo5XzAEmAIU

6.3.2 Linked Data Proofs

This specification utilizes Linked Data to publish information on the Web using standards, such as URLs and JSON-LD, to identify subjects and their associated properties. When information is presented in this manner, other related information can be easily discovered and new information can be easily merged into the existing graph of knowledge. Linked Data is extensible in a decentralized way, greatly reducing barriers to large scale integration. The data model in this specification works well with the Linked Data Proofs, Linked Data Signatures, and the associated Linked Data Cryptographic Suites, which are designed to protect the data model as described by this specification.

Unlike the use of JSON Web Token, no extra pre- or post-processing is necessary. The Linked Data Proofs format was designed to simply and easily protect verifiable credentials and verifiable presentations. Protecting a verifiable credential or verifiable presentation is as simple as passing a valid example in this specification to a Linked Data Signatures implementation and generating a digital signature.

Note

Information on the different qualities of the various syntax formats, e.g. JSON+JWT, JSON-LD+JWT, and JSON-LD+LD-Proofs may be found in the Verifiable Credentials Implementation Guidelines.

7. Privacy Considerations

This section is non-normative.

This section details the general privacy considerations and specific privacy implications of deploying the Verifiable Credentials Data Model into production environments.

7.1 Spectrum of Privacy

This section is non-normative.

It is important to recognize there is a spectrum of privacy ranging from pseudonymous to strongly identified. Depending on the use case, people have different comfort levels about what information they are willing to provide and what information can be derived from what is provided.

Horizontal bar with
          red on the left, orange in the middle, and green on the
          right.  The red has the text 'Highly correlatable (global
          IDs), e.g. government ID, shipping address, credit card
          number'.  The orange has the text 'Correlatable ia collusion
          (personally identifiable info), e.g. name, birthday, zip
          code'.  The green has the text 'Non-correlatable
          (pseudonyms), e.g. age over 21'.
Figure 11 Privacy spectrum ranging from pseudonymous to fully identified.

For example, most people probably want to remain anonymous when purchasing alcohol because the regulatory check required is solely based on whether a person is above a specific age. Alternatively, for medical prescriptions written by a doctor for a patient, the pharmacy fulfilling the prescription is required to more strongly identify the medical professional and the patient. Therefore there is not one approach to privacy that works for all use cases. Privacy solutions are use case specific.

Note

Even for those wanting to remain anonymous when purchasing alcohol, photo identification might still be required to provide appropriate assurance to the merchant. The merchant might not need to know your name or other details (other than that you are over a specific age), but in many cases just proof of age might still be insufficient to meet regulations.

The Verifiable Credentials Data Model strives to support the full privacy spectrum and does not take philosophical positions on the correct level of anonymity for any specific transaction. The following sections provide guidance for implementers who want to avoid specific scenarios that are hostile to privacy.

7.2 Personally Identifiable Information

This section is non-normative.

Data associated with verifiable credentials stored in the credential.credentialSubject field is susceptible to privacy violations when shared with verifiers. Personally identifying data, such as a government-issued identifier, shipping address, and full name, can be easily used to determine, track, and correlate an entity. Even information that does not seem personally identifiable, such as the combination of a birthdate and a postal code, has very powerful correlation and de-anonymizing capabilities.

Implementers are strongly advised to warn holders when they share data with these kinds of characteristics. Issuers are strongly advised to provide privacy-protecting credentials when possible. For example, issuing ageOver credentials instead of date of birth credentials when a verifier wants to determine if an entity is over the age of 18.

7.3 Identifier-Based Correlation

This section is non-normative.

Subjects of verifiable credentials are identified using the credential.credentialSubject.id field. The identifiers used to identify a subject create a greater risk of correlation when the identifiers are long-lived or used across more than one web domain.

Similarly, disclosing the credential identifier (credential.id) leads to situations where multiple verifiers, or an issuer and a verifier, can collude to correlate the holder. If holders want to reduce correlation, they should use credential schemes that allow hiding the identifier during presentation. Such schemes expect the holder to generate the identifier and might even allow hiding the identifier from the issuer, while still keeping the identifier embedded and signed in the credential.

If strong anti-correlation properties are a requirement in a verifiable credentials system, it is strongly advised that identifiers are either:

7.4 Signature-Based Correlation

This section is non-normative.

The contents of verifiable credentials are secured using the credential.proof field. The properties in this field create a greater risk of correlation when the same values are used across more than one session or domain and the value does not change. Examples include the creator, created, domain (for very specific domains), nonce, and signatureValue fields.

If strong anti-correlation properties are required, it is advised that signature values and metadata are regenerated each time using technologies like third-party pairwise signatures, zero-knowledge proofs, or group signatures.

Note

Even when using anti-correlation signatures, information might still be contained in a credential that defeats the anti-correlation properties of the cryptography used.

7.5 Long-Lived Identifier-Based Correlation

This section is non-normative.

Verifiable credentials might contain long-lived identifiers that could be used to correlate individuals. These types of identifiers include subject identifiers, email addresses, government-issued identifiers, organization-issued identifiers, addresses, healthcare vitals, credential-specific JSON-LD contexts, and many other sorts of long-lived identifiers.

Organizations providing software to holders should strive to identify fields in credentials containing information that could be used to correlate individuals and warn holders when this information is shared.

7.6 Device Fingerprinting

This section is non-normative.

There are mechanisms external to verifiable credentials that are used to track and correlate individuals on the Internet and the Web. Some of these mechanisms include Internet protocol (IP) address tracking, web browser fingerprinting, evercookies, advertising network trackers, mobile network position information, and in-application Global Positioning System (GPS) APIs. Using verifiable credentials cannot prevent the use of these other tracking technologies. Also, when these technologies are used in conjunction with verifiable credentials, new correlatable information could be discovered. For example, a birthday coupled with a GPS position can be used to strongly correlate an individual across multiple websites.

It is recommended that privacy-respecting systems prevent the use of these other tracking technologies when verifiable credentials are being used. In some cases, tracking technologies might need to be disabled on devices that transmit verifiable credentials on behalf of a holder.

7.7 Favor Abstract Claims

This section is non-normative.

To enable recipients of verifiable credentials to use them in a variety of circumstances without revealing more personally identifiable information than necessary for transactions, issuers should consider limiting the information published in a credential to a minimal set needed for the expected purposes. One way to avoid placing personally identifiable information in a credential is to use an abstract property that meets the needs of verifiers without providing specific information about a subject.

For example, this document uses the ageOver property instead of a specific birthdate, which constitutes much stronger personally identifiable information. If retailers in a specific market commonly require purchasers to be older than a certain age, an issuer trusted in that market might choose to offer a credential claiming that subjects have met that requirement instead of offering credentials containing claims about specific birthdates. This enables individual customers to make purchases without revealing specific personally identifiable information.

7.8 The Principle of Data Minimization

This section is non-normative.

Privacy violations occur when information divulged in one context leaks into another. Accepted best practice for preventing such violations is to limit the information requested, and received, to the absolute minimum necessary. This data minimization approach is required by regulation in multiple jurisdictions, including the Health Insurance Portability and Accountability Act (HIPAA) in the United States and the General Data Protection Regulation (GDPR) in the European Union.

With verifiable credentials, data minimization for issuers means limiting the content of a credential to the minimum required by potential verifiers for expected use. For verifiers, data minimization means limiting the scope of the information requested or required for accessing services.

For example, a driver's license containing a driver's ID number, height, weight, birthday, and home address is a credential containing more information than is necessary to establish that the person is above a certain age.

It is considered best practice for issuers to atomize information or use a signature scheme that allows for selective disclosure. For example, an issuer of driver's licenses could issue a credential containing every attribute that appears on a driver's license, as well as a set of credentials where every credential contains only a single attribute such as a person's birthday. It could also issue more abstract credentials (for example, a credential containing only an ageOver attribute). One possible adaptation would be for issuers to provide secure HTTP endpoints for retrieving single-use bearer credentials that promote the pseudonymous usage of credentials. Implementers that find this impractical or unsafe, should consider using selective disclosure schemes that eliminate dependence on issuers at proving time and reduce temporal correlation risk from issuers.

Verifiers are urged to only request information that is absolutely necessary for a specific transaction to occur. This is important for at least two reasons. It:

Note

While it is possible to practice the Principle of Minimum Disclosure, it might be impossible to avoid the strong identification of an individual for specific use cases during a single session or over multiple sessions. The authors of this document cannot stress how difficult it is to meet this principle in real-world scenarios.

7.9 Bearer Credentials

This section is non-normative.

A bearer credential is a privacy-enhancing piece of information, such as a concert ticket, which entitles the holder of the credential to a specific resource without divulging sensitive information about the holder. Bearer credentials are often used in low-risk use cases where the sharing of the credential is not a concern or would not result in large economic or reputational losses.

Verifiable credentials that are bearer credentials are made possible by not specifying the subject identifier, expressed using the id property, which is nested in the credentialSubject property. For example, the following verifiable credential is a bearer credential:

Example 32: Usage of issuer properties
{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.edu/credentials/temporary/28934792387492384",
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2017-10-22T12:23:48Z",
  "credentialSubject": {
    // note that the 'id' property is not specified for bearer credentials
    "degree": {
      "type": "BachelorDegree",
      "name": "<span lang='fr-CA'>Baccalauréat en musiques numériques</span>"
    }
  },
  "proof": { ... }
}

While bearer credentials can be privacy-enhancing, they must be carefully crafted so as not accidentally divulge more information than the holder of the credential expects. For example, repeated use of the same bearer credential across multiple sites enables these sites to potentially collude to unduly track or correlate the holder. Likewise, information that might seem non-identifying, such as a birthdate and postal code, can be used to statistically identify an individual when used together in the same credential or session.

Issuers of bearer credentials should ensure that the bearer credentials provide privacy-enhancing benefits that:

Holders should be warned by their software if bearer credentials containing sensitive information are issued or requested, or if there is a correlation risk when combining two or more bearer credentials across one or more sessions. While it might be impossible to detect all correlation risks, some might certainly be detectable.

Verifiers should not request bearer credentials that can be used to unduly correlate the holder.

7.10 Validity Checks

This section is non-normative.

When processing verifiable credentials, verifiers are expected to perform many of the checks listed in Appendix § A. Validation as well as a variety of specific business process checks. For example, validity checks might include checking:

The process of performing these checks might result in information leakage that leads to a privacy violation of the holder. For example, a simple operation like checking a revocation list can notify the issuer that a specific business is likely interacting with the holder. This could enable issuers to collude and correlate individuals without their knowledge.

Issuers are urged to not use mechanisms, such as credential revocation lists that are unique per credential, during the verification process that could lead to privacy violations. Organizations providing software to holders should warn when credentials include information that could lead to privacy violations during the verification process. Verifiers should consider rejecting credentials that produce privacy violations or that enable bad privacy practices.

7.11 Storage Providers and Data Mining

This section is non-normative.

When a holder receives a credential from an issuer, the credential needs to be stored somewhere (for example, in a credential repository). Holders are warned that the information in a verifiable credential is sensitive in nature and highly individualized, making it a high value target for data mining. Services that advertise free storage of verifiable credentials might in fact be mining personal data and selling it to organizations wanting to build individualized profiles on people and organizations.

Holders need to be aware of the terms of service for their credential repository, specifically the correlation and data mining protections in place for those who store their verifiable credentials with the service provider.

The following are some effective mitigations for data mining and profiling:

7.12 Aggregation of Credentials

This section is non-normative.

Holding two pieces of information about the same subject almost always reveals more about the subject than just the sum of two pieces of information, even when the information is delivered through different channels. The aggregation of credentials is a privacy risk and all participants in the ecosystem need to be aware of the risks of data aggregation.

For example, if two bearer credentials, one for an email address and then one stating the holder is over the age of 21, are provided across multiple sessions, the verifier of the information now has a unique identifier plus age-related information for the individual. It is now easy to create and build a profile for the holder such that more and more information is leaked over time. Aggregation of credentials can also be performed across multiple sites in collusion with each other, leading to privacy violations.

From a technological perspective, preventing the aggregation of information is a very difficult privacy problem to address. While new cryptographic techniques, such as zero-knowledge proofs, are being proposed as solutions to the problem of aggregation and correlation, the existence of long-lived identifiers and browser tracking techniques defeats even the most modern cryptographic techniques.

The solution to the privacy implications of correlation or aggregation tend not to be technological in nature, but policy driven instead. Therefore, if a holder does not want information about them to be aggregated, they must express this in the verifiable presentations they transmit.

7.13 Usage Patterns

This section is non-normative.

Despite the best efforts to assure privacy, actually using verifiable credentials can potentially lead to de-anonymization and a loss of privacy. This correlation can occur when:

In part, it is possible to mitigate this de-anonymization and loss of privacy by:

It is understood that these mitigation techniques are not always practical or even compatible with necessary usage. Sometimes correlation is a requirement.

For example, in some prescription drug monitoring programs, usage monitoring is a requirement. Enforcement entities need to be able to confirm that individuals are not cheating the system to get multiple prescriptions for controlled substances. This statutory or regulatory need to correlate usage overrides individual privacy concerns.

Verifiable credentials will also be used to intentionally correlate individuals across services, for example, when using a common persona to log in to multiple services, so all activity on each of those services is intentionally linked to the same individual. This is not a privacy issue as long as each of those services uses the correlation in the expected manner.

Privacy risks of credential usage occur when unintended or unexpected correlation arises from the presentation of verifiable credentials.

7.14 Sharing Information with the Wrong Party

This section is non-normative.

When a holder chooses to share information with a verifier, it might be the case that the verifier is acting in bad faith and requests information that could be used to harm the holder. For example, a verifier might ask for a bank account number, which could then be used with other information to defraud the holder or the bank.

Issuers should strive to tokenize as much information as possible such that if a holder accidentally transmits credentials to the wrong verifier, the situation is not catastrophic.

For example, instead of including a bank account number for the purpose of checking an individual's bank balance, provide a token that enables the verifier to check if the balance is above a certain amount. In this case, the bank could issue a verifiable credential containing a balance checking token to a holder. The holder would then include the verifiable credential in a verifiable presentation and bind the token to a credit checking agency using a digital signature. The verifier could then wrap the verifiable presentation in their digital signature, and hand it back to the issuer to dynamically check the account balance.

Using this approach, even if a holder shares the account balance token with the wrong party, an attacker cannot discover the bank account number, nor the exact value in the account. And given the validity period for the counter-signature, does not gain access to the token for more than a few minutes.

7.15 Frequency of Claim Issuance

This section is non-normative.

As detailed in Section § 7.13 Usage Patterns, usage patterns can be correlated into certain types of behavior. Part of this correlation is mitigated when a holder uses a verifiable credential without the knowledge of the issuer. Issuers can defeat this protection however, by making their credentials short lived and renewal automatic.

For example, an ageOver credential is useful for gaining access to a bar. If an issuer issues such a credential with a very short expiration date and an automatic renewal mechanism, then the issuer could possibly correlate the behavior of the holder in a way that negatively impacts the holder.

Organizations providing software to holders should warn them if they repeatedly use credentials with short lifespans, which could result in behavior correlation. Issuers should avoid issuing credentials in a way that enables them to correlate usage patterns.

7.16 Prefer Single-Use Credentials

This section is non-normative.

An ideal privacy-respecting system would require only the information necessary for interaction with the verifier to be disclosed by the holder. The verifier would then record that the disclosure requirement was met and forget any sensitive information that was disclosed. In many cases, competing priorities, such as regulatory burden, prevent this ideal system from being employed. In other cases, long-lived identifiers prevent single use. The design of any verifiable credentials ecosystem, however, should strive to be as privacy-respecting as possible by preferring single-use credentials whenever possible.

Using single-use credentials provides several benefits. The first benefit is to verifiers who can be sure that the data in a credential is fresh. The second benefit is to holders, who know that if there are no long-lived identifiers in the credential, the credential itself cannot be used to track or correlate them online. Finally, there is nothing for attackers to steal, making the entire ecosystem safer to operate within.

7.17 Private Browsing

This section is non-normative.

In an ideal private browsing scenario, no personally identifiable information (PII) will be revealed. Because many credentials include PII, organizations providing software to holders should warn them about the possibility of revealing PII if they wish to use credentials and presentations while in private browsing mode.

8. Security Considerations

This section is non-normative.

There are a number of security considerations that issuers, holders, and verifiers should be aware of when processing data described by this specification. Ignoring or not understanding the implications of this section can result in security vulnerabilities.

While this section attempts to highlight a broad set of security considerations, it is not a complete list. Implementers are urged to seek the advice of security and cryptography professionals when implementing mission critical systems using the technology outlined in this specification.

8.1 Cryptography Suites and Libraries

This section is non-normative.

Some aspects of the data model described in this specification can be protected through the use of cryptography. Implementers should be aware of the underlying cryptography suites and libraries used to implement the creation and verification of digital signatures and mathematical proofs used by their systems when processing credentials and presentations. Software developers with extensive experience implementing or auditing systems that use cryptography must be employed to ensure systems are properly designed. Proper red teaming is also suggested to remove bias from security reviews.

Cryptography suites and libraries have a shelf life and eventually fall to new attacks and technology advances. Production quality systems must take this into account and ensure mechanisms exist to easily and proactively upgrade expired or broken cryptography suites and libraries. Procedures should also exist to invalidate and replace existing credentials in the event of a cryptography suite or library failure. Regular monitoring of systems to ensure proper upgrades are made in a timely manner are also important to ensure the long term viability of systems processing verifiable credentials.

8.2 Content Integrity Protection

This section is non-normative.

Verifiable credentials often contain URLs to data that resides outside of the credential itself. Content that exists outside a verifiable credential, such as links to images, JSON-LD Contexts, and other machine-readable data, are often not protected against tampering because the data resides outside of the protection of the proof on the verifiable credential. For example, the following highlighted links are not content-integrity protected and probably should be:

While this specification does not recommend any particular content integrity protection, document authors that would like to ensure that links to content are integrity protected are advised to use URL schemes that enforce content integrity. Two such schemes are the Hashlink specification and the InterPlanetary File System (IPFS). The example below transforms the example above and adds content integrity protection to the JSON-LD Contexts using the Hashlink specification, and content integrity protection to the image by using an IPFS link:

Note

It is debatable whether or not the JSON-LD Contexts above need protection as it is expected that production implementations will ship with static copies of important JSON-LD Contexts.

While the example above is one way to achieve content integrity protection, there are other solutions that may be better suited for certain applications. Implementers are urged to understand how links to external machine-readable content that are not content-integrity protected may result in successful attacks against their applications.

8.3 Unsigned Claims

This section is non-normative.

This specification allows credentials to be produced that do not contain signatures or proofs of any kind. These types of credentials are often useful for intermediate storage, or self-asserted information, which is analogous to filling out a form on a web page. Implementers should note that these types of credentials are not verifiable because the authorship is either not known or cannot be trusted.

8.4 Token Binding

This section is non-normative.

A verifier might need to ensure it is the intended recipient of a verifiable presentation and not the target of a man-in-the-middle attack. Any protocol using the Verifiable Credentials Data Model that requires protection against these kinds of attacks needs to perform some sort of token binding, such as The Token Binding Protocol v1.0, which ties the request for a verifiable presentation with the response. Any protocol that does not perform token binding is susceptible to man-in-the-middle attacks.

8.5 Bundling Dependent Claims

This section is non-normative.

It is considered best practice for issuers to atomize information in a credential, or use a signature scheme that allows for selective disclosure. In the case of atomization, if it is not done securely by the issuer, the holder might bundle together different credentials in a way that was not intended by the issuer.

For example a university might issue two credentials to a person, each containing two properties, for example, "Staff Member" in the "Department of Computing" and "Post Graduate Student" in the "Department of Economics". If these credentials are atomized into separate properties, then the university would issue four credentials to the person, each containing one of the following properties, "Staff Member", "Post Graduate Student", "Department of Computing", and "Department of Economics". The holder could then transfer the "Staff Member" and "Department of Economics" credentials to a verifier, which together would comprise a false claim.

8.6 Highly Dynamic Information

This section is non-normative.

When verifiable credentials are issued for highly dynamic information, implementers should ensure the expiration times are set appropriately. Expiration periods longer than the timeframe where the credential is valid might create exploitable security vulnerabilities. Expiration periods shorter than the timeframe where the information expressed by the credential is valid creates a burden on holders and verifiers. It is therefore important to set validity periods for credentials that are appropriate to the use case and the expected lifetime for the information contained in the credential.

8.7 Device Theft and Impersonation

This section is non-normative.

When verifiable credentials are stored on a device and that device is lost or stolen, it might be possible for an attacker to gain access to systems using the victim's verifiable credentials. Ways to mitigate this type of attack include:

9. Accessibility Considerations

This section is non-normative.

There are a number of accessibility considerations implementers should be aware of when processing data described in this specification. As with any web standards or protocols implementation, ignoring accessibility issues makes this information unusable to a large subset of the population. It is important to follow accessibility guidelines and standards, such as [WCAG21], to ensure all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which historically, have created problems for assistive technologies.

This section details the general accessibility considerations to take into account when utilizing this data model.

9.1 Data First Approaches

This section is non-normative.

Many physical credentials in use today, such as government identification cards, have poor accessibility characteristics, including, but not limited to, small print, reliance on small and high-resolution images, and no affordances for people with vision impairments.

When utilizing this data model to create verifiable credentials, it is suggested that data model designers use a data first approach. For example, given the choice of using data or a graphical image to depict a credential, designers should express every element of the image, such as the name of an institution or the professional credential, in a machine-readable way instead of just relying on the image to convey this information. Using a data first approach is preferred because it provides the foundational elements of building different interfaces for people with varying abilities.

10. Internationalization Considerations

This section is non-normative.

There are a number of internationalization considerations implementers should be aware of when publishing data described in this specification. As with any web standards or protocols implementation, ignoring internationalization makes it difficult for data to be produced and consumed across a disparate set of languages and societies, which would limit the applicability of the specification and significantly diminish its value as a standard.

This section outlines general internationalization considerations to take into account when utilizing this data model.

10.1 Language Declarations

This section is non-normative.

When expressing human-readable text content in the data model, it is important for presentation, accessibility, and further processing to specify the language of the text.

10.2 Text direction

This section is non-normative.

When expressing human-readable text content in the data model, it is important to be able to explicitly encode the text direction. JSON and its derived formats use the UTF-8 encoding of [Unicode] for serializing and transmitting text. This enables text direction to be directly determined in simple cases, but the mechanism is insufficient for general use.

JSON-LD supports the expression of text layout information via the rdf:HTML string literal type, which is described in JSON-LD 1.0, Section 4.2.1: Typed Values. This mechanism enables a developer to use the internationalization features present in HTML to express language information. For example, consider the following key-value pair: "nameHtml": "<span dir="rtl" lang="ar">HTML و CSS: تصميم و إنشاء مواقع الويب</span>". If the JSON-LD Context states that any value associated with the nameHtml property is of type rdf:HTML, then software agents have sufficient information to deterministically identify the text direction of the language.

10.3 Ruby Text

This section is non-normative.

In some situations it is common to use Ruby characters) to ensure that text information is clear and as useful as possible. JSON-LD's support for HTML data allows text to be encoded with ruby, supporting these cases.

10.4 Further information

This section is non-normative.

The W3C Internationalisation document [string-meta] gives more information about the need to be able to provide reliable metadata about text to support internationalization

A. Validation

This section is non-normative.

While this specification does not provide conformance criteria for the process of the validation of verifiable credentials or verifiable presentations, readers may be curious about how the information in this data model is expected to be utilized by verifiers during the process of validation. This section captures a selection of conversations held by the Working Group related to the expected usage of the data fields in this specification by verifiers.

A.1 Credential Subject

This section is non-normative.

In the verifiable credentials presented by a holder, the value associated with the id property for each credentialSubject is expected to identify a subject to the verifier. If the holder is also the subject, then the verifier could authenticate the holder if they have public key metadata related to the holder. The verifier could then authenticate the holder using a signature generated by the holder contained in the verifiable presentation. The id property is optional. Verifiers could use other properties in a verifiable credential to uniquely identify a subject.

Note

For information on how authentication and WebAuthn might work with verifiable credentials, please refer to the Verifiable Credentials Implementation Guidelines.

A.2 Issuer

This section is non-normative.

The value associated with the issuer property is expected to identify an issuer that is known to and trusted by the verifier.

Relevant metadata about the issuer property is expected to be available to the verifier. For example, an issuer can publish information containing the public keys it uses to digitally sign verifiable credentials that it issued. This metadata is relevant when checking the proofs on the verifiable credentials.

A.3 Issuance Date

This section is non-normative.

The issuanceDate is expected to be within an expected range for the verifier. For example, a verifier can ensure that the issuance date of a verifiable credential is not in the future.

A.4 Proofs (Signatures)

This section is non-normative.

The cryptographic mechanism used to prove that the information in a verifiable credential or a verifiable presentation has not been tampered with is called a proof. There are many types of cryptographic proofs including, but not limited to, digital signatures, zero-knowledge proofs, Proofs of Work, and Proofs of Stake. In general, when verifying proofs implementations are expected to ensure that:

Some proofs are digital signatures. In general, when verifying digital signatures, implementations are expected to ensure that:

Note

The digital signature provides a number of protections, other than tamper resistance, that are not immediately obvious. For example, a Linked Data Signature created property establishes a date and time before which the credential should not be considered verified. The creator property enables the ability to dynamically discover information about the entity who created the data to ensure that the public key is not revoked or expired. The proofPurpose property ensures the reason the entity created the signature, such as for authentication or creating a verifiable credential, is clear and protected in the signature.

A.5 Expiration

This section is non-normative.

The expirationDate is expected to be within an expected range for the verifier. For example, a verifier can ensure that the expiration date of a verifiable credential is not in the past.

A.6 Status

This section is non-normative.

If the credentialStatus property is available, the status of a verifiable credential is expected to be evaluated by the verifier according to the credentialStatus type definition for the verifiable credential and the verifier's own status evaluation criteria. For example, a verifier can ensure that the status of the verifiable credential was withdrawn for cause by the issuer.

A.7 Fitness for Purpose

This section is non-normative.

The custom properties in the verifiable credential are appropriate for the verifier's purpose. For example if a verifier needs to determine whether a subject is older than 21 years of age, they might rely on a specific birthdate property, or more abstract properties, such as ageOver.

The issuer is trusted by the verifier to make the claims at hand. For example, a franchised fast food restaurant location trusts discount coupon claims made by the corporate headquarters of the franchise. Policy information expressed by the issuer in the verifiable credential should be respected by holders and verifiers unless they accept the liability of ignoring the policy.

B. Subject-Holder Relationships

This section is non-normative.

This section describes the possible relationships between a subject and a holder and how the Verifiable Credentials Data Model expresses these relationships. The following diagram illustrates the different types of relationships covered in the rest of this section.

Long decision tree
          from top to bottom.  For the first question, 'Subject
          Present?', No means Bearer Credential and Yes points to the
          rest of the tree.  From this point on until the very end,
          each Yes points to an answer and each No points to another
          question.  The first question here is 'Subject = Holder?',
          with Yes meaning Most Common Use Case.  If No, 'Credential
          Uniquely Identifies Subject?' with Yes meaning Irrelevant who
          Holder is.  If No, 'Subject Passes VC to Holder?' with Yes
          meaning E.g. Power of Attorney, Employee.  If No, 'Issuer
          Independently Authorises Holder?' with Yes meaning E.g. Law
          Enforcement.  If No, 'Holder Acts for Subject?' with Yes
          meaning E.g. Parent, Pet Owner, Travel Agent.  If No,
          'Holder Acts for Verifier?' with Yes meaning E.g. Recruiter
          passing on VC of job applicant to employer and No meaning
          'Random Holder with no relationship to Subject, Issuer or Verifier
Figure 12 Subject-Holder Relationships in Verifiable Credentials.

The following sections describe how each of these relationships are handled in the data model.

B.1 Subject is the Holder

This section is non-normative.

The most common relationship is when a subject is the holder. In this case, a verifier can easily deduce that a subject is the holder if the verifiable presentation is digitally signed by the holder and all contained verifiable credentials are about a subject that can be identified to be the same as the holder.

If only the credentialSubject is allowed to insert a verifiable credential into a verifiable presentation, the issuer MAY insert the nonTransferable property into the verifiable credential, as described below.

Issue 9

The nonTransferable feature is at risk and is likely to be removed due to lack of consensus.

B.1.1 nonTransferable Property

This section is non-normative.

The nonTransferable property states that a verifiable credential MUST only be encapsulated into a verifiable presentation whose proof was issued by the credentialSubject. A verifiable presentation that contains a verifiable credential containing the nonTransferable property, whose proof creator is not the credentialSubject, is invalid.

Example 35: Usage of the nonTransferable property
{
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "ProofOfAgeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageOver": 21
    },
  "nonTransferable": "True",
  "proof": { ..
  "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  ... }
}

B.2 Credential Uniquely Identifies a Subject

This section is non-normative.

In this case, the credentialSubject property might contain multiple properties each providing an aspect of the identity of the subject, which together, unambiguously identify the subject. Some use cases might not require the holder to be identified at all, such as checking to see if a doctor (the subject) is board-certified. Other use cases might require the verifier to use out-of-band knowledge to determine the relationship between the subject and the holder.

Example 36: A credential uniquely identifying a subject
{
  "@context": ["https://www.w3.org/2018/credentials/v1", "https://schema.org/"]
  "id": "http://example.edu/credentials/332",
  "type": ["VerifiableCredential", "IdentityCredential"],
  "issuer": "https://example.edu/issuers/4",
  "issuanceDate": "2017-02-24T19:73:24Z",
  "credentialSubject": {
    "name": "J. Doe",
    "address": {
      "streetAddress": "10 Rue de Chose",
      "postalCode": "98052",
      "addressLocality": "Paris",
      "addressCountry": "FR"
    },
    "birthDate": "1989-03-15"
    ...
  },
  "proof": { ... }
}

The example above uniquely identifies the subject using the name, address, and birthdate of the individual.

B.3 Subject Passes the Verifiable Credential to a Holder

This section is non-normative.

Usually verifiable credentials are presented to verifiers by the subject. However in some cases, the subject might need to pass the whole or part of a verifiable credential to another holder. For example, if a patient (the subject) is too ill to take a prescription (the verifiable credential) to the pharmacist (the verifier), a friend might take the prescription in to pick up the medication.

The data model allows for this, by the subject issuing a new verifiable credential and giving it to the new holder, who can then present both verifiable credentials to the verifier. However, the content of this second verifiable credential is likely to be application specific, so this specification cannot standardize the contents of this second verifiable credential. Nevertheless, a non-normative example is provided in Appendix § B.5 Subject Passes a Verifiable Credential to Someone Else.

B.4 Holder Acts on Behalf of the Subject

This section is non-normative.

The Verifiable Credentials Data Model supports the holder acting on behalf of the subject in at least the following ways. The:

The mechanisms listed above describe the relationship between the holder and the subject and helps the verifier decide whether the relationship is sufficiently expressed for a given use case.

Note

The additional mechanisms the issuer or the verifier uses to verify the relationship between the subject and the holder are outside the scope of this specification.

Example 37: The relationship property in a child's credential
{
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "AgeCredential", "RelationshipCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "ageUnder": 16,
    "parent": {
      "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
      "type": "Mother"
    }
  },
  "proof": { ... } // the proof is generated by the DMV
}

In the example above, the issuer expresses the relationship between the child and the parent such that a verifier would most likely accept the credential if it is provided by the child or the parent.

Example 38: A relationship credential issued to a parent
{
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "RelationshipCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
    "child": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "type": "Child"
    }
  },
  "proof": { ... } // the proof is generated by the DMV
}

In the example above, the issuer expresses the relationship between the child and the parent in a separate credential such that a verifier would most likely accept any of the child's credentials if they are provided by the child or if the credential above is provided with any of the child's credentials.

Example 39: A relationship credential issued by a child
{
  "id": "http://example.org/credentials/23894",
  "type": ["VerifiableCredential", "RelationshipCredential"],
  "issuer": "http://example.org/credentials/23894",
  "issuanceDate": "2010-01-01T19:23:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "parent": {
      "id": "did:example:ebfeb1c276e12ec211f712ebc6f",
      "type": "Mother"
    }
  },
  "proof": { ... } // the proof is generated by the child
}

In the example above, the child expresses the relationship between the child and the parent in a separate credential such that a verifier would most likely accept any of the child's credentials if the credential above is provided.

Similarly, the strategies described in the examples above can be used for many other types of use cases, including power of attorney, pet ownership, and patient prescription pickup.

B.5 Subject Passes a Verifiable Credential to Someone Else

This section is non-normative.

When a subject passes a verifiable credential to another holder, the subject might issue a new verifiable credential to the holder in which the:

The holder can now create a verifiable presentation containing these two verifiable credentials so that the verifier can verify that the subject gave the original verifiable credential to the holder.

Example 40: A holder presenting a verifiable credential that was passed to it by the subject
{
  "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
  "type": ["VerifiablePresentation"],
  "credential": [
    {
      "id": "http://example.gov/credentials/3732",
      "type": ["VerifiableCredential", "PrescriptionCredential"],
      "issuer": "https://example.edu",
      "issuanceDate": "2010-01-01T19:73:24Z",
      "credentialSubject": {
        "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
        "prescription": {....}
      },
      "revocation": {
        "id": "http://example.gov/revocations/738",
        "type": "SimpleRevocationList2017"
      },
      "proof": {....}
    },
    {
      "id": "https://example.com/VC/123456789",
      "type": ["VerifiableCredential", "PrescriptionCredential"],
      "issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "issuanceDate": "2010-01-03T19:73:24Z",
      "credentialSubject": {
        "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2",
        "prescription": {....}
      },
      "proof": {
        "type": "RsaSignature2018",
        "created": "2018-06-17T10:03:48Z",
        "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/234",
        "signatureValue": "pYw8XNi1..Cky6Ed="
      }
    }
  ],
  "proof": [{
    "type": "RsaSignature2018",
    "created": "2018-06-18T21:19:10Z",
    "verificationMethod": "did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2",
    "nonce": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e",
    "signatureValue": "BavEll0/I1..W3JT24="
  }]
}

In the above example, a patient (the original subject) passed a prescription (the original verifiable credential) to a friend, and issued a new verifiable credential to the friend, in which the friend is the subject, the original subject is the issuer, and the credential is a copy of the original prescription.

B.6 Issuer Authorises Holder

This section is non-normative.

When an issuer wants to authorize a holder to possess a credential that describes a subject who is not the holder, and the holder has no known relationship with the subject, then the issuer inserts the relationship of the holder to itself into the credential for the subject.

Note

Verifiable credentials are not an authorization framework and therefore delegation is out of scope for this specification. However, it is understood that verifiable credentials are likely to be used to build authorization and delegation systems. The following is one approach that may be appropriate for some use cases.

When an issuer wants to authorise a holder to possess a credential that describes a subject who is not the holder, and the holder has no known relationship with the subject, then the issuer might insert the relationship of the holder to itself into the subject's credential.

Example 41: A credential issued to a holder who is not the subject of the credential, who has no relationship with the subject of the credential, but who has a relationship with the issuer
{
  "id": "http://example.edu/credentials/3732",
  "type": ["VerifiableCredential", "NameAndAddress"],
  "issuer": "https://example.edu/issuers/14",
  "holder": {
    "type": "LawEnforcement",
    "id": "did:example:ebfeb1276e12ec21f712ebc6f1c"
  },
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": {
    "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
    "name": "Mr John Doe",
    "address": "10 Some Street, Anytown, ThisLocal, Country X"
  },
  "proof": {
    "type": "RsaSignature2018",
    "created": "2018-06-17T10:03:48Z",
    "verificationMethod": "https://example.edu/issuers/14/keys/234",
    "signatureValue": "pY9...Cky6Ed = "
  }
}

B.7 Holder Acts on Behalf of the Verifier, or has no Relationship with the Subject, Issuer, or Verifier

This section is non-normative.

The Verifiable Credentials Data Model currently does not support either of these scenarios. It is for further study how they might be supported.

C. References

C.1 Normative references

[JSON-LD]
JSON-LD 1.0. Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/json-ld/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[RFC3339]
Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://tools.ietf.org/html/rfc3339
[RFC7515]
JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7515
[RFC7516]
JSON Web Encryption (JWE). M. Jones; J. Hildebrand. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7516
[RFC7519]
JSON Web Token (JWT). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://tools.ietf.org/html/rfc7519
[RFC8259]
The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://tools.ietf.org/html/rfc8259

C.2 Informative references

[DEMOGRAPHICS]
Simple Demographics Often Identify People Uniquely. Latanya Sweeney. Data Privacy Lab. URL: http://dataprivacylab.org/projects/identifiability/paper1.pdf
[JSON-SCHEMA]
JSON Schema: core definitions and terminology. K. Zyp. Internet Engineering Task Force (IETF). 31 January 2013. Internet-Draft. URL: https://tools.ietf.org/html/draft-zyp-json-schema
[LD-PROOFS]
Linked Data Proofs. Manu Sporny; Dave Longley. Digital Verification Community Group. CG-DRAFT. URL: https://w3c-dvcg.github.io/ld-proofs/
[LD-SIGNATURES]
Linked Data Signatures. Manu Sporny; Dave Longley. Digital Verification Community Group. CG-DRAFT. URL: https://w3c-dvcg.github.io/ld-signatures/
[LINKED-DATA]
Linked Data Design Issues. Tim Berners-Lee. W3C. 27 July 2006. W3C-Internal Document. URL: https://www.w3.org/DesignIssues/LinkedData.html
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://tools.ietf.org/html/rfc3986
[string-meta]
Requirements for Language and Direction Metadata in Data Formats. Addison Phillips; Richard Ishida. Internationalization Working Group. Editors-DRAFT. URL: https://w3c.github.io/string-meta/
[Unicode]
The Unicode Standard. Unicode Consortium. URL: https://www.unicode.org/versions/latest/
[VC-STATUS-REGISTRY]
Verifiable Credentials Status Scheme Registry. Manu Sporny. Credentials Community Group. CG-DRAFT. URL: https://w3c-ccg.github.io/vc-status-registry/
[VC-USECASES]
Verifiable Claims Use Cases. Shane McCarron; Daniel Burnett; Gregg Kellogg; Brian Sletten; Manu Sporny. Verifiable Claims Working Group. W3C Note. URL: https://www.w3.org/TR/verifiable-claims-use-cases/
[WCAG21]
Web Content Accessibility Guidelines (WCAG) 2.1. Andrew Kirkpatrick; Joshue O Connor; Alastair Campbell; Michael Cooper. W3C. 5 June 2018. W3C Recommendation. URL: https://www.w3.org/TR/WCAG21/