Verifiable Credentials Data Model v1.1 (original) (raw)

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 section describes the status of this document at the time of its publication. 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 specification are welcome at any time, but readers should be aware that the comment period regarding this specific version of the document have ended and the Working Group will not be making substantive modifications to this version of the specification at this stage. Please file issues directly onGitHub, or send them topublic-vc-comments@w3.org(subscribe,archives).

The Working Group has received implementation feedback showing that there are at least two implementations for each normative feature in the specification. The group has obtained reports from fourteen (14) implementations. For details, see the test suite and implementation report.

This document was published by the Verifiable Credentials Working Group as a Recommendation using theRecommendation track.

W3C recommends the wide deployment of this specification as a standard for the Web.

A W3C Recommendation is a specification that, after extensive consensus-building, is endorsed byW3C and its Members, and has commitments from Working Group members toroyalty-free licensing for implementations.

This document was produced by a group operating under theW3C Patent Policy.W3C maintains apublic 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 containsEssential Claim(s) must disclose the information in accordance withsection 6 of the W3C Patent Policy.

This document is governed by the2 November 2021 W3C Process Document.

Table of Contents

  1. Abstract
  2. Status of This Document
  3. 1. Introduction
    1. 1.1 What is a Verifiable Credential?
    2. 1.2 Ecosystem Overview
    3. 1.3 Use Cases and Requirements
    4. 1.4 Conformance
  4. 2. Terminology
  5. 3. Core Data Model
    1. 3.1 Claims
    2. 3.2 Credentials
    3. 3.3 Presentations
    4. 3.4 Concrete Lifecycle Example
  6. 4. Basic Concepts
    1. 4.1 Contexts
    2. 4.2 Identifiers
    3. 4.3 Types
    4. 4.4 Credential Subject
    5. 4.5 Issuer
    6. 4.6 Issuance Date
    7. 4.7 Proofs (Signatures)
    8. 4.8 Expiration
    9. 4.9 Status
    10. 4.10 Presentations
  7. 5. Advanced Concepts
    1. 5.1 Lifecycle Details
    2. 5.2 Trust Model
    3. 5.3 Extensibility
    4. 5.4 Data Schemas
    5. 5.5 Refreshing
    6. 5.6 Terms of Use
    7. 5.7 Evidence
    8. 5.8 Zero-Knowledge Proofs
    9. 5.9 Disputes
    10. 5.10 Authorization
  8. 6. Syntaxes
    1. 6.1 JSON
    2. 6.2 JSON-LD
    3. 6.3 Proof Formats
  9. 7. Privacy Considerations
    1. 7.1 Spectrum of Privacy
    2. 7.2 Personally Identifiable Information
    3. 7.3 Identifier-Based Correlation
    4. 7.4 Signature-Based Correlation
    5. 7.5 Long-Lived Identifier-Based Correlation
    6. 7.6 Device Fingerprinting
    7. 7.7 Favor Abstract Claims
    8. 7.8 The Principle of Data Minimization
    9. 7.9 Bearer Credentials
    10. 7.10 Validity Checks
    11. 7.11 Storage Providers and Data Mining
    12. 7.12 Aggregation of Credentials
    13. 7.13 Usage Patterns
    14. 7.14 Sharing Information with the Wrong Party
    15. 7.15 Frequency of Claim Issuance
    16. 7.16 Prefer Single-Use Credentials
    17. 7.17 Private Browsing
    18. 7.18 Issuer Cooperation Impacts on Privacy
  10. 8. Security Considerations
  11. 8.1 Cryptography Suites and Libraries
  12. 8.2 Content Integrity Protection
  13. 8.3 Unsigned Claims
  14. 8.4 Token Binding
  15. 8.5 Bundling Dependent Claims
  16. 8.6 Highly Dynamic Information
  17. 8.7 Device Theft and Impersonation
  18. 9. Accessibility Considerations
  19. 9.1 Data First Approaches
  20. 10. Internationalization Considerations
  21. 10.1 Language and Base Direction
  22. 10.2 Complex Language Markup
  23. A. Validation
  24. A.1 Credential Subject
  25. A.2 Issuer
  26. A.3 Issuance Date
  27. A.4 Proofs (Signatures)
  28. A.5 Expiration
  29. A.6 Status
  30. A.7 Fitness for Purpose
  31. B. Contexts, Types, and Credential Schemas
  32. B.1 Base Context
  33. B.2 Differences between Contexts, Types, and CredentialSchemas
  34. C. Subject-Holder Relationships
  35. C.1 Subject is the Holder
  36. C.2 Credential Uniquely Identifies a Subject
  37. C.3 Subject Passes the Verifiable Credential to a Holder
  38. C.4 Holder Acts on Behalf of the Subject
  39. C.5 Subject Passes a Verifiable Credential to Someone Else
  40. C.6 Issuer Authorizes Holder
  41. C.7 Holder Acts on Behalf of the Verifier, or has no Relationship with the Subject, Issuer, or Verifier
  42. D. IANA Considerations
  43. E. Revision History
  44. F. Acknowledgements
  45. G. References
  46. G.1 Normative references
  47. G.2 Informative references

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 verifiedmachine-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 toverifiable credentials, the following sections provide an overview of:

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 generateverifiable presentations and then share theseverifiable presentations with verifiers to prove they possessverifiable 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 digitalcredentials, 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 Section7. 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.

The word "verifiable" in the termsverifiable credential and verifiable presentationrefers to the characteristic of a credential or presentationas being able to be verified by a verifier, as defined in this document. Verifiability of a credential does not imply that the truth of claims encoded therein can be evaluated; however, the issuer can include values in the evidence property to help the verifier apply their business logic to determine whether the claims have sufficient veracity for their needs.

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 moreverifiable credentials and generating verifiable presentationsfrom them. Example holders include students, employees, and customers.

issuer

A role an entity performs by asserting claims about one or more subjects, creating a verifiable credential from theseclaims, and transmitting the verifiable credential to aholder. Example issuers include corporations, non-profit organizations, trade associations, governments, and individuals.

subject

An entity about which claims are made. Example subjects include human beings, animals, and things. In many cases the holder of averifiable credential is the subject, but in certain cases it is not. For example, a parent (the holder) might hold theverifiable 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 C. Subject-Holder Relationships.

verifier

A role an entity performs by receiving one or moreverifiable credentials, optionally inside averifiable presentation, for processing. Example verifiers include employers, security personnel, and websites.

verifiable data registry

A role a system might perform by mediating the creation and verificationof identifiers, keys, and other relevant data, such asverifiable credential schemas, revocation registries, issuer public keys, and so on, 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

Figure 1 above provides an example ecosystem in which to ground the rest of the concepts in this specification. Other ecosystems exist, such as protected environments or proprietary systems, whereverifiable credentials also provide benefit.

This section is non-normative.

The Verifiable Credentials Use Cases document [VC-USE-CASES] 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:

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 in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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 Sections4. Basic Concepts, 5. Advanced Concepts, and6. Syntaxes of this document MUST be enforced. A serialization format for the conforming document MUST be deterministic, bi-directional, and lossless as described in Section 6. Syntaxes. The conforming document MAY be transmitted or stored in any such serialization format.

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.

Digital proof mechanisms, a subset of which are digital signatures, are required to ensure the protection of a verifiable credential. Having and validating proofs, which may be dependent on the syntax of the proof (for example, using the JSON Web Signature of a JSON Web Token for proofing a key holder), are an essential part of processing a verifiable credential. At the time of publication, Working Group members had implementedverifiable credentials using at least three proof mechanisms:

Implementers are advised to note that not all proof mechanisms are standardized as of the publication date of this specification. The group expects some of these mechanisms, as well as new ones, to mature independently and become standardized in time. Given there are multiple valid proof mechanisms, this specification does not standardize on any single digital signature mechanism. One of the goals of this specification is to provide a data model that can be protected by a variety of current and future digital proof mechanisms. Conformance to this specification does not depend on the details of a particular proof mechanism; it requires clearly identifying the mechanism averifiable credential uses.

This document also contains examples that contain JSON and JSON-LD content. Some of these examples contain characters that are invalid JSON, such as inline comments (//) and the use of ellipsis (...) to denote information that adds little value to the example. Implementers are cautioned to remove this content if they desire to use the information as valid JSON or JSON-LD.

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. Averifiable credential is a tamper-evident credential that has authorship that can be cryptographically verified. Verifiable credentials can be used to buildverifiable 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 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 averifiable credential and are associated with subjects such that averifiable credential itself can be easily ported from onerepository to another without the need to reissue the credential. An example of a DID is did:example:123456abcdef.

decentralized identifier document

Also referred to as a DID document, this is a document that is accessible using a 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 averifiable credential. These are useful in zero-knowledge-proof-styleverifiable 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 verifiable credentialdemonstrating 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.

entity

A thing with distinct and independent existence, such as a person, organization, or device that performs 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 might perform by possessing one or moreverifiable credentials and generating presentations from them. A holder is usually, but not always, a subject of the verifiable credentials they are holding. Holders store their credentials incredential repositories.

identity provider

An identity provider, sometimes abbreviated as IdP, is a system for creating, maintaining, and managing identity information forholders, while providing authentication services torelying party applications within a federation or distributed network. In this case the holder is always the subject. Even if theverifiable credentials are bearer credentials, it is assumed theverifiable 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 providerconcept into two distinct concepts: the issuer and the holder.

issuer

A role an entity can perform by asserting claims about one or more subjects, creating a verifiable credential from theseclaims, and transmitting the verifiable credential to aholder.

presentation

Data derived from one or more verifiable credentials, issued by one or more issuers, that is shared with a specific verifier. Averifiable presentationis 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 credentialwallet, that stores and protects access to holders' verifiable credentials.

selective disclosure

The ability of a holder to make fine-grained decisions about what information to share.

subject

A thing about which claims are made.

validation

The assurance that a verifiable credential or averifiable 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 orverifiable presentations is outside the scope of this specification.

verifiable data registry

A role a system might perform by mediating the creation and verificationof identifiers, keys, and other relevant data, such asverifiable credential schemas, revocation registries, issuer public keys, and so on, which might be required to use verifiable credentials. Some configurations might require correlatable identifiers for subjects. Some registries, such as ones for UUIDs and public keys, might just act as namespaces for identifiers.

verification

The evaluation of whether a verifiable credential or verifiable presentationis an authentic and timely statement of the issuer or presenter, respectively. This includes checking that: the credential (or presentation) conforms to the specification; the proof method is satisfied; and, if present, the status check succeeds. Verification of a credential does not imply evaluation of the truth of claims encoded in the credential..

verifier

A role an entity performs by receiving one or moreverifiable credentials, optionally inside averifiable presentation for processing. Other specifications might refer to this concept as a relying party.

URI

A Uniform Resource Identifier, as defined by [RFC3986].

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.

This section is non-normative.

A claim is a statement about a subject. A subject is a thing 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, illustrated in Figure 2above, 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 in [Figure 3](#basic-example "A basic claim expressing that Pat is an alumni of "Example University".") 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 shown inFigure 4 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 is expected to be added to the graph.

This section is non-normative.

A credential is a set of one or more claims made by the sameentity. Credentials might also include an identifier and metadata to describe properties of the credential, such as theissuer, 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. Averifiable 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. Aholder 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 averifiable credential, but abstracts the details about how claimsare organized into information graphs, which are then organized intoverifiable 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 graphexpresses the verifiable 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:23: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, 'verificationMethod' of Example University Public Key 7, 'created' of 2017-06-18T21:19:10Z, and 'jws' 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.

Note

It is possible to have a credential that does not contain anyclaims about the entity to which the credential was issued. For example, a credential that only contains claims about a specific dog, but is issued to its owner.

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 averifiable 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 moreverifiable credentials, and is packaged in such a way that the authorship of the data is verifiable. If verifiable credentialsare presented directly, they become verifiable presentations. Data formats derived from verifiable credentials that are cryptographicallyverifiable, but do not of themselves containverifiable credentials, might also be verifiable presentations.

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

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 averifiable presentation, but abstracts the details about howverifiable credentials are organized into information graphs, which are then organized into verifiable presentations.

Figure 8 below shows a more complete depiction of averifiable presentation, which is normally composed of at least four information graphs. The first of these information graphs, the Presentation Graph, expresses the verifiable presentationitself, which contains presentation metadata. TheverifiableCredential property in the Presentation Graphrefers to one or more verifiable credentials, each being one of the second information graphs, i.e., a self-contained CredentialGraph, which in turn contains credential metadata and claims. The third information graph, the Credential Proof Graph, expresses the credential graph proof, which is usually a digital signature. The fourth information graph, the Presentation Proof 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, 'verificationMethod' of Example Presenter Public Key 11, 'created' of 2018-01-15T12:43:56Z, 'challenge' of d28348djsj3239, and 'jws' 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.

This section is non-normative.

The previous sections introduced the concepts of claims,verifiable credentials, and verifiable 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 credentialsand presentations in theVerifiable 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 averifiable presentation for verifiers.
  4. Verification of the verifiable presentation by theverifier.

To illustrate this lifecycle, we will use the example of redeeming an alumni discount from a university. In the example below, Pat receives an alumniverifiable credential from a university, and Pat stores theverifiable credential in a digital wallet.

Example 1

: A simple example of a verifiable credential

{

"@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ],

"id": "http://example.edu/credentials/1872",

"type": ["VerifiableCredential", "AlumniCredential"],

"issuer": "https://example.edu/issuers/565049",

"issuanceDate": "2010-01-01T19:23:24Z",

"credentialSubject": {

"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",

"alumniOf": {
  "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
  "name": [{
    "value": "Example University",
    "lang": "en"
  }, {
    "value": "Exemple d'Université",
    "lang": "fr"
  }]
}

},

"proof": {

"type": "RsaSignature2018",

"created": "2017-06-18T21:19:10Z",

"proofPurpose": "assertionMethod",

"verificationMethod": "https://example.edu/issuers/565049#key-1",

"jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
  sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
  X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
  PAYuNzVBAh4vGHSrQyHUdBBPM"

} }

Pat then attempts to redeem the alumni 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 this process requests an alumniverifiable credential, and this request is routed to Pat's digital wallet. The digital wallet asks Pat if they would like to provide a previously issuedverifiable credential. Pat selects the alumniverifiable credential, which is then composed into averifiable presentation. The verifiable presentation is 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",

"verifiableCredential": [{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "id": "http://example.edu/credentials/1872", "type": ["VerifiableCredential", "AlumniCredential"], "issuer": "https://example.edu/issuers/565049", "issuanceDate": "2010-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": [{ "value": "Example University", "lang": "en" }, { "value": "Exemple d'Université", "lang": "fr" }] } }, "proof": { "type": "RsaSignature2018", "created": "2017-06-18T21:19:10Z", "proofPurpose": "assertionMethod", "verificationMethod": "https://example.edu/issuers/565049#key-1", "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj PAYuNzVBAh4vGHSrQyHUdBBPM" } }],

"proof": { "type": "RsaSignature2018", "created": "2018-09-14T21:19:10Z", "proofPurpose": "authentication", "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1",

"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"domain": "4jt78h47fh47",
"jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..kTCYt5
  XsITJX1CxPCT8yAV-TVIw5WEuts01mq-pQy7UJiN5mgREEMGlv50aqzpqh4Qq_PbChOMqs
  LfRoPsnsgxD-WUcX16dUOqV0G_zS245-kronKb78cPktb3rk-BuQy72IFLN25DYuNzVBAh
  4vGHSrQyHUGlcTwLtjPAnKb78"

} }

Note

Implementers that are interested in understanding more about theproof mechanism used above can learn more in Section 4.7 Proofs (Signatures) and by reading the following specifications: Data Integrity [DATA-INTEGRITY], Linked Data Cryptographic Suites Registry [LDP-REGISTRY], and JSON Web Signature (JWS) Unencoded Payload Option [RFC7797]. A list of proof mechanisms is available in the Verifiable Credentials Extension Registry [VC-EXTENSION-REGISTRY].

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

When two software systems need to exchange data, they need to use terminology 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 might be referred to as_the context of a conversation_.

Verifiable credentials and verifiable presentations have many attributes and values that are identified by URIs [RFC3986]. However, those URIs can be long and not very human-friendly. In such cases, short-form human-friendly aliases can be more helpful. This specification uses the @context property to map such short-form aliases to theURIs required by specific verifiable credentials and verifiable presentations.

Note

In JSON-LD, the @context property can also be used to communicate other details, such as datatype information, language information, transformation rules, and so on, which are beyond the needs of this specification, but might be useful in the future or to related work. For more information, seeSection 3.1: The Contextof the [JSON-LD] specification.

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 valuehttps://www.w3.org/2018/credentials/v1. For reference, a copy of the base context is provided in Appendix B.1 Base Context. Subsequent items in the array MUST express context information and be composed of any combination of URIs or objects. It is RECOMMENDED that eachURI in the @context be one which, if dereferenced, results in a document containing machine-readable information about the@context.

Note

Though this specification requires that a @context propertybe present, it is not required that the value of the @context property be processed using JSON-LD. This is to support processing using plain JSON libraries, such as those that might be used when theverifiable credential is encoded as a JWT. All libraries or processors_MUST_ ensure that the order of the values in the @context property is what is expected for the specific application. Libraries or processors that support JSON-LD can process the @context property using full JSON-LD processing as expected.

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"], "issuer": "https://example.edu/issuers/565049", "issuanceDate": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": [{ "value": "Example University", "lang": "en" }, { "value": "Exemple d'Université", "lang": "fr" }] } }, "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 example context URI(https://www.w3.org/2018/credentials/examples/v1) for the purpose of demonstrating examples. Implementations are expected to not use thisURI 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 athttps://www.w3.org/2018/credentials/. This concept is further expanded on in Section 5.3 Extensibility.

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. This specification defines the optional id property for such identifiers. Theid property is intended to unambiguously refer to an object, such as a person, product, or organization. Using the id property allows for the expression of statements about specific things in the verifiable credential.

If the id property is present:

Note

Developers should remember that identifiers might be harmful in scenarios where pseudonymity is required. Developers are encouraged to read Section7.3 Identifier-Based Correlation carefully when considering such scenarios. There are also other types of correlation mechanisms documented in Section 7. Privacy Considerations that create privacy concerns. 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 the URI in the id be one which, if dereferenced, results in a document containing machine-readable information about the id.

Example 4

: Usage of the id property

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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/565049", "issuanceDate": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "BachelorDegree", "name": "Bachelor of Science and Arts" } } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/v1"
],
"id": "http://example.edu/credentials/3732",
"type": [
"VerifiableCredential",
"UniversityDegreeCredential"
],
"issuer": "https://example.edu/issuers/565049",
"issuanceDate": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:42Z",
"verificationMethod": "https://example.edu/issuers/565049#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z3FXQjecWufY46yg5abdVZsXqLhxhueuSoZgNSARiKBk9czhSePTFehP
8c3PGfb6a22gkfUKods5D2UAUL5n2Brbx"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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/565049",
"issuanceDate": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"iss": "https://example.edu/issuers/565049",
"nbf": 1262304000,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLz
U2NTA0OSIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMDA6MDA6MDBaIiwiY3JlZGVudGlhb
FN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEi
LCJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IkJhY2hlbG9yIG9mIFN
jaWVuY2UgYW5kIEFydHMifX19LCJpc3MiOiJodHRwczovL2V4YW1wbGUuZWR1L2lzc3VlcnMvNT
Y1MDQ5IiwibmJmIjoxMjYyMzA0MDAwLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVud
GlhbHMvMzczMiIsInN1YiI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMy
MSJ9.giMDNtWUgKbvWL4pteSpSkrh-lhgkhJUZ_gatHdRvEFs9_kB4G9neABvTuuQKfwERzi2KF
Qz3X0nzF-jrOO-5w

The example above uses two types of identifiers. The first identifier is for the verifiable credential and uses an HTTP-based URL. The second identifier is for the subject of the verifiable 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 manyverifiable 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 withsubjects, issuers, holders, credential status lists, cryptographic keys, and other machine-readable information associated with averifiable credential.

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

Verifiable credentials and verifiable presentations MUST have atype property. That is, any credential orpresentation that does not have type property is not verifiable, so is neither a verifiable credentialnor a verifiable presentation.

type

The value of the type property MUST be, or map to (through interpretation of the @context property), one or more URIs. If more than one URI is provided, the URIs MUST be interpreted as an unordered set. Syntactic conveniences SHOULD be used to ease developer usage. Such conveniences might include JSON-LD terms. It is RECOMMENDED that each URI in the type be one which, if dereferenced, results in a document containing machine-readable information about thetype.

Example 5

: Usage of the type property

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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/565049", "issuanceDate": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "BachelorDegree", "name": "Bachelor of Science and Arts" } } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/v1"
],
"id": "http://example.edu/credentials/3732",
"type": [
"VerifiableCredential",
"UniversityDegreeCredential"
],
"issuer": "https://example.edu/issuers/565049",
"issuanceDate": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/565049#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "zeEdUoM7m9cY8ZyTpey83yBKeBcmcvbyrEQzJ19rD2UXArU2U1jPGoEt
rRvGYppdiK37GU4NBeoPakxpWhAvsVSt"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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/565049",
"issuanceDate": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"iss": "https://example.edu/issuers/565049",
"nbf": 1262304000,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLz
U2NTA0OSIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMDA6MDA6MDBaIiwiY3JlZGVudGlhb
FN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEi
LCJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IkJhY2hlbG9yIG9mIFN
jaWVuY2UgYW5kIEFydHMifX19LCJpc3MiOiJodHRwczovL2V4YW1wbGUuZWR1L2lzc3VlcnMvNT
Y1MDQ5IiwibmJmIjoxMjYyMzA0MDAwLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVud
GlhbHMvMzczMiIsInN1YiI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMy
MSJ9.IOKrRQb0yrNxHivWbzfNRdKsSbP-mzc-eaQpdkHKkxTi46x8D0h3aLS9KXcAprcMPioEN6
NNSyqLj9ZTDYeoyg

With respect to this specification, the following table lists the objects that_MUST_ have a type specified.

Object Type
Verifiable credential object (a subclass of acredential object) VerifiableCredential and, optionally, a more specificverifiable credential type. For example, "type": ["VerifiableCredential", "UniversityDegreeCredential"]
Credential object VerifiableCredential and, optionally, a more specificverifiable credential type. For example, "type": ["VerifiableCredential", "UniversityDegreeCredential"]
Verifiable presentation object (a subclass of apresentation object) VerifiablePresentation and, optionally, a more specificverifiable presentation type. For example, "type": ["VerifiablePresentation", "CredentialManagerPresentation"]
Presentation object VerifiablePresentation and, optionally, a more specificverifiable 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"

Note

The type system for the Verifiable Credentials Data Model is the same as for [JSON-LD] and is detailed inSection 5.4: Specifying the Type andSection 8: JSON-LD Grammar. When using a JSON-LD context (see Section5.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.

All credentials, presentations, and encapsulated objects _MUST_specify, or be associated with, additional more narrow types (likeUniversityDegreeCredential, 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 a 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 ofUniversityDegreeCredential, 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 thetype property for verification purposes. The expectation oftypes 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 used in the data model described in this specification allows for multiple ways to associate types with data. Implementers and authors are urged to read the section on typing in the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE].

A verifiable credential contains claims about one or moresubjects. This specification defines a credentialSubject property for the expression of claims about one or moresubjects.

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 asubject of the verifiable credential. Each object MAY contain anid, as described in Section 4.2 Identifiers.

Example 6

: Usage of the credentialSubject property

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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/565049", "issuanceDate": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "BachelorDegree", "name": "Bachelor of Science and Arts" } } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/v1"
],
"id": "http://example.edu/credentials/3732",
"type": [
"VerifiableCredential",
"UniversityDegreeCredential"
],
"issuer": "https://example.edu/issuers/565049",
"issuanceDate": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/565049#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "zeEdUoM7m9cY8ZyTpey83yBKeBcmcvbyrEQzJ19rD2UXArU2U1jPGoEt
rRvGYppdiK37GU4NBeoPakxpWhAvsVSt"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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/565049",
"issuanceDate": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"iss": "https://example.edu/issuers/565049",
"nbf": 1262304000,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLz
U2NTA0OSIsImlzc3VhbmNlRGF0ZSI6IjIwMTAtMDEtMDFUMDA6MDA6MDBaIiwiY3JlZGVudGlhb
FN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEi
LCJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IkJhY2hlbG9yIG9mIFN
jaWVuY2UgYW5kIEFydHMifX19LCJpc3MiOiJodHRwczovL2V4YW1wbGUuZWR1L2lzc3VlcnMvNT
Y1MDQ5IiwibmJmIjoxMjYyMzA0MDAwLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVud
GlhbHMvMzczMiIsInN1YiI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMy
MSJ9.z5vgMTK1nfizNCg5N-niCOL3WUIAL7nXy-nGhDZYO_-PNGeE-0djCpWAMH8fD8eWSID5Pf
kPBYkx_dfLJnQ7NA

It is possible to express information related to multiple subjects in averifiable credential. The example below specifies two subjectswho are spouses. Note the use of array notation to associate multiplesubjects with the credentialSubject property.

Example 7

: Specifying multiple subjects in a verifiable credential

{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "id": "http://example.edu/credentials/3732", "type": ["VerifiableCredential", "RelationshipCredential"], "issuer": "https://example.com/issuer/123", "issuanceDate": "2010-01-01T00:00:00Z", "credentialSubject": [{ "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "name": "Jayden Doe", "spouse": "did:example:c276e12ec21ebfeb1f712ebc6f1" }, { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Morgan Doe", "spouse": "did:example:ebfeb1f712ebc6f1c276e12ec21" }] }

This specification defines a property for expressing the issuer of a verifiable credential.

A verifiable credential MUST have an issuer property.

issuer

The value of the issuer property MUST be either aURI or an object containing an id property. It is_RECOMMENDED_ that the URI in the issuer or itsid be one which, if dereferenced, results in a document containing machine-readable information about the issuer that can be used toverify the information expressed in the credential.

Example 8

: Usage of issuer property

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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": "Bachelor of Science and Arts" } } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/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": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/14#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z4kWncP1KLByEaSU3oaijUNk8GPGCCgntz8q4Gk55QuMwQe1dsWgSmf7
RsRNYgfJUChdSV22khsfpBsX7ub14aYbe"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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": "Bachelor of Science and Arts"
}
}
},
"iss": "https://example.edu/issuers/14",
"nbf": 1262373804,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLz
E0IiwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQxOToyMzoyNFoiLCJjcmVkZW50aWFsU3Via
mVjdCI6eyJpZCI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSIsImRl
Z3JlZSI6eyJ0eXBlIjoiQmFjaGVsb3JEZWdyZWUiLCJuYW1lIjoiQmFjaGVsb3Igb2YgU2NpZW5
jZSBhbmQgQXJ0cyJ9fX0sImlzcyI6Imh0dHBzOi8vZXhhbXBsZS5lZHUvaXNzdWVycy8xNCIsIm
5iZiI6MTI2MjM3MzgwNCwianRpIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRlbnRpYWxzLzM3M
zIiLCJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEifQ.oOoii
TBKC6zbJ8rx916SSHEKk4Fhc5-gFD8Qh64zRsf5ea7D-bu9zA1ii12hnXLloL7Cz0reXKA9P1nB
ZzQvTw

It is also possible to express additional information about the issuer by associating an object with the issuer property:

Example 9

: Usage of issuer expanded property

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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": { "id": "did:example:76e12ec712ebc6f1c221ebfeb1f", "name": "Example University" }, "issuanceDate": "2010-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "BachelorDegree", "name": "Bachelor of Science and Arts" } } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/v1"
],
"id": "http://example.edu/credentials/3732",
"type": [
"VerifiableCredential",
"UniversityDegreeCredential"
],
"issuer": {
"id": "did:example:76e12ec712ebc6f1c221ebfeb1f",
"name": "Example University"
},
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "did:example:76e12ec712ebc6f1c221ebfeb1f#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z2Xdmp6YDYz5RPKeRFDcPYorAmnERyr7aRNzv176oLMxwcW7GgKxAQT4
5jUKwsMA1XvrmFT5Y8WCx7ZnkNTTHJnu9"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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": {
"id": "did:example:76e12ec712ebc6f1c221ebfeb1f",
"name": "Example University"
},
"issuanceDate": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"iss": {
"id": "did:example:76e12ec712ebc6f1c221ebfeb1f",
"name": "Example University"
},
"nbf": 1262373804,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjp7ImlkIjoiZGlkOmV4YW1wbGU6NzZlMTJlYzcxMm
ViYzZmMWMyMjFlYmZlYjFmIiwibmFtZSI6IkV4YW1wbGUgVW5pdmVyc2l0eSJ9LCJpc3N1YW5jZ
URhdGUiOiIyMDEwLTAxLTAxVDE5OjIzOjI0WiIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoi
ZGlkOmV4YW1wbGU6ZWJmZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIiwiZGVncmVlIjp7InR5cGU
iOiJCYWNoZWxvckRlZ3JlZSIsIm5hbWUiOiJCYWNoZWxvciBvZiBTY2llbmNlIGFuZCBBcnRzIn
19fSwiaXNzIjp7ImlkIjoiZGlkOmV4YW1wbGU6NzZlMTJlYzcxMmViYzZmMWMyMjFlYmZlYjFmI
iwibmFtZSI6IkV4YW1wbGUgVW5pdmVyc2l0eSJ9LCJuYmYiOjEyNjIzNzM4MDQsImp0aSI6Imh0
dHA6Ly9leGFtcGxlLmVkdS9jcmVkZW50aWFscy8zNzMyIiwic3ViIjoiZGlkOmV4YW1wbGU6ZWJ
mZWIxZjcxMmViYzZmMWMyNzZlMTJlYzIxIn0.ev4-5Dx9nRy_RUwWMLvnCJ1i-bizgom5VcyYE0
TpGsJ7-bPr6NFUh426Yzx5kc5cEh-a0JPPYBqM6jyrgmyvzA

Note

The value of the issuer property can also be a JWK (for example, "https://example.com/keys/foo.jwk") or a DID (for example, "did:example:abfe13f712120431c276e12ecab").

This specification defines the issuanceDate property for expressing the date and time when a credential becomes valid.

issuanceDate

A credential MUST have an issuanceDate property. The value of the issuanceDate property MUST be a string value of an [XMLSCHEMA11-2] combineddate-time string representing the date and time thecredential becomes valid, which could be a date and time in the future. Note that this value represents the earliest point in time at which the information associated with the credentialSubject property becomes valid.

Example 10

: Usage of issuanceDate property

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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": "Bachelor of Science and Arts" } } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/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": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/14#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z4kWncP1KLByEaSU3oaijUNk8GPGCCgntz8q4Gk55QuMwQe1dsWgSmf7
RsRNYgfJUChdSV22khsfpBsX7ub14aYbe"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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": "Bachelor of Science and Arts"
}
}
},
"iss": "https://example.edu/issuers/14",
"nbf": 1262373804,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLz
E0IiwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQxOToyMzoyNFoiLCJjcmVkZW50aWFsU3Via
mVjdCI6eyJpZCI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSIsImRl
Z3JlZSI6eyJ0eXBlIjoiQmFjaGVsb3JEZWdyZWUiLCJuYW1lIjoiQmFjaGVsb3Igb2YgU2NpZW5
jZSBhbmQgQXJ0cyJ9fX0sImlzcyI6Imh0dHBzOi8vZXhhbXBsZS5lZHUvaXNzdWVycy8xNCIsIm
5iZiI6MTI2MjM3MzgwNCwianRpIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRlbnRpYWxzLzM3M
zIiLCJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEifQ.6MNXY
zdnWzepi1_-Ourj0yv0aokF1MgTUfpXZKNSUWqde3ZF6qRMQt_h0RbDC-qW-oXkjcPdEGidxrbK
chO2Ng

Note

It is expected that the next version of this specification will add thevalidFrom property and will deprecate theissuanceDate property in favor of a new issued property. The range of values for both properties are expected to remain as [XMLSCHEMA11-2] combineddate-time strings. Implementers are advised that thevalidFrom and issued properties are reserved and use for any other purpose is discouraged.

At least one proof mechanism, and the details necessary to evaluate that proof,MUST be expressed for a credential or presentation to be averifiable credential or verifiable presentation; that is, to beverifiable.

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 on 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 Data Integrity Proofs.

When embedding a proof, the proof 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 thetype 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, theproof 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 11

: 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:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "BachelorDegree", "name": "Bachelor of Science and Arts" } }, "proof": { "type": "Ed25519Signature2020", "created": "2021-11-13T18:19:39Z", "verificationMethod": "https://example.edu/issuers/14#key-1", "proofPurpose": "assertionMethod", "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdo WhAfGFCF5bppETSTojQCrfFPP2oumHKtz" } }

Note

As discussed in Section 1.4 Conformance, there are multiple viable proof mechanisms, and this specification does not standardize nor recommend any single proof mechanism for use with verifiable credentials. For more information about the proof mechanism, see the following specifications: Data Integrity [DATA-INTEGRITY], Linked Data Cryptographic Suites Registries [LDP-REGISTRY], and JSON Web Signature (JWS) Unencoded Payload Option [RFC7797]. A list of proof mechanisms is available in the Verifiable Credentials Extension Registry [VC-EXTENSION-REGISTRY].

This specification defines the expirationDate property for the expression of credential expiration information.

expirationDate

If present, the value of the expirationDate property MUST be a string value of an [XMLSCHEMA11-2]date-time representing the date and time the credentialceases to be valid.

Example 12

: Usage of the expirationDate property

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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": "Bachelor of Science and Arts" } } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/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": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/14#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z3zwi434j3HdZv3C3TJxBnwmmiBgrtzRjM2oeDtZyAEkDeNDBeB9Metc
vyB4ZZUvQswKqPdgk5cFSAnyJ3yjvButH"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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": "Bachelor of Science and Arts"
}
}
},
"exp": 1577906604,
"iss": "https://example.edu/issuers/14",
"nbf": 1262373804,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLz
E0IiwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQxOToyMzoyNFoiLCJleHBpcmF0aW9uRGF0Z
SI6IjIwMjAtMDEtMDFUMTk6MjM6MjRaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6
ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJkZWdyZWUiOnsidHlwZSI6IkJ
hY2hlbG9yRGVncmVlIiwibmFtZSI6IkJhY2hlbG9yIG9mIFNjaWVuY2UgYW5kIEFydHMifX19LC
JleHAiOjE1Nzc5MDY2MDQsImlzcyI6Imh0dHBzOi8vZXhhbXBsZS5lZHUvaXNzdWVycy8xNCIsI
m5iZiI6MTI2MjM3MzgwNCwianRpIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRlbnRpYWxzLzM3
MzIiLCJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEifQ.M4eB
gls2xrn00dp5JX7UBzEPauEOTWhtMjR-omIIhVHBBI4-ksHH5F6nFHuKo6pDu7W8c-i_knDTlRr
1zRp3IA

Note

It is expected that the next version of this specification will add thevalidUntil property in a way that deprecates, but preserves backwards compatibility with the expirationDate property. Implementers are advised that the validUntil property is reserved and its use for any other purpose is discouraged.

This specification defines the following credentialStatus property for the discovery of information about the current status of averifiable credential, such as whether it is suspended or revoked.

credentialStatus

If present, the value of the credentialStatus property _MUST_include the following:

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 13

: Usage of the status property

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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": "Bachelor of Science and Arts" } }, "credentialStatus": { "id": "https://example.edu/status/24", "type": "CredentialStatusList2017" } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/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": "Bachelor of Science and Arts"
}
},
"credentialStatus": {
"id": "https://example.edu/status/24",
"type": "CredentialStatusList2017"
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/14#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z3BXsFfx1qJ5NsTkKqREjQ3AGh6RAmCwvgu1HcDSzK3P5QEg2TAw8ufk
tJBw8QkAQRciMGyBf5T2AHyRg2w13Uvhp"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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": "Bachelor of Science and Arts"
}
},
"credentialStatus": {
"id": "https://example.edu/status/24",
"type": "CredentialStatusList2017"
}
},
"iss": "https://example.edu/issuers/14",
"nbf": 1262373804,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLz
E0IiwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQxOToyMzoyNFoiLCJjcmVkZW50aWFsU3Via
mVjdCI6eyJpZCI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSIsImRl
Z3JlZSI6eyJ0eXBlIjoiQmFjaGVsb3JEZWdyZWUiLCJuYW1lIjoiQmFjaGVsb3Igb2YgU2NpZW5
jZSBhbmQgQXJ0cyJ9fSwiY3JlZGVudGlhbFN0YXR1cyI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS
5lZHUvc3RhdHVzLzI0IiwidHlwZSI6IkNyZWRlbnRpYWxTdGF0dXNMaXN0MjAxNyJ9fSwiaXNzI
joiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLzE0IiwibmJmIjoxMjYyMzczODA0LCJqdGki
OiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsInN1YiI6ImRpZDpleGFtcGx
lOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSJ9.YQKQUu_zreDs69AZ8YqpMGHLl9V_tWH4N
S9P9l67J1wWHf0QCyt5hyuA8ckM4seV-1TRbeiHwdJ3VRkDMcwFcg

Defining the data model, formats, and protocols for status schemes are out of scope for this specification. A Verifiable Credential Extension Registry [VC-EXTENSION-REGISTRY] exists that contains available status schemes for implementers who want to implement verifiable credentialstatus checking.

Presentations MAY be used to combine and present credentials. They can be packaged in such a way that the authorship of the data isverifiable. The data in a presentation is often all about the samesubject, but there is no limit to the number of subjects orissuers in the data. The aggregation of information from multipleverifiable credentials is a typical use ofverifiable presentations.

A verifiable presentation is typically composed of the following properties:

id

The id property is optional and MAY be used to provide a unique identifier for the presentation. For details related to the use of this property, see Section 4.2 Identifiers.

type

The type property is required and expresses the type of presentation, such as VerifiablePresentation. For details related to the use of this property, see Section 4.3 Types.

verifiableCredential

If present, the value of the verifiableCredential property MUST be constructed from one or more verifiable credentials, or of data derived from verifiable credentials in a cryptographicallyverifiable format.

holder

If present, the value of the holder propertyis expected to be a URI for the entity that is generating thepresentation.

proof

If present, the value of the proof property ensures that the presentation is verifiable. For details related to the use of this property, see Section 4.7 Proofs (Signatures).

The example below shows a verifiable presentation that embedsverifiable credentials.

Example 14

: 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", "CredentialManagerPresentation"], "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 Data Integrity [DATA-INTEGRITY] specification. An example of averifiable presentation using the JWT proof mechanism is given in section6.3.1 JSON Web Token.

Some zero-knowledge cryptography schemes might enable holders to indirectly prove they hold claims from a verifiable credentialwithout revealing the verifiable credential itself. In these schemes, aclaim from a verifiable credential might be used to derive a presented value, which is cryptographically asserted such that a verifiercan trust the value if they trust the issuer.

For example, a verifiable credential containing the claim date of birth might be used to derive the presented valueover the age of 15 in a manner that is cryptographicallyverifiable. That is, a verifier can still trust the derived value if they trust the issuer.

Note

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

Selective disclosure schemes using zero-knowledge proofs can use claimsexpressed 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 holderhas the flexibility to use the claim in any way that is applicable to the desired verifiable presentation.

Pat has a property dateOfBirth whose value is 2010-01-01

Figure 9 A basic claim expressing that Pat's date of birth is January 1, 2010. Date encoding would be determined by the schema.

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

This section is non-normative.

Section 1.2 Ecosystem Overview provided an overview of theverifiable credential ecosystem. This section provides more detail about how the ecosystem is envisaged to operate.

diagram showing how credentials flow from issuer to holder, and optionally from one holder to another; and how presentations flow from holder to verifier, where all parties can use information from a logical verifiable data registry

Figure 10 The roles and information flows for this specification.

The roles and information flows in the verifiable credential ecosystem are as follows:

Note

The order of the actions above is not fixed, and some actions might be taken more than once. Such action-recurrence might be immediate or at any later point.

The most common sequence of actions is envisioned to be:

  1. An issuer issues to a holder.
  2. The holder presents to a verifier.
  3. The verifier verifies.

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

This specification also does not define an authorization framework nor the decisions that a verifier might make after verifying averifiable credential or verifiable presentation, taking into account the holder, the issuers of theverifiable credentials, the contents of theverifiable credentials, and its own policies.

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

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 therelying 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 document [VC-USE-CASES].

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 tolearn about the security weaknesses introduced bybroadly delegating trust in the manner adopted by Certificate Authority systems.

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 modeling 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 15

: A simple credential

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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" } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/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": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/14#keys-1",
"proofPurpose": "assertionMethod",
"proofValue": "zyrpmzxPy2fDzqv9Pgr4XBzX2rys1FDuLNkYRVmhXuyype8fB44qNX8m
NnXf99i7x1eSpLdYKNhEKknEJmdGfQ4w"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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"
}
},
"iss": "https://example.com/issuers/14",
"nbf": 1519450084,
"jti": "http://example.com/credentials/4643",
"sub": "did:example:abcdef1234567"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuY29tL2NyZWRl
bnRpYWxzLzQ2NDMiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIl0sImlzc3VlciI6Imh
0dHBzOi8vZXhhbXBsZS5jb20vaXNzdWVycy8xNCIsImlzc3VhbmNlRGF0ZSI6IjIwMTgtMDItMj
RUMDU6Mjg6MDRaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZXhhbXBsZTphYmNkZ
WYxMjM0NTY3IiwibmFtZSI6IkphbmUgRG9lIn19LCJpc3MiOiJodHRwczovL2V4YW1wbGUuY29t
L2lzc3VlcnMvMTQiLCJuYmYiOjE1MTk0NTAwODQsImp0aSI6Imh0dHA6Ly9leGFtcGxlLmNvbS9
jcmVkZW50aWFscy80NjQzIiwic3ViIjoiZGlkOmV4YW1wbGU6YWJjZGVmMTIzNDU2NyJ9.oIDq_
JtiKwm1AVikEjMuurZcfZdTtNAvus63k2kbD1HF2l_5V36ekulxPPY7rKYEeiH3e6bTq1urNoML
K3UipA

This verifiable credential states that the entity associated withdid:example:abcdef1234567 has a name with a value ofJane Doe.

Now let us assume a developer wants to extend the verifiable credentialto 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 16

: 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 theverifiable credential. Assuming the above JSON-LD context is published athttps://example.com/contexts/mycontext.jsonld, we can extend this example by including the context and adding the new properties andcredential type to the verifiable credential.

Example 17

: 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" } }

This example demonstrates extending the Verifiable Credentials Data Model in a permissionless and decentralized way. The mechanism shown also ensures thatverifiable 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 whetherverifiable 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.

Implementers are advised to pay close attention to the extension points in this specification, such as in Sections 4.7 Proofs (Signatures),4.9 Status, 5.4 Data Schemas,5.5 Refreshing,5.6 Terms of Use, and 5.7 Evidence. While this specification does not define concrete implementations for those extension points, the Verifiable Credentials Extension Registry [VC-EXTENSION-REGISTRY] provides an unofficial, curated list of extensions that developers can use from these extension points.

This specification ensures that "plain" JSON and JSON-LD syntaxes are semantically compatible without requiring JSON implementations to use a JSON-LD processor. To achieve this, the specification imposes the following additional requirements on both syntaxes:

A human-readable document describing the expected order of values for the@context property is expected to be published by any implementer seeking interoperability. A machine-readable description (that is, a normal JSON-LD Context document) is expected to be published at the URL specified in the @context property by JSON-LD implementers seeking interoperability.

The requirements above guarantee semantic interoperability between JSON and JSON-LD for terms defined by the @context mechanism. While JSON-LD processors will use the specific mechanism provided and can verify that all terms are correctly specified, JSON-based processors implicitly accept the same set of terms without testing that they are correct. In other words, the context in which the data exchange happens is explicitly stated for both JSON and JSON-LD by using the same mechanism. With respect to JSON-based processors, this is achieved in a lightweight manner, without having to use JSON-LD processing libraries.

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:

It is important to understand that data schemas serve a different purpose from the @context property, which neither enforces data structure or data syntax, nor enables the definition of arbitrary encodings to alternate representation formats.

This specification defines the following property for the expression of a data schema, which can be included by an issuer in the verifiable credentials that it issues:

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. EachcredentialSchema MUST specify its type (for example,JsonSchemaValidator2018), and an id propertythat MUST be a URI identifying the schema file. The precise contents of each data schema is determined by the specific type definition.

Note

The credentialSchema property provides an opportunity to annotate type definitions or lock them to specific versions of the vocabulary. Authors of verifiable credentials can include a static version of their vocabulary using credentialSchema that is locked to some content integrity protection mechanism. The credentialSchema property also makes it possible to perform syntactic checking on thecredential and to use verification mechanisms such as JSON Schema [JSON-SCHEMA-2018] validation.

Example 18

: Usage of the credentialSchema property to perform JSON schema validation

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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": "Bachelor of Science and Arts" } }, "credentialSchema": { "id": "https://example.org/examples/degree.json", "type": "JsonSchemaValidator2018" } }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/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": "Bachelor of Science and Arts"
}
},
"credentialSchema": {
"id": "https://example.org/examples/degree.json",
"type": "JsonSchemaValidator2018"
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/14#keys-1",
"proofPurpose": "assertionMethod",
"proofValue": "z5JKxik9jw25W2s9Q3N3RMovCVLSt1h6bBTZrKsy3JWP48KokH4spdBU
xTykSb11FCtn8q5HWybySAGCFaWwN2aiT"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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": "Bachelor of Science and Arts"
}
},
"credentialSchema": {
"id": "https://example.org/examples/degree.json",
"type": "JsonSchemaValidator2018"
}
},
"iss": "https://example.edu/issuers/14",
"nbf": 1262373804,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLz
E0IiwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQxOToyMzoyNFoiLCJjcmVkZW50aWFsU3Via
mVjdCI6eyJpZCI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSIsImRl
Z3JlZSI6eyJ0eXBlIjoiQmFjaGVsb3JEZWdyZWUiLCJuYW1lIjoiQmFjaGVsb3Igb2YgU2NpZW5
jZSBhbmQgQXJ0cyJ9fSwiY3JlZGVudGlhbFNjaGVtYSI6eyJpZCI6Imh0dHBzOi8vZXhhbXBsZS
5vcmcvZXhhbXBsZXMvZGVncmVlLmpzb24iLCJ0eXBlIjoiSnNvblNjaGVtYVZhbGlkYXRvcjIwM
TgifX0sImlzcyI6Imh0dHBzOi8vZXhhbXBsZS5lZHUvaXNzdWVycy8xNCIsIm5iZiI6MTI2MjM3
MzgwNCwianRpIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRlbnRpYWxzLzM3MzIiLCJzdWIiOiJ
kaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEifQ.GRJHwxvQfgEOP8TaaBn
p2ZCPjFlA_KodpdBupHsRroql10gaE--8oAXR1e-wOuxjFoK-T814h9LKnv71IMI38Q

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

Note

For information about linkages to JSON Schema [JSON-SCHEMA-2018] or other optional verification mechanisms, see the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.

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 19

: 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": "Bachelor of Science and Arts" } }, "credentialSchema": { "id": "https://example.org/examples/degree.zkp", "type": "ZkpExampleSchema2018" }, "proof": { } }

In the example above, the issuer is specifying acredentialSchema 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 theverifiable credential is valid.

It is useful for systems to enable the manual or automatic refresh of an expired verifiable credential. For more information about expiredverifiable credentials, see Section 4.8 Expiration. This specification defines a refreshService property, which enables an issuer to include a link to a refresh service.

The issuer can include the refresh service as an element inside theverifiable 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 theholder to refresh the verifiable credential before creating averifiable presentation to share with a verifier. In the former case, including the refresh service inside the verifiable credentialenables either the holder or the verifier to perform future updates of the credential.

The refresh service is only expected to be used when either thecredential has expired or the issuer does not publishcredential status information. Issuers are advised not to put therefreshService property in a verifiable credentialthat does not contain public information or whose refresh service is not protected in some way.

Note

Placing a refreshService property in averifiable credential so that it is available to verifiers can remove control and consent from the holder and allow theverifiable credential to be issued directly to the verifier, thereby bypassing the holder.

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 verifiable credential. EachrefreshService value MUST specify its type (for example, ManualRefreshService2018) and its id, which is the URI of the service. There is an expectation that machine readable information needs to be retrievable from the URI. The precise content of each refresh service is determined by the specific refreshService type definition.

Example 20

: 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": "Bachelor of Science and Arts" } }, "refreshService": { "id": "https://example.edu/refresh/3732", "type": "ManualRefreshService2018" } }

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

Terms of use can be utilized by an issuer or a holder to communicate the terms under which a verifiable credential orverifiable presentation was issued. The issuer places their terms of use inside the verifiable credential. The holder places their terms of use inside a verifiable presentation. This specification defines a termsOfUse property for expressing terms of use information.

The value of the termsOfUse property tells theverifier what actions it is required to perform (an obligation), not allowed to perform (a prohibition), or allowed to perform (a_permission_) if it is to accept the verifiable credential orverifiable presentation.

Note

Further study is required to determine how a subject who is not aholder 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 aholder and place terms of use restrictions on the delegatedverifiable credential.

termsOfUse

The value of the termsOfUse property MUST specify one or more terms of use policies under which the creator issued the credentialor presentation. If the recipient (a holder orverifier) 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 21

: Usage of the termsOfUse property by an issuer

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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": "Bachelor of Science and Arts" } }, "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"] }] }]

}

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/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": "Bachelor of Science and Arts"
}
},
"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": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/14#keys-1",
"proofPurpose": "assertionMethod",
"proofValue": "z2ty8BNvrKCvAXGqJVXF8aZ1jK5o5uXFvhXJksUXhn61uSwJJmWdcntf
qvZTLbWmQHpieyhdcrG43em37Jo8bswvR"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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": "Bachelor of Science and Arts"
}
},
"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"
]
}
]
}
]
},
"iss": "https://example.edu/issuers/14",
"nbf": 1262373804,
"jti": "http://example.edu/credentials/3732",
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzLzM3MzIiLCJ0eXBlIjpbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwiVW5pdmVyc2l0eUR
lZ3JlZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjoiaHR0cHM6Ly9leGFtcGxlLmVkdS9pc3N1ZXJzLz
E0IiwiaXNzdWFuY2VEYXRlIjoiMjAxMC0wMS0wMVQxOToyMzoyNFoiLCJjcmVkZW50aWFsU3Via
mVjdCI6eyJpZCI6ImRpZDpleGFtcGxlOmViZmViMWY3MTJlYmM2ZjFjMjc2ZTEyZWMyMSIsImRl
Z3JlZSI6eyJ0eXBlIjoiQmFjaGVsb3JEZWdyZWUiLCJuYW1lIjoiQmFjaGVsb3Igb2YgU2NpZW5
jZSBhbmQgQXJ0cyJ9fSwidGVybXNPZlVzZSI6W3sidHlwZSI6Iklzc3VlclBvbGljeSIsImlkIj
oiaHR0cDovL2V4YW1wbGUuY29tL3BvbGljaWVzL2NyZWRlbnRpYWwvNCIsInByb2ZpbGUiOiJod
HRwOi8vZXhhbXBsZS5jb20vcHJvZmlsZXMvY3JlZGVudGlhbCIsInByb2hpYml0aW9uIjpbeyJh
c3NpZ25lciI6Imh0dHBzOi8vZXhhbXBsZS5lZHUvaXNzdWVycy8xNCIsImFzc2lnbmVlIjoiQWx
sVmVyaWZpZXJzIiwidGFyZ2V0IjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRlbnRpYWxzLzM3Mz
IiLCJhY3Rpb24iOlsiQXJjaGl2YWwiXX1dfV19LCJpc3MiOiJodHRwczovL2V4YW1wbGUuZWR1L
2lzc3VlcnMvMTQiLCJuYmYiOjEyNjIzNzM4MDQsImp0aSI6Imh0dHA6Ly9leGFtcGxlLmVkdS9j
cmVkZW50aWFscy8zNzMyIiwic3ViIjoiZGlkOmV4YW1wbGU6ZWJmZWIxZjcxMmViYzZmMWMyNzZ
lMTJlYzIxIn0.YMeGs_5KDNzta-h_ehAY9RS6jyyJ8kB36QOXQL6GR1WCkWUz7S2ZUUsBblvipk
cgnA4fCfdjI5c_aZI3Ce8byw

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

Example 22

: Usage of the termsOfUse property by a holder

{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1", { "@protected": true, "VerifiablePresentationTermsOfUseExtension": { "@id": "https://www.w3.org/2018/credentials/examples#VerifiablePresentationExtension", "@context": { "@protected": true, "termsOfUse": { "@id": "https://www.w3.org/2018/credentials#termsOfUse", "@type": "@id" } } } } ], "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "type": ["VerifiablePresentation", "VerifiablePresentationTermsOfUseExtension"], "verifiableCredential": [{ "@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": "Bachelor of Science and Arts" } }, "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": [ ... ] }

Note

Warning: The termsOfUse property is improperly defined within theVerifiablePresentation scoped context. This is a bug with the version 1 context and will be fixed in the version 2 context. In the meantime, implementors who wish to use this feature will be required to extend the context of their verifiable presentation with an additional term that defines thetermsOfUse property, which can then be used alongside theverifiable presentation type property, in order for the term to be semantically recognized in a JSON-LD processor.

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 subjectusing a third-party service. If the verifier were to use a third-party service for correlation, they would violate the terms under which theholder created the presentation.

This feature is also expected to be used by government-issuedverifiable credentials to instruct digital wallets to limit their use to similar government organizations in an attempt to protect citizens from unexpected usage of sensitive data. Similarly, someverifiable credentials issued by private industry are expected to limit usage to within departments inside the organization, or during business hours. Implementers are urged to read more about this rapidly evolving feature in the appropriate section of the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.

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 thesubject or perform a set of background checks before issuing thecredential. In certain scenarios, this information is useful to theverifier when determining the risk associated with relying on a givencredential.

This specification defines the evidence 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 typedefinition.

Note

For information about how attachments and references to credentials and non-credential data might be supported by the specification, see the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.

Example 23

: 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": "Bachelor of Science and Arts" } }, "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", "licenseNumber": "123AB4567" }], "proof": { } }

Note

In this evidence example, the issuer is asserting that they physically matched the subject of the credential to a physical copy of a driver's license with the stated license number. This driver's license was used in the issuance process to verify that "Example University" verified the subject before issuance of the credential and how they did so (physical verification).

Note

The evidence property provides different and complementary information to the proof property. The evidence property is used to express supporting information, such as documentary evidence, related to the integrity of the verifiable credential. In contrast, the proof property is used to express machine-verifiable mathematical proofs related to the authenticity of theissuer and integrity of the verifiable credential. For more information about the proof property, see Section4.7 Proofs (Signatures).

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 the ability of a holder to:

This specification describes a data model that supports selective disclosure with the use of zero-knowledge proof mechanisms. The examples below highlight how the data model can be used to issue, present, and verify zero-knowledgeverifiable credentials.

For a holder to use a zero-knowledge verifiable presentation, they need an issuer to have issued a verifiable credential in a manner that enables the holder to derive a proof from the originally issuedverifiable credential, so that the holder can present the information to a verifier in a privacy-enhancing manner. This implies that the holder can prove the validity of theissuer'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 Camenisch-Lysyanskaya Signature [CL-SIGNATURES], which allows the presentation of the verifiable credential in a way that supports the privacy of theholder and subject through the use of selective disclosure of theverifiable credential values. Some other cryptographic systems which rely upon zero-knowledge proofs to selectively disclose attributes can be found in the [LDP-REGISTRY] as well.

Example 24

: 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": "Bachelor of Science and Arts", "college": "College of Engineering" } }, "proof": { "type": "CLSignature2019", "issuerData": "5NQ4TgzNfSQxoLzf2d5AV3JNiCdMaTgm...BXiX5UggB381QU7ZCgqWivUmy4D", "attributes": "pPYmqDvwwWBDPNykXVrBtKdsJDeZUGFA...tTERiLqsZ5oxCoCSodPQaggkDJy", "signature": "8eGWSiTiWtEA8WnBwX4T259STpxpRKuk...kpFnikqqSP3GMW7mVxC4chxFhVs", "signatureCorrectnessProof": "SNQbW3u1QV5q89qhxA1xyVqFa6jCrKwv...dsRypyuGGK3RhhBUvH1tPEL8orH" } }

The example above provides the verifiable 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 averifiable presentation, so that the verifiable credentialdiscloses only the claims and additional credential metadata that theholder intended. To do this, all of the following requirements are expected to be met:

Example 25

: 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 11 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 who want to extend verifiable credentials and verifiable presentations to support zero-knowledge proof systems.

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

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

For example, if a credential with an identifier ofhttps://example.org/credentials/245 is disputed, the subjectcan issue the credential shown below and present it to theverifier along with the disputed credential.

Example 26

: 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.", "lang": "en" }, }, "issuer": "https://example.com/people#me", "issuanceDate": "2017-12-05T14:27:42Z", "proof": { } }

In the above verifiable credential the issuer is claiming that the address in the disputed verifiable credential is wrong.

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.

Note

This area of study is rapidly evolving and developers that are interested in publishing credentials that dispute the veracity of othercredentials are urged to read the section related to disputes in the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.

This section is non-normative.

Verifiable credentials are intended as a means of reliably identifyingsubjects. 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.

The data model as described in Sections3. Core Data Model, 4. Basic Concepts, and5. Advanced Concepts is the canonical structural representation of a verifiable credential or verifiable presentation. All serializations are representations of that data model in a specific format. This section specifies how the data model is realized in JSON-LD and plain JSON. Although syntactic mappings are provided for only these two syntaxes, applications and services can use any other data representation syntax (such as XML, YAML, or CBOR) that is capable of expressing the data model. As theverification and validation requirements are defined in terms of the data model, all serialization syntaxes have to be deterministically translated to the data model for processing, validation, or comparison. This specification makes no requirements for support of any specific serialization format.

The expected arity of the property values in this specification, and the resulting datatype which holds those values, can vary depending on the property. If present, the following properties are represented as a single value:

All other properties, if present, are represented as either a single value or an array of values.

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:

Note

As the transformations listed herein have potentially incompatible interpretations, additional profiling of the JSON format is required to provide a deterministic transformation to the data model.

[JSON-LD] is a JSON-based format used to serializeLinked 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. TheJSON-LD contextis 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 verifiable credentials in idiomatic JSON. TheJSON-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.

In general, the data model and syntaxes described in this document are designed such that developers can copy and paste examples to incorporateverifiable 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 data model described in this specification is designed to be proof format agnostic. This specification does not normatively require any particular digital proof or signature format. While the data model is the canonical representation of a credential or presentation, the proofing mechanisms for these are often tied to the syntax used in the transmission of the document between parties. As such, each proofing mechanism has to specify whether the verification of the proof is calculated against the state of the document as transmitted, against the possibly transformed data model, or against another form. 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:

JSON Web Token (JWT) [RFC7519] is still a widely used means to expressclaims 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 Section1.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.

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 standardverifiable credential and verifiable presentation MAY be omitted to avoid duplication.

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

To encode a verifiable credential as a JWT, specific propertiesintroduced by this specification MUST be either:

If no explicit rule is specified, properties are encoded in the same way as with a standard credential, and are added to thevc claim of the JWT. As with all JWTs, the JWS-based signature of a verifiable credential represented in the JWT syntax is calculated against the literal JWT string value as presented across the wire, before any decoding or transformation rules are applied. The following paragraphs describe these encoding rules.

If a JWS is present, the digital signature refers either to the issuerof the verifiable credential, or in the case of averifiable presentation, to the holder of theverifiable credential. The JWS proves that the iss 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 a more complex proof, as may be necessary if the creator is different from the issuer, or a proof not based on digital signatures, such as Proof of Work. Theissuer 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 rules apply to JOSE headers in the context of this specification:

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

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

Note

For more information about using JOSE header parameters and/or JWT claim names not specified herein, see the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.

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

Note

Implementers are warned that JWTs are not capable of encoding multiplesubjects and are thus not capable of encoding averifiable credential with more than one subject. JWTs might support multiple subjects in the future and implementers are advised to refer to the JSON Web Token Claim Registry for multi-subject JWT claim names or the Nested JSON Web Token specification.

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

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

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

In the example above, the verifiable credential uses aproof based on JWS digital signatures, and the corresponding verification key can be obtained using the kidheader parameter.

Example 28

: 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": "https://example.com/keys/foo.jwk", "nbf": 1541493724, "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": "Bachelor of Science and Arts" } } } }

In the example above, vc does not contain the id property because the JWT encoding uses the jtiattribute to represent a unique identifier. The sub attribute encodes the information represented by the id property ofcredentialSubject. The nonce has been added to stop a replay attack.

Example 29

: Verifiable credential using JWT compact serialization (non-normative)

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0 MzFjMjc2ZTEyZWNhYiNrZXlzLTEifQ.eyJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxY zI3NmUxMmVjMjEiLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsImlzc yI6Imh0dHBzOi8vZXhhbXBsZS5jb20va2V5cy9mb28uandrIiwibmJmIjoxNTQxNDkzNzI0LCJpYXQiO jE1NDE0OTM3MjQsImV4cCI6MTU3MzAyOTcyMywibm9uY2UiOiI2NjAhNjM0NUZTZXIiLCJ2YyI6eyJAY 29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd 3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZ UNyZWRlbnRpYWwiLCJVbml2ZXJzaXR5RGVncmVlQ3JlZGVudGlhbCJdLCJjcmVkZW50aWFsU3ViamVjd CI6eyJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IjxzcGFuIGxhbmc9J2ZyL UNBJz5CYWNjYWxhdXLDqWF0IGVuIG11c2lxdWVzIG51bcOpcmlxdWVzPC9zcGFuPiJ9fX19.KLJo5GAy BND3LDTn9H7FQokEsUEi8jKwXhGvoN3JtRa51xrNDgXDb0cq1UTYB-rK4Ft9YVmR1NI_ZOF8oGc_7wAp 8PHbF2HaWodQIoOBxxT-4WNqAxft7ET6lkH-4S6Ux3rSGAmczMohEEf8eCeN-jC8WekdPl6zKZQj0YPB 1rx6X0-xlFBs7cl6Wt8rfBP_tZ9YgVWrQmUWypSioc0MUyiphmyEbLZagTyPlUyflGlEdqrZAv6eSe6R txJy6M1-lD7a5HTzanYTWBPAUHDZGyGKXdJw-W_x0IWChBzI8t3kpG253fg6V3tPgHeKXE94fz_QpYfg --7kLsyBAfQGbg

In the example above, the verifiable presentation uses aproof based on JWS digital signatures, and the corresponding verification key can be obtained using the kidheader parameter.

Example 31

: 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", "nbf": 1541493724, "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"],

"verifiableCredential": [""]

} }

In the example above, vp does not contain the id property because the JWT encoding uses the jtiattribute to represent a unique identifier. verifiableCredentialcontains a string array of verifiable credentials usingJWT compact serialization. The nonce has been added to stop a replay attack.

Example 32

: Verifiable presentation using JWT compact serialization (non-normative)

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOjB4YWJjI2tleTEifQ.e yJpc3MiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJqdGkiOiJ1cm46d XVpZDozOTc4MzQ0Zi04NTk2LTRjM2EtYTk3OC04ZmNhYmEzOTAzYzUiLCJhdWQiOiJkaWQ6ZXhhbXBsZ To0YTU3NTQ2OTczNDM2ZjZmNmM0YTRhNTc1NzMiLCJuYmYiOjE1NDE0OTM3MjQsImlhdCI6MTU0MTQ5M zcyNCwiZXhwIjoxNTczMDI5NzIzLCJub25jZSI6IjM0M3MkRlNGRGEtIiwidnAiOnsiQGNvbnRleHQiO lsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL3d3dy53My5vc mcvMjAxOC9jcmVkZW50aWFscy9leGFtcGxlcy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50Y XRpb24iLCJDcmVkZW50aWFsTWFuYWdlclByZXNlbnRhdGlvbiJdLCJ2ZXJpZmlhYmxlQ3JlZGVudGlhb CI6WyJleUpoYkdjaU9pSlNVekkxTmlJc0luUjVjQ0k2SWtwWFZDSXNJbXRwWkNJNkltUnBaRHBsZUdGd GNHeGxPbUZpWm1VeE0yWTNNVEl4TWpBME16RmpNamMyWlRFeVpXTmhZaU5yWlhsekxURWlmUS5leUp6Z FdJaU9pSmthV1E2WlhoaGJYQnNaVHBsWW1abFlqRm1OekV5WldKak5tWXhZekkzTm1VeE1tVmpNakVpT ENKcWRHa2lPaUpvZEhSd09pOHZaWGhoYlhCc1pTNWxaSFV2WTNKbFpHVnVkR2xoYkhNdk16Y3pNaUlzS W1semN5STZJbWgwZEhCek9pOHZaWGhoYlhCc1pTNWpiMjB2YTJWNWN5OW1iMjh1YW5kcklpd2libUptS WpveE5UUXhORGt6TnpJMExDSnBZWFFpT2pFMU5ERTBPVE0zTWpRc0ltVjRjQ0k2TVRVM016QXlPVGN5T Xl3aWJtOXVZMlVpT2lJMk5qQWhOak0wTlVaVFpYSWlMQ0oyWXlJNmV5SkFZMjl1ZEdWNGRDSTZXeUpvZ EhSd2N6b3ZMM2QzZHk1M015NXZjbWN2TWpBeE9DOWpjbVZrWlc1MGFXRnNjeTkyTVNJc0ltaDBkSEJ6T 2k4dmQzZDNMbmN6TG05eVp5OHlNREU0TDJOeVpXUmxiblJwWVd4ekwyVjRZVzF3YkdWekwzWXhJbDBzS W5SNWNHVWlPbHNpVm1WeWFXWnBZV0pzWlVOeVpXUmxiblJwWVd3aUxDSlZibWwyWlhKemFYUjVSR1ZuY 21WbFEzSmxaR1Z1ZEdsaGJDSmRMQ0pqY21Wa1pXNTBhV0ZzVTNWaWFtVmpkQ0k2ZXlKa1pXZHlaV1VpT 25zaWRIbHdaU0k2SWtKaFkyaGxiRzl5UkdWbmNtVmxJaXdpYm1GdFpTSTZJanh6Y0dGdUlHeGhibWM5S jJaeUxVTkJKejVDWVdOallXeGhkWExEcVdGMElHVnVJRzExYzJseGRXVnpJRzUxYmNPcGNtbHhkV1Z6U EM5emNHRnVQaUo5ZlgxOS5LTEpvNUdBeUJORDNMRFRuOUg3RlFva0VzVUVpOGpLd1hoR3ZvTjNKdFJhN TF4ck5EZ1hEYjBjcTFVVFlCLXJLNEZ0OVlWbVIxTklfWk9GOG9HY183d0FwOFBIYkYySGFXb2RRSW9PQ nh4VC00V05xQXhmdDdFVDZsa0gtNFM2VXgzclNHQW1jek1vaEVFZjhlQ2VOLWpDOFdla2RQbDZ6S1pRa jBZUEIxcng2WDAteGxGQnM3Y2w2V3Q4cmZCUF90WjlZZ1ZXclFtVVd5cFNpb2MwTVV5aXBobXlFYkxaY WdUeVBsVXlmbEdsRWRxclpBdjZlU2U2UnR4Snk2TTEtbEQ3YTVIVHphbllUV0JQQVVIRFpHeUdLWGRKd y1XX3gwSVdDaEJ6STh0M2twRzI1M2ZnNlYzdFBnSGVLWEU5NGZ6X1FwWWZnLS03a0xzeUJBZlFHYmciX X19.ft_Eq4IniBrr7gtzRfrYj8Vy1aPXuFZU-6_ai0wvaKcsrzI4JkQEKTvbJwdvIeuGuTqy7ipO-EYi 7V4TvonPuTRdpB7ZHOlYlbZ4wA9WJ6mSVSqDACvYRiFvrOFmie8rgm6GacWatgO4m4NqiFKFko3r58Lu eFfGw47NK9RcfOkVQeHCq4btaDqksDKeoTrNysF4YS89INa-prWomrLRAhnwLOo1Etp3E4ESAxg73CR2 kA5AoMbf5KtFueWnMcSbQkMRdWcGC1VssC0tB0JffVjq7ZV6OTyV4kl1-UVgiPLXUTpupFfLRhf9QpqM BjYgP62KvhIvW8BbkGUelYMetA

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 withData Integrity and the associated Linked Data Cryptographic Suiteswhich 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 Data Integrity Proofs format was designed to simply and easily protectverifiable 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

For more information about the different qualities of the various syntax formats (for example, JSON+JWT, JSON-LD+JWT, or JSON-LD+LD-Proofs), see the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.

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.

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

This section is non-normative.

Data associated with verifiable credentials stored in thecredential.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 verifiable credentials when possible. For example, issuing ageOver verifiable credentials instead of date of birth verifiable credentials when a verifier wants to determine if an entity is over the age of 18.

Because a verifiable credential often contains personally identifiable information (PII), implementers are strongly advised to use mechanisms while storing and transporting verifiable credentials that protect the data from those who should not access it. Mechanisms that could be considered include Transport Layer Security (TLS) or other means of encrypting the data while in transit, as well as encryption or data access control mechanisms to protect the data in a verifiable credential while at rest.

This section is non-normative.

Subjects of verifiable credentials are identified using thecredential.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 multipleverifiers, or an issuer and a verifier, can collude to correlate the holder. If holders want to reduce correlation, they should use verifiable credential schemes that allow hiding the identifier during verifiable presentation. Such schemes expect theholder to generate the identifier and might even allow hiding the identifier from the issuer, while still keeping the identifier embedded and signed in the verifiable credential.

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

This section is non-normative.

The contents of verifiable credentials are secured using thecredential.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 theverificationMethod, created,proofPurpose, and jws 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 verifiable credential that defeats the anti-correlation properties of the cryptography used.

This section is non-normative.

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

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

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.

This section is non-normative.

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

For example, this document uses the ageOver propertyinstead of a specific birthdate, which constitutes much stronger PII. 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 averifiable credential claiming that subjects have met that requirement instead of offering verifiable credentials containingclaims about specific birthdates. This enables individual customers to make purchases without revealing specific PII.

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 verifiable 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, anissuer of driver's licenses could issue a verifiable credentialcontaining every attribute that appears on a driver's license, as well as a set of verifiable credentials where every verifiable credentialcontains only a single attribute, such as a person's birthday. It could also issue more abstract verifiable credentials (for example, averifiable 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 verifiable 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.

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 bearer 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 bearer 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 theid property, which is nested in thecredentialSubject property. For example, the followingverifiable credential is a bearer credential:

Example 33

: Usage of issuer properties

CredentialVerifiable Credential (with proof)Verifiable Credential (as JWT)

{ "@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": {

"degree": {
  "type": "BachelorDegree",
  "name": "Bachelor of Science and Arts"
}

} }

{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1",
"https://w3id.org/security/suites/ed25519-2020/v1"
],
"id": "http://example.edu/credentials/temporary/28934792387492384",
"type": [
"VerifiableCredential",
"UniversityDegreeCredential"
],
"issuer": "https://example.edu/issuers/14",
"issuanceDate": "2017-10-22T12:23:48Z",
"credentialSubject": {
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2022-02-25T14:58:43Z",
"verificationMethod": "https://example.edu/issuers/14#keys-1",
"proofPurpose": "assertionMethod",
"proofValue": "z49oZrBSGbo4ASwCLCms2YGkGbgHtFyAv8J5849XF4qwhNqRvs92FZtH
ZdHFMcA1uwDWNKhxvikAvRfmUjKFJUUWT"
}
}

---------------- JWT header ---------------
{
"alg": "ES256",
"typ": "JWT"
}
--------------- JWT payload ---------------
// NOTE: The example below uses a valid VC-JWT serialization
// that duplicates the iss, nbf, jti, and sub fields in the
// Verifiable Credential (vc) field.
{
"vc": {
"@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": {
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"iss": "https://example.edu/issuers/14",
"nbf": 1508675028,
"jti": "http://example.edu/credentials/temporary/28934792387492384"
}
--------------- JWT ---------------
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3
d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L
2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sImlkIjoiaHR0cDovL2V4YW1wbGUuZWR1L2NyZWRl
bnRpYWxzL3RlbXBvcmFyeS8yODkzNDc5MjM4NzQ5MjM4NCIsInR5cGUiOlsiVmVyaWZpYWJsZUN
yZWRlbnRpYWwiLCJVbml2ZXJzaXR5RGVncmVlQ3JlZGVudGlhbCJdLCJpc3N1ZXIiOiJodHRwcz
ovL2V4YW1wbGUuZWR1L2lzc3VlcnMvMTQiLCJpc3N1YW5jZURhdGUiOiIyMDE3LTEwLTIyVDEyO
jIzOjQ4WiIsImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImRlZ3JlZSI6eyJ0eXBlIjoiQmFjaGVsb3JE
ZWdyZWUiLCJuYW1lIjoiQmFjaGVsb3Igb2YgU2NpZW5jZSBhbmQgQXJ0cyJ9fX0sImlzcyI6Imh
0dHBzOi8vZXhhbXBsZS5lZHUvaXNzdWVycy8xNCIsIm5iZiI6MTUwODY3NTAyOCwianRpIjoiaH
R0cDovL2V4YW1wbGUuZWR1L2NyZWRlbnRpYWxzL3RlbXBvcmFyeS8yODkzNDc5MjM4NzQ5MjM4N
CJ9.g_t3HGoAWKXUXFaVemchk4HckdNfxizpLfMQxR7S_sMLsjCsxP1LniBVY0mORMrp_6W0u3_
IiqT1X1dGa4eqPg

While bearer credentials can be privacy-enhancing, they must be carefully crafted so as not accidentally divulge more information than the holderof the bearer credential expects. For example, repeated use of the samebearer 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 bearer credential or session.

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

Holders should be warned by their software if bearer credentialscontaining 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.

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. 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 such as 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 credentialrevocation lists that are unique per credential, during theverification 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.

This section is non-normative.

When a holder receives a verifiable credential from anissuer, the verifiable 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 theircredential repository, specifically the correlation and data mining protections in place for those who store their verifiable credentialswith the service provider.

Some effective mitigations for data mining and profiling include using:

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 the two pieces, even when the information is delivered through different channels. The aggregation ofverifiable 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 as well as age-related information for that 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 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 tends not to be technological in nature, but policy driven instead. Therefore, if aholder does not want information about them to be aggregated, they must express this in the verifiable presentations they transmit.

This section is non-normative.

Despite the best efforts to assure privacy, actually usingverifiable 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 credentials.

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, averifier 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 wrongverifier, 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 theverifier 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 theverifiable credential in a verifiable presentation and bind the token to a credit checking agency using a digital signature. Theverifier 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.

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 verifiable credentials short lived and renewal automatic.

For example, an ageOver verifiable credential is useful for gaining access to a bar. If an issuer issues such averifiable 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.

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-useverifiable credentials whenever possible.

Using single-use verifiable credentials provides several benefits. The first benefit is to verifiers who can be sure that the data in averifiable credential is fresh. The second benefit is to holders, who know that if there are no long-lived identifiers in theverifiable credential, the verifiable 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.

This section is non-normative.

In an ideal private browsing scenario, no PII will be revealed. Because manycredentials include PII, organizations providing software toholders should warn them about the possibility of revealing this information if they wish to use credentials and presentationswhile in private browsing mode. As each browser vendor handles private browsing differently, and some browsers might not have this feature at all, it is important for implementers to be aware of these differences and implement solutions accordingly.

This section is non-normative.

It cannot be overstated that verifiable credentials rely on a high degree of trust in issuers. The degree to which a holder might take advantage of possible privacy protections often depends strongly on the support an issuer provides for such features. In many cases, privacy protections which make use of zero-knowledge proofs, data minimization techniques, bearer credentials, abstract claims, and protections against signature-based correlation, require the issuer to actively support such capabilities and incorporate them into the verifiable credentials they issue.

It should also be noted that, in addition to a reliance on issuerparticipation to provide verifiable credential capabilities that help preserve holder and subject privacy, holders rely onissuers to not deliberately subvert privacy protections. For example, anissuer might sign verifiable credentials using a signature scheme that protects against signature-based correlation. This would protect theholder from being correlated by the signature value as it is shared amongverifiers. However, if the issuer creates a unique key for each issued credential, it might be possible for the issuer to trackpresentations of the credential, regardless of a verifier's inability to do so.

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.

This section is non-normative.

Some aspects of the data model described in this specification can be protected through the use of cryptography. It is important for implementers to understand the cryptography suites and libraries used to create and processcredentials and presentations. Implementing and auditing cryptography systems generally requires substantial experience. Effectivered teaming can also help 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 need to take this into account and ensure mechanisms exist to easily and proactively upgrade expired or broken cryptography suites and libraries, and to invalidate and replace existing credentials. Regular monitoring is important to ensure the long term viability of systems processing credentials.

This section is non-normative.

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

Example 34

: Non-content-integrity protected links

{ "@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", "image": "https://example.edu/images/58473", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": [{ "value": "Example University", "lang": "en" }, { "value": "Exemple d'Université", "lang": "fr" }] } }, "proof": { } }

While this specification does not recommend any specific content integrity protection, document authors who want to ensure 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 [IPFS]. The example below transforms the previous example 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.

Example 35

: Content-integrity protection for links to external data

{ "@context": [ "https://www.w3.org/2018/credentials/v1?hl=z3aq31uzgnZBuWNzUB", "https://www.w3.org/2018/credentials/examples/v1?hl=z8guWNzUBnZBu3aq31" ], "id": "http://example.edu/credentials/58473", "type": ["VerifiableCredential", "AlumniCredential"], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "image": "ipfs:/ipfs/QmXfrS3pHerg44zzK6QKQj6JDk8H6cMtQS7pdXbohwNQfK/image", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": [{ "value": "Example University", "lang": "en" }, { "value": "Exemple d'Université", "lang": "fr" }] } }, "proof": { } }

Note

It is debatable whether the JSON-LD Contexts above need protection because production implementations are expected to 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 might be better suited for certain applications. Implementers are urged to understand how links to external machine-readable content that are not content-integrity protected could result in successful attacks against their applications.

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 be aware that these types of credentials are not verifiable because the authorship either is not known or cannot be trusted.

This section is non-normative.

A verifier might need to ensure it is the intended recipient of averifiable presentation and not the target of aman-in-the-middle attack. Approaches such as token binding [RFC8471], which ties the request for averifiable presentation to the response, can secure the protocol. Any unsecured protocol is susceptible to man-in-the-middle attacks.

This section is non-normative.

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

For example, a university might issue two verifiable credentials to a person, each containing two properties, which must be taken together to to designate the "role" of that person in a given "department", such as "Staff Member" in the "Department of Computing", or "Post Graduate Student" in the "Department of Economics". If these verifiable credentials are atomized to put only one of these properties into each credential , then the university would issue four credentials to the person, each containing one of the following designations: "Staff Member", "Post Graduate Student", "Department of Computing", and "Department of Economics". Theholder might then transfer the "Staff Member" and "Department of Economics" verifiable credentials to a verifier, which together would comprise a false claim.

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 theverifiable credential is valid might create exploitable security vulnerabilities. Expiration periods shorter than the timeframe where the information expressed by the verifiable credential is valid creates a burden on holders and verifiers. It is therefore important to set validity periods for verifiable credentials that are appropriate to the use case and the expected lifetime for the information contained in theverifiable credential.

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:

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 implementation of any web standard or protocol, ignoring accessibility issues makes this information unusable by a large subset of the population. It is important to follow accessibility guidelines and standards, such as [WCAG21], to ensure that all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which have historically created problems for assistive technologies.

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

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 acredential, 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 relying on a viewer's interpretation of 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.

This section is non-normative.

Implementers are advised to be aware of a number of internationalization considerations 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 limits the applicability of the specification and significantly diminishes its value as a standard.

Implementers are strongly advised to read the_Strings on the Web: Language and Direction Metadata_ document [STRING-META], published by the W3C Internationalization Activity, which elaborates on the need to provide reliable metadata about text to support internationalization. For the latest information on internationalization considerations, implementers are also urged to read the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.

This section outlines general internationalization considerations to take into account when utilizing this data model and is intended to highlight specific parts of the _Strings on the Web: Language and Direction Metadata_document [STRING-META] that implementers might be interested in reading.

This section is non-normative.

Data publishers are strongly encouraged to read the section on Cross-Syntax Expression in the Strings on the Web: Language and Direction Metadata document [STRING-META] to ensure that the expression of language and base direction information is possible across multiple expression syntaxes, such as [JSON-LD], [JSON], and CBOR [RFC7049].

The general design pattern is to use the following markup template when expressing a text string that is tagged with a language and, optionally, a specific base direction.

Example 36

: Design pattern for natural language strings

"property": { "value": "The string value", "lang": "LANGUAGE" "dir": "DIRECTION" }

Using the design pattern above, the following example expresses the title of a book in the English language without specifying a text direction.

Example 37

: Expressing natural language text as English

"title": { "value": "HTML and CSS: Designing and Creating Websites", "lang": "en" }

The next example uses a similar title expressed in the Arabic language with a base direction of right-to-left.

Example 38

: Arabic text with a base direction of right-to-left

"title": { "value": "HTML و CSS: تصميم و إنشاء مواقع الويب", "lang": "ar" "dir": "rtl" }

Note

The text above would most likely be rendered incorrectly as left-to-right without the explicit expression of language and direction because many systems use the first character of a text string to determine text direction.

Implementers utilizing JSON-LD are strongly urged toextend the JSON-LD Context defining the internationalized property and use the Scoped Context feature of JSON-LD to alias the @value, @language, and@direction keywords to value, lang, and dir, respectively. An example of a JSON-LD Context snippet doing this is shown below.

Example 39

: Specifying scoped aliasing for language information

"title": { "@context": {"value": "@value", "lang": "@language", "dir": "@direction"}, "@id": "https://www.w3.org/2018/credentials/examples#title" }

This section is non-normative.

When multiple languages, base directions, and annotations are used in a single natural language string, more complex mechanisms are typically required. It is possible to use markup languages, such as HTML, to encode text with multiple languages and base directions. It is also possible to use therdf:HTML datatype to encode such values accurately in JSON-LD.

Despite the ability to encode information as HTML, implementers are strongly discouraged from doing this because it:

If implementers feel they must use HTML, or other markup languages capable of containing executable scripts, to address a specific use case, they are advised to analyze how an attacker would use the markup to mount injection attacks against a consumer of the markup and then deploy mitigations against the identified attacks.

This section is non-normative.

While this specification does not provide conformance criteria for the process of the validation of verifiable credentials orverifiable presentations, readers might be curious about how the information in this data model is expected to be utilized by verifiersduring 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.

This section is non-normative.

In the verifiable credentials presented by a holder, the value associated with the id property for eachcredentialSubject is expected to identify a subject to theverifier. 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 holdercontained in the verifiable presentation. The id property is optional. Verifiers could use other propertiesin a verifiable credential to uniquely identify a subject.

Note

For information on how authentication and WebAuthn might work withverifiable credentials, see the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.

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

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 signverifiable credentials that it issued. This metadata is relevant when checking the proofs on the verifiable credentials.

This section is non-normative.

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

This section is non-normative.

The cryptographic mechanism used to prove that the information in averifiable credential or verifiable presentation was not 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:

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

Note

The digital signature provides a number of protections, other than tamper resistance, which 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. TheverificationMethod property specifies, for example, the public key that can be used to verify the digital signature. Dereferencing a public key URL reveals information about the controller of the key, which can be checked against the issuer of the credential. TheproofPurpose property clearly expresses the purpose for the proof and ensures this information is protected by the signature. A proof is typically attached to a verifiable presentation for authentication purposes and to a verifiable credential as a method of assertion.

This section is non-normative.

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

This section is non-normative.

If the credentialStatus property is available, the status of averifiable credential is expected to be evaluated by the verifieraccording to the credentialStatus type definition for theverifiable credential and the verifier's own status evaluation criteria. For example, a verifier can ensure the status of theverifiable credential is not "withdrawn for cause by the issuer".

This section is non-normative.

Fitness for purpose is about whether the custom properties in theverifiable 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 on more abstract properties, such asageOver.

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

This section is non-normative.

This section is non-normative.

The base context, located athttps://www.w3.org/2018/credentials/v1 with a SHA-256 digest of**ab4ddd9a531758807a79a5b450510d61ae8d147eab966cc9a200c07095b0cdcc**, can be used to implement a local cached copy. For convenience, the base context is also provided in this section.

{
  "@context": {
    "@version": 1.1,
    "@protected": true,

    "id": "@id",
    "type": "@type",

    "VerifiableCredential": {
      "@id": "https://www.w3.org/2018/credentials#VerifiableCredential",
      "@context": {
        "@version": 1.1,
        "@protected": true,

        "id": "@id",
        "type": "@type",

        "cred": "https://www.w3.org/2018/credentials#",
        "sec": "https://w3id.org/security#",
        "xsd": "http://www.w3.org/2001/XMLSchema#",

        "credentialSchema": {
          "@id": "cred:credentialSchema",
          "@type": "@id",
          "@context": {
            "@version": 1.1,
            "@protected": true,

            "id": "@id",
            "type": "@type",

            "cred": "https://www.w3.org/2018/credentials#",

            "JsonSchemaValidator2018": "cred:JsonSchemaValidator2018"
          }
        },
        "credentialStatus": {"@id": "cred:credentialStatus", "@type": "@id"},
        "credentialSubject": {"@id": "cred:credentialSubject", "@type": "@id"},
        "evidence": {"@id": "cred:evidence", "@type": "@id"},
        "expirationDate": {"@id": "cred:expirationDate", "@type": "xsd:dateTime"},
        "holder": {"@id": "cred:holder", "@type": "@id"},
        "issued": {"@id": "cred:issued", "@type": "xsd:dateTime"},
        "issuer": {"@id": "cred:issuer", "@type": "@id"},
        "issuanceDate": {"@id": "cred:issuanceDate", "@type": "xsd:dateTime"},
        "proof": {"@id": "sec:proof", "@type": "@id", "@container": "@graph"},
        "refreshService": {
          "@id": "cred:refreshService",
          "@type": "@id",
          "@context": {
            "@version": 1.1,
            "@protected": true,

            "id": "@id",
            "type": "@type",

            "cred": "https://www.w3.org/2018/credentials#",

            "ManualRefreshService2018": "cred:ManualRefreshService2018"
          }
        },
        "termsOfUse": {"@id": "cred:termsOfUse", "@type": "@id"},
        "validFrom": {"@id": "cred:validFrom", "@type": "xsd:dateTime"},
        "validUntil": {"@id": "cred:validUntil", "@type": "xsd:dateTime"}
      }
    },

    "VerifiablePresentation": {
      "@id": "https://www.w3.org/2018/credentials#VerifiablePresentation",
      "@context": {
        "@version": 1.1,
        "@protected": true,

        "id": "@id",
        "type": "@type",

        "cred": "https://www.w3.org/2018/credentials#",
        "sec": "https://w3id.org/security#",

        "holder": {"@id": "cred:holder", "@type": "@id"},
        "proof": {"@id": "sec:proof", "@type": "@id", "@container": "@graph"},
        "verifiableCredential": {"@id": "cred:verifiableCredential", "@type": "@id", "@container": "@graph"}
      }
    },

    "EcdsaSecp256k1Signature2019": {
      "@id": "https://w3id.org/security#EcdsaSecp256k1Signature2019",
      "@context": {
        "@version": 1.1,
        "@protected": true,

        "id": "@id",
        "type": "@type",

        "sec": "https://w3id.org/security#",
        "xsd": "http://www.w3.org/2001/XMLSchema#",

        "challenge": "sec:challenge",
        "created": {"@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime"},
        "domain": "sec:domain",
        "expires": {"@id": "sec:expiration", "@type": "xsd:dateTime"},
        "jws": "sec:jws",
        "nonce": "sec:nonce",
        "proofPurpose": {
          "@id": "sec:proofPurpose",
          "@type": "@vocab",
          "@context": {
            "@version": 1.1,
            "@protected": true,

            "id": "@id",
            "type": "@type",

            "sec": "https://w3id.org/security#",

            "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"},
            "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}
          }
        },
        "proofValue": "sec:proofValue",
        "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"}
      }
    },

    "EcdsaSecp256r1Signature2019": {
      "@id": "https://w3id.org/security#EcdsaSecp256r1Signature2019",
      "@context": {
        "@version": 1.1,
        "@protected": true,

        "id": "@id",
        "type": "@type",

        "sec": "https://w3id.org/security#",
        "xsd": "http://www.w3.org/2001/XMLSchema#",

        "challenge": "sec:challenge",
        "created": {"@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime"},
        "domain": "sec:domain",
        "expires": {"@id": "sec:expiration", "@type": "xsd:dateTime"},
        "jws": "sec:jws",
        "nonce": "sec:nonce",
        "proofPurpose": {
          "@id": "sec:proofPurpose",
          "@type": "@vocab",
          "@context": {
            "@version": 1.1,
            "@protected": true,

            "id": "@id",
            "type": "@type",

            "sec": "https://w3id.org/security#",

            "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"},
            "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}
          }
        },
        "proofValue": "sec:proofValue",
        "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"}
      }
    },

    "Ed25519Signature2018": {
      "@id": "https://w3id.org/security#Ed25519Signature2018",
      "@context": {
        "@version": 1.1,
        "@protected": true,

        "id": "@id",
        "type": "@type",

        "sec": "https://w3id.org/security#",
        "xsd": "http://www.w3.org/2001/XMLSchema#",

        "challenge": "sec:challenge",
        "created": {"@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime"},
        "domain": "sec:domain",
        "expires": {"@id": "sec:expiration", "@type": "xsd:dateTime"},
        "jws": "sec:jws",
        "nonce": "sec:nonce",
        "proofPurpose": {
          "@id": "sec:proofPurpose",
          "@type": "@vocab",
          "@context": {
            "@version": 1.1,
            "@protected": true,

            "id": "@id",
            "type": "@type",

            "sec": "https://w3id.org/security#",

            "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"},
            "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}
          }
        },
        "proofValue": "sec:proofValue",
        "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"}
      }
    },

    "RsaSignature2018": {
      "@id": "https://w3id.org/security#RsaSignature2018",
      "@context": {
        "@version": 1.1,
        "@protected": true,

        "challenge": "sec:challenge",
        "created": {"@id": "http://purl.org/dc/terms/created", "@type": "xsd:dateTime"},
        "domain": "sec:domain",
        "expires": {"@id": "sec:expiration", "@type": "xsd:dateTime"},
        "jws": "sec:jws",
        "nonce": "sec:nonce",
        "proofPurpose": {
          "@id": "sec:proofPurpose",
          "@type": "@vocab",
          "@context": {
            "@version": 1.1,
            "@protected": true,

            "id": "@id",
            "type": "@type",

            "sec": "https://w3id.org/security#",

            "assertionMethod": {"@id": "sec:assertionMethod", "@type": "@id", "@container": "@set"},
            "authentication": {"@id": "sec:authenticationMethod", "@type": "@id", "@container": "@set"}
          }
        },
        "proofValue": "sec:proofValue",
        "verificationMethod": {"@id": "sec:verificationMethod", "@type": "@id"}
      }
    },

    "proof": {"@id": "https://w3id.org/security#proof", "@type": "@id", "@container": "@graph"}
  }
}

This section is non-normative.

The verifiable credential and verifiable presentation data models leverage a variety of underlying technologies including [JSON-LD] and [JSON-SCHEMA-2018]. This section will provide a comparison of the@context, type, and credentialSchemaproperties, and cover some of the more specific use cases where it is possible to use these features of the data model.

The type property is used to uniquely identify the type of the verifiable credential in which it appears, i.e., to indicate which set of claims the verifiable credential contains. This property, and the value VerifiableCredential within the set of its values, are mandatory. Whilst it is good practice to include one additional value depicting the unique subtype of this verifiable credential, it is permitted to either omit or include additional type values in the array. Many verifiers will request a verifiable credential of a specific subtype, then omitting the subtype value could make it more difficult for verifiers to inform the holder which verifiable credential they require. When a verifiable credential has multiple subtypes, listing all of them in the typeproperty is sensible. While the semantics are the same in both a [JSON] and [JSON-LD] representation, the usage of the type property in a [JSON-LD] representation of a verifiable credential is able to enforce the semantics of theverifiable credential better than a [JSON] representation of the same credential because the machine is able to check the semantics. With [JSON-LD], the technology is not only describing the categorization of the set of claims, the technology is also conveying the structure and semantics of the sub-graph of the properties in the graph. In [JSON-LD], this represents the type of the node in the graph which is why some [JSON-LD] representations of a verifiable credential will use the type property on many objects in theverifiable credential.

The primary purpose of the @context property, from a [JSON-LD] perspective, is to convey the meaning of the data and term definitions of the data in a verifiable credential, in a machine readable way. When encoding a pure [JSON] representation, the @context property remains mandatory and provides some basic support for global semantics. The @contextproperty is used to map the globally unique URIs for properties in verifiable credentials and verifiable presentations into short-form alias names, making both the [JSON] and [JSON-LD] representations more human-friendly to read. From a [JSON-LD] perspective, this mapping also allows the data in a credential to be modeled in a network of machine-readable data, by enhancing how the data in the verifiable credential or verifiable presentation relates to a larger machine-readable data graph. This is useful for telling machines how to relate the meaning of data to other data in an ecosystem where parties are unable to coordinate. This property, with the first value in the set beinghttps://www.w3.org/2018/credentials/v1, is mandatory.

Since the @context property is used to map data to a graph data model, and the type property in [JSON-LD] is used to describe nodes within the graph, the type property becomes even more important when using the two properties in combination. For example, if the type property is not included within the resolved@context resource using [JSON-LD], it could lead to claims being dropped and/or their integrity no longer being protected during production and consumption of the verifiable credential. Alternatively, it could lead to errors being raised during production or consumption of a verifiable credential. This will depend on the design choices of the implementation and both paths are used in implementations today, so it's important to pay attention to these properties when using a [JSON-LD] representation of a verifiable credential or verifiable presentation.

The primary purpose of the credentialSchema property is to define the structure of the verifiable credential, and the datatypes for the values of each property that appears. A credentialSchema is useful for defining the contents and structure of a set of claims in a verifiable credential, whereas [JSON-LD] and a @context in a verifiable credential are best used only for conveying the semantics and term definitions of the data, and can be used to define the structure of theverifiable credential as well.

While it is possible to use some [JSON-LD] features to allude to the contents of the verifiable credential, it's not generally suggested to use @context to constrain the data types of the data model. For example, "@type": "@json" is useful for leaving the semantics open-ended and not strictly defined. This can be dangerous if the implementer is looking to constrain the data type of the claims in thecredential, and is expected not to be used.

When the credentialSchema and @context properties are used in combination, both producers and consumers can be more confident about the expected contents and data types of the verifiable credentialand verifiable presentation.

This section is non-normative.

This section describes possible relationships between a subject and aholder and how the Verifiable Credentials Data Model expresses these relationships. The following diagram illustrates these relationships, with the subsequent sections describing how each of these relationships are handled in the data model.

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 Authorizes 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 13 Subject-Holder Relationships in Verifiable Credentials.

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 theholder if the verifiable presentation is digitally signed by theholder and all contained verifiable credentials are about asubject that can be identified to be the same as the holder.

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

This section is non-normative.

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

Example 40

: Usage of the nonTransferable 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", "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", ... } }

This section is non-normative.

In this case, the credentialSubject property might contain multiple properties, each providing an aspect of a description of thesubject, which combine together to unambiguously identify thesubject. 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 subjectand the holder.

Example 41

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

This section is non-normative.

Usually verifiable credentials are presented to verifiers by thesubject. 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 letting the subject issue a newverifiable credential and give 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 AppendixC.5 Subject Passes a Verifiable Credential to Someone Else.

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 theholder 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 42

: The relationship property in a child's credential

{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "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": { }
}

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

Example 43

: A relationship credential issued to a parent

{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "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": { } }

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

Example 44

: A relationship credential issued by a child

{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "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": { } }

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

This section is non-normative.

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

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

Example 45

: A holder presenting a verifiable credential that was passed to it by the subject

{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "id": "https://example.com/VP/0987654321", "type": ["VerifiablePresentation"], "verifiableCredential": [ { "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "id": "http://pharma.example.com/credentials/3732", "type": ["VerifiableCredential", "PrescriptionCredential"], "issuer": "https://pharma.example.com/issuer/4", "issuanceDate": "2010-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "prescription": {....} }, "credentialStatus": { "id": "https://pharma.example.com/credentials/status/3#94567", "type": "RevocationList2020Status", "revocationListIndex": "94567", "revocationListCredential": "https://pharma.example.com/credentials/status/3" }, "proof": {....} }, { "@context": [ "https://www.w3.org/2018/credentials/v1", "https://www.w3.org/2018/credentials/examples/v1" ], "id": "https://example.com/VC/123456789", "type": ["VerifiableCredential", "PrescriptionCredential"], "issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21", "issuanceDate": "2010-01-03T19:53:24Z", "credentialSubject": { "id": "did:example:76e12ec21ebhyu1f712ebc6f1z2", "prescription": {....} }, "proof": { "type": "RsaSignature2018", "created": "2018-06-17T10:03:48Z", "proofPurpose": "assertionMethod", "jws": "pYw8XNi1..Cky6Ed=", "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21/keys/234" } } ], "proof": [{ "type": "RsaSignature2018", "created": "2018-06-18T21:19:10Z", "proofPurpose": "authentication", "verificationMethod": "did:example:76e12ec21ebhyu1f712ebc6f1z2/keys/2", "challenge": "c0ae1c8e-c7e7-469f-b252-86e6a0e7387e", "jws": "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 subject of the originalverifiable credential is the issuer, and the credential is a copy of the original prescription.

This section is non-normative.

When an issuer wants to authorize a holder to possess acredential 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.

Note

Verifiable credentials are not an authorization framework and therefore delegation is outside the scope of 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 might be appropriate for some use cases.

Example 46

: A credential issued to a holder who is not the (only) subject of the credential, who has no relationship with the subject of the credential, but who has a relationship with the 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", "NameAndAddress"], "issuer": "https://example.edu/issuers/14", "holder": { "type": "LawEnforcement", "id": "did:example:ebfeb1276e12ec21f712ebc6f1c" }, "issuanceDate": "2010-01-01T19:23: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", "proofPurpose": "assertionMethod", "verificationMethod": "https://example.edu/issuers/14/keys/234", "jws": "pY9...Cky6Ed = " } }

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.

This section is non-normative.

This section will be submitted to the Internet Engineering Steering Group (IESG) for review, approval, and registration with IANA in the "JSON Web Token Claims Registry".

This section contains the substantive changes that have been made since the publication of v1.0 of this specification as a W3C Recommendation.

Changes since the Recommendation:

This section is non-normative.

The Working Group thanks the following individuals not only for their contributions toward the content of this document, but also for yeoman's work in this standards community that drove changes, discussion, and consensus among a sea of varied opinions: Matt Stone, Gregg Kellogg, Ted Thibodeau Jr, Oliver Terbu, Joe Andrieu, David I. Lehn, Matthew Collier, and Adrian Gropper.

Work on this specification has been supported by the Rebooting the Web of Trust community facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles, Brian Weller, Betty Dhamers, Kaliya Young, Manu Sporny, Drummond Reed, Joe Andrieu, Heather Vescent, Kim Hamilton Duffy, Samantha Chase, and Andrew Hughes. The participants in the Internet Identity Workshop, facilitated by Phil Windley, Kaliya Young, Doc Searls, and Heidi Nobantu Saul, also supported the refinement of this work through numerous working sessions designed to educate about, debate on, and improve this specification.

The Working Group also thanks our Chairs, Dan Burnett, Matt Stone, Brent Zundel, and Wayne Chang, as well as our W3C Staff Contacts, Kazuyuki Ashimura and Ivan Herman, for their expert management and steady guidance of the group through the W3C standardization process.

Portions of the work on this specification have been funded by the United States Department of Homeland Security's Science and Technology Directorate under contract HSHQDC-17-C-00019. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.

The Working Group would like to thank the following individuals for reviewing and providing feedback on the specification (in alphabetical order):

Christopher Allen, David Ammouial, Joe Andrieu, Bohdan Andriyiv, Ganesh Annan, Kazuyuki Ashimura, Tim Bouma, Pelle Braendgaard, Dan Brickley, Allen Brown, Jeff Burdges, Daniel Burnett, ckennedy422, David Chadwick, Chaoxinhu, Kim (Hamilton) Duffy, Lautaro Dragan, enuoCM, Ken Ebert, Eric Elliott, William Entriken, David Ezell, Nathan George, Reto Gmür, Ryan Grant, glauserr, Adrian Gropper, Joel Gustafson, Amy Guy, Lovesh Harchandani, Daniel Hardman, Dominique Hazael-Massieux, Jonathan Holt, David Hyland-Wood, Iso5786, Renato Iannella, Richard Ishida, Ian Jacobs, Anil John, Tom Jones, Rieks Joosten, Gregg Kellogg, Kevin, Eric Korb, David I. Lehn, Michael Lodder, Dave Longley, Christian Lundkvist, Jim Masloski, Pat McBennett, Adam C. Migus, Liam Missin, Alexander Mühle, Anthony Nadalin, Clare Nelson, Mircea Nistor, Grant Noble, Darrell O'Donnell, Nate Otto, Matt Peterson, Addison Phillips, Eric Prud'hommeaux, Liam Quin, Rajesh Rathnam, Drummond Reed, Yancy Ribbens, Justin Richer, Evstifeev Roman, RorschachRev, Steven Rowat, Pete Rowley, Markus Sabadello, Kristijan Sedlak, Tzviya Seigman, Reza Soltani, Manu Sporny, Orie Steele, Matt Stone, Oliver Terbu, Ted Thibodeau Jr, John Tibbetts, Mike Varley, Richard Varn, Heather Vescent, Christopher Lemmer Webber, Benjamin Young, Kaliya Young, Dmitri Zagidulin, and Brent Zundel.

[JSON-LD]

JSON-LD 1.1: A JSON-based Serialization for Linked Data. Gregg Kellogg; Manu Sporny; Dave Longley; Markus Lanthaler; Pierre-Antoine Champin; Niklas Lindström. W3C JSON-LD 1.1 Working Group. W3C Working Draft. URL: https://www.w3.org/TR/json-ld11/

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119

[RFC3986]

Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986

[RFC7515]

JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7515

[RFC7519]

JSON Web Token (JWT). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7519

[RFC8174]

Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174

[RFC8259]

The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259

[XMLSCHEMA11-2]

W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/

[CL-SIGNATURES]

A Signature Scheme with Efficient Protocols. Jan Camenisch; Anna Lysyanskaya. IBM Research. Peer Reviewed Paper. URL: https://www.researchgate.net/publication/220922101_A_Signature_Scheme_with_Efficient_Protocols

[DATA-INTEGRITY]

Data Integrity. Manu Sporny; Dave Longley. Credentials Community Group. CG-DRAFT. URL: https://w3c-ccg.github.io/data-integrity-spec/

[DEMOGRAPHICS]

Simple Demographics Often Identify People Uniquely. Latanya Sweeney. Data Privacy Lab. URL: https://dataprivacylab.org/projects/identifiability/paper1.pdf

[HASHLINK]

Cryptographic Hyperlinks. Manu Sporny. Internet Engineering Task Force (IETF). Internet-Draft. URL: https://datatracker.ietf.org/doc/draft-sporny-hashlink/

[IPFS]

InterPlanetary File System (IPFS). Wikipedia. URL: https://en.wikipedia.org/wiki/InterPlanetary_File_System

[JSON]

The JavaScript Object Notation (JSON) Data Interchange Format. T. Bray, Ed.. IETF. December 2017. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc8259

[JSON-SCHEMA-2018]

JSON Schema: A Media Type for Describing JSON Documents. Austin Wright; Henry Andrews. Internet Engineering Task Force (IETF). Internet-Draft. URL: https://datatracker.ietf.org/doc/draft-handrews-json-schema/

[LDP-REGISTRY]

Linked Data Cryptographic Suite Registry. Manu Sporny; Drummond Reed; Orie Steele. Credentials Community Group. CG-DRAFT. URL: https://w3c-ccg.github.io/ld-cryptosuite-registry/

[LINKED-DATA]

Linked Data Design Issues. Tim Berners-Lee. W3C. 27 July 2006. W3C-Internal Document. URL: https://www.w3.org/DesignIssues/LinkedData.html

[RFC7049]

Concise Binary Object Representation (CBOR). C. Bormann; P. Hoffman. IETF. October 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7049

[RFC7516]

JSON Web Encryption (JWE). M. Jones; J. Hildebrand. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7516

[RFC7797]

JSON Web Signature (JWS) Unencoded Payload Option. M. Jones. IETF. February 2016. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7797

[RFC8471]

The Token Binding Protocol Version 1.0. A. Popov, Ed.; M. Nystroem; D. Balfanz; J. Hodges. IETF. October 2018. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8471

[STRING-META]

Strings on the Web: Language and Direction Metadata. Addison Phillips; Richard Ishida. Internationalization Working Group. W3C Working Draft. URL: https://www.w3.org/TR/string-meta/

[VC-EXTENSION-REGISTRY]

Verifiable Credentials Extension Registry. Manu Sporny. Credentials Community Group. CG-DRAFT. URL: https://w3c-ccg.github.io/vc-extension-registry/

[VC-IMP-GUIDE]

Verifiable Credentials Implementation Guidelines 1.0. Andrei Sambra; Manu Sporny. Credentials Community Group. W3C Editor's Draft. URL: https://w3c.github.io/vc-imp-guide/

[VC-USE-CASES]

Verifiable Credentials Use Cases. Shane McCarron; Joe Andrieu; Matt Stone; Tzviya Siegman; Gregg Kellogg; Ted Thibodeau. W3C. 24 September 2019. W3C Working Group Note. URL: https://www.w3.org/TR/vc-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/