Copyright © 2023 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. This specification provides a mechanism to express these sorts of credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
Comments regarding this specification are welcome at any time. Please file issues directly on GitHub, or send them to public-vc-comments@w3.org (subscribe, archives).
This document was published by the Verifiable Credentials Working Group as a Working Draft using the Recommendation track.
Publication as a Working Draft does not imply endorsement by W3C and 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.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 12 June 2023 W3C Process Document.
This section is non-normative.
Credentials are a part of our daily lives; driver's licenses are used to assert that we are capable of operating a motor vehicle, university degrees can be used to assert our level of education, and government-issued passports enable us to travel between countries. These credentials provide benefits to us when used in the physical world, but their use on the Web continues to be elusive.
Currently it is difficult to express education qualifications, healthcare data, financial account details, and other sorts of third-party verified machine-readable personal information on the Web. The difficulty of expressing digital credentials on the Web makes it challenging to receive the same benefits through the Web that physical credentials provide us in the physical world.
This specification provides a standard way to express credentials on the Web in a way that is cryptographically secure, privacy respecting, and machine-verifiable.
For those unfamiliar with the concepts related to verifiable credentials, the following sections provide an overview of:
This section is non-normative.
In the physical world, a credential might consist of:
A verifiable credential can represent all of the same information that a physical credential represents. The addition of technologies, such as digital signatures, makes verifiable credentials more tamper-evident and more trustworthy than their physical counterparts.
Holders of verifiable credentials can generate verifiable presentations and then share these verifiable presentations with verifiers to prove they possess verifiable credentials with certain characteristics.
Both verifiable credentials and verifiable presentations can be transmitted rapidly, making them more convenient than their physical counterparts when trying to establish trust at a distance.
While this specification attempts to improve the ease of expressing digital credentials, it also attempts to balance this goal with a number of privacy-preserving goals. The persistence of digital information, and the ease with which disparate sources of digital data can be collected and correlated, comprise a privacy concern that the use of verifiable and easily machine-readable credentials threatens to make worse. This document outlines and attempts to address a number of these issues in Section 7. Privacy Considerations. Examples of how to use this data model using privacy-enhancing technologies, such as zero-knowledge proofs, are also provided throughout this document.
The word "verifiable" in the terms verifiable credential and verifiable presentation refers to the characteristic of a credential or presentation as being able to be verified by a verifier, as defined in this document. Verifiability of a credential does not imply that the truth of claims encoded therein can be evaluated; however, the issuer can include values in the evidence property to help the verifier apply their business logic to determine whether the claims have sufficient veracity for their needs.
This section is non-normative.
This section describes the roles of the core actors and the relationships between them in an ecosystem where verifiable credentials are expected to be useful. A role is an abstraction that might be implemented in many different ways. The separation of roles suggests likely interfaces and protocols for standardization. The following roles are introduced in this specification:
Figure 1 above provides an example ecosystem in which to ground the rest of the concepts in this specification. Other ecosystems exist, such as protected environments or proprietary systems, where verifiable credentials also provide benefit.
This section is non-normative.
The Verifiable Credentials Use Cases document [VC-USE-CASES] outlines a number of key topics that readers might find useful, including:
As a result of documenting and analyzing the use cases document, the following desirable ecosystem characteristics were identified for this specification:
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, RECOMMENDED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
A conforming document is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections 4. Basic Concepts, 5. Advanced Concepts, and 6. Syntaxes of this document MUST be enforced. A serialization format for the conforming document MUST be deterministic, bi-directional, and lossless as described in Section 6. Syntaxes. The conforming document MAY be transmitted or stored in any such serialization format.
A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming document. Conforming processors MUST produce errors when non-conforming documents are consumed.
This specification makes no normative statements with regard to the conformance of roles in the ecosystem, such as issuers, holders, or verifiers, because the conformance of ecosystem roles are highly application, use case, and market vertical specific.
Digital proof mechanisms, a subset of which are digital signatures, are required to ensure the protection of a verifiable credential. Having and validating proofs, which may be dependent on the syntax of the proof (for example, using the JSON Web Signature of a JSON Web Token for proofing a key holder), are an essential part of processing a verifiable credential. At the time of publication, Working Group members had implemented verifiable credentials using at least three proof mechanisms:
Implementers are advised to note that not all proof mechanisms are standardized as of the publication date of this specification. The group expects some of these mechanisms, as well as new ones, to mature independently and become standardized in time. Given there are multiple valid proof mechanisms, this specification does not standardize on any single digital signature mechanism. One of the goals of this specification is to provide a data model that can be protected by a variety of current and future digital proof mechanisms. Conformance to this specification does not depend on the details of a particular proof mechanism; it requires clearly identifying the mechanism a verifiable credential uses.
This document also contains examples that contain characters that are invalid
JSON, such as inline comments (//
) and the use of ellipsis
(...
) to denote information that adds little value to the example.
Implementers are cautioned to remove this content if they desire to use the
information as a valid document.
This section is non-normative.
The following terms are used to describe concepts in this specification.
did:example:123456abcdef
.
This section is non-normative.
The following sections outline core data model concepts, such as claims, credentials, and presentations, which form the foundation of this specification.
This section is non-normative.
A claim is a statement about a subject. A subject is a thing about which claims can be made. Claims are expressed using subject- property-value relationships.
The data model for claims, illustrated in Figure 2 above, is powerful and can be used to express a large variety of statements. For example, whether someone graduated from a particular university can be expressed as shown in Figure 3 below.
Individual claims can be merged together to express a graph of information about a subject. The example shown in Figure 4 below extends the previous claim by adding the claims that Pat knows Sam and that Sam is employed as a professor.
To this point, the concepts of a claim and a graph of information are introduced. To be able to trust claims, more information is expected to be added to the graph.
This section is non-normative.
A credential is a set of one or more claims made by the same entity. Credentials might also include an identifier and metadata to describe properties of the credential, such as the issuer, the validity date and time period, a representative image, a public key to use for verification purposes, the revocation mechanism, and so on. The metadata might be signed by the issuer. A verifiable credential is a set of tamper-evident claims and metadata that cryptographically prove who issued it.
Examples of verifiable credentials include digital employee identification cards, digital birth certificates, and digital educational certificates.
Credential identifiers are often used to identify specific instances of a credential. These identifiers can also be used for correlation. A holder wanting to minimize correlation is advised to use a selective disclosure scheme that does not reveal the credential identifier.
Figure 5 above shows the basic components of a verifiable credential, but abstracts the details about how claims are organized into information graphs, which are then organized into verifiable credentials. Figure 6 below shows a more complete depiction of a verifiable credential, which is normally composed of at least two information graphs. The first graph expresses the verifiable credential itself, which contains credential metadata and claims. The second graph expresses the digital proof, which is usually a digital signature.
It is possible to have a credential, such as a marriage certificate, containing multiple claims about different subjects that are not required to be related.
It is possible to have a credential that does not contain any claims about the entity to which the credential was issued. For example, a credential that only contains claims about a specific dog, but is issued to its owner.
This section is non-normative.
Enhancing privacy is a key design feature of this specification. Therefore, it is important for entities using this technology to be able to express only the portions of their persona that are appropriate for a given situation. The expression of a subset of one's persona is called 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 can express data from multiple verifiable credentials and contain arbitrary additional data encoded as JSON-LD. They are used by a holder to present claims to a verifier. It is also possible to present verifiable credentials directly.
The data in a presentation is often about the same subject, but might have been issued by multiple issuers. The aggregation of this information typically expresses an aspect of a person, organization, or entity.
Figure 7 above shows the components of a verifiable presentation, but abstracts the details about how verifiable credentials are organized into information graphs, which are then organized into verifiable presentations.
Figure 8 below shows a more complete depiction of a
verifiable presentation, which is normally composed of at least four
information graphs. The first of these information graphs, the
Presentation Graph, expresses the verifiable presentation
itself, which contains presentation metadata. The
verifiableCredential
property in the Presentation Graph
refers to one or more verifiable credentials, each being one of the
second information graphs, i.e., a self-contained Credential
Graph, which in turn contains credential metadata and claims. The
third information graph, the Credential Proof Graph, expresses
the credential graph proof, which is usually a digital signature. The fourth
information graph, the Presentation Proof Graph, expresses the
presentation graph proof, which is usually a digital signature.
It is possible to have a presentation, such as a business persona, which draws on multiple credentials about different subjects that are often, but not required to be, related.
This section is non-normative.
The previous sections introduced the concepts of claims, verifiable credentials, and verifiable presentations using graphical depictions. This section provides a concrete set of simple but complete lifecycle examples of the data model expressed in one of the concrete syntaxes supported by this specification. The lifecycle of credentials and presentations in the Verifiable Credentials Ecosystem often take a common path:
To illustrate this lifecycle, we will use the example of redeeming an alumni discount from a university. In the example below, Pat receives an alumni verifiable credential from a university, and Pat stores the verifiable credential in a digital wallet.
{ // set the context, which establishes the special terms we will be using // such as 'issuer' and 'alumniOf'. "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], // specify the identifier for the credential "id": "http://university.example/credentials/1872", // the credential types, which declare what data to expect in the credential "type": ["VerifiableCredential", "ExampleAlumniCredential"], // the entity that issued the credential "issuer": "https://university.example/issuers/565049", // when the credential was issued "validFrom": "2010-01-01T19:23:24Z", // claims about the subjects of the credential "credentialSubject": { // identifier for the only subject of the credential "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", // assertion about the only subject of the credential "alumniOf": { // identifier for the university "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", // name of the university "name": "Example University" }, // digital proof that makes the credential tamper-evident // see the NOTE at end of this section for more detail "proof": { // the type of embedded proof securing the verifiable credential "type": "DataIntegrityProof", // the name of the cryptographic signature suite "cryptosuite": "eddsa-2022", // the date the signature was created "created": "2023-06-18T21:19:10Z", // purpose of this proof "proofPurpose": "assertionMethod", // the identifier of the public key that can verify the signature "verificationMethod": "https://university.example/issuers/565049#key-123", // the digital signature value "proofValue": "zQeVbY4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYV8nQA pmEcqaqA3Q1gVHMrXFkXJeV6doDwLWx" } }
Pat then attempts to redeem the alumni discount. The verifier, a ticket sales system, states that any alumni of "Example University" receives a discount on season tickets to sporting events. Using a mobile device, Pat starts the process of purchasing a season ticket. A step in this process requests an alumni verifiable credential, and this request is routed to Pat's digital wallet. The digital wallet asks Pat if they would like to provide a previously issued verifiable credential. Pat selects the alumni verifiable credential, which is then composed into a verifiable presentation. The verifiable presentation is sent to the verifier and verified.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "type": "VerifiablePresentation", // the verifiable credential issued in the previous example "verifiableCredential": [{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "http://university.example/credentials/1872", "type": ["VerifiableCredential", "ExampleAlumniCredential"], "issuer": "https://university.example/issuers/565049", "validFrom": "2010-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "proof": { "type": "DataIntegrityProof", "cryptosuite": "eddsa-2022", "created": "2023-06-18T21:19:10Z", "proofPurpose": "assertionMethod", "verificationMethod": "https://university.example/issuers/565049#key-1", "proofValue": "zQeVbY4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYV8nQA pmEcqaqA3Q1gVHMrXFkXJeV6doDwLWx" } }], // digital signature by Pat on the presentation // protects against replay attacks "proof": { "type": "DataIntegrityProof", "cryptosuite": "eddsa-2022", "created": "2018-09-14T21:19:10Z", "proofPurpose": "authentication", "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1", // 'challenge' and 'domain' protect against replay attacks "challenge": "1f44d55f-f161-4938-a659-f8026467f126", "domain": "4jt78h47fh47", "proofValue": "zqpLMweBrSxMY2xHX5XTYV8nQAJeV6doDwLWxQeVbY4oey5q2pmEcqaqA3Q1 gVHMrXFkXM3XKaxup3tmzN4DRFTLV" } }
Implementers that are interested in understanding more about the
proof
mechanism used above can learn more in Section A.5 Proofs (Signatures) and by reading the following specifications:
Data Integrity [VC-DATA-INTEGRITY] and the "Proofs" section of the Verifiable
Credential Specifications Directory [VC-SPECS].
This section introduces some basic concepts for the specification, in preparation for Section 5. Advanced Concepts later in the document.
This specification is designed to ease the prototyping of new types of verifiable credentials. Developers can copy the template below and paste it into common verifiable credential tooling to start issuing, holding, and verifying prototype credentials.
It is expected that a developer will change MyPrototypeCredential
below to
the type of credential they would like to create. Since
verifiable credentials talk about subjects, each property-value pair in
the credentialSubject
object expresses a particular attribute of the
credential subject. Once a developer has added a number of these property-value
combinations, the modified object can be sent to verifiable credential
issuer sofware and a verifiable credential will be created for the
developer. From a prototyping standpoint, that is all a developer needs to do.
{ "@context": ["https://www.w3.org/ns/credentials/v2"], "type": ["VerifiableCredential", "MyPrototypeCredential"], "credentialSubject": { "mySubjectProperty": "mySubjectValue" } }
Once a developer has prototyped their credential to a point where they believe all of the credential properties are stable, it is advised that they generate vocabulary and context files for their application and publish them at stable URLs so that other developers can use the same vocabulary and context to achieve interoperability. This process is covered in Section 5.3 Extensibility. Alternatively, developers can reuse existing vocabulary and context files that happen to fit their use case. They can explore the Verifiable Credential Specifications Directory [VC-SPECS] for reusable resources.
When two software systems need to exchange data, they need to use terminology that both systems understand. As an analogy, consider how two people communicate. Both people must use the same language and the words they use must mean the same thing to each other. This might be referred to as the context of a conversation.
Verifiable credentials and verifiable presentations have many
attributes and values that are identified by URLs [URL]. However,
those URLs can be long and not very human-friendly. In such cases,
short-form human-friendly aliases can be more helpful. This specification uses
the @context
property to map such short-form aliases to the
URLs required by specific verifiable credentials and verifiable
presentations.
In JSON-LD, the @context
property can also be used to
communicate other details, such as datatype information, language information,
transformation rules, and so on, which are beyond the needs of this
specification, but might be useful in the future or to related work. For more
information, see
Section 3.1: The Context
of the [JSON-LD] specification.
Verifiable credentials and verifiable presentations MUST include a
@context
property.
@context
property MUST be an ordered set
where the first item is a URL with the value
https://www.w3.org/ns/credentials/v2
. For reference, a copy of
the base context is provided in Appendix B.1 Base Context.
Subsequent items in the array MUST express context information and be composed
of any combination of URLs or objects. It is RECOMMENDED that each
URL in the @context
be one which, if dereferenced, results
in a document containing machine-readable information about the
@context
.
This specification requires for a @context
property
to be present; this property is defined by [JSON-LD].
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "http://university.example/credentials/58473", "type": ["VerifiableCredential", "ExampleAlumniCredential"], "issuer": "https://university.example/issuers/565049", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "proof": { ... } }
The example above uses the base context URL
(https://www.w3.org/ns/credentials/v2
) to establish that the
conversation is about a verifiable credential. The second URL
(https://www.w3.org/ns/credentials/examples/v2
) establishes that
the conversation is about examples.
This document uses the example context URL
(https://www.w3.org/ns/credentials/examples/v2
) for the purpose
of demonstrating examples. Implementations are expected to not use this
URL for any other purpose, such as in pilot or production systems.
The data available at https://www.w3.org/ns/credentials/v2
is a
static document that is never updated and SHOULD be downloaded and cached. The
associated human-readable vocabulary document for the Verifiable Credentials
Data Model is available at
https://www.w3.org/2018/credentials/.
This concept is further expanded on in Section 5.3 Extensibility.
When expressing statements about a specific thing, such as a person, product, or
organization, it can be useful to use a globally unique identifier for that thing.
Globally unique identifiers enable others to express statements
about the same thing. This specification defines the optional id
property for such identifiers. The id
property
allows for the expression of statements about specific things in the
verifiable credential and is set by an issuer when expressing
objects in a verifiable credential or a holder when expressing
objects in a verifiable presentation. Example id
values
include UUIDs (urn:uuid:0c07c1ce-57cb-41af-bef2-1b932b986873
), HTTP URLs
(https://id.example/things#123
), and DIDs (did:example:1234abcd
).
If the id
property is present:
id
property MUST express an identifier that others are
expected to use when expressing statements about a specific thing identified
by that identifier.
id
property MUST NOT have more than one value.
id
property MUST be a URL which
MAY be dereferenced.
Developers should remember that identifiers might be harmful in scenarios
where pseudonymity is required. Developers are encouraged to read Section
7.3 Identifier-Based Correlation carefully when considering such
scenarios. There are also other types of correlation mechanisms documented in
Section 7. Privacy Considerations that create privacy concerns.
Where privacy is a strong consideration, the id
property
MAY be omitted. Some use cases do not require, or explicitly require omitting, the id
property.
id
property MUST be a single URL.
It is RECOMMENDED that the URL in the id
be one which, if
dereferenced, results in a document containing machine-readable information
about the id
.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "http://university.example/credentials/3732", "type": ["VerifiableCredential", "ExampleDegreeCredential"], "issuer": "https://university.example/issuers/565049", "validFrom": "2010-01-01T00:00:00Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts" } } }
The example above uses two types of identifiers. The first identifier is for the verifiable credential and uses an HTTP-based URL. The second identifier is for the subject of the verifiable credential (the thing the claims are about) and uses a decentralized identifier, also known as a DID.
As of this publication, DIDs are a new type of identifier that are not necessary for verifiable credentials to be useful. Specifically, verifiable credentials do not depend on DIDs and DIDs do not depend on verifiable credentials. However, it is expected that many verifiable credentials will use DIDs and that software libraries implementing this specification will probably need to resolve DIDs. DID-based URLs are used for expressing identifiers associated with subjects, issuers, holders, credential status lists, cryptographic keys, and other machine-readable information associated with a verifiable credential.
Software systems that process the kinds of objects specified in this document
use type information to determine whether or not a provided
verifiable credential or verifiable presentation is appropriate
for the intended use case. This specification defines a type
property for the expression of type information. This type information
can be used during validation processes as described in Appendix
A. Validation.
Verifiable credentials and verifiable presentations MUST have a
type
property. That is, any credential or
presentation that does not have type
property
is not verifiable, so is neither a verifiable credential
nor a verifiable presentation.
type
property MUST be, or map to (through
interpretation of the @context
property), one or more URLs.
If more than one URL is provided, the URLs MUST be interpreted
as an unordered set. Syntactic conveniences SHOULD be used to ease developer
usage. Such conveniences might include JSON-LD terms. It is RECOMMENDED that
each URL in the type
be one which, if dereferenced, results
in a document containing machine-readable information about the
type
.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/565049",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
}
With respect to this specification, the following table lists the objects that MUST have a type specified.
Object | Type |
---|---|
Verifiable credential object |
VerifiableCredential and, optionally, a more specific
verifiable credential type. For example,"type": ["VerifiableCredential", "ExampleDegreeCredential"]
|
Verifiable presentation object |
VerifiablePresentation and, optionally, a more specific
verifiable presentation type. For example,"type": ["VerifiablePresentation", "ExamplePresentation"]
|
Proof object |
A valid proof type. For example,"type": "DataIntegrityProof"
|
credentialStatus object |
A valid credential status type. For example,"type": "StatusList2021Entry"
|
termsOfUse object |
A valid terms of use type. For example,"type": "ExampleTermsPolicy" )
|
evidence object |
A valid evidence type. For example,"type": "ExampleEvidence"
|
The type system for the Verifiable Credentials Data Model is the same as
for [JSON-LD] and is detailed in
Section 3.5:
Specifying the Type and
Section 9: JSON-LD
Grammar. When using a JSON-LD context (see Section
5.3 Extensibility), this specification aliases the
@type
keyword to type
to make the JSON-LD documents
more easily understood. While application developers and document authors do
not need to understand the specifics of the JSON-LD type system, implementers
of this specification who want to support interoperable extensibility, do.
All credentials, presentations, and encapsulated objects MUST
specify, or be associated with, additional more narrow types (like
ExampleDegreeCredential
, for example) so software systems can
process this additional information.
When processing encapsulated objects defined in this specification, (for
example, objects associated with the credentialSubject
object or
deeply nested therein), software systems SHOULD use the type information
specified in encapsulating objects higher in the hierarchy. Specifically, an
encapsulating object, such as a credential, SHOULD convey the associated
object types so that verifiers can quickly determine the contents
of an associated object based on the encapsulating object type.
For example, a credential object with the type
of
ExampleDegreeCredential
, signals to a verifier that the
object associated with the credentialSubject
property contains the
identifier for the:
id
property.
type
property.
name
property.
This enables implementers to rely on values associated with the
type
property for verification purposes. The expectation of
types and their associated properties should be documented in at least a
human-readable specification, and preferably, in an additional machine-readable
representation.
The type system used in the data model described in this specification allows for multiple ways to associate types with data. Implementers and authors are urged to read the section on typing in the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE].
A verifiable credential contains claims about one or more
subjects. This specification defines a credentialSubject
property for the expression of claims about one or more
subjects.
A verifiable credential MUST have a credentialSubject
property.
credentialSubject
property is defined as
a set of objects that MUST contain one or more claims that are each related to a
subject of the verifiable credential. Each object MAY contain an
id
, as described in Section 4.3 Identifiers.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/565049",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
}
It is possible to express information related to multiple subjects in a
verifiable credential. The example below specifies two subjects
who are spouses. Note the use of array notation to associate multiple
subjects with the credentialSubject
property.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "RelationshipCredential"],
"issuer": "https://example.com/issuer/123",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": [{
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"name": "Jayden Doe",
"spouse": "did:example:c276e12ec21ebfeb1f712ebc6f1"
}, {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Morgan Doe",
"spouse": "did:example:ebfeb1f712ebc6f1c276e12ec21"
}]
}
This specification defines a property for expressing the issuer of a verifiable credential.
A verifiable credential MUST have an issuer
property.
issuer
property MUST be either a
URL or an object containing an id
property. It is
RECOMMENDED that the URL in the issuer
or its
id
be one which, if dereferenced, results in a document containing
machine-readable information about the issuer that can be used to
verify the information expressed in the credential.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
}
It is also possible to express additional information about the issuer by associating an object with the issuer property:
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": {
"id": "did:example:76e12ec712ebc6f1c221ebfeb1f",
"name": "Example University"
},
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
}
This specification defines the validFrom
property to help an
issuer to express the date and time when a credential becomes valid and
the validUntil
property for expressing the date and time
when a credential ceases to be valid.
validFrom
property MUST be
an [XMLSCHEMA11-2]
dateTimeStamp
string value representing the date and time the
credential becomes valid, which could be a date and time in the future.
Note that this value represents the earliest point in time
at which the information associated with the credentialSubject
property becomes valid.
validUntil
property MUST be an
[XMLSCHEMA11-2]
dateTimeStamp
string value representing the date and time the
credential ceases to be valid, which could be a date and time in the
past. Note that this value represents the latest point in time at which the
information associated with the credentialSubject
property
is valid. If a validFrom
value exists, the validUntil
value MUST be
temporally greater than the validFrom
value.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "http://university.example/credentials/3732", "type": ["VerifiableCredential", "ExampleDegreeCredential"], "issuer": "https://university.example/issuers/14", "validFrom": "2010-01-01T19:23:24Z", "validUntil": "2020-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts" } } }
If validFrom
and validUntil
are not present, the
verifiable credential validity period is considered valid
indefinitely. In such cases, the verifiable credential is assumed to be
valid from the time the verifiable credential
was created.
Implementers are urged to understand that representing and processing time values is not as straight-forward as it might seem and have a variety of idiosyncrasies that are not immediately obvious nor uniformly observed in different regions of the world. For example:
2023-01-01T00:00:00Z
), regardless of whether the system in question
understands leap seconds.
These are just a few examples that illustrate that the actual time of day, as
would be seen on a clock on the wall, can exist in one region but not exist in
another region. For this reason, implementers are urged to use time values
that are more universal, such as values anchored to the Z
time zone over
values that are affected by Daylight Saving/Summer Time.
This specification attempts to increase the number of universally recognized
combinations of dates and times, and reduce the potential for
misinterpretation of time values, by utilizing the
dateTimeStamp
construction first established by the [XMLSCHEMA11-2] specification. In
order to reduce misinterpretations between different regions, all times MUST be
specified as offsets against Universal Coordinated Time (UTC).
Time zone definitions are occasionally changed by their governing body. When
replacing or issuing new verifiable credentials, implementers are advised
to ensure that changes to local time zone rules do not result in unexpected gaps
in validity. For example, consider the zone America/Los_Angeles
, which has
a raw offset of UTC-8 and had voted to stop observing daylight savings time in
the year 2024. A given verifiable credential that had a validUtil
value of 2024-07-12T12:00:00-07:00
, might be re-issued to have a
validFrom
value of 2024-07-12T12:00:00-08:00
, which would create a gap of
an hour where the verifiable credential would not be valid.
Implementers that desire to check dateTimeStamp
values for validity
can use the regular expression provided below, which is reproduced from the [XMLSCHEMA11-2] specification for
convenience. To avoid doubt, the regular expression in [XMLSCHEMA11-2] is the
normative definition. Implementers are advised that not all
dateTimeStamp
values that pass the regular expression below are
valid moments in time. For example, the regular expression below allows for 31
days in every month, which allows for leap years, and leap seconds, as well as
days in places where they do not exist. That said, modern system libraries that
generate dateTimeStamp
values are often error-free in their
generation of valid dateTimeStamp
values. The regular
expression shown below (minus the whitespace included here for readability),
is often adequate when processing library-generated dates and times on
modern systems.
-?([1-9][0-9]{3,}|0[0-9]{3}) -(0[1-9]|1[0-2]) -(0[1-9]|[12][0-9]|3[01]) T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\.[0-9]+)?|(24:00:00(\.0+)?)) (Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))
At least one securing mechanism, and the details necessary to evaluate it, MUST be expressed for a credential or presentation to be a verifiable credential or verifiable presentation; that is, to be verifiable.
This specification recognizes two classes of securing mechanisms: those that use external proofs and those that use embedded proofs. An external proof is one that wraps an expression of this data model, such as via a JSON Web Token, which is elaborated on in the Securing Verifiable Credentials using JSON Web Tokens [VC-JWT] specification. An embedded proof is a mechanism where the proof is included in the data model, such as a Data Integrity Proof, which is elaborated on in Verifiable Credential Data Integrity [VC-DATA-INTEGRITY].
It should be noted that these two classes of securing mechanisms are not mutually exclusive.
Methods of securing credentials or presentations that embed a
proof in the data model MUST use the proof
property.
Methods of securing credentials or presentations that use an
external proof MAY use the proof
property.
type
property.
Because the method used for a mathematical proof varies by representation
language and the technology used, the set of name-value pairs that is expected
as the value of the proof
property will vary accordingly.
For example, if digital signatures are used for the proof mechanism, the
proof
property is expected to have name-value pairs that
include a signature, a reference to the signing entity, and a representation of
the signing date. The example below uses Ed25519 digital signatures.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://example.gov/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "Ed25519Signature2020",
"created": "2021-11-13T18:19:39Z",
"verificationMethod": "https://university.example/issuers/14#key-1",
"proofPurpose": "assertionMethod",
"proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdo
WhAfGFCF5bppETSTojQCrfFPP2oumHKtz"
}
}
As discussed in Section 1.4 Conformance, there are multiple viable
proof mechanisms, and this specification does not standardize nor recommend any
single proof mechanism for use with verifiable credentials. For more
information about the proof
mechanism, see the following
specifications: Data Integrity [VC-DATA-INTEGRITY], Securing Verifiable
Credentials using JSON Web Tokens [VC-JWT], and the "Proofs" section of
the Verifiable Credential Specifications Directory [VC-SPECS].
This specification defines the following credentialStatus
property for the discovery of information about the current status of a
verifiable credential, such as whether it is suspended or revoked.
credentialStatus
property MUST
include the following:
id
property, which MUST be a URL which MAY be
dereferenced.
type
property, which expresses the credential status
type.
The precise content of the credential status information is determined
by the specific credentialStatus
type definition, and varies
depending on factors such as whether it is simple to implement or if it is
privacy-enhancing. It is expected that the value will provide enough information
to determine the current status of the credential and that machine
readable information will be retrievable from the URL. For example, the
object could contain a link to an external document which notes whether or not the
credential is suspended or revoked.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://w3id.org/vc/status-list/2021/v1"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"credentialStatus": {
"id": "https://university.example/credentials/status/3#94567",
"type": "StatusList2021Entry",
"statusPurpose": "revocation",
"statusListIndex": "94567",
"statusListCredential": "https://university.example/credentials/status/3"
}
}
Defining the data model, formats, and protocols for status schemes are out of scope for this specification. A Verifiable Credential Specifications Directory [VC-SPECS] exists that contains available status schemes for implementers who want to implement verifiable credential status checking.
Verifiable presentations MAY be used to aggregate information from multiple verifiable credentials.
Verifiable presentations SHOULD be extremely short-lived, and bound to a challenge provided by a verifier. Details for accomplishing this depend on the securing mechanism, the transport protocol, and verifier policies. Unless additional requirements are defined by the particular securing mechanism or embedding protocol, a verifier cannot generally assume that the verifiable presentation has any correlation with the presented verifiable credentials.
The following properties are defined for a verifiable presentation:
id
property is optional. It MAY be used to provide a
unique identifier for the verifiable presentation. If present, the
normative guidance in Section 4.3 Identifiers MUST be followed.
type
property MUST be present. It is used to express the
type of verifiable presentation. One value of this property MUST be
VerifiablePresentation
, but additional types MAY be included. The
related normative guidance in Section 4.4 Types MUST be followed.
verifiableCredential
property MAY be present. The value
MUST be an array of one or more verifiable credentials, or of data
derived from verifiable credentials in a cryptographically
verifiable format.
holder
property. If present, the value MUST be either a URL or an object
containing an id
property. It is RECOMMENDED that the
URL in the holder
or its id
be one which, if
dereferenced, results in a document containing machine-readable information
about the holder that can be used to verify the information
expressed in the verifiable presentation.
If the holder
property is absent, information about the
holder is expected to either be obtained via the securing mechanism, or
to not pertain to the validation of the verifiable presentation.
proof
property. If present, the value SHOULD be used to express a securing
mechanism such as [VC-DATA-INTEGRITY]. A verifiable presentation MAY
be secured using an external proof such as [VC-JWT]. For details related to
the use of this property, see Section 4.8 Securing Verifiable Credentials.
The example below shows a verifiable presentation:
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
"type": ["VerifiablePresentation", "ExamplePresentation"],
"verifiableCredential": [{ ... }],
"proof": [{ ... }]
}
The contents of the verifiableCredential
property shown
above are verifiable credentials, as described by this specification. The
contents of the proof
property are proofs, as described by
the Data Integrity [VC-DATA-INTEGRITY] specification. An example of a
verifiable presentation using the JWT proof mechanism is
provided in the Securing Verifiable Credentials using JSON Web Tokens
[VC-JWT] specification.
Some zero-knowledge cryptography schemes might enable holders to indirectly prove they hold claims from a verifiable credential without revealing all claims in that verifiable credential. In these schemes, a verifiable credential might be used to derive presentable data, which is cryptographically asserted such that a verifier can trust the value if they trust the issuer.
Some selective disclosure schemes can share a subset of claims derived from a verifiable credential.
For an example of a ZKP-style verifiable presentation containing derived data instead of directly embedded verifiable credentials, see Section 5.8 Zero-Knowledge Proofs.
A holder MAY use the verifiableCredential
property in
a verifiable presentation to include verifiable credentials from
any issuer, including themselves. When the issuer of a
verifiable credential is the holder, the claims in that
verifiable credential are considered to be self-asserted.
Such self-asserted claims can be secured by the same mechanism that secures
the verifiable presentation in which they are included or by any
mechanism usable for other verifiable credentials.
The subject(s) of these self-asserted claims
are not limited, so these claims can include statements about the
holder, one of the other included verifiable credentials, or even
the verifiable presentation in which the self-asserted verifiable
credential is included. In each case, the id
property
is used to identify the specific subject, in the object where the
claims about it are made, just as it is done in
verifiable credentials that are not self-asserted.
A verifiable presentation that includes a self-asserted
verifiable credential that is only secured using the same mechanism as
the verifiable presentation MUST include a holder
property.
All of the normative requirements defined for verifiable credentials apply to self-asserted verifiable credentials.
When a self-asserted verifiable credential is secured using the same
mechanism as the verifiable presentation, the value of the
issuer
property of the verifiable credential
MUST be identical to the holder
property of the
verifiable presentation.
The example below shows a verifiable presentation that embeds a self-asserted verifiable credential that is secured using the same mechanism as the verifiable presentation.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "type": ["VerifiablePresentation", "ExamplePresentation"], "holder": "did:example:12345678", "verifiableCredential": [{ "@context": "https://www.w3.org/ns/credentials/v2", "type": ["VerifiableCredential", "ExampleFoodPreferenceCredential"], "issuer": "did:example:12345678", "credentialSubject": { "favoriteCheese": "Gouda" }, { ... } }], "proof": [{ ... }] }
The example below shows a verifiable presentation that embeds a self-asserted verifiable credential that holds claims about the verifiable presentation. It is secured using the same mechanism as the verifiable presentation.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "type": ["VerifiablePresentation", "ExamplePresentation"], "id": "urn:uuid:313801ba-24b7-11ee-be02-ff560265cf9b", "holder": "did:example:12345678", "verifiableCredential": [{ "@context": "https://www.w3.org/ns/credentials/v2", "type": ["VerifiableCredential", "ExampleAssertCredential"], "issuer": "did:example:12345678", "credentialSubject": { "id": "urn:uuid:313801ba-24b7-11ee-be02-ff560265cf9b", "assertion": "This VP is submitted by the subject as evidence of a legal right to drive" }, { ... } }], "proof": [{ ... }] }
Data schemas are useful when enforcing a specific structure on a given collection of data. There are at least two types of data schemas that this specification considers:
It is important to understand that data schemas serve a different purpose from
the @context
property, which neither enforces data structure or
data syntax, nor enables the definition of arbitrary encodings to alternate
representation formats.
This specification defines the following property for the expression of a data schema, which can be included by an issuer in the verifiable credentials that it issues:
The value of the credentialSchema
property MUST be one or
more data schemas that provide verifiers with enough information to
determine if the provided data conforms to the provided schema(s). Each
credentialSchema
MUST specify its type
(for example,
JsonSchema2023
), and an id
property
that MUST be a URL identifying the schema file. The precise contents of
each data schema is determined by the specific type definition.
If multiple schemas are present, validity is determined according to the
processing rules outlined by each associated credentialSchema
type
property.
The credentialSchema
property provides an opportunity to
annotate type definitions or lock them to specific versions of the vocabulary.
Authors of verifiable credentials can include a static version of their
vocabulary using credentialSchema
that is locked to some content
integrity protection mechanism. The credentialSchema
property also makes it possible to perform syntactic checking on the
credential and to use verification mechanisms such as JSON Schema
[VC-JSON-SCHEMA-2023] validation.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential", "ExamplePersonCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
},
"alumniOf": {
"name": "Example University"
}
},
"credentialSchema": [{
"id": "https://example.org/examples/degree.json",
"type": "JsonSchema2023"
},
{
"id": "https://example.org/examples/alumni.json",
"type": "JsonSchema2023"
}]
}
In the example above, the issuer is specifying a
credentialSchema
, which points to a [VC-JSON-SCHEMA-2023] file that
can be used by a verifier to determine if the
verifiable credential is well formed.
For information about linkages to JSON Schema [VC-JSON-SCHEMA-2023] or other optional verification mechanisms, see the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.
Data schemas can also be used to specify mappings to other formats, such as
those used to perform zero-knowledge proofs. For more information on using the
credentialSchema
property with zero-knowledge proofs,
see Section 5.8 Zero-Knowledge Proofs.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "http://university.example/credentials/3732", "type": ["VerifiableCredential", "ExampleDegreeCredential"], "issuer": "https://university.example/issuers/14", "validFrom": "2010-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts" } }, "credentialSchema": { "id": "https://example.org/examples/degree", "type": "ZkpExampleSchema2018" }, "proof": { ... } }
In the example above, the issuer is specifying a
credentialSchema
pointing to a means of transforming the input
data into a format which can then be used by a verifier to determine if
the proof provided with the verifiable credential is valid.
Building on the concepts introduced in Section 4. Basic Concepts, this section explores more complex topics about verifiable credentials.
This section is non-normative.
Section 1.2 Ecosystem Overview provided an overview of the verifiable credential ecosystem. This section provides more detail 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:
This specification does not define any protocol for transferring verifiable credentials or verifiable presentations, but assuming other specifications do specify how they are transferred between entities, then this Verifiable Credential Data Model is directly applicable.
This specification also does not define an authorization framework nor the decisions that a verifier might make after verifying a verifiable credential or verifiable presentation, taking into account the holder, the issuers of the verifiable credentials, the contents of the verifiable credentials, and its own policies.
In particular, Sections 5.6 Terms of Use and the Subject-Holder Relationships section in the Verifiable Credentials Implementation Guide [VC-IMP-GUIDE] specify how a verifier can determine:
This section is non-normative.
The verifiable credentials trust model is as follows:
This trust model differentiates itself from other trust models by ensuring the:
By decoupling the trust between the identity provider and the relying party a more flexible and dynamic trust model is created such that market competition and customer choice is increased.
For more information about how this trust model interacts with various threat models studied by the Working Group, see the Verifiable Credentials Use Cases document [VC-USE-CASES].
The data model detailed in this specification does not imply a transitive trust model, such as that provided by more traditional Certificate Authority trust models. In the Verifiable Credentials Data Model, a verifier either directly trusts or does not trust an issuer. While it is possible to build transitive trust models using the Verifiable Credentials Data Model, implementers are urged to learn about the security weaknesses introduced by broadly delegating trust in the manner adopted by Certificate Authority systems.
One of the goals of the Verifiable Credentials Data Model is to enable permissionless innovation. To achieve this, the data model needs to be extensible in a number of different ways. The data model is required to:
This approach to data modeling is often called an open world assumption, meaning that any entity can say anything about any other entity. While this approach seems to conflict with building simple and predictable software systems, balancing extensibility with program correctness is always more challenging with an open world assumption than with closed software systems.
The rest of this section describes, through a series of examples, how both extensibility and program correctness are achieved.
Let us assume we start with the verifiable credential shown below.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "http://example.com/credentials/4643", "type": ["VerifiableCredential"], "issuer": "https://example.com/issuers/14", "validFrom": "2018-02-24T05:28:04Z", "credentialSubject": { "id": "did:example:abcdef1234567", "name": "Jane Doe" } }
This verifiable credential states that the entity associated with
did:example:abcdef1234567
has a name
with a value of
Jane Doe
.
Now let us assume a developer wants to extend the verifiable credential to store two additional pieces of information: an internal corporate reference number, and Jane's favorite food.
The first thing to do is to create a JSON-LD context containing two new terms, as shown below.
{ "@context": { "referenceNumber": "https://example.com/vocab#referenceNumber", "favoriteFood": "https://example.com/vocab#favoriteFood" } }
After this JSON-LD context is created, the developer publishes it somewhere so
it is accessible to verifiers who will be processing the
verifiable credential. Assuming the above JSON-LD context is published at
https://example.com/contexts/mycontext.jsonld
, we can extend this
example by including the context and adding the new properties and
credential type to the verifiable credential.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2", "https://example.com/contexts/mycontext.jsonld" ], "id": "http://example.com/credentials/4643", "type": ["VerifiableCredential", "CustomExt12"], "issuer": "https://example.com/issuers/14", "validFrom": "2018-02-24T05:28:04Z", "referenceNumber": 83294847, "credentialSubject": { "id": "did:example:abcdef1234567", "name": "Jane Doe", "favoriteFood": "Papaya" } }
This example demonstrates extending the Verifiable Credentials Data Model in a permissionless and decentralized way. The mechanism shown also ensures that verifiable credentials created in this way provide a mechanism to prevent namespace conflicts and semantic ambiguity.
A dynamic extensibility model such as this does increase the implementation burden. Software written for such a system has to determine whether verifiable credentials with extensions are acceptable based on the risk profile of the application. Some applications might accept only certain extensions while highly secure environments might not accept any extensions. These decisions are up to the developers of these applications and are specifically not the domain of this specification.
Developers are urged to ensure that extension JSON-LD contexts are highly available. Implementations that cannot dereference a context will produce an error. Strategies for ensuring that extension JSON-LD contexts are always available include using content-addressed URLs for contexts, bundling context documents with implementations, or enabling aggressive caching of contexts.
Implementers are advised to pay close attention to the extension points in this specification, such as in Sections A.5 Proofs (Signatures), 4.9 Status, 4.11 Data Schemas,5.5 Refreshing, 5.6 Terms of Use, and 5.7 Evidence. While this specification does not define concrete implementations for those extension points, the Verifiable Credential Specifications Directory [VC-SPECS] provides an unofficial, curated list of extensions that developers can use from these extension points.
@protected
feature in the JSON-LD 1.1 specification.
A human-readable document describing the expected order of values for the
@context
property is expected to be published by any
implementer seeking interoperability. A machine-readable description
(that is, a normal JSON-LD Context document) is expected to be published
at the URL specified in the @context
property by
JSON-LD implementers seeking interoperability.
This feature is at risk and will be removed from the specification if at least two independent, interoperable implementations are not demonstrated for a single extension type by the end of the Candidate Recommendation Phase. If this feature is removed, the property will be included in Section 5.10 Reserved Extension Points, in anticipation of future implementation and inclusion in the specification.
It is useful for systems to enable the manual or automatic refresh of an expired
verifiable credential. For more information about validity periods for
verifiable credentials, see Section A.6 Validity Periods.
This specification defines a refreshService
property, which
enables an issuer to include a link to a refresh service.
The issuer can include the refresh service as an element inside the verifiable credential if it is intended for either the verifier or the holder (or both), or inside the verifiable presentation if it is intended for the holder only. In the latter case, this enables the holder to refresh the verifiable credential before creating a verifiable presentation to share with a verifier. In the former case, including the refresh service inside the verifiable credential enables either the holder or the verifier to perform future updates of the credential.
The refresh service is only expected to be used when either the
credential has expired or the issuer does not publish
credential status information. Issuers are advised not to put the
refreshService
property in a verifiable credential
that does not contain public information or whose refresh service is not
protected in some way.
Placing a refreshService
property in a
verifiable credential so that it is available to verifiers can
remove control and consent from the holder and allow the
verifiable credential to be issued directly to the verifier,
thereby bypassing the holder.
refreshService
property MUST be one or more
refresh services that provides enough information to the recipient's software
such that the recipient can refresh the verifiable credential. Each
refreshService
value MUST specify its type
(for
example, ManualRefreshService2018
) and its id
, which
is the URL of the service. There is an expectation that machine readable
information needs to be retrievable from the URL. The precise content of
each refresh service is determined by the specific refreshService
type definition.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"refreshService": {
"id": "https://university.example/refresh/3732",
"type": "ManualRefreshService2018"
}
}
In the example above, the issuer specifies a manual
refreshService
that can be used by directing the holder or
the verifier to https://university.example/refresh/3732
.
This feature is at risk and will be removed from the specification if at least two independent, interoperable implementations are not demonstrated for a single extension type by the end of the Candidate Recommendation Phase. If this feature is removed, the property will be included in Section 5.10 Reserved Extension Points, in anticipation of future implementation and inclusion in the specification.
Terms of use can be utilized by an issuer or a holder to
communicate the terms under which a verifiable credential or
verifiable presentation was issued. The issuer places their terms
of use inside the verifiable credential. The holder places their
terms of use inside a verifiable presentation. This specification defines
a termsOfUse
property for expressing terms of use
information.
The value of the termsOfUse
property tells the
verifier what actions it is required to perform (an obligation),
not allowed to perform (a prohibition), or allowed to perform (a
permission) if it is to accept the verifiable credential or
verifiable presentation.
Further study is required to determine how a subject who is not a holder places terms of use on their verifiable credentials. One way could be for the subject to request the issuer to place the terms of use inside the issued verifiable credentials. Another way could be for the subject to delegate a verifiable credential to a holder and place terms of use restrictions on the delegated verifiable credential.
termsOfUse
property MUST specify one or
more terms of use policies under which the creator issued the credential
or presentation. If the recipient (a holder or
verifier) is not willing to adhere to the specified terms of use, then
they do so on their own responsibility and might incur legal liability if they
violate the stated terms of use. Each termsOfUse
value MUST specify
its type, for example, IssuerPolicy
, and MAY specify its
instance id
. The precise contents of each term of use is determined
by the specific termsOfUse
type definition.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/3732",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2010-01-01T19:23:24Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"termsOfUse": [{
"type": "IssuerPolicy",
"id": "http://example.com/policies/credential/4",
"profile": "http://example.com/profiles/credential",
"prohibition": [{
"assigner": "https://university.example/issuers/14",
"assignee": "AllVerifiers",
"target": "http://university.example/credentials/3732",
"action": ["Archival"]
}]
}]
}
In the example above, the issuer (the assigner
) is
prohibiting verifiers (the assignee
) from storing the data
in an archive.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2", { "@protected": true, "VerifiablePresentationTermsOfUseExtension": { "@id": "https://www.w3.org/2018/credentials/examples#VerifiablePresentationExtension", "@context": { "@protected": true, "termsOfUse": { "@id": "https://www.w3.org/2018/credentials#termsOfUse", "@type": "@id" } } } } ], "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "type": ["VerifiablePresentation"], "verifiableCredential": [{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "http://university.example/credentials/3732", "type": ["VerifiableCredential", "ExampleDegreeCredential"], "issuer": "https://university.example/issuers/14", "validFrom": "2010-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts" } }, "proof": { ... } }], "termsOfUse": [{ "type": "HolderPolicy", "id": "http://example.com/policies/credential/6", "profile": "http://example.com/profiles/credential", "prohibition": [{ "assigner": "did:example:ebfeb1f712ebc6f1c276e12ec21", "assignee": "https://wineonline.example.org/", "target": "http://university.example/credentials/3732", "action": ["3rdPartyCorrelation"] }] }], "proof": [ ... ] }
In the example above, the holder (the assigner
), who is
also the subject, expressed a term of use prohibiting the verifier
(the assignee
, https://wineonline.example.org
) from
using the information provided to correlate the holder or subject
using a third-party service. If the verifier were to use a third-party
service for correlation, they would violate the terms under which the
holder created the presentation.
This feature is also expected to be used by government-issued verifiable credentials to instruct digital wallets to limit their use to similar government organizations in an attempt to protect citizens from unexpected usage of sensitive data. Similarly, some verifiable credentials issued by private industry are expected to limit usage to within departments inside the organization, or during business hours. Implementers are urged to read more about this rapidly evolving feature in the appropriate section of the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.
This feature is at risk and will be removed from the specification if at least two independent, interoperable implementations are not demonstrated for a single extension type by the end of the Candidate Recommendation Phase. If this feature is removed, the property will be included in Section 5.10 Reserved Extension Points, in anticipation of future implementation and inclusion in the specification.
Evidence can be included by an issuer to provide the verifier with additional supporting information in a verifiable credential. This could be used by the verifier to establish the confidence with which it relies on the claims in the verifiable credential.
For example, an issuer could check physical documentation provided by the subject or perform a set of background checks before issuing the credential. In certain scenarios, this information is useful to the verifier when determining the risk associated with relying on a given credential.
This specification defines the evidence
property for
expressing evidence information.
evidence
property MUST be one or more
evidence schemes providing enough information for a verifier to determine
whether the evidence gathered by the issuer meets its confidence
requirements for relying on the credential. Each evidence scheme is
identified by its type. The id
property is optional,
but if present, SHOULD contain a URL that points to where more information about
this instance of evidence can be found. The precise content of each evidence
scheme is determined by the specific evidence
type
definition.
For information about how attachments and references to credentials and non-credential data might be supported by the specification, see the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "http://university.example/credentials/3732", "type": ["VerifiableCredential", "ExampleDegreeCredential"], "issuer": "https://university.example/issuers/14", "validFrom": "2010-01-01T19:23:24Z", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts" } }, "evidence": [{ "id": "https://university.example/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d4231", "type": ["DocumentVerification"], "verifier": "https://university.example/issuers/14", "evidenceDocument": "DriversLicense", "subjectPresence": "Physical", "documentPresence": "Physical", "licenseNumber": "123AB4567" }], "proof": { ... } }
In this evidence
example, the issuer is asserting that they
physically matched the subject of the credential to a physical
copy of a driver's license with the stated license number. This driver's license
was used in the issuance process to verify that "Example University" verified
the subject before issuance of the credential and how they did so (physical
verification).
The evidence
property provides different and complementary
information to the proof
property. The evidence
property is used to express supporting information, such as documentary
evidence, related to the integrity of the verifiable credential. In
contrast, the proof
property is used to express
machine-verifiable mathematical proofs related to the authenticity of the
issuer and integrity of the verifiable credential. For more
information about the proof
property, see Section
A.5 Proofs (Signatures).
We plan to remove the normative requirements in this section if there are no active work items for securing verifiable credentials using zero knowledge proof mechanisms when we transition v2 of the data model to CR. Additionally, the remaining non-normative language will likely be moved to the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE].
Zero-knowledge proofs are cryptographic methods which enable a user to prove knowledge of a value without disclosing the actual value. This data model supports being secured with the use of zero-knowledge proof mechanisms.
Some capabilities that are compatible with verifiable credentials which are made possible by zero-knowledge proof mechanisms:
Not all capabilities are supported in all zero-knowledge proof mechanisms. Specific details about the capabilities and techniques provided by a particular zero knowledge proof mechanism, along with any normative requirements for using them with verifiable credentials, would be found in a specification for securing verifiable credentials with that zero-knowledge proof mechanism.
We note that in most instances, for holder to make use of zero knowledge mechanisms with verifiable credentials requires an issuer to secure the verifiable credential in a manner that supports these capabilities.
There are two requirements for verifiable credentials when they are to be used in zero-knowledge proof systems.
proof
property, so that the holder can derive a
verifiable presentation that reveals only the information that the
holder intends to reveal.
credentialSchema
property,
so that it can be used by all parties to perform various cryptographic
operations in zero-knowledge.
When a holder has selectively disclosed a portion of a
verifiable credential, it is important that the verifier check
whether the information provided in the derived verifiable credential is
compatible with the schema in the credentialSchema
property provided by the issuer. It is also possible for the
verifier to provide a schema to the holder as part of a request
for the holder's data, and for the verifier to ensure that the
derived verifiable credential is compatible with that schema as well. We do
not define such a request schema in this specification, but an example of one
method for doing so is [PRES-EX].
credentialSchema
implementers are encouraged to consider the
implications of selective disclosure credentials and provide guidance for
processing depending on the construction. If a schema is not formed with
selective disclosure in mind, then validation is likely to fail.
The examples below highlight how the data model might be used to issue and present verifiable credentials in zero-knowledge.
The provided examples will either be significantly re-written to demonstrate how to secure a verifiable credential using a normatively defined method that enable zero knowledge proofs, or they will be removed.
The following example shows one method of using verifiable credentials in zero-knowledge. It makes use of a Camenisch-Lysyanskaya Signature [CL-SIGNATURES], which allows the presentation of the verifiable credential in a way that supports the privacy of the holder and subject through the use of selective disclosure of the verifiable credential values. Some other cryptographic systems which rely upon zero-knowledge proofs to selectively disclose attributes can be found in the Verifiable Credential Specifications Directory [VC-SPECS] as well.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "type": ["VerifiableCredential", "ExampleDegreeCredential"], "credentialSchema": { "id": "did:example:cdf:35LB7w9ueWbagPL94T9bMLtyXDj9pX5o", "type": "did:example:schema:22KpkXgecryx9k7N6XN1QoN3gXwBkSU8SfyyYQG" }, "issuer": "did:example:Wz4eUg7SetGfaUVCn8U9d62oDYrUJLuUtcy619", "credentialSubject": { "givenName": "Jane", "familyName": "Doe", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts", "college": "College of Engineering" } }, "proof": { "type": "CLSignature2019", "issuerData": "5NQ4TgzNfSQxoLzf2d5AV3JNiCdMaTgm...BXiX5UggB381QU7ZCgqWivUmy4D", "attributes": "pPYmqDvwwWBDPNykXVrBtKdsJDeZUGFA...tTERiLqsZ5oxCoCSodPQaggkDJy", "signature": "8eGWSiTiWtEA8WnBwX4T259STpxpRKuk...kpFnikqqSP3GMW7mVxC4chxFhVs", "signatureCorrectnessProof": "SNQbW3u1QV5q89qhxA1xyVqFa6jCrKwv...dsRypyuGGK3RhhBUvH1tPEL8orH" } }
The example above provides the verifiable credential definition by using
the credentialSchema
property and a specific proof that is
usable in the Camenisch-Lysyanskaya Zero-Knowledge Proof system.
The next example utilizes the verifiable credential above to generate a new derived verifiable credential with a privacy-preserving proof. The derived verifiable credential is then placed in a verifiable presentation, so that the verifiable credential discloses only the claims and additional credential metadata that the holder intended. To do this, all of the following requirements are expected to be met:
proof
property to enable the verifier to check that all derived
verifiable credentials in the verifiable presentation were issued
to the same holder without leaking personally identifiable information
that the holder did not intend to share.
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "type": "VerifiablePresentation", "verifiableCredential": [ { "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "type": ["VerifiableCredential", "ExampleDegreeCredential"], "credentialSchema": { "id": "did:example:cdf:35LB7w9ueWbagPL94T9bMLtyXDj9pX5o", "type": "did:example:schema:22KpkXgecryx9k7N6XN1QoN3gXwBkSU8SfyyYQG" }, "issuer": "did:example:Wz4eUg7SetGfaUVCn8U9d62oDYrUJLuUtcy619", "credentialSubject": { "degreeType": "ExampleBachelorDegree", "degreeSchool": "College of Engineering" }, "proof": { "type": "AnonCredDerivedCredentialv1", "primaryProof": "cg7wLNSi48K5qNyAVMwdYqVHSMv1Ur8i...Fg2ZvWF6zGvcSAsym2sgSk737", "nonRevocationProof": "mu6fg24MfJPU1HvSXsf3ybzKARib4WxG...RSce53M6UwQCxYshCuS3d2h" } }], "proof": { "type": "AnonCredPresentationProofv1", "proofValue": "DgYdYMUYHURJLD7xdnWRinqWCEY5u5fK...j915Lt3hMzLHoPiPQ9sSVfRrs1D" } }
Important details regarding the format for the credential definition and of the proofs are omitted on purpose because they are outside of the scope of this document. The purpose of this section is to guide implementers who want to extend verifiable credentials and verifiable presentations to support zero-knowledge proof systems.
This section is non-normative.
Verifiable credentials are intended as a means of reliably identifying subjects. While it is recognized that Role Based Access Controls (RBACs) and Attribute Based Access Controls (ABACs) rely on this identification as a means of authorizing subjects to access resources, this specification does not provide a complete solution for RBAC or ABAC. Authorization is not an appropriate use for this specification without an accompanying authorization framework.
The Working Group did consider authorization use cases during the creation of this specification and is pursuing that work as an architectural layer built on top of this specification.
This specification reserves a number of properties to serve as possible extension points. While some implementers signaled interest in these properties, their inclusion in this specification was considered to be premature; these extension points might be more formally defined in future versions of this specification. It is important to note that these properties are not defined by this specification and implementers are cautioned that usage of these properties is considered experimental.
Implementers MAY use these properties, but SHOULD expect them and/or their meanings to change during the process to normatively specify them. Implementers SHOULD NOT use these properties without a publicly disclosed specification describing their implementation.
In order to avoid collisions regarding how the following properties are used,
implementations MUST specify a type
property in the value associated with the
reserved property. For more information related to adding type
information,
see Section 4.4 Types.
The working group is discussing if additional extension points
will be reserved in https://www.w3.org/ns/credentials/v2.
The working group currently plans to only reserve extension points that
have at least a draft specification that is being incubated in a community group.
Reserved Property | Description |
---|---|
evidence |
A property used for specifying the evidence that was presented in order to
issue the credential. The associated vocabulary URL MUST be
https://www.w3.org/2018/credentials#evidence .
Issue: (AT RISK) Reservation depends on implementations This property reservation might be deleted in favor of an existing section in the specification if at least one specification with two independent implementations are demonstrated by the end of the Candidate Recommendation Phase. If that does not occur, this reservation will remain, but the existing section in the specification will be removed. |
refreshService |
A property used for specifying how a credential can be refreshed. The
associated vocabulary URL MUST be
https://www.w3.org/2018/credentials#refreshService .
Issue: (AT RISK) Reservation depends on implementations This property reservation might be deleted in favor of an existing section in the specification if at least one specification with two independent implementations are demonstrated by the end of the Candidate Recommendation Phase. If that does not occur, this reservation will remain, but the existing section in the specification will be removed. |
renderMethod |
A property used for specifying how to render a credential into a visual,
auditory, or haptic format. The associated vocabulary URL MUST be
https://www.w3.org/2018/credentials#renderMethod .
Issue: (AT RISK) Reservation depends on implementations This reserved property is at risk and will be removed from the specification if at least one specification with two independent implementations are not demonstrated by the end of the Candidate Recommendation Phase. |
termsOfUse |
A property used for specifying the terms of use for a credential. The associated
vocabulary URL MUST be https://www.w3.org/2018/credentials#termsOfUse .
Issue: (AT RISK) Reservation depends on implementations This property reservation might be deleted in favor of an existing section in the specification if at least one specification with two independent implementations are demonstrated by the end of the Candidate Recommendation Phase. If that does not occur, this reservation will remain, but the existing section in the specification will be removed. |
An unofficial list of specifications that are associated with the extension points defined in this specification, as well as the reserved extension points defined in this section, can be found in the Verifiable Credentials Specifications Directory [VC-SPECS]. Items in the directory that refer to reserved extension points SHOULD be treated as experimental.
The data model as described in Sections
3. Core Data Model, 4. Basic Concepts, and
5. Advanced Concepts is the canonical structural representation of
a verifiable credential or verifiable presentation. All
serializations are representations of that data model in a specific format. This
section specifies how the data model is realized in JSON-LD for
application/vc+ld+json
, the base media type for Verifiable Credentials.
Although syntactic mappings are only provided for JSON-LD,
applications and services can use any other data representation syntax (such as
XML, YAML, or CBOR) that is capable of being mapped back to application/vc+ld+json
.
As the verification and validation requirements are defined in terms
of the data model, all serialization syntaxes have to be deterministically
translated to the data model for processing, validation, or comparison.
The expected arity of the property values in this specification, and the resulting datatype which holds those values, can vary depending on the property. If present, the following properties are represented as a single value:
All other properties, if present, are represented as either a single value or an array of values.
[JSON-LD] is a JSON-based format used to serialize Linked Data. The syntax is designed to easily integrate into deployed systems already using JSON, and provides a smooth upgrade path from JSON to [JSON-LD]. It is primarily intended to be a way to use Linked Data in Web-based programming environments, to build interoperable Web services, and to store Linked Data in JSON-based storage engines.
[JSON-LD] is useful when extending the data model described in this
specification. Instances of the data model are encoded in JSON-LD compact
form [JSON-LD] and include the @context
property. The
JSON-LD context
is described in detail in the [JSON-LD] specification and its use is
elaborated on in Section 5.3 Extensibility.
Multiple contexts MAY be used or combined to express any arbitrary information
about verifiable credentials in idiomatic JSON. The
JSON-LD context,
available at https://www.w3.org/ns/credentials/v2
, is a static
document that is never updated and can therefore be downloaded and cached client
side. The associated vocabulary document for the Verifiable Credentials Data
Model is available at https://www.w3.org/2018/credentials
.
This specification restricts the usage of JSON-LD representations of
the data model. JSON-LD compact document
form MUST be utilized for all representations of the data model in the
base media type, application/vc+ld+json
.
In general, the data model and syntaxes described in this document are designed such that developers can copy and paste examples to incorporate verifiable credentials into their software systems. The design goal of this approach is to provide a low barrier to entry while still ensuring global interoperability between a heterogeneous set of software systems. This section describes some of these approaches, which will likely go unnoticed by most developers, but whose details will be of interest to implementers. The most noteworthy syntactic sugars provided by [JSON-LD] are:
@id
and @type
keywords are aliased to
id
and type
respectively, enabling developers to use
this specification as idiomatic JSON.
verifiableCredential
and proof
properties
are treated as graph containers. That is, mechanisms used to isolate
sets of data asserted by different entities. This ensures, for example, proper
cryptographic separation between the data graph provided by each issuer
and the one provided by the holder presenting the
verifiable credential to ensure the provenance of the information for
each graph is preserved.
@protected
properties feature of [JSON-LD] 1.1 is used to
ensure that terms defined by this specification cannot be overridden. This means
that as long as the same @context
declaration is made at the top of
a verifiable credential or verifiable presentation,
interoperability is guaranteed for all terms understood by users of the data
model whether or not they use a [JSON-LD] processor.
Media types, as defined in [RFC6838], identify the syntax used to express a verifiable credential as well as other useful processing guidelines.
Syntaxes used to express the data model in this specification SHOULD be identified by a media type, and conventions outlined in this section SHOULD be followed when defining or using media types with verifiable credentials.
There are two media types associated with the core data model, which are
listed in the Section C. IANA Considerations:
application/vc+ld+json
and application/vp+ld+json
.
The application/vc+ld+json
and application/vp+ld+json
media types do not imply any particular securing
mechanism, but are intended to be used in conjunction with securing mechanisms.
A securing mechanism needs to be applied to protect the integrity of these media types.
Do not assume security of content regardless of the media type used to communicate it.
This section is non-normative.
At times, developers or systems might use lower precision media types to convey verifiable credentials or verifiable presentations. Some of the reasons for use of lower precision media types include:
text/plain
or application/octet-stream
when a file
extension is not available and it cannot determine the media type.
.json
could result in a
media type of application/json
and .jsonld
might result in a media type of
application/ld+json
.
application/json
instead of application/vp+ld+json
,
Implementers are urged to not raise errors when it is possible to determine the
intended media type from a payload, provided that the media type used is
acceptable in the given protocol. For example, if an application only accepts
payloads that conform to the rules associated with the application/vc+ld+json
media type, but the payload is tagged with application/json
or
application/ld+json
instead, the application might perform the following
steps to determine whether the payload also conforms to the higher precision
media type:
@context
field matches
https://www.w3.org/2018/credentials/v2
.
application/vp+ld+json
media type if the JSON document contains a
top-level type
field containing a VerifiablePresentation
element. Additional
subsequent checks are still expected to be performed (according to this
specification) to ensure the payload expresses a conformant Verifiable Presentation.
application/vc+ld+json
media type if the JSON document contains a
top-level type
field containing a VerifiableCredential
element. Additional
subsequent checks are still expected to be performed (according to this
specification) to ensure the payload expresses a conformant Verifiable Credential.
Whenever possible, implementers are advised to use the most precise (the highest precision) media type for all payloads defined by this specification. Implementers are also advised to recognize that a payload tagged with a lower precision media type does not mean that the payload does not meet the rules necessary to tag it with a higher precision type. Similarly, a payload tagged with a higher precision media type does not mean that the payload will meet the requirements associated with the media type. Receivers of payloads, regardless of their associated media type, are expected to perform appropriate checks to ensure that payloads conform with the requirements for their use in a given system.
The data model described in this specification is designed to be proof format agnostic. This specification does not normatively require any particular digital proof or signature format. While the data model is the canonical representation of a credential or presentation, the proofing mechanisms for these are often tied to the syntax used in the transmission of the document between parties. As such, each proofing mechanism has to specify whether the verification of the proof is calculated against the state of the document as transmitted, against the possibly transformed data model, or against another form. At the time of publication, at least two proof formats are being actively utilized by implementers and the Working Group felt that documenting what these proof formats are and how they are being used would be beneficial to implementers. The sections detailing the current proof formats being actively utilized to issue verifiable credentials are:
This section is non-normative.
This section details the general privacy considerations and specific privacy implications of deploying the Verifiable Credentials Data Model into production environments.
This section is non-normative.
It is important to recognize there is a spectrum of privacy ranging from pseudonymous to strongly identified. Depending on the use case, people have different comfort levels about what information they are willing to provide and what information can be derived from what is provided.
For example, most people probably want to remain anonymous when purchasing alcohol because the regulatory check required is solely based on whether a person is above a specific age. Alternatively, for medical prescriptions written by a doctor for a patient, the pharmacy fulfilling the prescription is required to more strongly identify the medical professional and the patient. Therefore there is not one approach to privacy that works for all use cases. Privacy solutions are use case specific.
Even for those wanting to remain anonymous when purchasing alcohol, photo identification might still be required to provide appropriate assurance to the merchant. The merchant might not need to know your name or other details (other than that you are over a specific age), but in many cases just proof of age might still be insufficient to meet regulations.
The Verifiable Credentials Data Model strives to support the full privacy spectrum and does not take philosophical positions on the correct level of anonymity for any specific transaction. The following sections provide guidance for implementers who want to avoid specific scenarios that are hostile to privacy.
This section is non-normative.
Data associated with verifiable credentials stored in the
credential.credentialSubject
field is susceptible to privacy
violations when shared with verifiers. Personally identifying data, such
as a government-issued identifier, shipping address, and full name, can be
easily used to determine, track, and correlate an entity. Even
information that does not seem personally identifiable, such as the
combination of a birthdate and a postal code, has very powerful correlation
and de-anonymizing capabilities.
Implementers are strongly advised to warn holders when they share data
with these kinds of characteristics. Issuers are strongly advised to
provide privacy-protecting verifiable credentials when possible. For
example, issuing ageOver
verifiable credentials instead of
date of birth verifiable credentials when a verifier wants to
determine if an entity is over the age of 18.
Because a verifiable credential often contains personally identifiable information (PII), implementers are strongly advised to use mechanisms while storing and transporting verifiable credentials that protect the data from those who should not access it. Mechanisms that could be considered include Transport Layer Security (TLS) or other means of encrypting the data while in transit, as well as encryption or data access control mechanisms to protect the data in a verifiable credential while at rest.
This section is non-normative.
Subjects of verifiable credentials are identified using the
credential.credentialSubject.id
field. The identifiers used to
identify a subject create a greater risk of correlation when the
identifiers are long-lived or used across more than one web domain.
Similarly, disclosing the credential identifier
(credential.id
) leads to situations where multiple
verifiers, or an issuer and a verifier, can collude to
correlate the holder. If holders want to reduce correlation, they
should use verifiable credential schemes that allow hiding the
identifier during verifiable presentation. Such schemes expect the
holder to generate the identifier and might even allow hiding the
identifier from the issuer, while still keeping the identifier embedded
and signed in the verifiable credential.
If strong anti-correlation properties are a requirement in a verifiable credentials system, it is strongly advised that identifiers are either:
This section is non-normative.
The contents of verifiable credentials are secured using the
credential.proof
field. The properties in this field
create a greater risk of correlation when the same values are used across more
than one session or domain and the value does not change. Examples include the
verificationMethod
, created
,
proofPurpose
, and jws
fields.
If strong anti-correlation properties are required, it is advised that signature values and metadata are regenerated each time using technologies like third-party pairwise signatures, zero-knowledge proofs, or group signatures.
Even when using anti-correlation signatures, information might still be contained in a verifiable credential that defeats the anti-correlation properties of the cryptography used.
This section is non-normative.
Verifiable credentials might contain long-lived identifiers that could be used to correlate individuals. These types of identifiers include subject identifiers, email addresses, government-issued identifiers, organization-issued identifiers, addresses, healthcare vitals, verifiable credential-specific JSON-LD contexts, and many other sorts of long-lived identifiers.
Organizations providing software to holders should strive to identify fields in verifiable credentials containing information that could be used to correlate individuals and warn holders when this information is shared.
This section is non-normative.
There are mechanisms external to verifiable credentials that are used to track and correlate individuals on the Internet and the Web. Some of these mechanisms include Internet protocol (IP) address tracking, web browser fingerprinting, evercookies, advertising network trackers, mobile network position information, and in-application Global Positioning System (GPS) APIs. Using verifiable credentials cannot prevent the use of these other tracking technologies. Also, when these technologies are used in conjunction with verifiable credentials, new correlatable information could be discovered. For example, a birthday coupled with a GPS position can be used to strongly correlate an individual across multiple websites.
It is recommended that privacy-respecting systems prevent the use of these other tracking technologies when verifiable credentials are being used. In some cases, tracking technologies might need to be disabled on devices that transmit verifiable credentials on behalf of a holder.
This section is non-normative.
To enable recipients of verifiable credentials to use them in a variety of circumstances without revealing more PII than necessary for transactions, issuers should consider limiting the information published in a credential to a minimal set needed for the expected purposes. One way to avoid placing PII in a credential is to use an abstract property that meets the needs of verifiers without providing specific information about a subject.
For example, this document uses the ageOver
property
instead of a specific birthdate, which constitutes much stronger PII. If
retailers in a specific market commonly require purchasers to be older than a
certain age, an issuer trusted in that market might choose to offer a
verifiable credential claiming that subjects have met that
requirement instead of offering verifiable credentials containing
claims about specific birthdates. This enables individual customers to
make purchases without revealing specific PII.
This section is non-normative.
Privacy violations occur when information divulged in one context leaks into another. Accepted best practice for preventing such violations is to limit the information requested, and received, to the absolute minimum necessary. This data minimization approach is required by regulation in multiple jurisdictions, including the Health Insurance Portability and Accountability Act (HIPAA) in the United States and the General Data Protection Regulation (GDPR) in the European Union.
With verifiable credentials, data minimization for issuers means limiting the content of a verifiable credential to the minimum required by potential verifiers for expected use. For verifiers, data minimization means limiting the scope of the information requested or required for accessing services.
For example, a driver's license containing a driver's ID number, height, weight, birthday, and home address is a credential containing more information than is necessary to establish that the person is above a certain age.
It is considered best practice for issuers to atomize information or use
a signature scheme that allows for selective disclosure. For example, an
issuer of driver's licenses could issue a verifiable credential
containing every attribute that appears on a driver's license, as well as a set
of verifiable credentials where every verifiable credential
contains only a single attribute, such as a person's birthday. It could also
issue more abstract verifiable credentials (for example, a
verifiable credential containing only an ageOver
attribute).
One possible adaptation would be for issuers to provide secure HTTP
endpoints for retrieving single-use bearer credentials that promote the
pseudonymous usage of verifiable credentials. Implementers that find this
impractical or unsafe, should consider using selective disclosure schemes
that eliminate dependence on issuers at proving time and reduce temporal
correlation risk from issuers.
Verifiers are urged to only request information that is absolutely necessary for a specific transaction to occur. This is important for at least two reasons. It:
While it is possible to practice the principle of minimum disclosure, it might be impossible to avoid the strong identification of an individual for specific use cases during a single session or over multiple sessions. The authors of this document cannot stress how difficult it is to meet this principle in real-world scenarios.
This section is non-normative.
A bearer credential is a privacy-enhancing piece of information, such as a concert ticket, which entitles the holder of the bearer credential to a specific resource without divulging sensitive information about the holder. Bearer credentials are often used in low-risk use cases where the sharing of the bearer credential is not a concern or would not result in large economic or reputational losses.
Verifiable credentials that are bearer credentials are made
possible by not specifying the subject identifier, expressed using the
id
property, which is nested in the
credentialSubject
property. For example, the following
verifiable credential is a bearer credential:
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/temporary/28934792387492384",
"type": ["VerifiableCredential", "ExampleDegreeCredential"],
"issuer": "https://university.example/issuers/14",
"validFrom": "2017-10-22T12:23:48Z",
"credentialSubject": {
// note that the 'id' property is not specified for bearer credentials
"degree": {
"type": "ExampleBachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
}
While bearer credentials can be privacy-enhancing, they must be carefully crafted so as not accidentally divulge more information than the holder of the bearer credential expects. For example, repeated use of the same bearer credential across multiple sites enables these sites to potentially collude to unduly track or correlate the holder. Likewise, information that might seem non-identifying, such as a birthdate and postal code, can be used to statistically identify an individual when used together in the same bearer credential or session.
Issuers of bearer credentials should ensure that the bearer credentials provide privacy-enhancing benefits that:
Holders should be warned by their software if bearer credentials containing sensitive information are issued or requested, or if there is a correlation risk when combining two or more bearer credentials across one or more sessions. While it might be impossible to detect all correlation risks, some might certainly be detectable.
Verifiers should not request bearer credentials that can be used to unduly correlate the holder.
This section is non-normative.
When processing verifiable credentials, verifiers are expected to perform many of the checks listed in Appendix A. Validation as well as a variety of specific business process checks. Validity checks might include checking:
The process of performing these checks might result in information leakage that leads to a privacy violation of the holder. For example, a simple operation such as checking a revocation list can notify the issuer that a specific business is likely interacting with the holder. This could enable issuers to collude and correlate individuals without their knowledge.
Issuers are urged to not use mechanisms, such as credential revocation lists that are unique per credential, during the verification process that could lead to privacy violations. Organizations providing software to holders should warn when credentials include information that could lead to privacy violations during the verification process. Verifiers should consider rejecting credentials that produce privacy violations or that enable bad privacy practices.
This section is non-normative.
When a holder receives a verifiable credential from an issuer, the verifiable credential needs to be stored somewhere (for example, in a credential repository). Holders are warned that the information in a verifiable credential is sensitive in nature and highly individualized, making it a high value target for data mining. Services that advertise free storage of verifiable credentials might in fact be mining personal data and selling it to organizations wanting to build individualized profiles on people and organizations.
Holders need to be aware of the terms of service for their credential repository, specifically the correlation and data mining protections in place for those who store their verifiable credentials with the service provider.
Some effective mitigations for data mining and profiling include using:
This section is non-normative.
Holding two pieces of information about the same subject almost always reveals more about the subject than just the sum of the two pieces, even when the information is delivered through different channels. The aggregation of verifiable credentials is a privacy risk and all participants in the ecosystem need to be aware of the risks of data aggregation.
For example, if two bearer credentials, one for an email address and then one stating the holder is over the age of 21, are provided across multiple sessions, the verifier of the information now has a unique identifier as well as age-related information for that individual. It is now easy to create and build a profile for the holder such that more and more information is leaked over time. Aggregation of credentials can also be performed across multiple sites in collusion with each other, leading to privacy violations.
From a technological perspective, preventing aggregation of information is a very difficult privacy problem to address. While new cryptographic techniques, such as zero-knowledge proofs, are being proposed as solutions to the problem of aggregation and correlation, the existence of long-lived identifiers and browser tracking techniques defeats even the most modern cryptographic techniques.
The solution to the privacy implications of correlation or aggregation tends not to be technological in nature, but policy driven instead. Therefore, if a holder does not want information about them to be aggregated, they must express this in the verifiable presentations they transmit.
This section is non-normative.
Despite the best efforts to assure privacy, actually using verifiable credentials can potentially lead to de-anonymization and a loss of privacy. This correlation can occur when:
In part, it is possible to mitigate this de-anonymization and loss of privacy by:
It is understood that these mitigation techniques are not always practical or even compatible with necessary usage. Sometimes correlation is a requirement.
For example, in some prescription drug monitoring programs, usage monitoring is a requirement. Enforcement entities need to be able to confirm that individuals are not cheating the system to get multiple prescriptions for controlled substances. This statutory or regulatory need to correlate usage overrides individual privacy concerns.
Verifiable credentials will also be used to intentionally correlate individuals across services, for example, when using a common persona to log in to multiple services, so all activity on each of those services is intentionally linked to the same individual. This is not a privacy issue as long as each of those services uses the correlation in the expected manner.
Privacy risks of credential usage occur when unintended or unexpected correlation arises from the presentation of credentials.
This section is non-normative.
When a holder chooses to share information with a verifier, it might be the case that the verifier is acting in bad faith and requests information that could be used to harm the holder. For example, a verifier might ask for a bank account number, which could then be used with other information to defraud the holder or the bank.
Issuers should strive to tokenize as much information as possible such that if a holder accidentally transmits credentials to the wrong verifier, the situation is not catastrophic.
For example, instead of including a bank account number for the purpose of checking an individual's bank balance, provide a token that enables the verifier to check if the balance is above a certain amount. In this case, the bank could issue a verifiable credential containing a balance checking token to a holder. The holder would then include the verifiable credential in a verifiable presentation and bind the token to a credit checking agency using a digital signature. The verifier could then wrap the verifiable presentation in their digital signature, and hand it back to the issuer to dynamically check the account balance.
Using this approach, even if a holder shares the account balance token with the wrong party, an attacker cannot discover the bank account number, nor the exact value in the account. And given the validity period for the counter-signature, does not gain access to the token for more than a few minutes.
This section is non-normative.
As detailed in Section 7.13 Usage Patterns, usage patterns can be correlated into certain types of behavior. Part of this correlation is mitigated when a holder uses a verifiable credential without the knowledge of the issuer. Issuers can defeat this protection however, by making their verifiable credentials short lived and renewal automatic.
For example, an ageOver
verifiable credential is useful for
gaining access to a bar. If an issuer issues such a
verifiable credential with a very short validity period and an automatic
renewal mechanism, then the issuer could possibly correlate the behavior
of the holder in a way that negatively impacts the holder.
Organizations providing software to holders should warn them if they repeatedly use credentials with short lifespans, which could result in behavior correlation. Issuers should avoid issuing credentials in a way that enables them to correlate usage patterns.
This section is non-normative.
An ideal privacy-respecting system would require only the information necessary for interaction with the verifier to be disclosed by the holder. The verifier would then record that the disclosure requirement was met and forget any sensitive information that was disclosed. In many cases, competing priorities, such as regulatory burden, prevent this ideal system from being employed. In other cases, long-lived identifiers prevent single use. The design of any verifiable credentials ecosystem, however, should strive to be as privacy-respecting as possible by preferring single-use verifiable credentials whenever possible.
Using single-use verifiable credentials provides several benefits. The first benefit is to verifiers who can be sure that the data in a verifiable credential is fresh. The second benefit is to holders, who know that if there are no long-lived identifiers in the verifiable credential, the verifiable credential itself cannot be used to track or correlate them online. Finally, there is nothing for attackers to steal, making the entire ecosystem safer to operate within.
This section is non-normative.
In an ideal private browsing scenario, no PII will be revealed. Because many credentials include PII, organizations providing software to holders should warn them about the possibility of revealing this information if they wish to use credentials and presentations while in private browsing mode. As each browser vendor handles private browsing differently, and some browsers might not have this feature at all, it is important for implementers to be aware of these differences and implement solutions accordingly.
This section is non-normative.
It cannot be overstated that verifiable credentials rely on a high degree of trust in issuers. The degree to which a holder might take advantage of possible privacy protections often depends strongly on the support an issuer provides for such features. In many cases, privacy protections which make use of zero-knowledge proofs, data minimization techniques, bearer credentials, abstract claims, and protections against signature-based correlation, require the issuer to actively support such capabilities and incorporate them into the verifiable credentials they issue.
It should also be noted that, in addition to a reliance on issuer participation to provide verifiable credential capabilities that help preserve holder and subject privacy, holders rely on issuers to not deliberately subvert privacy protections. For example, an issuer might sign verifiable credentials using a signature scheme that protects against signature-based correlation. This would protect the holder from being correlated by the signature value as it is shared among verifiers. However, if the issuer creates a unique key for each issued credential, it might be possible for the issuer to track presentations of the credential, regardless of a verifier's inability to do so.
This section is non-normative.
There are a number of security considerations that issuers, holders, and verifiers should be aware of when processing data described by this specification. Ignoring or not understanding the implications of this section can result in security vulnerabilities.
While this section attempts to highlight a broad set of security considerations, it is not a complete list. Implementers are urged to seek the advice of security and cryptography professionals when implementing mission critical systems using the technology outlined in this specification.
This section is non-normative.
Some aspects of the data model described in this specification can be protected through the use of cryptography. It is important for implementers to understand the cryptography suites and libraries used to create and process credentials and presentations. Implementing and auditing cryptography systems generally requires substantial experience. Effective red teaming can also help remove bias from security reviews.
Cryptography suites and libraries have a shelf life and eventually fall to new attacks and technology advances. Production quality systems need to take this into account and ensure mechanisms exist to easily and proactively upgrade expired or broken cryptography suites and libraries, and to invalidate and replace existing credentials. Regular monitoring is important to ensure the long term viability of systems processing credentials.
This section is non-normative.
Verifiable credentials often contain URLs to data that resides outside of the verifiable credential itself. Linked content that exists outside a verifiable credential, such as images, JSON-LD Contexts, and other machine-readable data, are often not protected against tampering because the data resides outside of the protection of the proof on the verifiable credential. For example, the following highlighted links are not content-integrity protected but probably should be:
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "http://university.example/credentials/58473", "type": ["VerifiableCredential", "ExampleAlumniCredential"], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "image": "https://university.example/images/58473", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "proof": { ... } }
While this specification does not recommend any specific content integrity protection, document authors who want to ensure links to content are integrity protected are advised to use URL schemes that enforce content integrity. Two such schemes are the [HASHLINK] specification and the [IPFS]. The example below transforms the previous example and adds content integrity protection to the JSON-LD Contexts using the [HASHLINK] specification, and content integrity protection to the image by using an [IPFS] link.
{ "@context": [ "https://www.w3.org/ns/credentials/v2?hl=z3aq31uzgnZBuWNzUB", "https://www.w3.org/ns/credentials/examples/v2?hl=z8guWNzUBnZBu3aq31" ], "id": "http://university.example/credentials/58473", "type": ["VerifiableCredential", "ExampleAlumniCredential"], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "image": "ipfs:/ipfs/QmXfrS3pHerg44zzK6QKQj6JDk8H6cMtQS7pdXbohwNQfK/image", "alumniOf": { "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", "name": "Example University" } }, "proof": { ... } }
It is debatable whether the JSON-LD Contexts above need protection because production implementations are expected to ship with static copies of important JSON-LD Contexts.
While the example above is one way to achieve content integrity protection, there are other solutions that might be better suited for certain applications. Implementers are urged to understand how links to external machine-readable content that are not content-integrity protected could result in successful attacks against their applications.
This section is non-normative.
This specification allows credentials to be produced that do not contain signatures or proofs of any kind. These types of credentials are often useful for intermediate storage, or self-asserted information, which is analogous to filling out a form on a web page. Implementers should be aware that these types of credentials are not verifiable because the authorship either is not known or cannot be trusted.
This section is non-normative.
A verifier might need to ensure it is the intended recipient of a verifiable presentation and not the target of a man-in-the-middle attack. Approaches such as token binding [RFC8471], which ties the request for a verifiable presentation to the response, can secure the protocol. Any unsecured protocol is susceptible to man-in-the-middle attacks.
This section is non-normative.
It is considered best practice for issuers to atomize information in a credential, or use a signature scheme that allows for selective disclosure. In the case of atomization, if it is not done securely by the issuer, the holder might bundle together different credentials in a way that was not intended by the issuer.
For example, a university might issue two verifiable credentials to a person, each containing two properties, which must be taken together to designate the "role" of that person in a given "department", such as "Staff Member" in the "Department of Computing", or "Post Graduate Student" in the "Department of Economics". If these verifiable credentials are atomized to put only one of these properties into each credential , then the university would issue four credentials to the person, each containing one of the following designations: "Staff Member", "Post Graduate Student", "Department of Computing", and "Department of Economics". The holder might then transfer the "Staff Member" and "Department of Economics" verifiable credentials to a verifier, which together would comprise a false claim.
This section is non-normative.
When verifiable credentials are issued for highly dynamic information, implementers should ensure the validity periods are set appropriately. Validity periods longer than the timeframe where the verifiable credential is meant for use might create exploitable security vulnerabilities. Validity periods shorter than the timeframe where the information expressed by the verifiable credential is expected to be used creates a burden on holders and verifiers. It is therefore important to set validity periods for verifiable credentials that are appropriate to the use case and the expected lifetime for the information contained in the verifiable credential.
This section is non-normative.
When verifiable credentials are stored on a device and that device is lost or stolen, it might be possible for an attacker to gain access to systems using the victim's verifiable credentials. Ways to mitigate this type of attack include:
This section is non-normative.
There are a number of accessibility considerations implementers should be aware of when processing data described in this specification. As with implementation of any web standard or protocol, ignoring accessibility issues makes this information unusable by a large subset of the population. It is important to follow accessibility guidelines and standards, such as [WCAG21], to ensure that all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which have historically created problems for assistive technologies.
This section details the general accessibility considerations to take into account when utilizing this data model.
This section is non-normative.
Many physical credentials in use today, such as government identification cards, have poor accessibility characteristics, including, but not limited to, small print, reliance on small and high-resolution images, and no affordances for people with vision impairments.
When utilizing this data model to create verifiable credentials, it is suggested that data model designers use a data first approach. For example, given the choice of using data or a graphical image to depict a credential, designers should express every element of the image, such as the name of an institution or the professional credential, in a machine-readable way instead of relying on a viewer's interpretation of the image to convey this information. Using a data first approach is preferred because it provides the foundational elements of building different interfaces for people with varying abilities.
This section is non-normative.
Implementers are advised to be aware of a number of internationalization considerations when publishing data described in this specification. As with any web standards or protocols implementation, ignoring internationalization makes it difficult for data to be produced and consumed across a disparate set of languages and societies, which limits the applicability of the specification and significantly diminishes its value as a standard.
Implementers are strongly advised to read the Strings on the Web: Language and Direction Metadata document [STRING-META], published by the W3C Internationalization Activity, which elaborates on the need to provide reliable metadata about text to support internationalization. For the latest information on internationalization considerations, implementers are also urged to read the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.
This section outlines general internationalization considerations to take into account when utilizing this data model and is intended to highlight specific parts of the Strings on the Web: Language and Direction Metadata document [STRING-META] that implementers might be interested in reading.
This section is non-normative.
Data publishers are strongly encouraged to read the section on Cross-Syntax Expression in the Strings on the Web: Language and Direction Metadata document [STRING-META] to ensure that the expression of language and base direction information is possible across multiple expression syntaxes, such as [JSON-LD], [JSON], and CBOR [RFC7049].
The general design pattern is to use the following markup template when expressing a text string that is tagged with a language and, optionally, a specific base direction.
"property": { "value": "The string value", "lang": "LANGUAGE
" "dir": "DIRECTION
" }
Using the design pattern above, the following example expresses the title of a book in the English language without specifying a text direction.
"title": {
"value": "HTML and CSS: Designing and Creating Websites",
"lang": "en
"
}
The next example uses a similar title expressed in the Arabic language with a base direction of right-to-left.
"title": { "value": "HTML و CSS: تصميم و إنشاء مواقع الويب", "lang": "ar
" "dir": "rtl
" }
The text above would most likely be rendered incorrectly as left-to-right without the explicit expression of language and direction because many systems use the first character of a text string to determine text direction.
Implementers utilizing JSON-LD are strongly urged to
extend the JSON-LD Context defining the
internationalized property and use the Scoped Context feature of JSON-LD
to alias the @value
, @language
, and
@direction
keywords to value
, lang
,
and dir
, respectively. An example of a JSON-LD Context snippet
doing this is shown below.
"title": {
"@context": {"value": "@value", "lang": "@language", "dir": "@direction"},
"@id": "https://www.w3.org/2018/credentials/examples#title"
}
This section is non-normative.
When multiple languages, base directions, and annotations are used in a single
natural language string, more complex mechanisms are typically required. It is
possible to use markup languages, such as HTML, to encode text with multiple
languages and base directions. It is also possible to use the
rdf:HTML
datatype to encode such values accurately in JSON-LD.
Despite the ability to encode information as HTML, implementers are strongly discouraged from doing this because it:
script
tag that
an attacker injected at some point during the data production process.
If implementers feel they must use HTML, or other markup languages capable of containing executable scripts, to address a specific use case, they are advised to analyze how an attacker would use the markup to mount injection attacks against a consumer of the markup and then deploy mitigations against the identified attacks.
This section is non-normative.
While this specification does not provide conformance criteria for the process of the validation of verifiable credentials or verifiable presentations, readers might be curious about how the information in this data model is expected to be utilized by verifiers during the process of validation. This section captures a selection of conversations held by the Working Group related to the expected usage of the data fields in this specification by verifiers.
This section is non-normative.
When a verifier requests one or more verifiable credentials
from a holder, they can specify the type of credential(s) that they would
like to receive. The type of a credential is expressed via the
type property. A verifiable credential of a specific
type is expected to contain specific properties that can be used to
determine whether or not the presentation meets a set of processing rules
that the verifier is executing. By requesting
verifiable credentials of a particular type
, the
verifier is able to gather specific information from the holder,
which originated with the issuer of each verifiable credential,
that will enable it to determine the next stage of an interaction with a
holder.
This section is non-normative.
In the verifiable credentials presented by a holder, the value
associated with the id
property for each
credentialSubject
is expected to identify a subject to the
verifier. If the holder is also the subject, then
the verifier could authenticate the holder if they have
public key metadata related to the holder. The verifier could then
authenticate the holder using a signature generated by the holder
contained in the verifiable presentation. The id
property is optional. Verifiers could use other properties
in a verifiable credential to uniquely identify a subject.
For information on how authentication and WebAuthn might work with verifiable credentials, see the Verifiable Credentials Implementation Guidelines [VC-IMP-GUIDE] document.
This section is non-normative.
The value associated with the issuer
property is expected
to identify an issuer that is known to and trusted by the
verifier.
Relevant metadata about the issuer
property is expected
to be available to the verifier. For example, an issuer can
publish information containing the public keys it uses to digitally sign
verifiable credentials that it issued. This metadata is relevant when
checking the proofs on the verifiable credentials.
This section is non-normative.
The validFrom
is expected to be within an expected range for the
verifier. For example, a verifier can check that the start of
the validity period for a verifiable credential is not in the future.
This section is non-normative.
The cryptographic mechanism used to prove that the information in a verifiable credential or verifiable presentation was not tampered with is called a proof. There are many types of cryptographic proofs including, but not limited to, digital signatures and zero-knowledge proofs. In general, when verifying proofs, implementations are expected to ensure:
Some proofs are digital signatures. In general, when verifying digital signatures, implementations are expected to ensure:
proofPurpose
property,
it is expected to exist and be a valid value, such as
assertionMethod
.
The digital signature provides a number of protections, other than tamper
resistance, which are not immediately obvious. For example, a Linked Data
Signature created
property establishes a date and time
before which the credential should not be considered verified. The
verificationMethod
property specifies, for example, the
public key that can be used to verify the digital signature. Dereferencing a
public key URL reveals information about the controller of the key, which can
be checked against the issuer of the credential. The
proofPurpose
property clearly expresses the purpose for
the proof and ensures this information is protected by the signature. A proof is
typically attached to a verifiable presentation for authentication
purposes and to a verifiable credential as a method of assertion.
This section is non-normative.
The validFrom
and validUntil
properties are expected
to be within an expected range for the verifier. For example, a
verifier can check that the end of the validity period of a verifiable
credential is not in the past.
This section is non-normative.
If the credentialStatus
property is available, the status of a
verifiable credential is expected to be evaluated by the verifier
according to the credentialStatus
type definition for the
verifiable credential and the verifier's own status evaluation
criteria. For example, a verifier can ensure the status of the
verifiable credential is not "withdrawn for cause by the issuer".
This section is non-normative.
If the credentialSchema
property is available, the schema of a
verifiable credential is expected to be evaluated by the verifier
according to the credentialSchema
type definition for the
verifiable credential and the verifier's own schema evaluation
criteria. For example, if the credentialSchema
's type
value is
[VC-JSON-SCHEMA-2023], then a verifier can ensure a credential's
data is valid against the given JSON Schema.
This section is non-normative.
Fitness for purpose is about whether the custom properties in the
verifiable credential are appropriate for the verifier's purpose.
For example, if a verifier needs to determine whether a subject is
older than 21 years of age, they might rely on a specific birthdate
property, or on more abstract properties, such as
ageOver
.
The issuer is trusted by the verifier to make the claims at hand. For example, a franchised fast food restaurant location trusts the discount coupon claims made by the corporate headquarters of the franchise. Policy information expressed by the issuer in the verifiable credential should be respected by holders and verifiers unless they accept the liability of ignoring the policy.
This section is non-normative.
This section lists cryptographic hash values that might change during the Candidate Recommendation phase based on implementer feedback that requires the referenced files to be modified.
Implementations MUST ensure that the base context value, located at
https://www.w3.org/ns/credentials/v2
, matches the following
SHA-384 digest of the value computed and encoded according to the [SRI] definition of digest
:
lHKDHh0msc6pRx8PhDOMkNtSI8bOfsp4giNbUrw71nXXLf13nTqNJoRp3Nx+ArVK
.
The base context value matching the digest previously stated can be used to
implement a local cached copy. It is possible to confirm the
SHA-384 digest by running the following command from a modern Unix command
interface line:
curl -s https://www.w3.org/ns/credentials/v2 | openssl dgst -sha384 -binary | openssl base64 -A
.
The Working Group is currently discussing what a processor should do if a hash value differs from one that is listed in the specification.
This section serves as a reminder of the importance of ensuring that, when verifying verifiable credentials and verifiable presentations, the verifier has information that is consistent with what the issuer or holder had when securing the credential or presentation. This information might include at least:
Verifiers are warned that other data that is referenced from within a credential, such as resources that are linked to via URLs, are not cryptographically protected by default. It is considered a best practice to ensure that the same sorts of protections are provided for any URL that is critical to the security of the credential through the use of permanently cached files and/or cryptographic hashes. See the Content Integrity section of the Verifiable Credential Implementation Guide for further information. Ultimately, knowing the cryptographic digest of any linked external content enables a verifier to confirm that the content is the same as what the issuer or holder intended.
This section lists URL values that might change during the Candidate Recommendation phase based on migration of documents to the W3C Technical Reports namespace and implementer feedback that requires the referenced URLs to be modified.
Implementations MUST ensure that the following vocabulary URLs used in the base context ultimately resolve to the following files, which are normative:
URL | Media Type | Content |
---|---|---|
https://www.w3.org/2018/credentials# | text/html | https://www.w3.org/2018/credentials/index.html |
https://www.w3.org/2018/credentials# | application/ld+json | https://www.w3.org/2018/credentials/index.jsonld |
https://schema.org/ | text/html | https://schema.org/ |
https://schema.org/ | application/ld+json | https://schema.org/version/latest/schemaorg-current-https.jsonld |
https://w3id.org/security# | text/html | https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.html |
https://w3id.org/security# | application/ld+json | https://w3c.github.io/vc-data-integrity/vocab/security/vocabulary.jsonld |
The URLs listed above that start with
https://w3c.github.io/vc-data-integrity/vocab/security/
are expected to change
to https://www.w3.org/ns/security/
or an equally normative and archived
location under W3C control.
The Working Group is currently discussing how it might want to normatively refer to the vocabulary files that are under the control of the Working Group. Current options are: inclusion of the files directly into the specification or publishing the files in W3C TR space and referring to them by using a cryptographic hash.
This section is non-normative.
The verifiable credential and verifiable presentation data models
leverage a variety of underlying technologies including [JSON-LD] and
[VC-JSON-SCHEMA-2023]. This section will provide a comparison of the
@context
, type
, and credentialSchema
properties, and cover some of the more specific use cases where it is possible
to use these features of the data model.
The type
property is used to uniquely identify
the type of the verifiable credential in which it appears, i.e., to
indicate which set of claims the verifiable credential contains.
This property, and the value VerifiableCredential
within the set of
its values, are mandatory. Whilst it is good practice to include one additional
value depicting the unique subtype of this verifiable credential, it is permitted
to either omit or include additional type values in the array. Many
verifiers will request a verifiable credential of a specific subtype, then
omitting the subtype value could make it more difficult for verifiers to inform
the holder which verifiable credential they require. When a verifiable
credential has multiple subtypes, listing all of them in the type
property is sensible. The usage of the type
property in a
[JSON-LD] representation of a verifiable credential enables to enforce the semantics of the
verifiable credential because the machine is able to check the semantics. With [JSON-LD],
the technology is not only describing the categorization of the set of claims,
the technology is also conveying the structure and semantics of the sub-graph of
the properties in the graph. In [JSON-LD], this represents the type of the node
in the graph which is why some [JSON-LD] representations of a verifiable
credential will use the type
property on many objects in the
verifiable credential.
The primary purpose of the @context
property, from a [JSON-LD]
perspective, is to convey the meaning of the data and term definitions of the
data in a verifiable credential, in a machine readable way. The @context
property is used to map the globally unique URLs for properties in verifiable
credentials and verifiable presentations into short-form alias names,
making [JSON-LD] representations more human-friendly
to read. From a [JSON-LD] perspective, this mapping also allows the data in
a credential to be modeled in a network of machine-readable data, by
enhancing how the data in the verifiable credential or verifiable
presentation relates to a larger machine-readable data graph. This is
useful for telling machines how to relate the meaning of data to
other data in an ecosystem where parties are unable to coordinate. This
property, with the first value in the set being
https://www.w3.org/ns/credentials/v2
, is mandatory.
Since the @context
property is used to map data to a graph
data model, and the type
property in [JSON-LD] is used to
describe nodes within the graph, the type
property becomes
even more important when using the two properties in combination. For example,
if the type
property is not included within the resolved
@context
resource using [JSON-LD], it could lead to claims being
dropped and/or their integrity no longer being protected during production and
consumption of the verifiable credential. Alternatively, it could lead to
errors being raised during production or consumption of a verifiable
credential. This will depend on the design choices of the implementation and
both paths are used in implementations today, so it's important to pay attention
to these properties when using a [JSON-LD] representation of a verifiable
credential or verifiable presentation.
The primary purpose of the credentialSchema
property is to
define the structure of the verifiable credential, and the datatypes for
the values of each property that appears. A credentialSchema
is useful
for defining the contents and structure of a set of claims in a verifiable
credential, whereas [JSON-LD] and a @context
in a verifiable
credential are best used only for conveying the semantics and term
definitions of the data, and can be used to define the structure of the
verifiable credential as well.
While it is possible to use some [JSON-LD] features to allude to the
contents of the verifiable credential, it's not generally
suggested to use @context
to constrain the data types of the
data model. For example, "@type": "@json"
is useful for leaving the
semantics open-ended and not strictly defined. This can be dangerous if
the implementer is looking to constrain the data type of the claims in the
credential, and is expected not to be used.
When the credentialSchema
and @context
properties
are used in combination, both producers and consumers can be more confident
about the expected contents and data types of the verifiable credential
and verifiable presentation.
This section is non-normative.
This section will be submitted to the Internet Engineering Steering Group (IESG) for review, approval, and registration with IANA.
This specification registers the application/vc+ld+json
Media Type
specifically for identifying documents conforming to the Verifiable Credentials
format.
Type name: | application |
Subtype name: | vc+ld+json |
Required parameters: | None |
Encoding considerations: |
Resources that use the "application/vc+ld+json " Media Type are
required to conform to all of the requirements for the
"application/ld+json " Media Type and are therefore subject to the
same encoding considerations specified in Section 11 of [RFC7159].
|
Security considerations: | As defined in this specification. |
Contact: | W3C Verifiable Credentials Working Group public-vc-wg@w3.org |
Note that while the Verifiable Credentials format uses JSON-LD conventions, there are a number of constraints and additional requirements for Verifiable Credential implementations that justify the use of a specific media type.
This media type can be used with credentials secured using an external proof.
A [JSON-LD] context is expected to be present in the body of the document, and
as indicated by the presence of ld+json
in the media type, the credential is
expected to be a valid
JSON-LD
document.
This specification registers the application/vp+ld+json
Media
Type specifically for identifying documents conforming to the Verifiable
Presentations format.
Type name: | application |
Subtype name: | vp+ld+json |
Required parameters: | None |
Encoding considerations: |
Resources that use the "application/vp+ld+json " Media Type are
required to conform to all of the requirements for the
"application/ld+json " Media Type and are therefore subject to the
same encoding considerations specified in Section 11 of [RFC7159].
|
Security considerations: | As defined in this specification. |
Contact: | W3C Verifiable Credentials Working Group public-vc-wg@w3.org |
Note that while the Verifiable Credentials format uses JSON-LD conventions, there are a number of constraints and additional requirements for Verifiable Credential implementations that justify the use of a specific media type.
This media type can be used with presentations secured using an external proof.
A [JSON-LD] context is expected to be present in the body of the document, and
as indicated by the presence of ld+json
in the media type, the credential is
expected to be a valid
JSON-LD
document.
This section contains the substantive changes that have been made to this specification over time.
Changes since the v1.1 Recommendation:
Changes since the v1.0 Recommendation:
id
property of the credentialStatus
and
refreshService
sections of the data model.
issuer
, issuanceDate
,
credentialStatus
, dates, dead links, and minor syntax errors.
This section is non-normative.
The Working Group thanks the following individuals not only for their contributions toward the content of this document, but also for yeoman's work in this standards community that drove changes, discussion, and consensus among a sea of varied opinions: Matt Stone, Gregg Kellogg, Ted Thibodeau Jr, Oliver Terbu, Joe Andrieu, David I. Lehn, Matthew Collier, and Adrian Gropper.
Work on this specification has been supported by the Rebooting the Web of Trust community facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles, Brian Weller, Betty Dhamers, Kaliya Young, Manu Sporny, Drummond Reed, Joe Andrieu, Heather Vescent, Kim Hamilton Duffy, Samantha Chase, and Andrew Hughes. The participants in the Internet Identity Workshop, facilitated by Phil Windley, Kaliya Young, Doc Searls, and Heidi Nobantu Saul, also supported the refinement of this work through numerous working sessions designed to educate about, debate on, and improve this specification.
The Working Group also thanks our Chairs, Dan Burnett, Matt Stone, Brent Zundel, Wayne Chang, and Kristina Yasuda as well as our W3C Staff Contacts, Kazuyuki Ashimura and Ivan Herman, for their expert management and steady guidance of the group through the W3C standardization process.
Portions of the work on this specification have been funded by the United States Department of Homeland Security's Science and Technology Directorate under contract HSHQDC-17-C-00019. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.
The Working Group would like to thank the following individuals for reviewing and providing feedback on the specification (in alphabetical order):
Christopher Allen, David Ammouial, Joe Andrieu, Bohdan Andriyiv, Ganesh Annan, Kazuyuki Ashimura, Tim Bouma, Pelle Braendgaard, Dan Brickley, Allen Brown, Jeff Burdges, Daniel Burnett, ckennedy422, David Chadwick, Chaoxinhu, Kim (Hamilton) Duffy, Lautaro Dragan, enuoCM, Ken Ebert, Eric Elliott, William Entriken, David Ezell, Nathan George, Reto Gmür, Ryan Grant, glauserr, Adrian Gropper, Joel Gustafson, Amy Guy, Lovesh Harchandani, Daniel Hardman, Dominique Hazael-Massieux, Jonathan Holt, David Hyland-Wood, Iso5786, Renato Iannella, Richard Ishida, Ian Jacobs, Anil John, Tom Jones, Rieks Joosten, Gregg Kellogg, Kevin, Eric Korb, David I. Lehn, Michael Lodder, Dave Longley, Christian Lundkvist, Jim Masloski, Pat McBennett, Adam C. Migus, Liam Missin, Alexander Mühle, Anthony Nadalin, Clare Nelson, Mircea Nistor, Grant Noble, Darrell O'Donnell, Nate Otto, Matt Peterson, Addison Phillips, Eric Prud'hommeaux, Liam Quin, Rajesh Rathnam, Drummond Reed, Yancy Ribbens, Justin Richer, Evstifeev Roman, RorschachRev, Steven Rowat, Pete Rowley, Markus Sabadello, Kristijan Sedlak, Tzviya Seigman, Reza Soltani, Manu Sporny, Orie Steele, Matt Stone, Oliver Terbu, Ted Thibodeau Jr, John Tibbetts, Mike Varley, Richard Varn, Heather Vescent, Christopher Lemmer Webber, Benjamin Young, Kaliya Young, Dmitri Zagidulin, and Brent Zundel.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: