Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
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. The family of W3C Recommendations for Verifiable Credentials, described in this overview document, provides a mechanism to express these sorts of credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable.
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/.
This document was published by the Verifiable Credentials Working Group as a Group Note using the Note track.
This Group Note is endorsed by the Verifiable Credentials Working Group, but is not endorsed by W3C itself nor its Members.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
The W3C Patent Policy does not carry any licensing requirements or commitments on this document.
This document is governed by the 03 November 2023 W3C Process Document.
This document provides a non-normative, high-level overview for W3C's Verifiable Credential specifications and serves as a roadmap for the documents that define, describe, and secure these credentials. It is not the goal of this document to be very precise, nor does this overview cover all the details. The intention is to provide users, implementers, or anyone interested in the subject, a general understanding of the concepts and how the various specifications, published by the Verifiable Credentials Working Group, fit together.
Figure 1 provides an overview of the main building blocks for Verifiable Credentials, including their (normative) dependencies. For more details, see the subsequent sections in this document.
The Verifiable Credentials Data Model v2.0 [VC-DATA-MODEL-2.0] specification, which defines the core concepts that all other specifications depend on, plays a central role. The model is defined in abstract terms, and applications express their specific credentials using a serialization of the data model. The current specifications mostly use a JSON serialization; the community may develop other serializations in the future.
When Verifiable Credentials are serialized in JSON, it is important to trust that the structure of a Credential may be interpreted in a consistent manner by all participants in the verifiable credential ecosystem. The Verifiable Credentials JSON Schema Specification [VC-JSON-SCHEMA] defines how [JSON-SCHEMA] can be used for that purpose.
Credentials can be secured using two different mechanisms: enveloping proofs or embedded proofs. In both cases, a Credential is cryptographically secured by a proof (for example, using digital signatures). In the enveloping case, the proof wraps around the Credential, whereas embedded proofs are included in the serialization, alongside the Credential itself.
A family of enveloping proofs is defined in the Securing Verifiable Credentials using JOSE and COSE [VC-JOSE-COSE] document, relying on technologies defined by the IETF. Other types of enveloping proofs may be specified by the community.
The general structure for embedded proofs is defined in a separate Verifiable Credential Data Integrity 1.0 [VC-DATA-INTEGRITY] specification. Furthermore, the Working Group also specifies some instances of this general structure in the form of the "cryptosuites": Data Integrity EdDSA Cryptosuites v1.0 [VC-DI-EDDSA], Data Integrity ECDSA Cryptosuites v1.0 [VC-DI-ECDSA], and Data Integrity BBS Cryptosuites v1.0 [VC-DI-BBS]. Other cryptosuites may be specified by the community.
The Bitstring Status List v1.0 [VC-BITSTRING-STATUS-LIST] specification defines a privacy-preserving, space-efficient, and high-performance mechanism for publishing the status of a specific Verifiable Credential, such as its suspension or revocation, through the use of bitstrings.
Finally, the Controller Documents 1.0 [CONTROLLER-DOCUMENT] specification defines some common terms (e.g., verification relationships and methods) that are used not only by other Verifiable Credential specifications, but also other Recommendations such as Decentralized Identifiers (DIDs) v1.0 [DID-CORE].
The Verifiable Credential specifications rely on an ecosystem consisting of entities playing different "roles". The main roles are:
For a more precise definition of these roles, as well as other roles, see the relevant section in the data model specification.
A core concept is "claims": statements made about various entities, referred to as "subjects". Subjects may be a holder, an issuer, or a verifier as listed above, but may also any be another person (e.g., the person holding a university degree), an animal, an abstract concept, etc. Claims may also be on a Credential itself, such as issuance date, validity periods, etc. (Such claims are also loosely referred to as "credential metadata".)
Claims are expressed using "properties" referring to "values". Values may be literals, but may also be other entities referred to, usually, by a [URL]. It that case, the entity may become the subject of another claim; these claims, together, form a "graph" of claims that represents a Credential. (See Figure 6 for an example of such a graph represented graphically. For more complex examples, refer to the Verifiable Credentials Data Model v2.0 specification itself.)
The Verifiable Credentials Data Model v2.0 document specifies a number of standard properties. These include, for example, credentialSubject
, type
, issuer
, or validFrom
.
Developers may define their own properties to express specific types of Credentials, like a driving license, a university degree, or a marriage certificate.
A Credential is a set of one or more claims made by the same entity. Credentials might also include an identifier and metadata to describe properties of the Credential, such as a reference to the issuer, the validity date, a representative image, the revocation mechanism, and so on. A Verifiable Credential is a set of claims and metadata that also includes verification mechanisms that cryptographically prove who issued it, ensures that the data has not been tampered with, etc.
For a more detailed description of abstract Verifiable Credentials, with examples, see the relevant section in the data model specification.
Enhancing privacy is a key design feature of Verifiable Credentials. Therefore, it is important, for entities using this technology, to be able to express only the portions of their persona that are appropriate for a given situation. The expression of a subset of one's persona is called a Verifiable Presentation. Examples of different personas include a person's professional persona, their online gaming persona, their family persona, or an incognito persona.
A Verifiable Presentation is created by a holder, can express data stemming from multiple Verifiable Credentials, and can contain additional metadata in forms of additional claims. They are used to present claims to a verifier. It is also possible to present Verifiable Credential directly.
A Verifiable Presentation is usually short-lived, it is not meant to be stored for a longer period.
For a more detailed description of abstract Verifiable Presentations, with examples, see the relevant section in the data model specification.
In the [VC-DATA-MODEL-2.0] specification, as in the other documents, Verifiable Credentials and Presentations are mostly expressed in JSON [RFC7519], more specifically [JSON-LD11].
In this serialization, properties of claims are represented as JSON names, and values as JSON literals or objects.
Subjects of claims are either explicitly identified by an id
property, or implicitly by appearing as an object of another claim.
Standard properties defined by the [VC-DATA-MODEL-2.0] form a distinct set of JSON names, referred to as a (standard) vocabulary. An important characteristics of Verifiable Credentials in JSON-LD is that it favors a decentralized and permissionless approach to extend to a new application area through application-specific set of properties, i.e., vocabularies, distributed on the Web. Anyone can "publish" such a vocabulary, following some rules described in the extensibility section of the specification.
The following JSON-LD code is an example for a simple Credential. It states that the person named "Pat", identified by https://www.exampl.org/persons/pat
, is an alumni of the Example University (identified by did:example:c276e12ec21ebfeb1f712ebc6f1
).
The Credential is valid from the 1st of January 2010, and is issued by an entity identified by did:example:2g55q912ec3476eba2l9812ecbfe
.
Most of the properties in the Credential are from the standard Verifiable Credentials vocabulary, but some terms (like alumniOf
, AlumniCredential
) are added by the application-specific vocabulary referred to by https://www.w3.org/ns/credentials/examples/v2
.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": ["VerifiableCredential", "ExampleAlumniCredential"], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } } }
Figure 6 shows the same Credential, but represented as a graph of claims, as described in 3.1.1 Claims, Properties.
The Credential in Example 1 is used throughout this document to show how to apply additional features defined by the various specifications.
The Credential in Example 1, issued by Example University, is stored by a holder (who may be a person, a digital wallet, or any other entity). On request, the holder may "present" a Credential to a verifier, encapsulated in a Verifiable Presentation. This is how the result may look like in the JSON-LD serialization:
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"type": "VerifiablePresentation",
"id": "urn:uuid:313801ba-24b7-11ee-be02-ff560265cf9b",
"holder": "did:example:12345678",
"validUntil": "2020-12-31T00:00:00Z"
"verifiableCredential": {
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
}
}
}
Note that the holder could have presented several Credentials within the same presentation or create a new Credential by either combining it with others, or removing some claims as irrelevant for the specific context.
A significant part of the integrity of a Verifiable Credential comes from the ability to structure its contents so that all three parties — issuer, holder, verifier — may have a consistent mechanism of trust in interpreting the data that they are provided with. One way of doing that is to use [JSON-SCHEMA] to check the structural validity of the Credential. The Verifiable Credentials JSON Schema Specification [VC-JSON-SCHEMA] specification adds standard properties to express the association of a Credential with a JSON Schema.
Consider the following example:
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
"credentialSchema": {
"id": "https://university.example/Credential-schema.json",
"type": "JsonSchema"
}
}
When dereferenced, the URL https://university.example/Credential-schema.json
should return a JSON Schema, for example:
{ "$id": "https://university.example/schemas/credential.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ExampleAlumniCredential", "description": "Alumni Credential using JsonSchema", "type": "object", "properties": { "credentialSubject": { "type": "object", "properties": { "alumniOf": { "type": "string", "format": "url" } }, "required": [ "alumniOf" ] } } }
Using this JSON Schema, a verifier can check whether the Credential is structurally valid or not.
For security reasons one may want to go a step further: check/verify the JSON Schema itself to see if, for example, it has been tempered with.
This can be done by referring to the JSON Schema indirectly through a separate Verifiable Credential.
The reference to such a Verifiable Credential looks very much like Example 3 except for the value of the type
:
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
"credentialSchema": {
"id": "https://university.example/Credential-schema-credential",
"type": "JsonSchemaCredential"
}
}
In this case, when dereferenced, the URL https://university.example/Credential-schema-credential
should return a Verifiable Credential, whose credentialSubject
property refers to the required JSON Schema (i.e., https://university.example/Credential-schema.json
).
See the example in the Verifiable Credentials JSON Schema Specification specification for an example and for further details.
Enveloping proofs of Credentials, defined by this Working Group, are based on JSON Object Signing and Encryption (JOSE), CBOR Object Signing and Encryption (COSE) [RFC9052], or Selective Disclosure for JWTs [SD-JWT]. These are all IETF specifications, or groups of specifications (like JOSE, that refers to JWT [RFC7519], JWS [RFC7515], or JWK [RFC7517]). The Securing Verifiable Credentials using JOSE and COSE [VC-JOSE-COSE] recommendation defines a "bridge" between these and the Verifiable Credentials Data Model v2.0, specifying the suitable header claims, media types, etc.
In the case of JOSE, the Credential is the "payload" (to use the IETF terminology). This is preceded by a suitable header whose details are specified by the relevant section of the [VC-JOSE-COSE] specification. These are encoded, concatenated, and signed, to be transferred in a compact form by one entity to another (e.g., sent by the holder to the verifier). All the intricate details on signatures, encryption keys, etc., are defined by the IETF specifications; see Example 6 for a specific case.
The usage of COSE [RFC9052] is similar to JOSE, except that all structures are represented in CBOR [RFC8949]. From the Credentials point of view, however, the structure is similar insofar as the Credential (or the Presentation) is again the payload for COSE. The usage of CBOR means that the final representation of the Verifiable Credential (or Presentation) has a significantly reduced footprint which can be, for example, shown in a QR Code.
The [SD-JWT] is a variant of JOSE, which allows for the selective disclosure of individual claims. Claims can be selectively hidden or revealed to the verifier, but all claims are cryptographically protected against modification. This approach is obviously more complicated than the JOSE case but, from the Credentials point of view, the structure is again similar. The original Credential is the payload for SD-JWT; and it is the holder's responsibility to use the SD-JWT when presenting the Credential to a verifier using selective disclosure.
Example 6 shows the Credential example shown in Example 1, enriched with a reference to a JSON Schema in Example 3. It is secured by two different enveloping proofs, namely JOSE and COSE.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": ["VerifiableCredential", "ExampleAlumniCredential"], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" } }
{ "kid": "ExHkBMW9fmbkvV266mRpuP2sUY_N_EWIN1lapUzO8ro", "alg": "ES256" }application/vc
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": [ "VerifiableCredential", "ExampleAlumniCredential" ], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" } }application/vc+jwt
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": [ "VerifiableCredential", "ExampleAlumniCredential" ], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" } }application/cbor-diagnostic
/ cose-sign1 / 18([
/ protected / << {
/ alg / 1 : -35 / ES384 /
} >>,
/ unprotected / {
},
/ payload / h'7b224063...6c227d7d',
/ signature / h'8e5652db...a845d38c'
])
The operation of Data Integrity is conceptually simple. To create a cryptographic proof, the following steps are performed: 1) Transformation, 2) Hashing, and 3) Proof Generation.
Verification of a proof involves repeating the same transformation and hashing steps on the verifier's side and, depending on the proof method, validating the newly calculated hash value with the proof associated with the data. In the case of a digital signature, this means verifying, using the cryptographic algorithms associated with the asymmetric keys, that the proof value indeed signs the newly calculated hash.
The Verifiable Credential Data Integrity 1.0 [VC-DATA-INTEGRITY] specification relies on the general structure and defines a set of standard properties describing the details of the proof generation process. The specific details (canonicalization algorithm, hash and/or proof method algorithms, etc.) are defined by separate cryptosuites. The Working Group has defined a number of such cryptosuites as separate specifications, see 4.2.3 Cryptosuites below.
The core property, in the general structure, is proof
.
This property embeds a claim in the Credential, referring to a separate collection of claims (referred to as a Proof Graph) detailing all the claims about the proof itself:
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": ["VerifiableCredential", "ExampleAlumniCredential"], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" }, "proof": { "type": "DataIntegrityProof", … // All the details about the proof … "proofValue": "zQeVb…Wx" } }
Note the proofValue
property, whose object is the result of the proof generation process.
The proof value is for illustrative purposes only, and does not reflect the result of real cryptographic calculations.
The definition of proof
introduces a number of additional properties.
Some of these are metadata properties on the proof itself, like created
, expires
, or domain
.
Others provide the necessary details on the proof generation process itself, like cryptosuite
, nonce
(if needed), or verificationMethod
that usually refers to cryptographic keys.
The exact format of the public keys, when used for Credentials, is defined in the [CONTROLLER-DOCUMENT] specification, and is based on either the JWK [RFC7517] format or a Multibase encoding of the keys, called Multikey.
Details of the key values are defined by other communities (IETF, cryptography groups, etc.) and are dependent on the specific cryptographic functions they operate with.
It is possible to embed several proofs for the same Credential. These may be a set of independent proofs (based, for example, on different cryptosuites, to accommodate to the specificities of different verifiers), but may also be a "chain" of proofs that must be evaluated in a given order.
A proof may also specify its "purpose" via the proofPurpose
property: different proofs may be provided for authentication, for assertion, or for key agreement protocols.
These are defined in the [CONTROLLER-DOCUMENT] specification.
The verifier is supposed to choose the right proof depending on the purpose of its own operations, which is yet another possible reasons why the holder or the issuer may provide several proofs for the same Credential.
The Working Group publishes three cryptosuite documents: Data Integrity EdDSA Cryptosuites v1.0 [VC-DI-EDDSA], Data Integrity ECDSA Cryptosuites v1.0 [VC-DI-ECDSA], and Data Integrity BBS Cryptosuites v1.0 [VC-DI-BBS]. As their name suggests, the documents rely on existing cryptographic signature schemes: the Edwards-Curve Digital Signature Algorithm (EdDSA) specification [RFC8032], the Elliptic Curve Digital Signature Algorithm (ECDSA) specification [FIPS-186-5], and the BBS Signature Scheme [CFRG-BBS-SIGNATURE], respectively.
Figure 8 provides an overall view of the six cryptosuites defined by the three recommendations. They all implement the general pipeline of proof generation as described in section 4.2.1. As shown on the figure, one axes of differentiation is the data transformation function, i.e., the canonicalization of the JSON serialization: two cryptosuites use JSON Canonicalization (JCS) [RFC8785], the others use RDF Dataset Canonicalization (RDFC-1.0) [RDF-CANON]. The other axis is whether the cryptosuite provides selective disclosure, which is the case for two of the six cryptosuites.
A common characteristics of all these cryptosuites is that keys must always be encoded using the Multikey encoding. For the ECDSA case the keys may also carry the choice of the hash functions to be used by the proof generation algorithm. This provides yet another differentiation axis among cryptosuites.
The two EdDSA cryptosuites, as well as ecdsa-rdfc-2019
and ecdsa-jcs-2019
, follow a simple version of the proof generation pipeline as described in section 4.2.1: the Credential is canonicalized (using either JCS or RDFC-1.0) and the result is hashed (using the hash functions as defined by the signature key).
The calculation of the hash values depend on the canonicalization method: in the JCS case the canonical JSON data is hashed directly, whereas
in the RDFC-1.0 case the individual canonicalized claims are first sorted and then concatenated before being hashed.
However, before signing the hash values, there is an extra twist: the same pipeline is also used on a set of claims called proof options, i.e., all the claims
of the proof graph except proofValue
.
This set of claims is also canonicalized and hashed, following the same process as for the Credential itself, yielding a second hash value.
It is the concatenation of these two values that is signed by EdDSA or ECDSA, respectively, producing the value for the proofValue
property.
By doing so, the various proof metadata, as well as the public key reference itself, are also signed and become verifiable.
The ecdsa-sd-2023
and bbs-2023
cryptosuites provide selective disclosures of individual claims.
In both cases, the process separates the base proof (calculated by the issuer for the holder), and the derived proof (which is typically calculated by the holder when selectively presenting credential claims to the verifier).
To calculate the base proof, the Credential is supplemented with extra information that separates the mandatory and non-mandatory claims.
Using that information, the issuer's transformation step in section 4.2.1 produces a
data structure containing the hash of the proof options (much like in the case of the full disclosure schemes) and of the set of mandatory claims, plus the identification of mandatory claims.
Some elements of this data structure are then signed, the resulting structure is converted into CBOR, and
encoded to provide as a multibase-encoded proofValue
.
The derived proof is generated by the holder upon a request containing JSON pointers [RFC6901] identifying the claims to be disclosed.
To answer the request the information in the proofValue
is used to create a reveal document, i.e., a new Credential containing the mandatory claims and the requested non-mandatory claims.
Finally, the holder generates a derived proof for this reveal document, which is sent to the verifier.
The verifier should be in position to trust the proof of the reveal document without having access to the original data and its (base) proof.
In the ecdsa-sd-2023
case, each non-mandatory claim is signed separately by the issuer using a common, ephemeral ECDSA secret key, whose public counterpart is part of the both the base and derived proof values. That can be used to check the disclosed non-mandatory claims.
The bbs-2023
case relies on the cryptographic properties of the BBS scheme itself, which support the creation proofs for the verification of selectively disclosed data.
This is based on the mathematical nature of the BBS scheme: the BBS signature of all the claims (generated by the issuer and part of the base proof) can be reused by the holder to generate a BBS Proof of the subset of the claims (which is part of the derived proof). The BBS specific verification step ensures the required trust.
It is worth noting that the bbs-2023
cryptosuite also offers a number of additional, privacy preserving options; see the sections on
anonymous holder biding,
pseudonyms with issuer-known id, or
pseudonyms with hidden id in the Data Integrity BBS Cryptosuites v1.0 specification.
Example 8 shows the Credential example, shown in Example 1 and enriched with a reference to a JSON Schema in Example 3.
It is secured by two different embedded proofs, using the ecdsa-rdfc-2019
and eddsa-rdfc-2022
cryptosuites.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": ["VerifiableCredential", "ExampleAlumniCredential"], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" } }
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": [ "VerifiableCredential", "ExampleAlumniCredential" ], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" }, "proof": { "type": "DataIntegrityProof", "created": "2024-10-22T15:23:45Z", "verificationMethod": "did:key:zDnaedkp9qeS6isKX16CyW13fcE35sKGjpfkt61B RQWMY8jge", "cryptosuite": "ecdsa-rdfc-2019", "proofPurpose": "assertionMethod", "proofValue": "z2ynJef4aw87QF32xPT8zUBaeNRQpd1Zq9faBGgjNz81aHGZJCgNRE3n BCD7WdA2HCHyaLiDCk9yK2rqrP4bWsj8A" } }
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": [ "VerifiableCredential", "ExampleAlumniCredential" ], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" }, "proof": { "type": "DataIntegrityProof", "created": "2024-10-22T15:23:45Z", "verificationMethod": "did:key:z6MkqGXA65b2WJL5aY54mgcGbXg5Y6t8QyoP7rr1 t5TWHhjJ", "cryptosuite": "eddsa-rdfc-2022", "proofPurpose": "assertionMethod", "proofValue": "z3ePG3srRRu22NYSZECCTYcnJ4h5S78EjXn4HUow35vn6ihbofhdV9TX NJZM7XzrgqpDZuaTRHnDtcZLayCGp6zvc" } }
When dereferenced, the URL did:example:2g55q912ec3476eba2l9812ecbfe#ecdsa-public-key
should return an ECDSA public key in Multikey format, for example:
{ "@context": [ "https://www.w3.org/ns/did/v1", "https://w3id.org/security/multikey/v1" ], "id": "did:example:2g55q912ec3476eba2l9812ecbfe#ecdsa-public-key", "type": "Multikey", "controller": "did:example:2g55q912ec3476eba2l9812ecbfe", "publicKeyMultibase": "z42twTcNeSYcnqg1FLuSFs2bsGH3ZqbRHFmvS9XMsYhjxvHN" }
Note that the value of the verificationMethod
property may have been the public key itself, instead of a reference to a separate resource containing the key.
It is often useful for an issuer of Verifiable Credentials to link to a location where a verifier can check to see if a credential has been suspended or revoked. This additional resource is referred to as a "status list".
The simplest approach for a status list, where there is a one-to-one mapping between a Verifiable Credential and a URL where the status is published, raises privacy as well as performance issues. In order to meet privacy expectations, it is useful to bundle the status of large sets of credentials into a single list to help with group privacy. However, doing so can place an impossible burden on both the server and client if the status information is as much as a few hundred bytes in size per credential across a population of hundreds of millions of holders. The Bitstring Status List v1.0 [VC-BITSTRING-STATUS-LIST] specification defines a highly compressible, highly space-efficient bitstring-based status list mechanism.
Conceptually, a bitstring status list is a sequence of bits. When a single bit specifies a status, such as "revoked" or "suspended", then that status is expected to be true when the bit is set and false when unset. One of the benefits of using a bitstring is that it is a highly compressible data format since, in the average case, large numbers of credentials will remain unrevoked. If compressed using run-length compression techniques such as GZIP [RFC1952] the result is a significantly smaller set of data: the default status list size is 131,072 entries, equivalent to 16 KB of single bit values and, when only a handful of verifiable credentials are revoked, GZIP compresses the bitstring down to a few hundred bytes.
The specification introduces the credentialStatus
property, as well as some additional sub-properties, that should be used to add this additional information to a Verifiable Credential.
Example 10 shows the example from Example 8, combined with the information on the credential status: the purpose of that status information, the reference to the bitstring, and the index into this bitstring for the enclosing credential:
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://university.example/Credential123",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "https://www.example.org/persons/pat",
"name": "Pat",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
},
"credentialSchema": {
"id": "https://university.example/Credential123-schema-credential",
"type": "JsonSchemaCredential"
},
"credentialStatus": {
"id": "https://university.example/statuslist#123456",
"type": "BitstringStatusListEntry",
"statusPurpose": "revocation",
"statusListIndex": "123456",
"statusListCredential": "https://university.example/CredentialStatusList"
}
}
The statusListCredential
property, when dereferenced, should return a separate Credential for the status list.
The status list itself is the subject of that Credential (which, of course, can also be signed). An example is:
{
"@context": [
"https://www.w3.org/ns/credentials/v2"
],
"id": "https://university.example/CredentialStatusList",
"type": ["VerifiableCredential", "BitstringStatusListCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe"",
"validFrom": "2005-01-01T00:00:00",
"credentialSubject": {
"id": "https://university.example/statuslist#list",
"type": "BitstringStatusList",
"statusPurpose": "revocation",
"encodedList": "uH4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
}
}
The core property in this case is encodedList
, which is a base64url encoded version of the GZIP compressed bitstring status list.
The VC Working Group has also published, and maintains, a few additional documents in the form of Working Group Notes. Although these are not formal standards, they represent consensus among the Working Group Participants. These documents are:
As explained in the introductory sections, the specifications define a number of standard vocabularies, i.e., standard sets of properties used as JSON names. These are used by Verifiable Credentials to ensure interoperability. Although the formal specifications of these terms are provided by the respective specifications, the vocabularies are also published as separates documents. This is done for an easier reference and overview, and these documents are also important if Credentials are used by applications based on RDF [RDF11-CONCEPTS]. These vocabulary documents are:
Example 12 shows the Credential example used throughout this document, enriched with a reference to a JSON Schema and to the status information. It is secured via different securing mechanisms defined for Verifiable Credentials.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": ["VerifiableCredential", "ExampleAlumniCredential"], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" }, "credentialStatus": { "id": "https://university.example/statuslist#123456", "type": "BitstringStatusListEntry", "statusPurpose": "revocation", "statusListIndex": "123456", "statusListCredential": "https://university.example/CredentialStatusList" } }
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": [ "VerifiableCredential", "ExampleAlumniCredential" ], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" }, "credentialStatus": { "id": "https://university.example/statuslist#123456", "type": "BitstringStatusListEntry", "statusPurpose": "revocation", "statusListIndex": "123456", "statusListCredential": "https://university.example/CredentialStatusLis t" }, "proof": { "type": "DataIntegrityProof", "created": "2024-10-22T15:23:45Z", "verificationMethod": "did:key:zDnaedkp9qeS6isKX16CyW13fcE35sKGjpfkt61B RQWMY8jge", "cryptosuite": "ecdsa-rdfc-2019", "proofPurpose": "assertionMethod", "proofValue": "z3iPjGCWGVS94L1fA5NJgucQRc7z2n4eb9ARaosxkgFN8rRtUModHsqP 1rDHeZEVt4aWAqHTqugCTrdgD2h6oYh7q" } }
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": [ "VerifiableCredential", "ExampleAlumniCredential" ], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" }, "credentialStatus": { "id": "https://university.example/statuslist#123456", "type": "BitstringStatusListEntry", "statusPurpose": "revocation", "statusListIndex": "123456", "statusListCredential": "https://university.example/CredentialStatusLis t" }, "proof": { "type": "DataIntegrityProof", "created": "2024-10-22T15:23:45Z", "verificationMethod": "did:key:z6MkqGXA65b2WJL5aY54mgcGbXg5Y6t8QyoP7rr1 t5TWHhjJ", "cryptosuite": "eddsa-rdfc-2022", "proofPurpose": "assertionMethod", "proofValue": "z43pTq48dHZucgipUN8gaLQN3LXhwozmjWRnkxYd9poVtexXKBV9w148 mZWKs4Z9uTxCUFxRafPuyNnmqKBeX9gbJ" } }
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": [ "VerifiableCredential", "ExampleAlumniCredential" ], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" }, "credentialStatus": { "id": "https://university.example/statuslist#123456", "type": "BitstringStatusListEntry", "statusPurpose": "revocation", "statusListIndex": "123456", "statusListCredential": "https://university.example/CredentialStatusLis t" }, "proof": { "type": "DataIntegrityProof", "verificationMethod": "did:key:zUC74mGUM9RisRJpUvFcHmphSATn1X4787DN56a4 dRjdKZ1KuCTU2KeX5P21jbszqB6Nf9dJCThqDd53f2yHa3xGamKoQugMkF6HHt8UJENuKkB8Jdf xNGGxiaLiR1uCC5Vdvzd", "cryptosuite": "bbs-2023", "proofPurpose": "assertionMethod", "proofValue": "u2V0ChVhQljdZQOC6-rTtyEcUX5wS31D8COvNAbwhm2r8gAJniYd9s2S wRowF4QDpKau6m7JuZvALD-icaAoJVPbR51PJM89glEPRC-zoQJTB5l26HOhYQBGaYC1gfNHwIQ Z_QV_aKrAJA1UMbYeLzhcjDKxm_Mdxq55pIrtFHSJQO7wOSd6iet3GiHpGE_HGk6G6KLCUQT9YY Isgz4Uy-J-Fi4gfPg6uCcVdEzk8YsG7IeYQ1kbYUKo4dshJIAcpw713QopMvlfCRxHOq3-SHsg4 8iJGR4k5yTAho7D6Zg1Z7usy1gYyti5_UY0LzJtinSVNKJP9FCC7olggo91MnAjcDklFUFLCFRP zvzBfsTy4JD_rmDAEJlFFqeGBZy9pc3N1ZXI" } }
{ "kid": "ExHkBMW9fmbkvV266mRpuP2sUY_N_EWIN1lapUzO8ro", "alg": "ES256" }application/vc
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": [ "VerifiableCredential", "ExampleAlumniCredential" ], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" }, "credentialStatus": { "id": "https://university.example/statuslist#123456", "type": "BitstringStatusListEntry", "statusPurpose": "revocation", "statusListIndex": "123456", "statusListCredential": "https://university.example/CredentialStatusList" } }application/vc+jwt
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://university.example/Credential123", "type": [ "VerifiableCredential", "ExampleAlumniCredential" ], "issuer": "did:example:2g55q912ec3476eba2l9812ecbfe", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "https://www.example.org/persons/pat", "name": "Pat", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "credentialSchema": { "id": "https://university.example/Credential123-schema-credential", "type": "JsonSchemaCredential" }, "credentialStatus": { "id": "https://university.example/statuslist#123456", "type": "BitstringStatusListEntry", "statusPurpose": "revocation", "statusListIndex": "123456", "statusListCredential": "https://university.example/CredentialStatusList" } }application/cbor-diagnostic
/ cose-sign1 / 18([
/ protected / << {
/ alg / 1 : -35 / ES384 /
} >>,
/ unprotected / {
},
/ payload / h'7b224063...74227d7d',
/ signature / h'3fe10092...82f20da8'
])
{
"kid": "ExHkBMW9fmbkvV266mRpuP2sUY_N_EWIN1lapUzO8ro",
"alg": "ES256"
}
{
"_sd_alg": "sha-256",
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"name": "Pat",
"alumniOf": {
"name": "Example University",
"_sd": [
"5NRdVdokGj0DnYRV0Xkqc0mMBCzK4Mbo5VwGnyW0caQ"
]
},
"_sd": [
"9tIx1CEOyR8nR1dFL2izihz7PxA6GjfHg2KpUINifBA"
]
},
"credentialSchema": {
"_sd": [
"4fJ3DzaFIXEEvffF0C_5lePT7c_m4RFXSKcNKvN5kD8",
"iuxGnvKnHoUWU4JxempjoYdEZwTG45d4xuPHkX-8b08"
]
},
"credentialStatus": {
"statusPurpose": "revocation",
"statusListIndex": "123456",
"statusListCredential": "https://university.example/CredentialStatusList",
"_sd": [
"-JmdstSniV60ahq0AALiW_kCzvyaLvCwsxssCGAa-mU",
"O4iU3JG3d3_G2TEDFT9duBbKFH-LNaZzGJKFrqVIQSk"
]
},
"_sd": [
"EYOYhxR17KIIkS6GuE_KZZYiWMGDcg7ZSwcJKIetkzM",
"eHinHd3Iqwr9iaawiIfyY2S5KpJS3cHLmRUdeZ-gO6k"
]
}
SHA-256 Hash: eHinHd3Iqwr9iaawiIfyY2S5KpJS3cHLmRUdeZ-gO6k
Disclosure(s): WyJhZEZyeDZEWUZTZFRPRkdzMC01T0xnIiwgImlkIiwgImh0dHBzOi8vdW5pdmVyc2l0eS5leGFtcGxlL0NyZWRlbnRpYWwxMjMiXQ
Contents: [
"adFrx6DYFSdTOFGs0-5OLg",
"id",
"https://university.example/Credential123"
]
SHA-256 Hash: EYOYhxR17KIIkS6GuE_KZZYiWMGDcg7ZSwcJKIetkzM
Disclosure(s): WyJjeUY4WVlHM1RvQkx0UlJ1X2ZEYzZ3IiwgInR5cGUiLCBbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwgIkV4YW1wbGVBbHVtbmlDcmVkZW50aWFsIl1d
Contents: [
"cyF8YYG3ToBLtRRu_fDc6w",
"type",
[
"VerifiableCredential",
"ExampleAlumniCredential"
]
]
SHA-256 Hash: 9tIx1CEOyR8nR1dFL2izihz7PxA6GjfHg2KpUINifBA
Disclosure(s): WyJRZjZJeWVCa0FfSWo3TGRhTElQeFJBIiwgImlkIiwgImh0dHBzOi8vd3d3LmV4YW1wbGUub3JnL3BlcnNvbnMvcGF0Il0
Contents: [
"Qf6IyeBkA_Ij7LdaLIPxRA",
"id",
"https://www.example.org/persons/pat"
]
SHA-256 Hash: 5NRdVdokGj0DnYRV0Xkqc0mMBCzK4Mbo5VwGnyW0caQ
Disclosure(s): WyJPcnJ0RkVFUXdseE53S1NyLVpNYlhBIiwgImlkIiwgImRpZDpleGFtcGxlOmMyNzZlMTJlYzIxZWJmZWIxZjcxMmViYzZmMSJd
Contents: [
"OrrtFEEQwlxNwKSr-ZMbXA",
"id",
"did:example:c276e12ec21ebfeb1f712ebc6f1"
]
SHA-256 Hash: 4fJ3DzaFIXEEvffF0C_5lePT7c_m4RFXSKcNKvN5kD8
Disclosure(s): WyItRkN5NEdwOHRzWUk3SW1hdzJRWXVRIiwgImlkIiwgImh0dHBzOi8vdW5pdmVyc2l0eS5leGFtcGxlL0NyZWRlbnRpYWwxMjMtc2NoZW1hLWNyZWRlbnRpYWwiXQ
Contents: [
"-FCy4Gp8tsYI7Imaw2QYuQ",
"id",
"https://university.example/Credential123-schema-credential"
]
SHA-256 Hash: iuxGnvKnHoUWU4JxempjoYdEZwTG45d4xuPHkX-8b08
Disclosure(s): WyJQbmRBcG5tYkNVbnFqYklHNFA5SlhBIiwgInR5cGUiLCAiSnNvblNjaGVtYUNyZWRlbnRpYWwiXQ
Contents: [
"PndApnmbCUnqjbIG4P9JXA",
"type",
"JsonSchemaCredential"
]
SHA-256 Hash: O4iU3JG3d3_G2TEDFT9duBbKFH-LNaZzGJKFrqVIQSk
Disclosure(s): WyJ6LUZlTVMtSG5IZEVPRDhfdndPMGR3IiwgImlkIiwgImh0dHBzOi8vdW5pdmVyc2l0eS5leGFtcGxlL3N0YXR1c2xpc3QjMTIzNDU2Il0
Contents: [
"z-FeMS-HnHdEOD8_vwO0dw",
"id",
"https://university.example/statuslist#123456"
]
SHA-256 Hash: -JmdstSniV60ahq0AALiW_kCzvyaLvCwsxssCGAa-mU
Disclosure(s): WyJrVDh2b1J3YzBGdklWSnhibk9zLWd3IiwgInR5cGUiLCAiQml0c3RyaW5nU3RhdHVzTGlzdEVudHJ5Il0
Contents: [
"kT8voRwc0FvIVJxbnOs-gw",
"type",
"BitstringStatusListEntry"
]
The previous sections provided an overview of the Verifiable Credential ecosystem. This section provides more details about how the ecosystem is envisaged to operate.
The roles and information flows in the Verifiable Credential ecosystem are as follows:
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:
These specifications do not define any protocol for transferring Verifiable Credentials or Verifiable Presentations, but assuming other specifications do specify how they are transferred between entities, then the Verifiable Credential Data Model is directly applicable.
These specifications neither define an authorization framework nor does it restrict the business decisions that a verifier might make after verifying a Verifiable Credential or Verifiable presentation. Rather, verifiers apply their own business rules before treating any claim as valid, taking into account the holder, the issuer of the Verifiable Credential, the claims of the Verifiable Credential, and the verifier's own policies.
In particular, sections Terms of Use in the Data Model specification, and the Subject-Holder Relationships section in the Verifiable Credentials Implementation Guide [VC-IMP-GUIDE] specify how a verifier can determine: