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-ld+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'bc6a0cb4...0ad18e44'
])
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 structure of proofs as described in 4.2.1 Generic Data Integrity Structure. 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 the proof generation pipeline as described in 4.2.1 Generic Data Integrity Structure: the Credential is canonicalized (using either JCS or RDFC-1.0), the result is hashed (using the hash functions as defined by the signature key), and the resulting hash value is used for the generation of the proof.
There is, however, 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, producing a second hash value.
It is the concatenation of these two values that is signed by EdDSA or ECDSA, respectively, producing a value for the proofValue
property.
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), and the "Derived Proof" (which is typically calculated by the holder when selectively presenting the credential claims to the verifier).
The challenge is that the verifier should check that the holder can be trusted when verifying a partial value, without having access to the full original data.
To calculate the Base Proof, the Credential is supplemented with extra information that separates the "mandatory" and "non-mandatory" claims. Using that extra information, the transformation step described in 4.2.1 Generic Data Integrity Structure does not only canonicalize the Credential, but also transforms it by explicitly separating these two types of claims into their own sets. Furthermore, each non-mandatory claim must be signed individually, yielding a series of signatures. The final Base Proof is, conceptually, the concatenation of all these signatures and related informations like the separation of mandatory and non-mandatory claims.
The Derived Proof is generated by the holder, when presenting the (derived) Credential. These data are combined with the kind of selective disclosure requests the holder is prepared to honor; it is the combination of all these data that are used for the creation of a Derived Proof that is forwarded to the verifier.
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-14T13:38:58Z", "verificationMethod": "did:key:zDnaeRCkiK28fewJv2ziHyWCDTc3oCkxKhGR26WV JZNwV9jWx", "cryptosuite": "ecdsa-rdfc-2019", "proofPurpose": "assertionMethod", "proofValue": "z2ABDJ549NVwvGKnLDGCuiCLxkEmQmJmDaHo6BAsKdVenmhC5pECcn9d LCrCWaoEJQJCfFMjQN9oAx6TSYZ1nwC9b" } }
{ "@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-14T13:38:58Z", "verificationMethod": "did:key:z6Mkwd8n9jX452rCse7foE1vKrAicSJ78WYkWyeH euGtUBQB", "cryptosuite": "eddsa-rdfc-2022", "proofPurpose": "assertionMethod", "proofValue": "z3gjZd4Ppi5ZqqKvvS6LLoY7NPZ9Sii68EH4k1jvmGXhqLS1pGcmMziT rQYKuHhUd7YsP4AGVp5HwYtqMac6PF2Nx" } }
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-14T13:38:58Z", "verificationMethod": "did:key:zDnaeRCkiK28fewJv2ziHyWCDTc3oCkxKhGR26WV JZNwV9jWx", "cryptosuite": "ecdsa-rdfc-2019", "proofPurpose": "assertionMethod", "proofValue": "z5xmXzYTnwgJ6x6gxjoZBeRyDroVMBQ77Evd65kwqzLgNaMnpG8WfheG Ka6ogFj7P4fdASCWu4gsYpTrewqBvqLTa" } }
{ "@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-14T13:38:58Z", "verificationMethod": "did:key:z6Mkwd8n9jX452rCse7foE1vKrAicSJ78WYkWyeH euGtUBQB", "cryptosuite": "eddsa-rdfc-2022", "proofPurpose": "assertionMethod", "proofValue": "zXkRUuKpzCKxhVGRQsRPHghiBtdJBiwGjHtGbLSxyPJ2Zec2h6pPCcCF i9X9zagefWZseNEP76KJjgsK2DrJLZV8" } }
{ "@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:zUC7GhPZ3gic6CMRdo7UP8MEAGvCdPQnAGECdeUb eQH8ciXSjryRGNNhcq8vACBmenYSgzGw6J8BUPsK7jaBgixddeX8FYhLAq5f2w7jFDuj7RCrx1t Hiip8Fk9bea5YCrkLhA1", "cryptosuite": "bbs-2023", "proofPurpose": "assertionMethod", "proofValue": "u2V0ChVhQg60QBHyhPFj1NQ7723otpnxLzXm6oKnb6qzrYaoLslSt17L L1svW8A8HkuX2SeFdEs_0WBAVAYCgxzTv-ulJ2ku6jM5ONAKfT4JHgkHUoOtYQJDIgggv2TShOv 9i22PYnSBqrQFSxTjIjqIiAQKrOQ5-q55pIrtFHSJQO7wOSd6iet3GiHpGE_HGk6G6KLCUQT9YY K3FC2Vvm-OX_AgI0oHfF4DrqsNpSd4kMs_J6fSBDRrbm5hxZ7OjnY9FwRoWnogTDwvbxs8J-AYX jNd6ktDFVCxgFx9s1_CJUJJHzRFs0Kpqqa614hh_-mE0qlyJ8u3iMlggwEdf8welFesNSUVudE4 FT0WWg7GQfP5kgona3UufvcqBZy9pc3N1ZXI" } }
{ "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-ld+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'7dccbfaa...171fdbac'
])
{
"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": [
"fFQJIFBubqde-gsEQIgrBG8wPy8VH_S5YyvH8s76Fy4"
]
},
"_sd": [
"3lZgWRsU__k2EQlLK1tiiUlw5sAYUZ5pgGoxtZUczvo"
]
},
"credentialSchema": {
"_sd": [
"X8puwfuuuvsQqZCvcyeoIzwebiA50tnB5584CzoOOIo",
"tbXUnG8zUGeqB5fHfyEq_z3u89kcn3tlXdOLAVxIzl0"
]
},
"credentialStatus": {
"statusPurpose": "revocation",
"statusListIndex": "123456",
"statusListCredential": "https://university.example/CredentialStatusList",
"_sd": [
"VnlkLvWWnLiDVhhHJpKFJi0-zUjB5BpnZVF6hX8sbOI",
"vgTybJGxssM-VePSN4CAN3mfKSd7yuT1aVbMm1AGhNE"
]
},
"_sd": [
"B6VP4XwHunNkE3zG14MVYORRY3fxaqPrr7t3fBhveDM",
"NSQg4TDsADsjAOsYBHuK190O8HQuLJ2zLPp3F_iE23c"
]
}
SHA-256 Hash: B6VP4XwHunNkE3zG14MVYORRY3fxaqPrr7t3fBhveDM
Disclosure(s): WyI3X2M2djBIRHdaakQzb2JERU1RSm5nIiwgImlkIiwgImh0dHBzOi8vdW5pdmVyc2l0eS5leGFtcGxlL0NyZWRlbnRpYWwxMjMiXQ
Contents: [
"7_c6v0HDwZjD3obDEMQJng",
"id",
"https://university.example/Credential123"
]
SHA-256 Hash: NSQg4TDsADsjAOsYBHuK190O8HQuLJ2zLPp3F_iE23c
Disclosure(s): WyJ6R1Jqa0M0TmUyNy1jNVh3RjdTYjh3IiwgInR5cGUiLCBbIlZlcmlmaWFibGVDcmVkZW50aWFsIiwgIkV4YW1wbGVBbHVtbmlDcmVkZW50aWFsIl1d
Contents: [
"zGRjkC4Ne27-c5XwF7Sb8w",
"type",
[
"VerifiableCredential",
"ExampleAlumniCredential"
]
]
SHA-256 Hash: 3lZgWRsU__k2EQlLK1tiiUlw5sAYUZ5pgGoxtZUczvo
Disclosure(s): WyJTUGZkcTRvN05DWDB2aFRKNmt4TTRRIiwgImlkIiwgImh0dHBzOi8vd3d3LmV4YW1wbGUub3JnL3BlcnNvbnMvcGF0Il0
Contents: [
"SPfdq4o7NCX0vhTJ6kxM4Q",
"id",
"https://www.example.org/persons/pat"
]
SHA-256 Hash: fFQJIFBubqde-gsEQIgrBG8wPy8VH_S5YyvH8s76Fy4
Disclosure(s): WyJZMnpkY1A2VHFJNXo4TEloTndTeDhnIiwgImlkIiwgImRpZDpleGFtcGxlOmMyNzZlMTJlYzIxZWJmZWIxZjcxMmViYzZmMSJd
Contents: [
"Y2zdcP6TqI5z8LIhNwSx8g",
"id",
"did:example:c276e12ec21ebfeb1f712ebc6f1"
]
SHA-256 Hash: tbXUnG8zUGeqB5fHfyEq_z3u89kcn3tlXdOLAVxIzl0
Disclosure(s): WyJBbjJWa3dkcVBNR1NnTGUzNXhubXB3IiwgImlkIiwgImh0dHBzOi8vdW5pdmVyc2l0eS5leGFtcGxlL0NyZWRlbnRpYWwxMjMtc2NoZW1hLWNyZWRlbnRpYWwiXQ
Contents: [
"An2VkwdqPMGSgLe35xnmpw",
"id",
"https://university.example/Credential123-schema-credential"
]
SHA-256 Hash: X8puwfuuuvsQqZCvcyeoIzwebiA50tnB5584CzoOOIo
Disclosure(s): WyIySUJGc1JPT2RCVnNiNnpEUTVqdlZBIiwgInR5cGUiLCAiSnNvblNjaGVtYUNyZWRlbnRpYWwiXQ
Contents: [
"2IBFsROOdBVsb6zDQ5jvVA",
"type",
"JsonSchemaCredential"
]
SHA-256 Hash: VnlkLvWWnLiDVhhHJpKFJi0-zUjB5BpnZVF6hX8sbOI
Disclosure(s): WyJrbzVzRUZZTU1HVmJfNVhsZHFidHhRIiwgImlkIiwgImh0dHBzOi8vdW5pdmVyc2l0eS5leGFtcGxlL3N0YXR1c2xpc3QjMTIzNDU2Il0
Contents: [
"ko5sEFYMMGVb_5XldqbtxQ",
"id",
"https://university.example/statuslist#123456"
]
SHA-256 Hash: vgTybJGxssM-VePSN4CAN3mfKSd7yuT1aVbMm1AGhNE
Disclosure(s): WyJZNFI1Q0ZqMHZ5RHFHSERJdDVxMGpRIiwgInR5cGUiLCAiQml0c3RyaW5nU3RhdHVzTGlzdEVudHJ5Il0
Contents: [
"Y4R5CFj0vyDqGHDIt5q0jQ",
"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: