Averifiable credential is a specific way to express a set ofclaimsmade by anissuer, such as a driver's license or an education certificate. Thisspecification describes the extensible data model forverifiable credentials,how they can be secured from tampering, and a three-party ecosystem forthe exchange of these credentials that is composed ofissuers,holders,andverifiers. This document also covers a variety of security, privacy,internationalization, and accessibility considerations for ecosystems thatuse the technologies described in this specification.
Credentials are integral to our daily lives: driver's licenses confirmour capability to operate motor vehicles; university degrees assert our levelof education; and government-issued passports attest to our citizenship whentraveling between countries. This specification provides a mechanism forexpressing these sorts ofcredentials on the Web in a way that iscryptographically secure, privacy respecting, and machine verifiable. Thesecredentials provide benefits to us when used in the physical world, buttheir use on the Web continues to be elusive.
It is currently difficult to express educational qualifications, healthcaredata, financial account details, and other third-party-verifiedpersonal information in a machine readable way on the Web. The challenge ofexpressing digitalcredentials on the Web hinders our ability to receivethe same benefits from them that physicalcredentials provide in thereal world.
For those unfamiliar with the concepts related toverifiable credentials, the following sections provide an overview of:
In the physical world, acredential might consist of:
Information related to identifying thesubject of thecredential(for example, a photo, name, or identification number)
Information related to the issuing authority (for example, a city government,national agency, or certification body)
Information related to the type ofcredential (for example, aDutch passport, an American driving license, or a health insurance card)
Information related to specific properties asserted bythe issuing authority about thesubject (for example, nationality,date of birth, or the classes of vehicle they're qualified to drive)
Evidence by which asubject was demonstrated to have satisfied thequalifications required for issuance of thecredential (for example,a measurement, proof of citizenship, or test result)
Information related to constraints on the credential (for example,validity period, or terms of use).
Averifiable credential can represent all the same information that aphysicalcredential represents. Adding technologies such asdigital signatures can makeverifiable credentials more tamper-evident andtrustworthy than their physical counterparts.
While this specification attempts to improve the ease of expressing digitalcredentials, it also aims to balance this goal with severalprivacy-preserving goals. The persistence of digital information, and the easewith which disparate sources of digital data can be collected and correlated,comprise a privacy concern that the use ofverifiable and easilymachine-readablecredentials threatens to make worse. This documentoutlines and attempts to address several of these issues in Section8.Privacy Considerations. Examples of how to use this data modelusing privacy-enhancing technologies, such as zero-knowledge proofs, are alsoprovided throughout this document.
The word "verifiable" in the termsverifiable credential andverifiable presentation refers to the characteristic of acredentialorpresentation as being able to beverified by averifier,as defined in this document. Verifiability of a credential does not implythe truth ofclaims encoded therein. Instead, upon establishing theauthenticity and currency of averifiable credential orverifiable presentation, averifier validates the includedclaims usingtheir own business rules before relying on them. Such reliance only occurs afterevaluating the issuer, the proof, the subject, and the claims against one ormore verifier policies.
1.2Ecosystem Overview
This section is non-normative.
This section describes the roles of the core actors and the relationshipsbetween them in an ecosystem where one expectsverifiable credentialsto be useful. A role is an abstraction that might be implemented in manydifferent ways. The separation of roles suggests likely interfaces andprotocols for standardization. This specification introduces the followingroles:
A role a system might perform by mediating the creation andverification ofidentifiers,verification material, and other relevant data, such asverifiable credential schemas, revocation registries, and so on, which mightrequire usingverifiable credentials. Some configurations might requirecorrelatable identifiers forsubjects. Some registries, such as ones forUUIDs andverification material, might just act as namespaces foridentifiers. Examples of verifiable data registries include trusted databases,decentralized databases, government ID databases, and distributed ledgers. Often,more than one type of verifiable data registry used in an ecosystem.
Figure1 The roles and information flows forming the basis for this specification.
Note: Other types of ecosystems exist
Figure1 above provides an example ecosystem to ground therest of the concepts in this specification. Other ecosystems exist, such asprotected environments or proprietary systems, whereverifiable credentials also provide benefits.
This ecosystem contrasts with the typical two-party or federated identityprovider models. An identity provider, sometimes abbreviated asIdP,is a system for creating, maintaining, and managing identity information forholders while providing authentication services torelying partyapplications within a federation or distributed network. In a federatedidentity model, theholder is tightly bound to the identity provider.This specification avoids using "identity provider," "federated identity," or"relying party" terminology, except when comparing or mapping these conceptsto other specifications. This specification decouples the identity providerconcept into two distinct concepts: theissuer and theholder.
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 wordsMAY,MUST,MUST NOT,OPTIONAL,RECOMMENDED,REQUIRED,SHOULD, andSHOULD NOT in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
Aconforming document is acompacted JSON-LDdocument that complies with all of the relevant "MUST" statements in thisspecification. Specifically, the relevant normative "MUST" statements inSections4.Basic Concepts,5.Advanced Concepts, and6.Syntaxes of this documentMUST be enforced.A conforming documentMUST be either averifiable credentialwith a media type ofapplication/vc or averifiable presentationwith a media type ofapplication/vp. A conforming documentMUST besecured by at least one securing mechanism as described in Section4.12Securing Mechanisms.
This document also contains examples that contain characters that are invalidJSON, 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 theinformation as a valid document.
Note: Human-readable texts in English are illustrative
Examples provided throughout this document include descriptive properties, such asname anddescription, with values in English to simplify the concepts in eachexample of the specification. These examples do not necessarily reflect the datastructures needed for international use, described in more detail inSection11.Internationalization Considerations.
2.Terminology
The following terms are used to describe concepts in this specification.
Anything that can be referenced in statements as an abstract or concrete noun.Entities include but are not limited to people, organizations, physical things,documents, abstract concepts, fictional characters, and arbitrary text. Anyentity might perform roles in the ecosystem, if it can do so. Notethat some entities fundamentally cannot take actions, for example, the string "abc"cannot issue credentials.
graph
A set of claims, forming a network of information composed ofsubjectsand their relationship to othersubjects or data. Eachclaim ispart of a graph; either explicit in the case ofnamed graphs, orimplicit for thedefault graph.
Agraph associated with specific properties, such asverifiableCredential. These propertiesresult in separategraphs that contain allclaims defined in thecorresponding JSON objects.
The assurance that aclaim from a specificissuer satisfies the businessrequirements of averifier for a particular use. This specification defineshow verifiers verifyverifiable credentials andverifiable presentations. It also specifies thatverifiers validate claims inverifiable credentials before relying on them. However, the means for suchvalidation vary widely and are outside the scope of this specification.Verifiers trust certainissuers for certain claims and apply their ownrules to determine which claims in whichcredentials are suitable for use bytheir systems.
verifiable credential
A tamper-evidentcredential whose authorship can be cryptographicallyverified. Verifiable credentials can be used to buildverifiable presentations, which can also be cryptographically verifiable.
verifiable data registry
A role a system might perform by mediating the creation andverificationof identifiers,verification material, and other relevant data, such asverifiable credential schemas, revocation registries,and so on, which might require usingverifiable credentials. Someconfigurations might require correlatable identifiers forsubjects. Someregistries, such as ones for UUIDs andverification material, might actas namespaces for identifiers.
verifiable presentation
A tamper-evident presentation of information encoded in such a way thatauthorship of the data can be trusted after a process of cryptographicverification. Certain types of verifiable presentations might contain data thatis synthesized from, but does not contain, the originalverifiable credentials(for example, zero-knowledge proofs).
verification
The evaluation of whether averifiable credential orverifiable presentation is an authentic and current statement of the issuer or presenter,respectively. This includes checking that the credential or presentationconforms to the specification, the securing mechanism is satisfied, and, ifpresent, the status check succeeds. Verification of a credential does not implyevaluation of the truth ofclaims encoded in the credential.
Information that is used to verify the security of cryptographicallyprotected information. For example, a cryptographic public key is used to verifya digital signature associated with averifiable credential.
URL
A Uniform Resource Locator, as defined by theURL Standard. URLs can bedereferenced to result in a resource, such as a document. The rulesfor dereferencing, or fetching, a URL are defined by the URLscheme.This specification does not use the term URI or IRI because those terms havebeen deemed to be confusing to Web developers.
The data model forclaims, illustrated inFigure2above, is powerful and can be used to express a large variety of statements. Forexample, whether someone graduated from a particular university can be expressedas shown inFigure3 below.
Figure3A basic claim expressing that Pat is an alum of "Example University".
Individualclaims can be merged together to express agraph ofinformation about asubject. The example shown inFigure4 below extends the previousclaim byadding theclaims that Pat knows Sam and that Sam is employed as aprofessor.
Figure4Multiple claims can be combined to express a graph of information.
To this point, the concepts of aclaim and agraph of informationare introduced. More information is expected to be added to the graph in orderto be able to trustclaims, more information isexpected to be added to the graph.
3.2Credentials
This section is non-normative.
Acredential is a set of one or moreclaims made by the sameentity.Credentials might also include an identifier and metadata to describeproperties of thecredential, such as theissuer, the validity date andtime period, a representative image,verification material, statusinformation, and so on. Averifiable credential is a set of tamper-evidentclaims and metadatathat cryptographically prove who issued it. Examples ofverifiable credentials include, but are not limited to, digital employee identificationcards, digital driver's licenses, and digital educational certificates.
Figure5Basic components of a verifiable credential.
Enhancing privacy is a key design feature of this specification. Therefore, itis crucial forentities using this technology to express onlythe portions of their personas that are appropriate for given situations. Theexpression of a subset of one's persona is called averifiable presentation.Examples of different personas include a person's professional persona,online gaming persona, family persona, or incognito persona.
The data in apresentation is often about the samesubject but mighthave been issued by multipleissuers. The aggregation of this informationexpresses an aspect of a person, organization, orentity.
Figure8Basic components of a verifiable presentation.
This section introduces some basic concepts for the specification inpreparation for Section5.Advanced Concepts later in thedocument.
4.1Getting Started
This section is non-normative.
This specification is designed to ease the prototyping of new types ofverifiable credentials. Developers can copy the template below and paste itinto commonverifiable credential tooling to start issuing, holding, andverifying prototype credentials.
A developer will changeMyPrototypeCredential below to the type of credentialthey would like to create. Sinceverifiable credentials talk about subjects,each property-value pair in thecredentialSubject object expresses aparticular property of the credential subject. Once a developer has added anumber of these property-value combinations, the modified object can be sent toaconforming issuer implementation, and averifiable credential will becreated for the developer. From a prototyping standpoint, that is all adeveloper needs to do.
Example 1: A template for creating prototype verifiable credentials
After stabilizing all credential properties, developers are advised to generateand publish vocabulary and context files at stable URLs to facilitateinteroperability with other developers. Thehttps://www.w3.org/ns/credentials/examples/v2 URL abovewould then be replaced with the URL of a use-case-specific context. Thisprocess is covered in Section5.2Extensibility. Alternatively,developers can reuse existing vocabulary and context files that happen to fittheir use case. They can explore theVerifiable Credential Extensionsfor reusable resources.
When two software systems need to exchange data, they need to use terminologythat both systems understand. Consider how two people communicate effectivelyby using the same language, where the words they use, such as "name" and"website," mean the same thing to each individual. This is sometimes referredto asthe context of a conversation. This specification uses a similarconcept to achieve similar results for software systems by establishing acontext in which to communicate.
Software systems that processverifiable credentials andverifiable presentations identify terminology by usingURLs for each term. However,thoseURLs can be long and not very human-friendly, while short-form,human-friendly aliases can be more helpful. This specification uses the@contextproperty to map short-form aliases to theURLs.
Verifiable credentials andverifiable presentationsMUST include a@contextproperty. Application developersMUST understand every JSON-LDcontext used by their application, at least to the extent that it affects themeaning of the terms used by their application. One mechanism fordoing so is described in the Section onValidating Contexts intheVerifiable Credential Data Integrity 1.0 specification. Other specifications that buildupon this specificationMAY require that JSON-LD contexts be integrity protectedby using therelatedResource feature described in Section5.3Integrity of Related Resources or any effectively equivalent mechanism.
@context
The value of the@contextpropertyMUST be anordered setwhere the first item is aURL with the valuehttps://www.w3.org/ns/credentials/v2.Subsequent items in theordered setMUST be composed of any combination ofURLs and objects, where each is processable as aJSON-LD Context.
The example above uses the base contextURL(https://www.w3.org/ns/credentials/v2) to establish that the data exchange isabout averifiable credential. This concept is further detailed inSection5.2Extensibility. The data available athttps://www.w3.org/ns/credentials/v2 is a permanently cacheable staticdocument with instructions for processing it provided in AppendixB.1Base Context. The associated human-readable vocabulary document for theVerifiable Credentials Data Model is available athttps://www.w3.org/2018/credentials/.
The secondURL (https://www.w3.org/ns/credentials/examples/v2) is used todemonstrate examples. Implementations are expected to not usethisURL for any other purpose, such as in pilot or production systems.
Note: See JSON-LD for more information about @context.
When expressing statements about a specific thing, such as a person, product, ororganization, using a globally unique identifier for that thing can be useful.Globally unique identifiers enable others to express statementsabout the same thing. This specification defines the optionalidproperty for such identifiers. Theidpropertyallows for expressing statements about specific things in theverifiable credential and is set by anissuer when expressingobjects in averifiable credential or aholder when expressingobjects in averifiable presentation. Theidproperty expresses anidentifier that others are expected to use when expressing statements about thespecific thing identified by that identifier. Exampleid valuesinclude UUIDs (urn:uuid:0c07c1ce-57cb-41af-bef2-1b932b986873), HTTP URLs(https://id.example/things#123), and DIDs (did:example:1234abcd).
Note: Identifiers of any kind increase correlatability
Developers are reminded that identifiers might be harmfulwhen pseudonymity is required. When considering such scenarios, developers areencouraged to read Section8.4Identifier-Based Correlation carefullyThere are also other types of access and correlation mechanisms documentedin Section8.Privacy Considerations that create privacy concerns.Where privacy is a vital consideration, it is permissible to omit theidproperty. Some use cases do not need or explicitly need to omit,theidproperty. Similarly, special attention is to be given to the choicebetween publicly resolvable URLs and other forms of identifiers. Publiclyresolvable URLs can facilitate ease of verification and interoperability, yetthey might also inadvertently grant access to potentially sensitive informationif not used judiciously.
id
Theidproperty isOPTIONAL. If present,idproperty's valueMUST be a singleURL, whichMAY be dereferenceable. It isRECOMMENDED that theURL in theid be one which, if dereferenceable, resultsin a document containing machine-readable information about theid.
Software systems that process the kinds of objects specified in this documentuse type information to determine whether or not a providedverifiable credential orverifiable presentation is appropriatefor the intended use-case. This specification defines atypeproperty for expressing object type information. This typeinformation can be used duringvalidation processes, as described in AppendixA.Validation.
A valid credentialSchematype. For example, "type": "JsonSchema"
Note: The Verifiable Credentials Data Model is based on JSON-LD
Thetype system for the Verifiable Credentials Data Model is the same asforJSON-LD 1.1 and is detailed inSection 3.5:Specifying the Type andSection 9: JSON-LDGrammar. When using a JSON-LD context (see Section5.2Extensibility), this specification aliases the@type keyword totype to make the JSON-LD documentsmore easily understood. While application developers and document authors donot need to understand the specifics of the JSON-LD type system, implementersof this specification who want to support interoperable extensibility do.
Allcredentials,presentations, and encapsulated objectsSHOULDspecify, or be associated with, additional, more narrowtypes (likeExampleDegreeCredential, for example) so software systems canmore easily detect and process this additional information.
When processing encapsulated objects defined in this specification, such asobjects associated with thecredentialSubject object or deeply nested therein,software systemsSHOULD use thetype information specified in encapsulatingobjects higher in the hierarchy. Specifically, an encapsulating object, such asacredential,SHOULD convey the associated objecttypes so thatverifiers can quickly determine the contents of an associated object basedon the encapsulating objecttype.
For example, acredential object with thetype ofExampleDegreeCredential, signals to averifier that theobject associated with thecredentialSubject property contains theidentifier for the:
This enables implementers to rely on values associated with thetype propertyforverification. Object types and their associated values areexpected to be documented in at least a human-readable specification that canbe found at theURL for the type. For example, the human-readabledefinition for theBitstringStatusList type can be found athttps://www.w3.org/ns/credentials/status/#BitstringStatusList. It is alsosuggested that amachine-readable version be provided through HTTP content negotiation atthe same URL.
Note: See the Implementation Guide for creating new credential types
When displaying acredential, it can be helpful to havetext provided by theissuer that furnishes thecredential with a name and a short description of itspurpose. Thename anddescriptionpropertiesserve these purposes.
name
AnOPTIONAL property that expresses the name of thecredential. Ifpresent, the value of thenamepropertyMUST be a string ora language value object as described in11.1Language and Base Direction. Ideally, the name of acredential is concise, human-readable, and could enable an individual toquickly differentiate onecredential from any othercredentialsthey might hold.
description
AnOPTIONAL property that conveys specific details about acredential. Ifpresent, the value of thedescriptionpropertyMUST be astring or a language value object as described in11.1Language and Base Direction. Ideally, the description of acredential is no more than a few sentences in length and conveys enoughinformation about thecredential to remind an individual of its contentswithout having to look through the entirety of theclaims.
Example 5: Use of the name and description properties
{ "@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": "https://university.example/issuers/565049", "name": "Example University", "description": "A public university focusing on teaching examples." }, "validFrom": "2015-05-10T12:30:00Z", "name": "Example University Degree", "description": "2015 Bachelor of Science and Arts Degree", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts" } }}
application/vc
{ "@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": "https://university.example/issuers/565049", "name": "Example University", "description": "A public university focusing on teaching examples." }, "validFrom": "2015-05-10T12:30:00Z", "name": "Example University Degree", "description": "2015 Bachelor of Science and Arts Degree", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts" } }, "proof": { "type": "DataIntegrityProof", "created": "2025-04-27T17:58:33Z", "verificationMethod": "did:key:zDnaebSRtPnW6YCpxAhR5JPxJqt9UunCsBPhLEtUokUvp87nQ", "cryptosuite": "ecdsa-rdfc-2019", "proofPurpose": "assertionMethod", "proofValue": "z2LeuoNi3yR1b6c3fkRsEvXJ5ex8X4RdutyK7L6HAo2bJQwr21w85Y5KWy3DptXR8ke52Assqik6wKTy9DKqkEZ2r" }}
application/vc
{ "@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": "https://university.example/issuers/565049", "name": "Example University", "description": "A public university focusing on teaching examples." }, "validFrom": "2015-05-10T12:30:00Z", "name": "Example University Degree", "description": "2015 Bachelor of Science and Arts Degree", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts" } }, "proof": { "type": "DataIntegrityProof", "created": "2025-04-27T17:58:33Z", "verificationMethod": "did:key:zDnaerJh8WwyBVVGcZKKkqRKK9iezje8ut6t9bnNChtxcWwNv", "cryptosuite": "ecdsa-sd-2023", "proofPurpose": "assertionMethod", "proofValue": "u2V0AhVhA5A-VvZ6RF2KlLjsYsx1DosYuzhbD7hn6N6gTF5yv22oTPKcqHyElGQn3TcerwktEbNrRiuWMvmfuw1XmwhCk-lgjgCQCHC44msX1XnfID2VfkUX1j1PHUzfjdORSePcGUhVB3KxYIBeo1lJt0Rp-So7_Ch6hiCE36oR-r6WyVaT6r-o0Nf1nh1hATMKDPXogkIVw6n-pqlDoJMti8cCVJvle_IWSAqv5vShtqt5E6NEJ3PTiK7NwSMSGMVE0XdJXZlEj3xck6UL0vlhAa7ltjeSjPD1TD52OkPPjuQrhADwoTsDXERr-UCuNICq-uxKiFsxebXjys1SeHIFzT0TQA5TlTl-J55vFL90q-lhAi8EKNrgQiKdl_EAlgv3aS15FLuIpUmfROB6srPRpHI4cz-kC8xlarcp9XMqHIpL5hncUJd2EoGTmMpm3nzs3PVhAr4sC2Lin-35yxMSvWXrq7cEGw4IomJnayfWsxmXencGOmXQzZxJbsUHmLCAprm51apFj19BZED6G-82Ilx0ZvlhADRiBGvSKeF3hYkihvS7kkZDnySRU4Q4yfNm_Hwe6kysHhtP5rnbu3LYfU-hI_0P6FbZJrPQ7uifIMg2QMHxARFhAxjQMayCxmcOVGlo5ICU5zQxx6qTgjgpNl1GC1dGjnA1J3xhFALceL5DHxJbSvcRsRVwRjBybMkZurUWhPgzpwVhAhbwrQWJSLLhyXqFcQef_-eKnNE3F5oBq2phORFJ16m3uRU-R-vSoXJlSpyLBZrNGU7gwCHVv0b_e2ZC13MiFR4FnL2lzc3Vlcg" }}
application/vc
{ "@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": "https://university.example/issuers/565049", "name": "Example University", "description": "A public university focusing on teaching examples." }, "validFrom": "2015-05-10T12:30:00Z", "name": "Example University Degree", "description": "2015 Bachelor of Science and Arts Degree", "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": "Bachelor of Science and Arts" } }, "proof": { "type": "DataIntegrityProof", "verificationMethod": "did:key:zUC78GzFRA4TWh2mqRiKro1wwRb5KDaMJ3M1AD3qGtgEbFrwWGvWbnCzArkeTZCyzBz4Panr2hLaZxsXHiBQCwBc3fRPH6xY4u5v8ZAd3dPW1aw89Rra86CVwXr3DczANggYbMD", "cryptosuite": "bbs-2023", "proofPurpose": "assertionMethod", "proofValue": "u2V0ChVhQkS0mcHTu9KLuuY8_DlU_2lj8Su_EXxWyY0xMPZuCGQMRzah3DFaerG-CRDFWR1KBWkYUpPizkPDULYOU8XsXoC3a8_00GgHfKuoiNCLnSNBYQGd_DaMQQsoaryttl5TvxnFT-Vm4SkVx03K9qNJ4jhArXFDE8ZX70eeJX1DawHuw0sW9CBV3sa68IaRGcnZiiQpYYJVTGbTfcflzyx41E-f9kSqmf10xYzxJrGfC7b7GPY8X7VjMT__ZKSuwdH-5jak-5gkjocsHI6oxIKlLrhW1Wh5yrDCH-QC823TS8NE9VGBzIFAfUt5qazGEcJ8CxeSPxFggbCn9jbv1yUPTocre_YTgvXiebb8lJMqxhmAnw4MiFbWBZy9pc3N1ZXI" }}
Names and descriptions also support expressing content in different languages.To express a string with language andbase direction information,one can use an object that contains the@value,@language, and@directionproperties to express the text value, language tag, and base direction,respectively. See11.1Language and Base Direction for further information.
Note: @direction is not required for single-language strings
The@direction property in the examples below is not requiredfor the associated single-language strings, as their default directions are thesame as those set by the@direction value. We include the@directionproperty here for clarity of demonstration and to make copy+paste+edit deliverfunctional results. Implementers are encouraged to read the section onString Internationalizationin theJSON-LD 1.1 specification.
Example 6: Use of the name and description properties
{ "@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": "https://university.example/issuers/565049", "name": [{ "@value": "Example University", "@language": "en" }, { "@value": "Université Exemple", "@language": "fr" }, { "@value": "جامعة المثال", "@language": "ar", "@direction": "rtl" }], "description": [{ "@value": "A public university focusing on teaching examples.", "@language": "en" }, { "@value": "Une université publique axée sur l'enseignement d'exemples.", "@language": "fr" }, { "@value": ".جامعة عامة تركز على أمثلة التدريس", "@language": "ar", "@direction": "rtl" }] }, "validFrom": "2015-05-10T12:30:00Z", "name": [{ "@value": "Example University Degree", "@language": "en" }, { "@value": "Exemple de Diplôme Universitaire", "@language": "fr" }, { "@value": "مثال الشهادة الجامعية", "@language": "ar", "@direction": "rtl" }], "description": [{ "@value": "2015 Bachelor of Science and Arts Degree", "@language": "en" }, { "@value": "2015 Licence de Sciences et d'Arts", "@language": "fr" }, { "@value": "2015 بكالوريوس العلوم والآداب", "@language": "ar", "@direction": "rtl" }], "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "degree": { "type": "ExampleBachelorDegree", "name": [{ "@value": "Bachelor of Science and Arts Degree", "@language": "en" }, { "@value": "Licence de Sciences et d'Arts", "@language": "fr" }, { "@value": "بكالوريوس العلوم والآداب", "@language": "ar", "@direction": "rtl" }] } }}
The value of theissuerpropertyMUST be either aURL or an objectcontaining anidproperty whose value is aURL; in either case, theissuer selects thisURL to identify itself in a globally unambiguous way. ItisRECOMMENDED that theURL be one which, if dereferenced, results in acontrolled identifier document, as defined in theControlled Identifiers v1.0 specification,about theissuer that can be used toverify the information expressedin thecredential.
The value of theissuerproperty can also be a JWK (forexample,"https://jwk.example/keys/foo.jwk") or aDID (forexample,"did:example:abfe13f712120431c276e12ecab").
The value of thecredentialSubjectproperty is a set of objects where eachobjectMUST be thesubject of one or moreclaims, whichMUST beserialized inside thecredentialSubjectproperty. Each objectMAY alsocontain anidproperty to identify thesubject, as described inSection4.4Identifiers.
Expressing information related to multiplesubjects in averifiable credential is possible. The example below specifies twosubjects who are spouses. Note the use of array notation to associatemultiplesubjects with thecredentialSubject property.
Example 10: Specifying multiple subjects in a verifiable credential
This specification defines thevalidFromproperty to help anissuer to express the date and time when acredential becomes valid andthevalidUntilproperty to express the date and timewhen acredential ceases to be valid.
When comparing dates and times, the calculation is done "temporally",meaning that the string value is converted to a "temporal value" which existsas a point on a timeline. Temporal comparisons are then performed by checkingto see where the date and time being compared are in relation toa particular point on the timeline.
validFrom
If present, the value of thevalidFrompropertyMUST be a[XMLSCHEMA11-2]dateTimeStamp string value representing the date and time thecredential becomes valid, which could be a date and time in the future orthe past. Note that this value represents the earliest point in time at whichthe information associated with thecredentialSubjectproperty becomes valid. If avalidUntil value also exists, thevalidFrom valueMUST express a point in time that is temporally the same orearlier than the point in time expressed by thevalidUntil value.
validUntil
If present, the value of thevalidUntilpropertyMUST be a[XMLSCHEMA11-2]dateTimeStamp string value representing the date and time thecredential ceases to be valid, which could be a date and time in the pastor the future. Note that this value represents the latest point in time atwhich the information associated with thecredentialSubjectproperty is valid. If avalidFrom value also exists, thevalidUntilvalueMUST express a point in time that is temporally the same or later than thepoint in time expressed by thevalidFrom value.
Example 11: Use of the validFrom and validUntil properties
Note: Validity start period for Verifiable Credentials
IfvalidFrom andvalidUntil are not present, theverifiable credential validity period is considered validindefinitely. In such cases, theverifiable credential is assumed to bevalid from the time theverifiable credential was created.
4.10Status
This specification defines thecredentialStatusproperty fordiscovering information related to the status of averifiable credential, such as whether it is suspended or revoked.
If present, the value associated with thecredentialStatusproperty is asingle object or a set of one or more objects. The followingpropertiesare defined for every object:
id
Theidproperty isOPTIONAL. ItMAY be used to provide aunique identifier for the credential status object. If present, thenormative guidance in Section4.4IdentifiersMUST be followed.
type
Thetypeproperty isREQUIRED. It is used to express thetype of status information expressed by the object. The related normativeguidance in Section4.5TypesMUST be followed.
The precise content of thecredential status information is determined bythe specificcredentialStatustype definition and variesdepending on factors such as whether it is simple to implement or if it isprivacy-enhancing. The value will provide enough information to determine thecurrent status of thecredential and whether machine-readable information willbe retrievable from the URL. For example, the object could contain a link to anexternal document that notes whether thecredential is suspended or revoked.
Implementers are cautioned thatcredentials with multiple status entriesmight contain conflicting information. Reconciling such conflicts is a part ofthevalidation process, hence part of the verifier's business logic, andtherefore out of scope for this specification.
Defining the data model, formats, and protocols for status schemes is out of thescope of this specification. TheVerifiable Credential Extensions document containsavailable status schemes for implementers who want to implementverifiable credential status checking.
Credential status specificationsMUST NOT enable tracking of individuals, suchas anissuer being notified (either directly or indirectly) when averifier is interested in a specificholder orsubject. Unacceptableapproaches include "phoning home," such that every use of a credential contactstheissuer of the credential to check the status for a specific individual,or "pseudonymity reduction," such that every use of the credential causes arequest for information from theissuer that theissuer can useto deduceverifier interest in a specific individual.
4.11Data Schemas
Data schemas are useful when enforcing a specific structure on a givendata collection. There are at least two types of data schemas that thisspecification considers:
Data verification schemas, which are used to establish that the structureand contents of acredential orverifiable credential conform to apublished schema.
Data encoding schemas, which are used to map the contents of averifiable credential to an alternative representation format, such as aformat used in a zero-knowledge proof.
It is important to understand that data schemas serve a different purpose fromthe@context property, which neither enforces data structure ordata syntax nor enables the definition of arbitrary encodings to alternaterepresentation formats.
This specification defines the followingproperty for expressing adata schema, which anissuer can include in theverifiable credentialsthat it issues:
credentialSchema
The value of thecredentialSchemapropertyMUST be one ormore data schemas that provideverifiers with enough information todetermine whether the provided data conforms to the provided schema(s). EachcredentialSchemaMUST specify itstype (for example,JsonSchema) and anidpropertythatMUST be aURL identifying the schema file. The specific typedefinition determines the precise contents of each data schema.
If multiple schemas are present, validity is determined according to theprocessing rules outlined by each associatedtype property.
Note: Credential type-specific syntax checking is possible
ThecredentialSchemaproperty allows one toannotate type definitions or lock them to specific versions of the vocabulary.Authors ofverifiable credentials can include a static version of theirvocabulary usingcredentialSchema that is secured by some contentintegrity protection mechanism. ThecredentialSchemaproperty also makes it possible to perform syntactic checking on thecredential and to useverification mechanisms such as JSON Schema[VC-JSON-SCHEMA] validation.
Example 14: Using the credentialSchema property to perform JSON schema validation
In the example above, theissuer is specifying twocredentialSchemaobjects, each of which point to a JSON Schema [VC-JSON-SCHEMA] file that averifier can use to determine whether theverifiable credential iswell-formed.
4.12Securing Mechanisms
This specification recognizes two classes ofsecuring mechanisms:those that use enveloping proofs and those that use embedded proofs.
These two classes of securing mechanisms are not mutually exclusive. Additionalsecuring mechanism specifications might also be defined according to the rulesin Section5.13Securing Mechanism Specifications.
Example 15: A verifiable credential using an embedded proof
Theembedded proof above secures the originalcredential by decoratingthe original data with a digital signature via theproof property. Thisresults in averifiable credential that is easy to manage in modernprogramming environments and database systems.
Example 16: A verifiable credential that uses an enveloping proof in SD-JWT format
Theenveloping proof above secures the originalcredential byencapsulating the original data in a digital signature envelope, resulting in averifiable credential that can be processed using tooling that understandsthe SD-JWT format.
Verifiable presentationsSHOULD be extremely short-lived and bound to achallenge provided by averifier. Details for accomplishing this dependon the securing mechanism, the transport protocol, andverifier policies.Unless additional requirements are defined by the particular securing mechanismor embedding protocol, averifier cannot generally assume that theverifiable presentation correlates with the presentedverifiable credentials.
ThetypepropertyMUST be present. It is used to express thetype ofverifiable presentation. One value of this propertyMUST beVerifiablePresentation, but additional typesMAY be included. Therelated normative guidance in Section4.5TypesMUST be followed.
Theverifiable presentationMAY include aholderproperty. If present, the valueMUST be either aURL or an objectcontaining anidproperty. It isRECOMMENDED that theURL in theholder or itsid be one which, ifdereferenced, results in a document containing machine-readable informationabout theholder that can be used toverify the informationexpressed in theverifiable presentation.If theholderproperty is absent, information about theholder is obtained either via the securing mechanism ordoes not pertain to thevalidation of theverifiable presentation.
It is possible that an implementer might want to process the object described inthis section and the enveloped presentation expressed by theid value in anRDF environment and create linkages between the objects that are relevant toRDF. The desire and mechanisms for doing so are use case dependent and will,thus, be implementation dependent.
Some zero-knowledge cryptography schemes might enableholders toindirectly prove they holdclaims from averifiable credentialwithout revealing all claims in thatverifiable credential. In theseschemes, averifiable credential might be used to derive presentabledata, which is cryptographically asserted such that averifier can trustthe value if they trust theissuer.
Example 21: A verifiable presentation, secured with an embedded Data Integrity proof, with a self-asserted verifiable credential about 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", "https://www.w3.org/ns/credentials/examples/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": {... } }], "proof": {... }}
Acredential is transmitted in a way that clearly establishes that theissuer generated thecredential, and that thecredential was nottampered with in transit nor storage. This expectation could be weakened,depending on the risk assessment by theverifier.
Allentities expect theverifiable data registry to be tamper-evidentand to be a correct record of which data is controlled by whichentities.This is typically achieved by the method of its publication. This could be via apeer-to-peer protocol from a trusted publisher, a publicly accessible and wellknown web site (with a content hash), a blockchain, etc. When entities publishmetadata about themselves, the publication can be integrity-protected by beingsecured using with the entity's private key.
Theholder might trust theissuer'sclaims because theholderhas a pre-existing trust relationship with theissuer. For example, anemployer might provide an employee with an employmentverifiable credential,or a government might issue an electronic passport to a citizen.
Where no pre-existing trust relationship exists, theholder mighthave some out-of-band means of determining whether theissuer isqualified to issue theverifiable credential being provided.
Note: It is not always necessary for theholder to trust theissuer,since the issuedverifiable credential might be an assertion aboutasubject who is not theholder, or about no-one, and theholdermight be willing to relay this information to averifier withoutbeing held accountable for its veracity.
By decoupling the expectations between theissuer and theverifier,a more flexible and dynamic trust model is created, such that marketcompetition and customer choice is increased.
Note: Trust model differs from the traditional Certificate Authority system
The data model detailed in this specification does not imply a transitive trustmodel, such as that provided by more traditional Certificate Authority trustmodels. In the Verifiable Credentials Data Model, averifier eitherdirectly trusts or does not trust anissuer. While it is possible tobuild transitive trust models using the Verifiable Credentials Data Model,implementers are urged tolearnabout the security weaknesses introduced bybroadly delegating trust in the manner adopted by Certificate Authoritysystems.
5.2Extensibility
One of the goals of the Verifiable Credentials Data Model is to enablepermissionless innovation. To achieve this, the data model needs to beextensible in a number of different ways. The data model is required to:
Model complex multi-entity relationships through the use of agraph-baseddata model.
Extend the machine-readable vocabularies used to describe information in thedata model, without the use of a centralized system for doing so, through theuse of Linked Data [LINKED-DATA].
Provide all of the extensibility mechanisms outlined above in a data format thatis popular with software developers and web page authors, and is enabled throughthe use ofJSON-LD 1.1.
This approach to data modeling is often called anopen world assumption, meaning that any entity can say anything aboutany other entity. While this approach seems to conflict with building simple andpredictable software systems, balancing extensibility with program correctnessis always more challenging with an open world assumption than with closedsoftware systems.
The rest of this section describes, through a series of examples, how bothextensibility and program correctness are achieved.
Let us assume we start with thecredential shown below.
Thisverifiable credential states that theentity associated withdid:example:abcdef1234567 has aname with a value ofJane Doe.
Now let us assume a developer wants to extend theverifiable credentialto store two additional pieces of information: an internal corporate referencenumber, and Jane's favorite food.
The first thing to do is to create a JSON-LD context containing two new terms,as shown below.
After this JSON-LD context is created, the developer publishes it somewhere soit is accessible toverifiers who will be processing theverifiable credential. Assuming the above JSON-LD context is published athttps://extension.example/my-contexts/v1, we can extend thisexample by including the context and adding the newproperties andcredentialtype to theverifiable credential.
Example 24: A verifiable credential with a custom extension
This example demonstrates extending the Verifiable Credentials Data Model in apermissionless and decentralized way. The mechanism shown also ensures thatverifiable credentials created in this way provide a way to preventnamespace conflicts and semantic ambiguity.
A dynamic extensibility model such as this does increase the implementationburden. Software written for such a system has to determine whetherverifiable credentials with extensions are acceptable based on the riskprofile of the application. Some applications might accept only certainextensions while highly secure environments might not accept any extensions.These decisions are up to the developers of these applications and arespecifically not the domain of this specification.
Extension specification authors are urged to ensure that their documents, suchas JSON-LD Contexts, are highly available. Developers using these documentsmight use software that produces errors when these documents cannot beretrieved. Strategies for ensuring that extension JSON-LD contexts are alwaysavailable include bundling these documents with implementations, contentdistribution networks with long caching timeframes, or usingcontent-addressed URLs for contexts. These approaches are covered in furtherdetail in AppendixB.Contexts, Vocabularies, Types, and Credential Schemas.
Whenever possible, it isRECOMMENDED to re-use terms — and their correspondingURLs — defined by well-known, public vocabularies, such asSchema.org.
New termsMUSTdefine a new URL for each term. When doing so, thegeneral guidelines for [LINKED-DATA] are expected to be followed, inparticular:
Human-readable documentationMUST be published, describing the semantics of andthe constraints on the use of each term.
It isRECOMMENDED to also publish the collection of all new terms as amachine-readable vocabulary usingRDF Schema 1.1.
ItSHOULD be possible to dereference the URL of a term, resulting in itsdescription and/or formal definition.
Furthermore, a machine-readable description (that is, aJSON-LD Context document)MUST bepublished at the URL specified in the@contextproperty for thevocabulary. This contextMUST map each term to its corresponding URL, possiblyaccompanied by further constraints like the type of the property value. Ahuman-readable document describing the expected order of values for the@contextproperty is also expected to be published by any implementerseeking interoperability.
Note: Term redefinition is not allowed
When processing theactivecontext defined by the base JSON-LD Context documentdefined in this specification, compliant JSON-LD-basedprocessors produce an error when a JSON-LD contextredefines any term.The only way to change the definition of existing terms is to introduce a newterm that clears the active context within the scope of that new term. Authorsthat are interested in this feature should read about the@protectedkeyword in the JSON-LD 1.1 specification.
Aconforming documentSHOULD NOT use the@vocab feature in productionas it can lead to JSON term clashes, resulting in semantic ambiguities withother applications. Instead, to achieve proper interoperability, aconforming documentSHOULD use JSON-LD Contexts that define all terms used by theirapplications, as described earlier in Section5.2Extensibility. If aconforming document does not use JSON-LD Contexts that define all termsused, itMUST include thehttps://www.w3.org/ns/credentials/undefined-terms/v2as the last value in the@context property.
5.3Integrity of Related Resources
When including a link to an external resource in averifiable credential, itis desirable to know whether the resource has been modified since theverifiable credential was issued. This applies to cases where there is anexternal resource that is remotely retrieved, as well as to cases where theissuer and/orverifier might have locally cached copies of a resource.It can also be desirable to know that the contents of the JSON-LD context(s)used in theverifiable credential are the same when used by theverifieras they were when used by theissuer.
To extend integrity protection to a related resource, anissuer of averifiable credentialMAY include therelatedResource property:
relatedResource
The value of therelatedResource propertyMUST be one or more objects of thefollowing form:
Property
Description
id
The identifier for the resource isREQUIRED and conforms to the format definedin Section4.4Identifiers. The valueMUST be unique among the list ofrelated resource objects.
mediaType
AnOPTIONAL valid media type as listed in theIANA Media Types registry.
Each object associated withrelatedResourceMUST contain at least adigestSRI or adigestMultibase value.
If amediaType is listed, implementations that retrieve the resourceidentified by theid property usingHTTP SemanticsSHOULD:
use the media type in theAccept HTTP Header, and
reject the response if it includes aContent-Type HTTP Header with a differentmedia type.
Any object in theverifiable credential that contains anidpropertyMAY be annotated with integrity information by adding either thedigestSRI ordigestMultibase property, either of whichMAY beaccompanied by the additionally optionalmediaType property.
Any objects for which selective disclosure or unlinkable disclosure is desiredSHOULD NOT be included as an object in therelatedResource array.
Aconforming verifier implementation that makes use of a resource based ontheid of arelatedResource object inside aconforming document with acorresponding cryptographic digest appearing in arelatedResource object valueMUST compute the digest of the retrieved resource. If the digest provided by theissuer does not match the digest computed for the retrieved resource, theconforming verifier implementationMUST produce an error.
Implementers are urged to consult appropriate sources, such as theFIPS 180-4 Secure Hash Standard and theCommercial National Security Algorithm Suite 2.0 to ensure that they arechoosing a current and reliable hash algorithm. At the time of this writingsha384SHOULD be considered the minimum strength hash algorithm for use byimplementers.
An example of a related resource integrity object referencing JSON-LD contexts.
Example 25: Use of the digestSRI property (base64-encoded SHA2-384)
It is useful for systems to enable the manual or automatic refresh of an expiredverifiable credential. For more information about validity periods forverifiable credentials, see SectionA.7Validity Periods.This specification defines arefreshServiceproperty, whichenables anissuer to include a link to a refresh service.
The refresh service is only expected to be used when either thecredential has expired or theissuer does not publishcredential status information.Issuers are advised not to put therefreshServiceproperty in averifiable credentialthat does not contain public information or whose refresh service is notprotected in some way.
refreshService
The value of therefreshServicepropertyMUST be one or morerefresh services that provides enough information to the recipient's softwaresuch that the recipient can refresh theverifiable credential. EachrefreshService valueMUST specify itstype. The precise content of eachrefresh service is determined by the specificrefreshServicetypedefinition.
Example 27: Use of the refreshService property by an issuer
In the example above, theissuer specifies an automaticrefreshService that can be used by POSTing theverifiable credential tothe refresh serviceurl. Note that this particular verifiable credential isnot intended to be shared with anyone except for the original issuer.
The value of thetermsOfUseproperty might be usedto tell theverifier any or all of the following, among other things:
the procedures or policies that were used in issuing theverifiable credential, by providing, for example, a pointer to a public location(to avoid "phone home" privacy issues) where these procedures or policiescan be found, or the name of the standard that defines them
the rules and policies of theissuer that apply to the presentationof thisverifiable credential to averifier, by providing,for example, a pointer to a public location (to avoid "phone home" privacyissues) where these rules or policies can be found
The value of thetermsOfUsepropertyMUST specify one ormore terms of use policies under which the creator issued thecredentialorpresentation. If the recipient (aholder orverifier) is not willing to adhere to the specified terms of use, thenthey do so on their own responsibility and might incur legal liability if theyviolate the stated terms of use. EachtermsOfUse valueMUST specifyitstype, for example,TrustFrameworkPolicy, andMAY specify itsinstanceid. The precise contents of each term of use is determinedby the specifictermsOfUsetype definition.
Example 28: Use of the termsOfUse property by an issuer
In the example above, theissuer is asserting that the legal basisunder which theverifiable credential has been issued is the"professional qualifications directive" using the "Employment&Life" trustframework, with a specific link to the policy.
This feature is expected to be used by government-issuedverifiable credentials to instruct digital wallets to limit their use to similargovernment organizations in an attempt to protect citizens from unexpected useof sensitive data. Similarly, someverifiable credentials issued by privateindustry are expected to limit use to within departments inside theorganization, or during business hours. Implementers are urged to read moreabout this evolving feature in the appropriate section of the VerifiableCredentials Implementation Guidelines [VC-IMP-GUIDE] document.
5.6Evidence
Evidence can be included by anissuer to provide theverifier withadditional supporting information in averifiable credential. This could beused by theverifier to establish the confidence with which it relies on theclaims in theverifiable credential. For example, anissuer could checkphysical documentation provided by thesubject or perform a set ofbackground checks before issuing thecredential. In certain scenarios, thisinformation is useful to theverifier when determining the risk associatedwith relying on a givencredential.
This specification defines theevidenceproperty for expressing evidenceinformation.
evidence
If present, the value of theevidencepropertyMUST be either a singleobject or a set of one or more objects. The followingproperties are definedfor every evidence object:
id
Theidproperty isOPTIONAL. ItMAY be used to provide a unique identifierfor the evidence object. If present, the normative guidance in Section4.4IdentifiersMUST be followed.
type
Thetypeproperty isREQUIRED. It is used to express the type of evidenceinformation expressed by the object. The related normative guidance in Section4.5TypesMUST be followed.
Note: See Implementation Guide for strategies for providing evidence
For information about how attachments and references tocredentials andnon-credential data might be supported by the specification, see Section5.3Integrity of Related Resources.
Example 29: Example of evidence supporting a skill achievement credential
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json" ], "id": "http://1edtech.edu/credentials/3732", "type": [ "VerifiableCredential", "OpenBadgeCredential" ], "issuer": { "id": "https://1edtech.edu/issuers/565049", "type": "Profile" }, "credentialSubject": { "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", "type": "AchievementSubject", "name": "Alice Smith", "activityEndDate": "2023-12-02T00:00:00Z", "activityStartDate": "2023-12-01T00:00:00Z", "awardedDate": "2024-01-01T00:00:00Z", "achievement": [{ "id": "urn:uuid:d46e8ef1-c647-419b-be18-5e045d1c4e64", "type": ["Achievement"], "name": "Basic Barista Training", "criteria": { "narrative": "Team members are nominated for this badge by their supervisors, after passing the Basic Barista Training course." }, "description": "This achievement certifies that the bearer is proficient in basic barista skills." }] }, "evidence": [{// url to an externally hosted evidence file/artifact "id": "https://videos.example/training/alice-espresso.mp4", "type": ["Evidence"], "name": "Talk-aloud video of double espresso preparation", "description": "This is a talk-aloud video of Alice demonstrating preparation of a double espresso drink.",// digest hash of the mp4 video file "digestMultibase": "uELq9FnJ5YLa5iAszyJ518bXcnlc5P7xp1u-5uJRDYKvc" } ]}
In theevidence example above, theissuer is asserting that they havevideo of thesubject of thecredential demonstrating the achievement.
Note: Evidence has a different purpose from securing mechanisms
Theevidenceproperty provides information that is different from andinformation to the securing mechanism used. Theevidenceproperty isused to express supporting information, such as documentary evidence, related totheverifiable credential. In contrast, the securing mechanism is used toexpress machine-verifiable mathematical proofs related to the authenticity oftheissuer and integrity of theverifiable credential. For moreinformation about securing mechanisms, see Section4.12Securing Mechanisms.
5.7Zero-Knowledge Proofs
Zero-knowledge proofs aresecuring mechanismswhich enable aholder to prove that they hold averifiable credentialcontaining a value without disclosing the actual value such as being able toprove that an individual is over the age of 25 without revealing their birthday.This data model supports being secured using zero-knowledge proofs.
Some capabilities that are compatible withverifiable credentials which aremade possible by zero-knowledge proof mechanisms include:
Not all capabilities are supported in all zero-knowledge proof mechanisms.Specific details about the capabilities and techniques provided by a particularzero knowledge proof mechanism, along with any normative requirements for usingthem withverifiable credentials, would be found in a specification forsecuringverifiable credentials with that zero-knowledge proof mechanism.For an example of such a specification, refer to theData Integrity BBS Cryptosuites v1.0.
The example above is averifiable credential where theissuer hasenabled a BBS-based unlinkable disclosure scheme to create a base proof thatcan then be used by theholder to create a derived proof that reveals onlyparticular pieces of information from the originalverifiable credential.
Example 31: Verifiable presentation using the Data Integrity BBS Cryptosuite with a derived credential and proof
Theverifiable presentation above includes averifiable credential thatcontains an unlinkable subset of the information from the previous example and aderived proof that theverifier can use to verify that the informationoriginated from the expectedissuer and is bound to this particularexchange of information.
5.8Representing Time
Implementers are urged to understand that representing and processing timevalues is not as straight-forward as it might seem and have a variety ofidiosyncrasies that are not immediately obvious nor uniformly observed indifferent regions of the world. For example:
Calendaring systems other than the Gregorian calendar are actively used byvarious regions.
When processing Daylight Saving/Summer Time, it is important to understand that1) it is not observed in all regions, 2) it does not necessarily begin or end onthe same day or at the same time of day, and 3) the amount or direction of theadjustment does not always match other similar regions.
Leap seconds might not be taken into account in all software systems, especiallyfor dates and times that precede the introduction of the leap second. Leapseconds can affect highly sensitive systems that depend on the exactmillisecond offset from the epoch. However, note that for most applications theonly moment in time that is affected is the one second period of the leap seconditself. That is, the moment after the most recent leap second can always berepresented as the first moment of the next day (for example,2023-01-01T00:00:00Z), regardless of whether the system in questionunderstands leap seconds.
These are just a few examples that illustrate that the actual time of day, aswould be seen on a clock on the wall, can exist in one region but not exist inanother region. For this reason, implementers are urged to use time valuesthat are more universal, such as values anchored to theZ time zone overvalues that are affected by Daylight Saving/Summer Time.
This specification attempts to increase the number of universally recognizedcombinations of dates and times, and reduce the potential formisinterpretation of time values, by using thedateTimeStamp construction first established by the [XMLSCHEMA11-2] specification. Inorder to reduce misinterpretations between different time zones, all time valuesexpressed inconforming documentsSHOULD be specified indateTimeStampformat, either in Universal Coordinated Time (UTC), denoted by aZ at the endof the value, or with a time zone offset relative to UTC. Time values that areincorrectly serialized without an offsetMUST be interpreted as UTC. Examples ofvalid time zone offsets relative to UTC includeZ,+01:00,-08:00, and+14:00. See the regular expression at the end of this section for a formaldefinition of all acceptable values.
Time zone definitions are occasionally changed by their governing body. Whenreplacing or issuing newverifiable credentials, implementers are advisedto ensure that changes to local time zone rules do not result in unexpected gapsin validity. For example, consider the zoneAmerica/Los_Angeles, which hasa raw offset of UTC-8 and had voted to stop observing daylight savings time inthe year 2024. A givenverifiable credential that had avalidUtilvalue of2024-07-12T12:00:00-07:00, might be re-issued to have avalidFrom value of2024-07-12T12:00:00-08:00, which would create a gap ofan hour where theverifiable credential would not be valid.
Implementers that desire to checkdateTimeStamp values for validitycan use the regular expression provided below, which is reproduced from the [XMLSCHEMA11-2] specification forconvenience. To avoid doubt, the regular expression in [XMLSCHEMA11-2] is thenormative definition. Implementers are advised that not alldateTimeStamp values that pass the regular expression below arevalid moments in time. For example, the regular expression below allows for 31days in every month, which allows for leap years, and leap seconds, as well asdays in places where they do not exist. That said, modern system libraries thatgeneratedateTimeStamp values are often error-free in theirgeneration of validdateTimeStamp values. The regularexpression shown below (minus the whitespace included here for readability),is often adequate when processing library-generated dates and times onmodern systems.
Example 32: Regular expression to detect a valid XML Schema 1.1: Part 2 dateTimeStamp
Verifiable credentials are intended as a means of reliably identifyingsubjects. While it is recognized that Role Based Access Controls (RBACs)and Attribute Based Access Controls (ABACs) rely on this identification as ameans of authorizingsubjects to access resources, this specificationdoes not provide a complete solution for RBAC or ABAC. Authorization is not anappropriate use for this specification without an accompanying authorizationframework.
The Working Group did consider authorization use cases during the creation ofthis specification and is pursuing that work as an architectural layer builton top of this specification.
5.10Reserved Extension Points
This specification reserves a number ofproperties to serve as possibleextension points. While some implementers signaled interest in these properties,their inclusion in this specification was considered to be premature. It isimportant to note that none of these properties are defined by thisspecification. Consequently, implementers are cautioned that use of theseproperties is considered experimental.
ImplementersMAY use these properties, butSHOULD expect them and/ortheir meanings to change during the process of normatively specifying them.ImplementersSHOULD NOT use these properties without a publicly disclosedspecification describing their implementation.
In order to avoid collisions regarding how the following properties are used,implementationsMUST specify atype property in the value associated with thereserved property. For more information related to addingtype information,see Section4.5Types.
Reserved Property
Description
confidenceMethod
A property used for specifying one or more methods that a verifier might use toincrease their confidence that the value of a property in or of a verifiablecredential or verifiable presentation is accurate. The associated vocabularyURLMUST behttps://www.w3.org/2018/credentials#confidenceMethod.
renderMethod
A property used for specifying one or more methods to render a credential into avisual, auditory, haptic, or other format. The associated vocabulary URLMUST behttps://www.w3.org/2018/credentials#renderMethod.
An unofficial list of specifications that are associated with the extensionpoints defined in this specification, as well as the reserved extension pointsdefined in this section, can be found in theVerifiable Credential Extensions. Items in thedirectory that refer to reserved extension pointsSHOULD be treated asexperimental.
If conceptually aligned digital credential formats can be transformed into aconforming document according to the rules provided in this section, theyare considered"compatible with theW3C Verifiable Credentialsecosystem". Specification authors are advised to adhere to the followingrules when documenting transformations that enable compatibility with theVerifiable Credentials ecosystem. The transformation specification —
MUST identify whether the transformation to this data model is one-way-only orround-trippable.
MUST preserve the@context values when performing round-trippabletransformation.
MUST result in aconforming document when transforming to the datamodel described by this specification.
MUST specify a registered media type for the input document.
SHOULD provide a test suite that demonstrates that the specified transformationalgorithm to the data model in this specification results inaconforming document.
SHOULD ensure that all semantics used in the transformedconforming document follow best practices for Linked Data. SeeSection4.1Getting Started, Section5.2Extensibility, and Linked Data Best Practices [LD-BP]for additional guidance.
Note: What constitutes a verifiable credential?
Readers are advised that a digital credential is only considered compatible withtheW3C Verifiable Credentials ecosystem if it is aconforming documentand it uses at least one securing mechanism, as described by theirrespective requirements in this specification. While some communities might callsome digital credential formats that are notconforming documents"verifiable credentials", doing so does NOT make that digital credentialcompliant to this specification.
5.12Verifiable Credential Graphs
When expressingverifiable credentials (for example in apresentation), it is important to ensure that data in oneverifiable credential is not mistaken to be the same data in anotherverifiable credential. For example, if one has twoverifiable credentials, eachcontaining an object of the following form:{"type": "Person", "name": "JaneDoe"}, it is not possible to tell if one object is describing the same personas the other object. In other words, merging data between twoverifiable credentials without confirming that they are discussing the same entitiesand/or properties, can lead to a corrupted data set.
Using thesegraphs has a concrete effect when performing JSON-LDprocessing, which properly separates graph node identifiers in one graph fromthose in another graph. Implementers that limit their inputs toapplication-specific JSON-LD documents will also need to keep this in mind ifthey merge data from oneverifiable credential with data from another,such as when thecredentialSubject.id is the same in bothverifiable credentials, but the object might contain objects of the "Jane Doe" formdescribed in the previous paragraph. It is important to not merge objects thatseem to have similar properties but do not contain anid property that uses aglobal identifier, such as a URL.
5.13Securing Mechanism Specifications
As described in Section4.12Securing Mechanisms, there aremultiple strategies that an implementer can use when securing aconforming document. In order to maximize utility and interoperability,specification authors that desire to author new ways of securingconforming documents are provided with the guidance in this section.
Securing mechanism specificationsMUST document normative algorithms thatprovide content integrity protection forconforming documents. ThealgorithmsMAY be general in nature andMAY be used to secure data other thanconforming documents.
Securing mechanism specificationsMUST provide a verification algorithm thatreturns the information in theconforming document that has been secured, inisolation, without including any securing mechanism information, such asproof orJOSE/COSE header parameters and signatures. Verification algorithmsMAY returnadditional information that might be helpful (for example, during validation orfor debugging purposes), such as details of the securing mechanism. A verificationalgorithmMUST provide an interface that receives a media type (stringinputMediaType) and input data (byte sequence ormapinputData).Securing mechanism specificationsMAY provide algorithms and interfaces inaddition to the ones specified in this document. The verification algorithmreturns a verification result with at least the followingitems:
Securing mechanism specificationsSHOULD provide integrity protection for anyinformation referenced by a URL that is critical to validation. Mechanisms thatcan achieve this protection are discussed in Section5.3Integrity of Related Resources and SectionB.1Base Context.
The securing mechanismMUST define all terms used by theproof graph. Forexample, the mechanism could define vocabulary specifications and@contextfiles in the same manner as they are used by this specification.
The data model as described in Sections3.Core Data Model,4.Basic Concepts, and5.Advanced Concepts is the canonical structuralrepresentation of averifiable credential orverifiable presentation.All syntaxes are representations of that data model in a specific format. Thissection specifies how the data model is serialized in JSON-LD forapplication/vc andapplication/vp, the base media types forverifiable credentials andverifiable presentations, respectively. Although syntacticmappings are only provided for JSON-LD, applications and services can use anyother data representation syntax (such as XML, YAML, or CBOR) that is capable ofbeing mapped back toapplication/vc orapplication/vp. As theverification andvalidation requirements are defined in terms of thedata model, all serialization syntaxes have to be deterministically translatedto the data model for processing,validation, or comparison.
The expected arity of the property values in this specification, and theresulting datatype which holds those values, can vary depending on the property.If present, the following properties are represented as a single value:id(Section4.4Identifiers),issuer (Section4.7Issuer), andvalidFrom/validUntil (Section4.9Validity Period). 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 serializeLinked Data. LinkedData is modeled using Resource Description Framework (RDF) [RDF11-CONCEPTS].RDF is a technology for modeling graphs of statements. Each statement is asinglesubject→property→value (also known asentity→attribute→value) relationship, which is referred to as aclaim in this specification. JSON-LD is a technology that enables theexpression of RDF using idiomatic JSON, enabling developers familiar with JSONto write applications that consume RDF as JSON. SeeRelationship of JSON-LD to RDFfor more details.
Notable JSON-LD Features
In general, the data model and syntax described in this document enablesdevelopers to largely treatverifiable credentials as JSON documents,allowing them to copy and paste examples, with minor modification, into theirsoftware systems. The design goal of this approach is to provide a low barrierto entry while still ensuring global interoperability between a heterogeneousset of software systems. This section describes some of the JSON-LD featuresthat are used to make this possible, which will likely go unnoticed by mostdevelopers, but whose details might be of interest to implementers. The mostnoteworthy features inJSON-LD 1.1 used by this specification include:
The@id and@type keywords are aliased toid andtype respectively, enabling developers to usethis specification as idiomatic JSON.
Data types, such as integers, dates, units of measure, and URLs, areautomatically typed to provide stronger type guarantees for use cases thatrequire them.
TheverifiableCredentialpropertyis defined as aJSON-LD 1.1 graphcontainer. This requires the creation ofnamed graphs, used to isolatesets of data asserted by different entities. This ensures, for example, propercryptographic separation between the data graph provided by eachissuerand the one provided by theholder presenting theverifiable credential to ensure the provenance of the information for each graph ispreserved.
The@protected properties feature ofJSON-LD 1.1 is used to ensure thatterms defined by this specification cannot be overridden. This means that aslong as the same@context declaration is made at the top of averifiable credential orverifiable presentation, interoperability is guaranteed forall terms understood by users of the data model whether or not they use aJSON-LD 1.1 processor.
Restrictions on JSON-LD
In order to increase interoperability, this specification restricts the use ofJSON-LD representations of the data model. JSON-LDcompacted documentformMUST be used for all representations of the data model using theapplication/vc orapplication/vp media type.
As elaborated upon in Section6.3Type-Specific Credential Processing, some software applicationsmight not perform generalized JSON-LD processing. Authors ofconforming documents are advised that interoperability might be reduced if JSON-LDkeywords in the@context value are used to globally affect values in averifiable credential orverifiable presentation, such as bysetting either or both of the@base or@vocab keywords. For example, settingthese values might trigger a failure in a mis-implemented JSON Schema test ofthe@context value in an implementation that is performingtype-specific credential processing and not expecting the@base and/or@vocab value tobe expressed in the@context value.
In-line declaration of JSON-LD keywords in the@context value that globallymodify document term and value processing, such as setting@base or@vocab
Use of JSON-LD contexts that override declarations in previous contexts, such asresetting@vocab
In-line declaration of JSON-LD contexts in the@context property
Use of full URLs for JSON-LD terms and types (for example,https://www.w3.org/2018/credentials#VerifiableCredential orhttps://vocab.example/myvocab#SomeNewType) instead of the short forms ofany such values (for example,VerifiableCredential orSomeNewType) that areexplicitly defined in JSON-LD@context mappings (for example, inhttps://www.w3.org/ns/credentials/v2)
While this specification cautions against the use of@vocab, there arelegitimate uses of the feature, such as to ease experimentation, development,and localized deployment. If an application developer wants to use@vocab inproduction, which is advised against to reduce term collisions and leverage thebenefits of semantic interoperability, they are urged to understand that any useof@vocab will disable reporting of "undefined term" errors, andlater use(s) will override any previous@vocab declaration(s). Different valuesof@vocab can change the semantics of the information contained in the document,so it is important to understand whether and how these changes will affect theapplication being developed.
Lists and Arrays
Lists, arrays, and even lists of lists, are possible when usingJSON-LD 1.1.We encourage those who want RDF semantics in use cases requiring lists andarrays to follow the guidance onlists in JSON-LD 1.1.
In general, a JSON array is ordered, while a JSON-LD array is not ordered unlessthat array uses the@list keyword.
Note: Array order might not matter
While it is possible to use this data model by performingtype-specific credential processing, those who do so and make use of arrays need to be awarethat unless the above guidance is followed, the order of items in an arrayare not guaranteed in JSON-LD. This might lead to unexpected behavior.
If JSON structure or ordering is important to your application, we recommend youmark such elements as@json via an@context that is specific to youruse case. An example of such a declaration is shown below.
Example 33: A @context file that defines a matrix as an embedded JSON data structure
When the context shown above is used in the example below, by including thehttps://website.example/matrix/v1 context in the@context property, thevalue incredentialSubject.matrix retains its JSON semantics; the exact orderof all elements in the two dimensional matrix is preserved.
Example 34: A verifiable credential with an embedded JSON data structure
Media types, as defined in [RFC6838], identify the syntax used to express averifiable credential as well as other useful processing guidelines.
Syntaxes used to express the data model in this specificationSHOULD beidentified by a media type, and conventions outlined in this sectionSHOULD befollowed when defining or using media types withverifiable credentials.
There are two media types associated with the core data model, which arelisted in the SectionC.IANA Considerations:application/vc andapplication/vp.
Theapplication/vc andapplication/vp media types do notimply any particular securing mechanism, but are intended to be used inconjunction with securing mechanisms. A securing mechanism needs to be appliedto protect the integrity of these media types. Do not assume security of contentregardless of the media type used to communicate it.
Media Type Precision
This section is non-normative.
At times, developers or systems might use lower precision media types to conveyverifiable credentials orverifiable presentations. Some of the reasonsfor use of lower precision media types include:
A web server defaults totext/plain orapplication/octet-stream when a fileextension is not available and it cannot determine the media type.
A developer adds a file extension that leads to a media type that is lessspecific than the content of the file. For example,.json could result in amedia type ofapplication/json and.jsonld might result in a media type ofapplication/ld+json.
A protocol requires a less precise media type for a particular transaction; forexample,application/json instead ofapplication/vp,
Implementers are urged to not raise errors when it is possible to determine theintended media type from a payload, provided that the media type used isacceptable in the given protocol. For example, if an application only acceptspayloads that conform to the rules associated with theapplication/vc mediatype, but the payload is tagged withapplication/json orapplication/ld+jsoninstead, the application might perform the following steps to determine whetherthe payload also conforms to the higher precision media type:
Parse the payload as a JSON document.
Ensure that the first element of the@context property matcheshttps://www.w3.org/ns/credentials/v2.
Assume anapplication/vp media type if the JSON document contains a top-leveltype property containing aVerifiablePresentation element. Additionalsubsequent checks are still expected to be performed (according to thisspecification) to ensure the payload expresses a conformantverifiable presentation.
Assume anapplication/vc media type if the JSON document contains a top-leveltype property containing aVerifiableCredential element. Additionalsubsequent checks are still expected to be performed (according to thisspecification) to ensure the payload expresses a conformantverifiable credential.
Whenever possible, implementers are advised to use the most precise (the highestprecision) media type for all payloads defined by this specification.Implementers are also advised to recognize that a payload tagged with a lowerprecision media type does not mean that the payload does not meet the rulesnecessary to tag it with a higher precision type. Similarly, a payload taggedwith a higher precision media type does not mean that the payload will meet therequirements associated with the media type. Receivers of payloads, regardlessof their associated media type, are expected to perform appropriate checks toensure that payloads conform with the requirements for their use in a givensystem.
HTTP clients and servers use media types associated withverifiable credentials andverifiable presentations in accept headers and whenindicating content types. Implementers are warned that HTTP servers might ignorethe accept header and return another content type, or return an error code suchas415 Unsupported Media Type.
6.3Type-Specific Credential Processing
This section is non-normative.
As JSON can be used to express different kinds of information, a consumer ofa particular JSON document can only properly interpret the author's intent if theypossess information that contextualizes and disambiguates it from other possibleexpressions. Information to assist with this interpretation can either be whollyexternal to the JSON document or linked from within it. Compacted JSON-LD documentsinclude a@context property that internally expresses or links tocontextual information to expressclaims. These featuresenable generalized processors to be written to convert JSON-LD documents from onecontext to another, but this is not needed when consumers receive JSON-LD documentsthat already use the context and shape that they expect. Authors of JSON-LDdocuments, such asissuers ofverifiable credentials, are requiredto provide proper JSON-LD contexts and follow these rules in order to facilitateinteroperability.
The text below helps consumers understand how to ensure a JSON-LD document isexpressed in a context and shape that their application already understandssuch that they do not need to transform it in order to consume its contents.Notably, this does not mean that consumers do not need to understand anycontext at all; rather, consuming applications only need to understand a chosenset of contexts and document shapes to work with and not others. Issuers canpublish contexts and information about theirverifiable credentials toaid consumers who do not use generalized processors, just as can be donewith any other JSON-formatted data.
General JSON-LD processing is defined as a mechanism that uses aJSON-LD software library to process aconforming document by performingvarioustransformations.Type-specific credential processing is defined as a lighter-weightmechanism for processingconforming documents, that doesn't requirea JSON-LD software library. Some consumers ofverifiable credentialsonly need to consume credentials with specific types. These consumers can usetype-specific credential processing instead of generalized processing. Scenarioswhere type-specific credential processing can be desirable include, but are notlimited to, the following:
Ensure that all values associated with a@context property are in the expectedorder, the contents of the context files match known good cryptographic hashesfor each file, and domain experts have deemed that the contents are appropriatefor the intended use case.
Using static context files with a JSON Schema is one acceptable approach toimplementing the rule above. This can ensure proper term identification,typing, and order, when performingtype-specific credential processing.
The rule above guarantees semantic interoperability between the two processingmechanisms for mapping literal JSON keys to URIs via the@context mechanism.Whilegeneral JSON-LD processing can use previously unseen@contextvalues provided in its algorithms to verify that all terms are correctlyspecified, implementations that performtype-specific credential processing only accept specific@context values which the implementationis engineered ahead of time to understand, resulting in the same semanticswithout invoking any JSON-LD APIs. In other words, the context in which the dataexchange happens is explicitly stated for both processing mechanisms by using@context in a way that leads to the sameconforming document semantics.
7.Algorithms
This section contains algorithms that can be used by implementations to performcommon operations, such asverification. Conformance requirements phrased asalgorithms use normative concepts from theInfra Standard [INFRA]. See thesection onAlgorithm Conformancein theInfra Standard for more guidance on implementation requirements.
Note: Implementers can include additional checks, warnings, and errors.
Implementers are advised that the algorithms in this section contain the bareminimum set of checks used by implementations to test conformance to thisspecification. Implementations are expected to provide additional checks thatreport helpful warnings for developers to help debug potential issues.Similarly, implementations are likely to provide additional checks thatcould result in new types of errors being reported in order to stop harmfulcontent. Any of these additional checks might be integrated into futureversions of this specification.
a controller of the verification method associated with the securing mechanism(stringcontroller)
a controlled identifier document that is associated with the verification methodused to verify the securing mechanism (mapcontrolledIdentifierDocument)
Ensure that the securing mechanism has properly protected theconforming document by performing the following steps:
Set theverifyProof function by using theinputMediaType and theSecuring Mechanismssection of theVerifiable Credential Extensions document, or other mechanisms known to theimplementation, to determine the cryptographic suite to use when verifying thesecuring mechanism. TheverifyProof functionMUST implement the interfacedescribed in5.13Securing Mechanism Specifications.
If theverifyProof function expects abyte sequence, provideinputMediaType andinputData to the algorithm. If theverifyProof functionexpects amap, provideinputMediaType and the result ofparse JSON bytes to an Infra value giveninputData. Setresult to the result of thecall to theverifyProof function. If the call was successful,result willcontain thestatus,document,mediaType,controller,controlledIdentifierDocument,warnings, anderrors properties.
Ifresult.status is set totrue, ensure thatresult.document is aconforming document. If it isnot, setresult.status tofalse, remove thedocument property fromresult, and add at leastoneMALFORMED_VALUE_ERROR toresult.errors. Other warnings and errorsMAY be includedto aid any debugging process.
Returnresult.
The steps for verifying the state of the securing mechanism and verifyingthat the input document is aconforming documentMAY be performed ina different order than that provided above as long as theimplementation returns errors for the same invalid inputs.ImplementationsMAY produce different errors than described above.
7.2Problem Details
When an implementation detects an anomaly while processing a document, aProblemDetails object can be used to report the issue to othersoftware systems. The interface for these objects follow [RFC9457]to encode the data. AProblemDetails object consists of the followingproperties:
type
ThetypepropertyMUST be present and its valueMUST be aURLidentifying the type of problem.
title
ThetitlepropertySHOULD provide a shortbut specific human-readable string for the problem.
detail
ThedetailpropertySHOULD provide alonger human-readable string for the problem.
The following problem description types are defined by this specification:
The securing mechanism for the document has detected amodification in the contents of the document since it was created;potential tampering detected. See Section7.1Verification.
The value associated with a particularproperty is malformed. Thename of theproperty and the path to the propertySHOULD be providedin theProblemDetails object. See Section7.1Verification.
https://www.w3.org/TR/vc-data-model#RANGE_ERROR
A provided value is outside of the expected range of an associated value,such as a given index value for an array being larger than the current sizeof the array.
ImplementationsMAY extend theProblemDetails object by specifyingadditional types or properties. See theExtension Member sectionin [RFC9457] for further guidance on using this mechanism.
8.Privacy Considerations
This section is non-normative.
This section details the general privacy considerations and specific privacyimplications of deploying the Verifiable Credentials Data Model into productionenvironments.
8.1Spectrum of Privacy
This section is non-normative.
It is important to recognize there is a spectrum of privacy ranging frompseudonymous to strongly identified. Depending on the use case, people havedifferent comfort levels about the information they are willing to provideand the information that can be derived from it.
Figure13Privacy spectrum ranging from pseudonymous to fully identified.
Privacy solutions are use case specific.For example, many people would prefer to remain anonymous when purchasingalcohol because the regulation is only to verify whether a purchaser isabove a specific age. In contrast, when filling prescriptions written bya medical professional for a patient, the pharmacy is legally requiredto more strongly identify both the prescriber and the patient. No singleapproach to privacy works for all use cases.
Note: Proof of age might be insufficient for some use cases
Even those who want to remain anonymous when purchasing alcohol might needto provide photo identification to appropriately assure the merchant. Themerchant might not need to know your name or any details other than thatyou are over a specific age, but in many cases, simple proof of age mightbe insufficient to meet regulations.
The Verifiable Credentials Data Model strives to support the full privacyspectrum and does not take philosophical positions on the correct level ofanonymity for any specific transaction. The following sections will guideimplementers who want to avoid specific scenarios that are hostile toprivacy.
8.2Software Trust Boundaries
This section is non-normative.
A variety of trust relationships exist in theecosystem described by this specification. Anindividual using a web browser trusts the web browser, also known as auser agent, to preservethat trust by not uploading their personal information to a data broker;similarly, entities filling the roles in the ecosystem described by thisspecification trust the software that operates on behalf of each of those roles.Examples include the following:
Anissuer'suser agent(issuer software), such as an online education platform, is expected toissueverifiable credentials only to individuals that the issuer assertshave completed their educational program.
Aholder'suser agent(holder software), such as a digital wallet, is expected to only divulgeinformation to averifier when theholder consents toreleasing that information.
The examples above are not exhaustive, and the users in these roles can alsoexpect various other things from the software they use to achieve theirgoals. In short, the user expects the software to operate in the user's bestinterests; any violations of this expectation breach trust and can lead to thesoftware's replacement with a more trustworthy alternative. Implementers arestrongly encouraged to create software that preserves user trust. Additionally,they are encouraged to include auditing features that enable users or trustedthird parties to verify that the software is operating in alignment with theirbest interests.
Readers are advised that some software, like a website providing servicesto a singleverifier and multipleholders, might operate as auser agent to bothroles but might not always be able to operate simultaneously in the bestinterests of all parties. For example, suppose a website detects an attempt atfraudulentverifiable credential use among multipleholders. In thatcase, it might report such an anomaly to theverifier, which might beconsidered not to be in allholders' best interest, but would be in thebest interest of theverifier and anyholdersnot committingsuch a violation. It is imperative that when software operates in this manner,it is made clear in whose best interest(s) the software is operating, throughmechanisms such as a website use policy.
8.3Personally Identifiable Information
This section is non-normative.
Data associated withverifiable credentials stored in thecredential.credentialSubject property is susceptible to privacy violationswhen shared withverifiers. Personally identifying data, such as agovernment-issued identifier, shipping address, or full name, can be easilyused to determine, track, and correlate anentity. Even information thatdoes not seem personally identifiable, such as the combination of abirthdate and a postal code, has powerful correlation and de-anonymizationcapabilities.
Implementers of software used byholders are strongly advised to warnholders when they share data with these kinds of characteristics.Issuers are strongly advised to provide privacy-protectingverifiable credentials when possible — for example, by issuingageOververifiable credentials instead ofdateOfBirthverifiable credentials for use when averifier wants to determine whether anentity is at least 18 years of age.
Because averifiable credential often contains personally identifiableinformation (PII), implementers are strongly advised to use mechanisms whilestoring and transportingverifiable credentials that protect the data fromthose who ought not have access to it. Mechanisms that could be considered includeTransport Layer Security (TLS) or other means of encrypting the data while intransit, as well as encryption or access control mechanisms to protectthe data in averifiable credential when at rest.
Generally, individuals are advised to assume that averifiable credential,like most physical credentials, will leak personally identifiable informationwhen shared. To combat such leakage,verifiable credentials and theirsecuring mechanisms need to be carefully designed to prevent correlation.Verifiable credentials specifically designed to protect against leakageof personally identifiable information are available. Individuals andimplementers are encouraged to choose these credential types over those notdesigned to protect personally identifiable information.
8.4Identifier-Based Correlation
This section is non-normative.
Verifiable credentials might contain long-lived identifiers that could beused to correlate individuals. These identifiers includesubjectidentifiers, email addresses, government-issued identifiers, organization-issuedidentifiers, addresses, healthcare vitals, and many other long-livedidentifiers. Implementers of software forholders are encouraged todetect identifiers inverifiable credentials that could be usedto correlate individuals and to warnholders before they share thisinformation. The rest of this section elaborates on guidance related tousing long-lived identifiers.
Subjects ofverifiable credentials are identified using theidproperty, as defined in Section4.4Identifiers and used in places suchas thecredentialSubject.id property. The identifiers used to identify asubject create a greater correlation risk when the identifiers arelong-lived or used across more than one web domain. Other types of identifiersthat fall into this category are email addresses, government-issued identifiers,and organization-issued identifiers.
Securing mechanism specification authors are advised to avoid enablingidentifier-based correlation by designing their technologies to avoid the useof correlating identifiers that cannot be selectively disclosed.
If strong anti-correlation properties are required in averifiable credentials system, it is essential that identifiers meet one or moreof the following criteria:
Selectively disclosable
Bound to a single origin
Single-use
Not used and instead replaced by short-lived, single-use bearer tokens.
8.5Signature-Based Correlation
This section is non-normative.
The contents of averifiable credential are secured using asecuring mechanism. Values representing the securing mechanism pose a greaterrisk of correlation when they remain the same across multiple sessionsor domains. Examples of these include the following values:
the binary value of the digital signature
timestamp information associated with the creation of the digital signature
cryptographic material associated with the digital signature, such asa public key identifier
Different extension points, such as those described in Section4.Basic Concepts and Section5.Advanced Concepts, canunintentionally or undesirably serve as a correlation mechanism, if relativelyfewissuers use a specific extension type or combination of types.For example, using certain cryptographic methods unique to particularnation-states, revocation formats specific to certain jurisdictions,or credential types employed by specific localities, can serve as mechanismsthat reduce the pseudonymity aholder might expect when selectivelydisclosing information to averifier.
Issuers are encouraged to minimize metadata-based correlation risks whenissuingverifiable credentials intended for pseudonymous use by limitingthe types of extensions that could reduce theholder's pseudonymity.Credential types, extensions, and technology profiles with global adoption aremost preferable, followed by those with national use; those with only localuse are least preferable.
8.7Device Tracking and Fingerprinting
This section is non-normative.
There are mechanisms external toverifiable credentials thattrack and correlate individuals on the Internet and the Web. Thesemechanisms include Internet protocol (IP) address tracking, web browserfingerprinting, evercookies, advertising network trackers, mobile networkposition information, and in-application Global Positioning System (GPS) APIs.Usingverifiable credentials cannot prevent the use of these othertracking technologies; rather, using these technologies alongsideverifiable credentials can reveal new correlatable information. Forinstance, a birthdate combined with a GPS position can strongly correlatean individual across multiple websites.
Privacy-respecting systems ought to aim to prevent the combination of othertracking technologies withverifiable credentials. In some instances,tracking technologies might need to be disabled on devices thattransmitverifiable credentials on behalf of aholder.
The Oblivious HTTP protocol [RFC9458] is one mechanism implementersmight consider using when fetching external resources associated with averifiable credential or averifiable presentation.Oblivious HTTP allows a client to make multiple requests to an origin serverwithout that server being able to link those requests to that client or even toidentify those requests as having come from a single client, while placing onlylimited trust in the nodes used to forward the messages. Oblivious HTTPis one privacy-preserving mechanism that can reduce the possibilityof device tracking and fingerprinting. Below are some concrete examples ofways that Oblivious HTTP can benefit ecosystem participants.
Aholder using a digital wallet can reduce the chances that theywill be tracked by a 3rd party when accessing external links within averifiable credential stored in their digital wallet.For example, a digital wallet might fetch and render linked images, orit might check the validity of averifiable credential by fetchingan externally linked revocation list.
Issuers are encouraged to limit the information included in averifiable credential to the smallest set required for the intended purposes, so as toallow recipients to use them in various situations without disclosing morepersonally identifiable information (PII) than necessary. One way to avoidplacing PII in averifiable credential is to use an abstractpropertythat meets the needs ofverifiers without providing overly specificinformation about asubject.
For example, this document uses theageOverpropertyinstead of a specific birthdate, which would represent more sensitive PII. Ifretailers in a particular market commonly require purchasers to be older thana certain age, anissuer trusted in that market might choose to offerverifiable credentials that claim thatsubjects have met thatrequirement rather than offeringverifiable credentials that containclaims about the customers' birthdays. This practice enables individualcustomers to make purchases without disclosing more PII than necessary.
8.9The Principle of Data Minimization
This section is non-normative.
Privacy violations occur when information divulged in one context leaks intoanother. One accepted best practice for preventing such a violation is forverifiers to limit the information requested and received, to the absoluteminimum necessary for a particular transaction. Regulations in multiplejurisdictions, including the Health Insurance Portability and AccountabilityAct (HIPAA) in the United States and the General Data Protection Regulation(GDPR) in the European Union, mandate this data minimization approach.
Withverifiable credentials, data minimization forissuers meanslimiting the content of averifiable credential to the minimum required bypotentialverifiers for expected use. Forverifiers, data minimizationmeans restricting the scope of information requested or required foraccessing services.
For example, a driver's license containing a driver's ID number, height, weight,birthday, and home address expressed as averifiable credential containsmore information than is necessary to establish that the person is above acertain age.
It is considered best practice forissuers to atomize information or use asecuring mechanism that allows forselective disclosure. For example, anissuer of driver's licenses could issue averifiable credentialcontaining every property that appears on a driver's license, and allow theholder to disclose each property selectively. It could also issue moreabstractverifiable credentials (for example, averifiable credentialcontaining only anageOver property). One possible adaptation would be forissuers to provide secure HTTP endpoints for retrieving single-usebearer credentials that promote the pseudonymous use ofverifiable credentials.Implementers that find this impractical or unsafe might consider usingselective disclosure schemes that eliminate dependence onissuers atproving time and reduce the risk of temporal correlation byissuers.
Verifiers are urged to only request information that is strictly necessaryfor a specific transaction to occur. This is important for at leasttwo reasons:
It reduces the liability on theverifier for handling highly sensitiveinformation that it does not need to handle.
It enhances thesubject's and/orholder's privacy by only asking forinformation that is necessary for a specific transaction.
Implementers of software used byholders are encouraged to disclose theinformation being requested by averifier, allowing theholder todecline to share specific information that is unnecessary for thetransaction. Implementers of software used byholders are also advisedto giveholders access to logs of information shared withverifiers,enabling theholders to provide this information to authorities if theybelieve that they have been subjected to information overreach or coerced toshare more information than necessary for a particular transaction.
Note: Minimum disclosure can still lead to unique identification
While it is possible to practice the principle of minimum disclosure, it mightbe impossible to avoid the strong identification of an individual forspecific use cases during a single session or over multiple sessions. Theauthors of this document cannot stress how difficult it is to meet thisprinciple in real-world scenarios.
8.10Bearer Credentials
This section is non-normative.
Abearer credential is aprivacy-enhancing piece of information, such as a concert ticket, that entitlesitsholder to a specific resource without requiring theholder todivulge sensitive information. In low-risk scenarios, entities often use bearercredentials where multipleholders presenting the sameverifiable credentialis not a concern or would not result in large economic or reputational losses.
Whilebearer credentials are privacy-enhancing,issuers still need totake care in their design to avoid unintentionally divulging more informationthan theholder of thebearer credential expects. For example,repeated use of the samebearer credential across multiple sites canenable these sites to collude in illicitly tracking or correlating theholder. Similarly, information that might seem non-identifying, such asa birthdate and postal code, can be used together to statistically identifyan individual when used inthe samebearer credential or session.
Do not contain personally identifying information.
Are not unduly correlatable.
Holders ought to be warned by their software if it detects thatbearer credentialscontaining sensitive information have been issued or requested, or that acorrelation risk is posed by the combination of two or morebearer credentials across oneor more sessions. While detecting all correlation risks might be impossible,some might certainly be detectable.
When processingverifiable credentials,verifiersevaluate relevantclaims before relying upon them. Thisevaluation might be done in any manner desired as long as it satisfiesthe requirements of theverifier doing the validation.Many verifiers will perform the checks listed in AppendixA.Validation aswell as a variety of specific business process checks such as:
If a relationship exists between theholder and theentitywith whom theholder is attempting to interact.
The geolocation information associated with theholder.
The process of performing these checks might result in information leakage thatleads to a privacy violation of theholder. For example, a simpleoperation, such as checking an improperly configured revocation list, cannotify theissuer that a specific business is likely interactingwith theholder. This couldenableissuers to collude to correlate individuals without theirknowledge.
Issuers are urged to not use mechanisms, such ascredentialrevocation lists that are unique percredential, during theverification process, which could lead to privacy violations. Organizationsproviding software toholders ought to warn whencredentials includeinformation that could lead to privacy violations during the verificationprocess.Verifiers are urged to consider rejectingcredentials thatproduce privacy violations or that enable substandard privacy practices.
8.12Storage Providers and Data Mining
This section is non-normative.
When aholder receives averifiable credential from anissuer, theverifiable credential needs to be stored somewhere(for example, in acredential repository).Holders need to be awarethat the information in averifiable credential can be sensitive and highlyindividualized, making it a prime target for data mining. Services offering"free of charge" storage ofverifiable credentials might mine personal dataand sell it to organizations interesting in building individualized profileson people and organizations.
Holders need to be aware of the terms of service for theircredential repository, specifically the correlation and data miningprotections in place for those who store theirverifiable credentialswith the service provider.
Some effective mitigations for data mining and profiling include using:
Service providers that do not sell your information to third parties.
Software that storesverifiable credentials locally on a device that youcontrol and that does not upload or analyze your information beyond yourexpectations.
In addition to the mitigations above, civil society and regulatoryparticipation in vendor analysis and auditing can help ensure that legalprotections are enacted and enforced for individuals affected by practicesthat are not aligned with their best interests.
8.13Aggregation of Credentials
This section is non-normative.
Having two pieces of information about the samesubject often revealsmore about thesubject than the combination of those two pieces, evenwhen the pieces are delivered through different channels. Aggregatingverifiable credentials poses a privacy risk, and all participants inthe ecosystem need to be aware of the risks of data aggregation.
For example, suppose twobearer credentials, one for an email address andone stating theholder is over 21, are provided to the sameverifieracross multiple sessions. Theverifier of the information now has a uniqueidentifier (the email address) along with age-related ("over 21") informationfor that individual. It is now easy to create a profile for theholder,building it by adding more and more information as it leaks over time.Aggregation of suchcredentials can also be performed by multiple sitesin collusion with each other, leading to privacy violations.
From a technological perspective, preventing information aggregation is achallenging privacy problem. While new cryptographic techniques, such aszero-knowledge proofs, are being proposed as solutions to aggregation andcorrelation issues, the existence of long-lived identifiers andbrowser-tracking techniques defeats even the most modern cryptographictechniques.
The solution to the privacy implications of correlation or aggregation tendsnot to be technological in nature, but policy-driven instead. Therefore, if aholder wishes to avoid the aggregation of their information, they need toexpress this in theverifiable presentations they transmit, andby theholders andverifiers to whom they transmit theirverifiable presentations.
8.14Patterns of Use
This section is non-normative.
Despite best efforts by all involved to assure privacy, usingverifiable credentials can potentially lead to de-anonymization and aloss of privacy. This correlation can occur when any of the following occurs:
The sameverifiable credential is presented to differentverifiers, and either thoseverifiers collude, or a third partyhas access to transaction records from bothverifiers. An observantparty could infer that the individual presenting theverifiable credential is the same person at both services. That is, thesame person controls both accounts.
The underlying information in acredential can be used to identify anindividual across services. In this case, using information from other sources(including information provided directly by theholder),verifierscan use information inside thecredential to correlate the individualwith an existing profile. For example, if aholder presentscredentials that include postal code, age, and gender, averifiercan potentially correlate thesubject of thatcredential with anestablished profile. For more information, see [DEMOGRAPHICS].
Passing the identifier of acredential to a centralized revocation server.The centralized server can correlate uses of thecredential acrossinteractions. For example, if acredential is used to prove age in thismanner, the centralized service could know everywhere thatcredential waspresented (all liquor stores, bars, adult stores, lottery sellers, and so on).
In part, it is possible to mitigate this de-anonymization and loss of privacyby:
Theissuer using a globally-distributed service for revocation such thatit is not contacted when revocation checks are performed.
Specification authors designing revocation mechanisms that do not depend onsubmitting a unique identifier for averifiable credential to a query API,and instead use, for example, a privacy-preserving revocation list.
Issuers avoiding the association of personally identifiable informationwith any specific long-livedsubject identifier.
Unfortunately, these mitigation techniques are only sometimes practical oreven compatible with necessary use. Sometimes, correlation is a requirement.
For example, in some prescription drug monitoring programs, monitoring prescriptionuse is a requirement. Enforcement entities need to be able to confirm that individualsare not cheating the system to get multiple prescriptions for controlledsubstances. This statutory or regulatory need to correlate prescriptionuse overrides individual privacy concerns.
Verifiable credentials will also be used to intentionally correlateindividuals across services. For example, when using a common persona to log into multiple services, all activity on each of those services isintentionally linked to the same individual. This is not a privacy issue aslong as each of those services uses the correlation in the expected manner.
Legal processes can compelissuers,holders, andverifiers todisclose private information to authorities, such as law enforcement. It isalso possible for the same private information to be accidentally disclosedto an unauthorized party through a software bug or security failure. Authorsof legal processes and compliance regimes are advised to draft guidelines thatrequire notifying thesubjects involved when their private information isintentionally or accidentally disclosed to a third party. Providers of softwareservices are advised to be transparent about known circumstances that mightcause such private information to be shared with a third party, as well as theidentity of any such third party.
8.16Sharing Information with the Wrong Party
This section is non-normative.
When aholder chooses to share information with averifier, itmight be the case that theverifier is acting in bad faith and requestsinformation that could harm theholder. For example, averifier might ask for a bank account number, which could then be usedwith other information to defraud theholder or the bank.
Issuers ought to strive to tokenize as much information as possible sothat if aholder accidentally transmitscredentials to the wrongverifier, the situation is not catastrophic.
For example, instead of including a bank account number to checkan individual's bank balance, provide a token that enables theverifier to check if the balance is above a certain amount. In thiscase, the bank could issue averifiable credential containing a balancechecking token to aholder. Theholder would then include theverifiable credential in averifiable presentation and bind thetoken to a credit checking agency using a digital signature. Theverifier could then wrap theverifiable presentation in theirdigital signature and hand it back to the issuer to check theaccount balance dynamically.
Using this approach, even if aholder shares the account balance tokenwith the wrong party, an attacker cannot discover the bank account number orthe exact value of the account. Also, given the validity period of thecounter-signature, the attacker gains access to the token for only afew minutes.
8.17Data Theft
This section is non-normative.
The data expressed inverifiable credentials andverifiable presentations are valuable since they contain authenticstatements made by trusted third parties (such asissuers) orindividuals (such asholders orsubjects). The storage andaccessibility of this data can inadvertently create honeypots ofsensitive data for malicious actors. These adversaries often seek toexploit such reservoirs of sensitive information, aiming toacquire and exchange that data for financial gain.
Issuers are advised to retain the minimum amount of datanecessary to issueverifiable credentials toholders andto manage the status and revocation of those credentials. Similarly,issuers are advised to avoid creating publiclyaccessible credentials that include personally identifiable information(PII) or other sensitive data. Software implementers are advisedto safeguardverifiable credentials using robust consentand access control measures, ensuring that they remaininaccessible to unauthorized entities.
Holders are advised to use implementations that appropriatelyencrypt their data in transit and at rest and protect sensitivematerial (such as cryptographic secrets) in ways that cannot be easilyextracted from hardware or other devices. It is further suggested thatholders store and manipulate their data only on devices theycontrol, away from centralized systems, to reduce the likelihood ofan attack on their data or inclusion in a large-scale theft if an attack issuccessful. Furthermore,holders are encouraged to rigorously controlaccess to their credentials and presentations, allowing access only to thosewith explicit authorization.
Verifiers are advised to ask only for data necessary for a particulartransaction and to retain no data beyond the needs of any particulartransaction.
Regulators are advised to reconsider existing audit requirements such thatmechanisms that better preserve privacy can be used to achieve similarenforcement and audit capabilities. For example, audit-focused regulationsthat insist on the collection and long-term retention of personallyidentifiable information can cause harm to individuals and organizationsif that same information is later compromised and accessed by an attacker.The technologies described by this specification enableholders toprove properties about themselves and others more readily, reducing theneed for long-term data retention byverifiers. Alternatives includekeeping logs that the information was collected and checked, as well asrandom tests to ensure that compliance regimes are operating as expected.
8.18Frequency of Claim Issuance
This section is non-normative.
As detailed in Section8.14Patterns of Use, patterns of use can becorrelated with certain types of behavior. This correlation is partiallymitigated when aholder uses averifiable credential without theknowledge of theissuer.Issuers can defeat this protectionhowever, by making theirverifiable credentials short lived and renewalautomatic.
For example, anageOververifiable credential is helpful ingaining access to a bar. If anissuer issues such averifiable credential with a very short validity period and an automaticrenewal mechanism, then theissuer could correlate theholder'sbehavior in a way that negatively impacts theholder.
Organizations providing software toholders ought to warn them if theyrepeatedly usecredentials with short lifespans, which could result inbehavior correlation.Issuers ought to avoid issuingcredentials thatenable them to correlate patterns of use.
8.19Prefer Single-Use Credentials
This section is non-normative.
An ideal privacy-respecting system would require only the information necessaryfor interaction with theverifier to be disclosed by theholder.Theverifier then records that the disclosure requirement has been metand discards any sensitive information disclosed. In many cases,competing priorities, such as regulatory burden, prevent this ideal system frombeing employed. In other instances, long-lived identifiers prevent single use.The designer of anyverifiable credentials ecosystem ought to striveto make it as privacy-respecting as possible by preferring single-useverifiable credentials whenever possible.
Using single-useverifiable credentials provides several benefits. Thefirst benefit is toverifiers who can be sure that the data in averifiable credential is fresh. The second benefit is toholders,who know that if there are no long-lived identifiers in theverifiable credential, theverifiable credential itself cannot beused to track or correlate them online. Finally, there is nothing for attackersto steal, making the entire ecosystem safer to operate within.
8.20Private Browsing
This section is non-normative.
In an ideal private browsing scenario, no PII will be revealed. Because manycredentials include PII, organizations providing software toholders ought to warn them about the possibility of this informationbeing revealed if they usecredentials andpresentations while inprivate browsing mode. As each browser vendor handles private browsingdifferently, and some browsers might not have this feature, it isimportant that implementers not depend on private browsing mode to provideany privacy protections. Instead, implementers are advised to rely ontooling that directly usable by their software to provide privacy guarantees.
8.21Issuer Cooperation Impacts on Privacy
This section is non-normative.
Verifiable credentials rely on a high degree of trust inissuers.The degree to which aholder might take advantage of possible privacyprotections often depends strongly on the support anissuer provides forsuch features. In many cases, privacy protections which make use ofzero-knowledge proofs, data minimization techniques, bearer credentials,abstract claims, and protections against signature-based correlation requireactive support by theissuer, who need to incorporate those capabilitiesinto theverifiable credentials they issue.
It is crucial to note thatholders not only depend onissuerparticipation to provideverifiable credential capabilities that helppreserveholder andsubject privacy, but also rely onissuers tonot deliberately subvert these privacy protections. For example, anissuer might signverifiable credentials using a signature schemethat protects against signature-based correlation. This would protect theholder from being correlated by the signature value as it is shared amongverifiers. However, if theissuer creates a unique key for eachissuedcredential, it might be possible for theissuer to trackpresentations of thecredential, regardless of averifier'sinability to do so.
In addition to previously described privacy protections anissuer mightoffer,issuers need to be aware of data they leak that is associated withidentifiers and claim types they use when issuingcredentials. Oneexample of this would be anissuer issuing driver's licenses which revealboth the location(s) in which they have jurisdiction and the location of thesubject's residence.Verifiers might take advantage of this byrequesting acredential to check that thesubject is licensed todrive when, in fact, they are interested in metadataabout thecredential, such as whichissuer issued the credential, and tangentialinformation that might have been leaked by theissuer, such as thesubject's home address. To mitigate such leakage,issuers mightuse common identifiers to mask specific location information or other sensitivemetadata; for example, a sharedissuer identifier at a state or nationallevel instead of at the level of a county, city, town, or other smallermunicipality. Further,verifiers can useholder attestation mechanismsto preserve privacy, by providing proof that anissuer exists in a set oftrusted entities without needing to disclose the exactissuer.
9.Security Considerations
This section is non-normative.
Issuers,holders, andverifiers should be aware of a number ofsecurity considerations when processing data described by this specification.Ignoring or not understanding the implications of this section can result insecurity vulnerabilities.
While this section highlights a broad set of security considerations, it is apartial list. Implementers of mission-critical systems using the technologydescribed in this specification are strongly encouraged to consult security andcryptography professionals for comprehensive guidance.
9.1Cryptography Suites and Libraries
This section is non-normative.
Cryptography can protect some aspects of the data model described in thisspecification. It is important for implementers to understand the cryptographysuites and libraries used to create and processcredentials andpresentations. Implementing and auditing cryptography systems generallyrequires substantial experience. Effectivered teaming can alsohelp remove bias from security reviews.
Cryptography suites and libraries have a shelf life and eventually succumb tonew attacks and technological advances. Production quality systems need to takethis into account and ensure mechanisms exist to easily and proactively upgradeexpired or broken cryptography suites and libraries, and to invalidate andreplace existingcredentials. Regular monitoring is important toensure the long term viability of systems processingcredentials.
9.2Key Management
This section is non-normative.
The security of most digital signature algorithms, used to secureverifiable credentials andverifiable presentations, depends on the quality andprotection of theirprivate signing keys. The management ofcryptographic keys encompasses a vast and complex field. For comprehensiverecommendations and in-depth discussion, readers are directed to[NIST-SP-800-57-Part-1]. As strongly recommended in both [FIPS-186-5] and[NIST-SP-800-57-Part-1], a private signing key is not to be used for multiplepurposes; for example, a private signing key is not to be used for encryptionas well as signing.
[NIST-SP-800-57-Part-1] strongly advises that private signing keys andpublic verification keys have limitedcryptoperiods, whereacryptoperiod is "the time span during which a specific key isauthorized for use by legitimate entities or the keys for a given system willremain in effect." [NIST-SP-800-57-Part-1] gives extensiveguidance on cryptoperiods for different key types under various conditionsand recommends a one to three year cryptoperiod for a private signing key.
To deal with potential private key compromises, [NIST-SP-800-57-Part-1]provides recommendations for protective measures, harm reduction, andrevocation. Although this section focuses primarily on the security of theprivate signing key, [NIST-SP-800-57-Part-1] also highly recommendsconfirmation of the validity of allverification material before using it.
Section5.3Integrity of Related Resources of this specification provides anoptional mechanism for ensuring the integrity of the content of externalresources. This mechanism is not necessary for external resources that do notimpact theverifiable credential's security. However, its implementationis crucial for external resources where content changes could potentiallyintroduce security vulnerabilities.
Implementers need to recognize the potential security risks associated withunprotected URLs of external machine-readable content. Such vulnerabilitiescould lead to successful attacks on their applications. Where changes toexternal resources might compromise security, implementers will benefit byemploying the content integrity protection mechanism outlined in thisspecification.
9.4Unsigned Claims
This section is non-normative.
This specification enables the creation ofcredentials without signaturesor proofs. Thesecredential classes are often useful for intermediatestorage or self-asserted information, analogous to filling out a form on a webpage. Implementers ought to be aware that thesecredential types are notverifiable because the authorship either is unknown or cannot be trusted.
9.5Man-in-the-Middle (MITM), Replay, and Cloning Attacks
This section is non-normative.
The data model does not inherently preventMan-in-the-Middle (MITM),replay, andspoofing attacks.Both online and offline use cases might be susceptible to these attacks, wherean adversary intercepts, modifies, re-uses, and/or replicates theverifiable credential data during transmission or storage.
Other approaches, such as token binding [RFC8471], which ties the request foraverifiable presentation to the response, can help secure the protocol.Any unsecured protocol is susceptible to man-in-the-middle attacks.
9.5.2Replay Attack
Averifier might wish to limit the number of times thatverifiable presentation can be used. For example, multiple individualspresenting the sameverifiable credential representing an event ticketmight be granted entry to the event, undermining the purpose of the ticketfrom the perspective of itsissuer. To prevent such replay attacks,verifiers requireholders to include additional security measuresin theirverifiable presentations. Examples include the following:
Verifiers might have a vested interest in knowing that aholder isauthorized to present theclaims inside of averifiable presentation.While the data model outlines the structure and data elements necessary for averifiable credential, it does not include a mechanism to ascertain theauthorization of presentedcredentials. To address this concern,implementers might need to explore supplementary methods, such as bindingverifiable credentials to strong authentication mechanisms or usingadditional properties inverifiable presentationsto enable proof of control.
9.6Bundling Dependent Claims
This section is non-normative.
It is considered best practice forissuers to atomize information in acredential or use a signature scheme that allows for selectivedisclosure. When atomizing information, if it is not done securely by theissuers, theholders might bundle togetherclaims from differentcredentials in ways that theissuers did not intend.
Consider a university issuing twoverifiable credentials to an individual.Eachcredential contains two properties that, when combined, indicate theperson's "role" in a specific "department." For instance, onecredentialpair might designate "Staff Member" in the "Department of Computing," whileanother could signify "Post Graduate Student" in the "Department of Economics."Atomizing theseverifiable credentials results in the university issuingfour separatecredentials to the individual. Eachcredential containsa single designation: "Staff Member", "Post Graduate Student", "Department ofComputing", or "Department of Economics". Theholder might then presentthe "Staff Member" and "Department of Economics"verifiable credentials toaverifier, which, together, would comprise a falseclaim.
9.7Highly Dynamic Information
This section is non-normative.
Whenverifiable credentials contain highly dynamic information, carefulconsideration of validity periods becomes crucial. Issuingverifiable credentials with validity periods that extend beyond their intended use createspotential security vulnerabilities that malicious actors could exploit. Validityperiods shorter than the timeframe where the information expressed by theverifiable credential is expected to be used creates a burden onholders andverifiers. It is, therefore, important to set validityperiods forverifiable credentials appropriate to the use case and theexpected lifetime of the information contained in theverifiable credential.
9.8Device Theft and Impersonation
This section is non-normative.
Storingverifiable credentials on a device poses risks if the device islost or stolen. An attacker gaining possession of such a device potentiallyacquires unauthorized access to systems using the victim'sverifiable credentials. Ways to mitigate this type of attack include:
Enabling password, pin, pattern, or biometric screen unlock protection on thedevice.
Enabling password, biometric, or multi-factor authentication for thecredential repository.
Enabling password, biometric, or multi-factor authentication when accessingcryptographic keys.
Using a separate hardware-based signature device.
All or any combination of the above.
Furthermore, instances of impersonation can manifest in various forms,including situations where anentity attempts to disavow its actions.Elevating trust and security within the realm ofverifiable credentialsentails more than averting impersonation; it also involves implementingnon-repudiation mechanisms. These mechanisms solidify anentity'sresponsibility for its actions or transactions, reinforcing accountability anddeterring malicious behavior. Attainment of non-repudiation is amultifaceted endeavor, encompassing an array of techniques includingsecuring mechanisms, proofs of possession,and authentication schemes in various protocols designed to foster trust andreliability.
9.9Acceptable Use
This section is non-normative.
Ensuring alignment between anentity's actions — such aspresentation,and the intended purpose of those actions — is essential. It involves having theauthorization to useverifiable credentials and usingcredentials in amanner that adheres to their designated scope(s) and objective(s). Two criticalaspects in this context areUnauthorized Use andInappropriate Use.
9.9.1Unauthorized Use
Entities usingverifiable credentials andverifiable presentationsbeyond their intended purpose are engaging in unauthorized activity. One classof unauthorized use is aconfidentiality violation. Consider aholderthat shares averifiable presentation with averifierto establish their age and residency status. If theverifier then proceedsto employ theholder's data without proper consent, such as by selling thedata to a data broker, that would constitute an unauthorized use of the data,violating an expectation of privacy that theholder might have in thetransaction.
Similarly, anissuer can employ atermsOfUseproperty to specify how and when aholder might be permitted and expectedto use acredential. Aholder usingcredentials outside of thescope(s) defined in thetermsOfUse would be considered to be unauthorized.
Note: Digital Rights Management is out of scope
Further study is required to determine how aholder can assert andenforce authorized use of their data afterpresentation.
9.9.2Inappropriate Use
While valid cryptographic signatures and successful status checks signify thereliability ofcredentials, they do not signify that allcredentials are interchangeable for all contexts. It is crucial thatverifiers alsovalidate any relevantclaims,considering the source and nature of theclaim alongside the purposefor which theholder presents thecredential.
For instance, in scenarios where a certified medical diagnosis is required, aself-assertedcredential carrying the necessary data might not sufficebecause it lacks validity from an authoritative medical source. To ensure propercredential use, stakeholders need to assess thecredential's relevance and authority within thespecific context of their intended application.
9.10Code Injection
This section is non-normative.
Data inverifiable credentials can include injectable code or code fromscripting languages. Authors ofverifiable credentials benefit from avoidingsuch inclusions unless necessary and only after mitigating associated risks tothe fullest extent possible.
For example, a single natural language string containing multiple languages orannotations often requires additional structure or markup for correctpresentation. Markup languages, such as HTML, can label text spans in differentlanguages or supply string-internal markup needed to displaybidirectional text properly. It is also possible to use therdf:HTML datatype to encodesuch values accurately in JSON-LD.
Despite the ability to encode information as HTML, implementers are stronglydiscouraged from doing so for the following reasons:
It requires some version of an HTML processor, which increases the burden ofprocessing language and base direction information.
It increases the security attack surface when using this data model,because naively processing HTML could result in the execution of ascripttag that an attacker injected at some point during the data production process.
If implementers feel they need to use HTML, or other markup languages capable ofcontaining executable scripts, to address a specific use case, they are advisedto analyze how an attacker could use the markup to mount injection attacksagainst a consumer of the markup. This analysis should be followed by theproactive deployment of mitigations against the identified attacks, such asrunning the HTML rendering engine in a sandbox with no ability to access thenetwork.
10.Accessibility Considerations
This section is non-normative.
There are a number of accessibility considerations implementers should beaware of when processing data described in this specification. As withimplementation of any web standard or protocol, ignoring accessibility issuesmakes this information unusable by a large subset of the population. It isimportant 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 using cryptography,which have historically created problems for assistive technologies.
This section details the general accessibility considerations to take intoaccount when using this data model.
10.1Data First Approaches
This section is non-normative.
Many physicalcredentials in use today, such as government identificationcards, have poor accessibility characteristics, including, but not limited to,small print, reliance on small and high-resolution images, and no affordancesfor people with vision impairments.
When using this data model to createverifiable credentials, it issuggested that data model designers use adata first approach. Forexample, given the choice of using data or a graphical image to depict acredential, designers should express every element of the image, such asthe name of an institution or the professionalcredential, in amachine-readable way instead of relying on a viewer's interpretation of theimage to convey this information. Using a data first approach is preferredbecause it provides the foundational elements of building different interfacesfor people with varying abilities.
11.Internationalization Considerations
This section is non-normative.
Implementers are advised to be aware of a number of internationalizationconsiderations when publishing data described in this specification.As with any web standards or protocols implementation, ignoringinternationalization makes it difficult for data to be produced and consumedacross a disparate set of languages and societies, which limits theapplicability of the specification and significantly diminishes its value as astandard.
This section outlines general internationalization considerations to take intoaccount when using this data model and is intended to highlight specificparts of theStrings on the Web: Language and Direction Metadatadocument [STRING-META] that implementers might be interested in reading.
11.1Language and Base Direction
Data publishers are strongly encouraged to read the section onCross-Syntax Expression in theStrings on the Web: Language and DirectionMetadata document [STRING-META] to ensure that expressinglanguage andbase direction information ispossible across multiple expression syntaxes, such as [JSON-LD11], [JSON],and CBOR [RFC7049].
The general design pattern is to use the following markup template whenexpressing a text string that is tagged with a language and, optionally, aspecific base direction.
Example 36: Design pattern for natural language strings
"myProperty": { "@value": "The string value", "@language": "LANGUAGE" "@direction": "DIRECTION"}
When the language value object is used in place of a string value, the objectMUST contain a@value property whose value is a string, andSHOULD contain a@language property whose value is a string containing a well-formedLanguage-Tag as defined by [BCP47], andMAY contain a@direction propertywhose value is abase direction string defined by the@directionproperty in [JSON-LD11]. The language value objectMUST NOT include any otherkeys beyond@value,@language, and@direction.
Using the design pattern above, the following example expresses the title of abook in the English language without specifying a text direction.
Example 37: Expressing natural language text as English
"title": { "@value": "HTML and CSS: Designing and Creating Websites", "@language": "en"}
The next example uses a similar title expressed in the Arabic language with abase direction of right-to-left.
Example 38: Arabic text with a base direction of right-to-left
"title": { "@value": "HTML و CSS: تصميم و إنشاء مواقع الويب", "@language": "ar", "@direction": "rtl"}
Note: Properly rendering internationalized text is challenging
The text above would most likely be rendered incorrectly as left-to-rightwithout the explicit expression of language and direction because many systemsuse the first character of a text string to determine itsbase direction.
Multiple language value objectsMAY be provided as an array value for theproperty:
Example 39: Multiple language texts provided for title
"title": [ { "@value": "HTML and CSS: Designing and Creating Websites", "@language": "en" }, { "@value": "HTML و CSS: تصميم و إنشاء مواقع الويب", "@language": "ar", "@direction": "rtl" }]
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://achievement.example/multilingual/v2" ], "type": [ "VerifiableCredential", "ExampleAchievementCredential" ], "issuer": { "id": "did:example:2g55q912ec3476eba2l9812ecbfe", "type": "Profile" }, "validFrom": "2024-03-14T22:32:52Z", "validUntil": "2025-01-01T00:00:00Z", "credentialSubject": { "type": [ "AchievementSubject" ], "achievement": { "id": "urn:uuid:9a652678-4616-475d-af12-aca21cfbe06d", "type": [ "Achievement" ], "name": { "en": "Successful installation of the Example application", "es": "Instalación exitosa de la aplicación Example" }, "criteria": { "narrative": { "es": "Instaló exitosamente de la aplicación Example.", "en": "Successfully installed the Example application." } } } }}
11.2Providing Default Language and Direction
The language and base direction of each natural language string property valueSHOULD be provided, either via the language value structure for each propertyvalue, or via a default language and base direction for all values in the entirecredential. Using the per-value language value structure is preferred, becauseusing document defaults can result in a requirement that downstream processorsperform JSON-LD expansion-based transformation which is otherwise optional. SeetheString Internationalization section of the [JSON-LD11] specification formore information. Natural language string values that do not have a languageassociated with themSHOULD be treated as if the language value isundefined(language tag "und"). Natural language string values that do not have a basedirection associated with themSHOULD be treated as if the direction value is"auto".
A.Validation
This section is non-normative.
While this specification does not provide conformance criteria for the processof thevalidation ofverifiable credentials orverifiable presentations, readers might be curious about how theinformation in this data model is expected to be used byverifiersduring the process ofvalidation. This section captures a selection ofconversations held by the Working Group related to the expected use of theproperties in this specification byverifiers.
A.1Credential Type
This section is non-normative.
When averifier requests one or moreverifiable credentials from aholder, they can specify thetype of credential(s)that they would like to receive. Credential types, as well as validation schemasfor each type and each of theirclaims, are defined by specification authorsand are published in places like theVerifiable Credential Extensions.
The type of a credential is expressed via thetypeproperty. Averifiable credential of a specific type contains specificproperties (which might be deeply nested) that can be used to determinewhether or not thepresentation satisfies a set of processing rules that theverifier executes. By requestingverifiable credentials of a particulartype, theverifier is able to gather specific information from theholder, which originated with theissuer of eachverifiable credential, that will enable theverifier to determine the next stage ofan interaction with aholder.
When averifier requests averifiable credential of a specific type,there will be a set of mandatory and optionalclaims that are associatedwith that type. Averifier's validation of averifiable credential willfail when mandatoryclaims are not included, and anyclaim that isnot associated with the specific type will be ignored. In other words, averifier will perform input validation on theverifiable credential itreceives and will reject malformed input based on the credential typespecification.
Metadata related to theissuerproperty is available to theverifier through theverificationalgorithm as defined in Section7.1Verification.This metadata includes identification of the verified controller of theverification method used by the securing mechanism to secure eachverifiable credential orverifiable presentation, of which the controller istypically the respectiveissuer orholder.
Some ecosystems might have more complex relationships betweenissuersand controllers of verification methods and might use lists of verifiedissuers in addition to, or instead of, the mapping described above.
A.4Holder
This section is non-normative.
The value associated with theholderproperty is used to identify theholder to theverifier.
Often relevant metadata about theholder, as identified by the value oftheholderproperty, is available to, or retrievable by, theverifier. For example, aholder can publish information containingtheverification material used to secureverifiable presentations. Thismetadata is used when checking proofs onverifiable presentations.Some cryptographic identifiers contain all necessary metadata in the identifieritself. In those cases, no additional metadata is required. Other identifiersuse verifiable data registries where such metadata is automatically publishedfor use byverifiers, without any additional action by theholder.
Note: Validation is the process of applying business rules
Validation is the process by which verifiers apply business rules toevaluate the propriety of a particular use of averifiable credential.
Averifier might need to validate a givenverifiable presentationagainst complex business rules; for example, the verifier might need confidencethat theholder is the same entity as asubject of averifiable credential. In such a situation, the following factors can provide averifier with reasonable confidence that the claims expressed regardingthat identifier, in includedverifiable credentials, are, in fact, aboutthe current presenter:
The identifier in theholder property of theverifiable presentationand at least one identifier property of at least one object in thecredentialSubject array are the same.
That common identifier can be used to discover or derive the verificationmaterial used to verify the integrity of thatverifiable presentation.
A.5Issuance Date
This section is non-normative.
ThevalidFrom is expected to be within an expected range for theverifier. For example, averifier can check that the start ofthe validity period for averifiable credential is not in the future.
A.6Proofs (Signatures)
This section is non-normative.
The securing mechanism used to prove that the information in averifiable credential orverifiable presentation was not tampered with is called acryptographic proof. There are many types of cryptographic proofsincluding, but not limited to, digital signatures and zero-knowledge proofs. Ingeneral, when verifying cryptographic proofs, implementations are expected toensure:
The cryptographic proof is available in a form defined by a known cryptographicsuite.
All required cryptographic proofproperties are present.
The cryptographic proofverification algorithm, when applied to the data,results in an accepted cryptographic proof.
In general, when verifying digital signatures, implementations are expected toensure:
Acceptably recent metadata regarding theverification material associatedwith the signature is available. For example, if theverification materialis a cryptographic public key, the metadata might includeproperties relatedto the validity period, the controller, or the authorized purpose, such asauthentication or encryption, of the cryptographic public key.
The public key is not suspended, revoked, or expired.
The digital signature verifies.
Any additional requirements defined by the securing mechanism are satisfied.
A.7Validity Periods
This section is non-normative.
Theverifier expects that thevalidFrom andvalidUntil properties will be within a certain range. For example,averifier can check that the end of the validity period of averifiable credential is not in the past. Because some credentials can beuseful for secondary purposes even if their original validity period hasexpired, validity period, as expressed using thevalidFrom andvalidUntil properties, is always considered a component ofvalidation, which is performedafter verification.
If thecredentialSchema property is available, the schema of averifiable credential is expected to be evaluated by theverifieraccording to thecredentialSchematype definition for theverifiable credential and theverifier's own schema evaluationcriteria. For example, if thecredentialSchema'stypevalue is [VC-JSON-SCHEMA], then averifier can ensure a credential'sdata is valid against the given JSON Schema.
A.10Fitness for Purpose
This section is non-normative.
Fitness for purpose is about whether the customproperties in theverifiable credential are appropriate for theverifier's purpose.For example, if averifier needs to determine whether asubject isolder than 21 years of age, they might rely on a specificbirthdateproperty, or on more abstractproperties, such asageOver.
Theissuer is trusted by theverifier to make theclaims athand. For example, a franchised fast food restaurant location trusts thediscount couponclaims made by the corporate headquarters of thefranchise. Policy information expressed by theissuer in theverifiable credential should be respected byholders andverifiers unless they accept the liability of ignoring the policy.
A.11"Artificial Intelligence" and "Machine Learning"
This section is non-normative.
Systems using what is today commonly referred to as "artificial intelligence"and/or "machine learning" might be capable of performing complex tasks at alevel that meets or exceeds human performance. This might include tasks such asthe acquisition and use ofverifiable credentials. Using such tasks todistinguish between human and automated "bot" activity, as is commonly donetoday with aCAPTCHA,for instance, might thereby cease to provide adequate or acceptable protection.
Implementers of security architectures that useverifiable credentialsand/or perform validation on their content are urged to consider the existenceof machine-based actors, such as those which are today commonly referred to as"artificial intelligence", that might legitimately holdverifiable credentials for use in interactions with other systems. Implementers mightalso consider how threat actors could couple such "artificial intelligence"systems withverifiable credentials to pose as humans when interacting withtheir systems. Such systems might include, but not be limited to, globalinfrastructure such as social media, election, energy distribution, supplychain, and autonomous vehicle systems.
B.Contexts, Vocabularies, Types, and Credential Schemas
B.1Base Context
ImplementationsMUST treat the base context value, located athttps://www.w3.org/ns/credentials/v2, as already retrieved;the following value is the hexadecimal encoded SHA2-256 digest value of the basecontext file:59955ced6697d61e03f2b2556febe5308ab16842846f5b586d7f1f7adec92734. It is possible to confirmthe cryptographic digest above by running the following command from a modernUnix command interface line:curl -s https://www.w3.org/ns/credentials/v2 | openssl dgst -sha256.
It is strongly advised that all JSON-LD Context URLs used by anapplication use the same mechanism, or a functionally equivalent mechanism,to ensure end-to-end security. Implementations are expected to throw errorsif a cryptographic hash value for a resource does not match the expected hashvalue.
Implementations that apply the base context above, as well as other contextsand values in any@context property, during operations such asJSON-LD Expansion ortransformation to RDF, are expected to do so without experiencing anyerrors. If such operations are performed and result in an error,theverifiable credential orverifiable presentationMUST resultin a verification failure.
Note: See errata if hash value changes are detected
It is extremely unlikely that the files that have associated cryptographic hashvalues in this specification will change. However, if critical errata arefound in the specification and corrections are required to ensureecosystem stability, the cryptographic hash values might change. As such, theHTTP cache times for the files are not set to infinity and implementers areadvised to check for errata if a cryptographic hash value change is detected.
The content in a credential whose meaning depends on a link to an external URL,such as a JSON-LD Context, which can be secured by using a local static copyor a cryptographic digest of the file. See Section5.3Integrity of Related Resources for more details.
Verifiers are warned that other data that is referenced from within acredential, such as resources that are linked to via URLs, are notcryptographically protected by default. It is considered a best practice toensure that the same sorts of protections are provided for any URL that iscritical to the security of theverifiable credential through the use ofpermanently cached files and/or cryptographic hashes. Ultimately, knowing thecryptographic digest of any linked external content enables averifier toconfirm that the content is the same as what theissuer orholderintended.
B.2Vocabularies
Implementations that depend on RDF vocabulary processingMUST ensure that thefollowing vocabulary URLs used in the base context ultimately resolve to thefollowing files when loading the JSON-LD serializations, which are normative.Other semantically equivalent serializations of the vocabulary filesMAY be usedby implementations. A cryptographic hash is provided for each JSON-LD documentto ensure that developers can verify that the content of each file is correct.
It is possible to confirm the cryptographic digests listed above by runninga command like the following, replacing<DOCUMENT_URL>with the appropriate value, through a modern UNIX-like OS command line interface:curl -sL -H "Accept: application/ld+json" <DOCUMENT_URL> | openssl dgst -sha256
Note: schema.org changes regularly, but is considered stable
Implementers and document authors might note that cryptographic digests forschema.org are not provided. This is because theschema.org vocabularyundergoes regular changes; any digest provided would be out of date withinweeks of publication. The Working Group discussed this concern and concludedthat the vocabulary terms fromschema.org, that are used by thisspecification, have been stable for years and are highly unlikely to change intheir semantic meaning.
The following base classes are defined in this specification for processorsand other specifications that benefit from such definitions:
Base Class
Purpose
CredentialEvidence
Serves as a superclass for specific evidence types that are placed into theevidence property.
CredentialSchema
Serves as a superclass for specific schema types that are placed into thecredentialSchema property.
CredentialStatus
Serves as a superclass for specific credential status types that are placed intothecredentialStatus property.
ConfidenceMethod
Serves as a superclass for specific confidence method types that are placed intotheconfidenceMethod property.
RefreshService
Serves as a superclass for specific refresh service types that are placed intothecredentialRefresh property.
RenderMethod
Serves as a superclass for specific render method types that are placed intotherenderMethod property.
TermsOfUse
Serves as a superclass for specific terms of use types that are placed intothetermsOfUse property.
B.3Datatypes
This section defines datatypes that are used by this specification.
B.3.1ThesriString Datatype
ThesriString datatype is associated with a value to provide the integrityinformation for a resource using the method specified in theSubresource Integrityspecification. ThesriString datatype is defined as follows:
The URL denoting this datatype
https://www.w3.org/2018/credentials#sriString
The lexical space
See theABNFgrammar, defining theintegrity attribute in the [SRI] specification,for the restrictions on the string format.
The value space
A (possibly empty) list of(alg,val) pairs, wherealg identifies ahash function, andval is an integer as a standard mathematical concept.
The lexical-to-value mapping
Any element of the lexical space is mapped to the value space by following theparse metadata algorithmbased on theABNFgrammar in the [SRI] specification.
The canonical mapping
The canonical mapping consists of the lexical-to-value mapping.
B.4Differences between Contexts, Types, and CredentialSchemas
This section is non-normative.
Theverifiable credential andverifiable presentation data modelsleverage a variety of underlying technologies including [JSON-LD11] and[VC-JSON-SCHEMA]. This section will provide a comparison of the@context,type, andcredentialSchemaproperties, and cover some of the more specific use cases where it is possibleto use these features of the data model.
Thetype property is used to uniquely identify the type of theverifiable credential in which it appears, that is, to indicate which set ofclaims theverifiable credential contains. This property, and the valueVerifiableCredential within the set of its values, are mandatory.Whilst it is good practice to include one additional value depicting the uniquesubtype of thisverifiable credential, it is permitted to either omit orinclude additional type values in the array. Many verifiers will request averifiable credential of a specific subtype, then omitting the subtypevalue could make it more difficult for verifiers to inform the holder whichverifiable credential they require. When averifiable credentialhas multiple subtypes, listing all of them in thetypeproperty is sensible. The use of thetype property in a[JSON-LD11] representation of averifiable credential enables to enforcethe semantics of theverifiable credential because the machine is able tocheck the semantics. With [JSON-LD11], the technology is not only describing thecategorization of the set of claims, the technology is also conveying thestructure and semantics of the sub-graph of the properties in the graph. In[JSON-LD11], this represents the type of the node in the graph which is why some[JSON-LD11] representations of averifiable credential will use thetype property on many objects in theverifiable credential.
The primary purpose of the@context property, from a [JSON-LD11]perspective, is to convey the meaning of the data and term definitions of thedata in averifiable credential, in a machine-readable way. The@context property is used to map the globally unique URLs forproperties inverifiable credentials andverifiable presentationsinto short-form alias names, making [JSON-LD11] representations morehuman-friendly to read. From a [JSON-LD11] perspective, this mapping also allowsthe data in acredential to be modeled in a network of machine-readabledata, by enhancing how the data in theverifiable credential orverifiable presentation relates to a larger machine-readable data graph.This is useful for telling machines how to relate the meaning of data to otherdata in an ecosystem where parties are unable to coordinate. This property, withthe first value in the set beinghttps://www.w3.org/ns/credentials/v2, is mandatory.
Since the@context property is used to map data to a graphdata model, and thetype property in [JSON-LD11] is used todescribe nodes within the graph, thetype property becomeseven more important when using the two properties in combination. For example,if thetype property is not included within the resolved@context resource using [JSON-LD11], it could lead to claims beingdropped and/or their integrity no longer being protected during production andconsumption of theverifiable credential. Alternatively, it could lead toerrors being raised during production or consumption of averifiable credential. This will depend on the design choices of the implementation andboth paths are used in implementations today, so it's important to pay attentionto these properties when using a [JSON-LD11] representation of averifiable credential orverifiable presentation.
The primary purpose of thecredentialSchema property is to definethe structure of theverifiable credential, and the datatypes for thevalues of each property that appears. AcredentialSchema is usefulfor defining the contents and structure of a set of claims in averifiable credential, whereas [JSON-LD11] and a@context in averifiable credential are best used only for conveying the semantics andterm definitions of the data, and can be used to define the structure of theverifiable credential as well.
While it is possible to use some [JSON-LD11] features to allude to thecontents of theverifiable 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 notstrictly defined. This can be dangerous if the implementer is looking toconstrain the data type of the claims in thecredential, and is expectednot to be used.
When thecredentialSchema and@context propertiesare used in combination, both producers and consumers can be more confidentabout the expected contents and data types of theverifiable credentialandverifiable presentation.
C.IANA Considerations
This section is non-normative.
This section will be submitted to the Internet Engineering Steering Group(IESG) for review, approval, and registration with IANA.
C.1application/vc
This specification registers theapplication/vc media type specifically foridentifying documents conforming to theverifiable credentials format.
Type name:
application
Subtype name:
vc
Required parameters:
None
Encoding considerations:
Resources that use theapplication/vc media type are required to conform toall of the requirements for theapplication/ld+json media type and aretherefore subject to the same encoding considerations specified in Section 11ofThe JavaScript Object Notation (JSON) Data Interchange Format.
Note that while theverifiable credentials format uses JSON-LD conventions,there are a number of constraints and additional requirements forverifiable credential implementations that justify the use of a specific media type.
This media type can be used in anenveloping proof to denote the envelopedpayload.
The credential is expected to be a validJSON-LD document.Verifiable credentials served with theapplication/vc media type areexpected to have allJSON-LD 1.1 context information, including referencesto external contexts, within the body of the document. Contexts linked via ahttp://www.w3.org/ns/json-ld#context HTTP Link Header(seeSection 6.1ofJSON-LD 1.1) are ignored.
C.2application/vp
This specification registers theapplication/vp media type specifically foridentifying documents conforming to theverifiable presentations format.
Type name:
application
Subtype name:
vp
Required parameters:
None
Encoding considerations:
Resources that use theapplication/vp media type are required to conform toall of the requirements for theapplication/ld+json media type and aretherefore subject to the same encoding considerations specified in Section 11ofThe JavaScript Object Notation (JSON) Data Interchange Format.
Note that while theverifiable presentations format uses JSON-LDconventions, there are a number of constraints and additional requirements forverifiable presentation implementations that justify the use of a specificmedia type.
This media type can be used in anenveloping proof to denote the envelopedpayload.
The presentation is expected to be a validJSON-LD document.Verifiable presentations served with theapplication/vp media type are expected to haveallJSON-LD 1.1 context information, including references to externalcontexts, within the body of the document. Contexts linked via ahttp://www.w3.org/ns/json-ld#context HTTP Link Header (seeSection 6.1of [JSON-LD11]) are ignored.
D.Additional Diagrams for Verifiable Presentations
Update previous normative references that pointed to RFC3339 for date-timedetails to now normatively reference the date-time details described inXMLSCHEMA11-2 which more accurately reflect date-time use in examples andlibraries.
Loosen the requirement to allowURLs that cannot be dereferenced in theid property of thecredentialStatus andrefreshService sections of the data model.
Loosen normative statements in the zero-knowledge proofs section to enablecompliance of new zero-knowledge proof schemes, such as BBS+, that have beencreated since the v1.0 specification was published as a Recommendation.
Update all references to point to the latest version of the referencedspecifications. Fix broken links to papers that have become unavailable toupdated locations where the papers are available.
Increase accessibility of SVG diagrams.
Fix editorial bugs in a few examples related toissuer,issuanceDate,credentialStatus, dates, dead links, and minor syntax errors.
Move acknowledgements from Status of the Document section into theAcknowledgements appendix.
F.Acknowledgements
This section is non-normative.
The Working Group thanks the following individuals not only for theircontributions toward the content of this document, but also for yeoman's workin this standards community that drove changes, discussion, and consensus amonga sea of varied opinions: David Chadwick, Dave Longley, Ted Thibodeau Jr.,Brent Zundel, Ivan Herman, Joe Andrieu, and Gabe Cohen.
Work on this specification has been supported by the Rebooting the Web of Trustcommunity facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles,Brian Weller, Betty Dhamers, Kaliya Young, Manu Sporny, Drummond Reed, JoeAndrieu, Heather Vescent, Kim Hamilton Duffy, Samantha Chase, Andrew Hughes,Will Abramson, Erica Connell, Eric Schuh, Zaïda Rivai, and Shigeya Suzuki.The participants in the Internet Identity Workshop, facilitated by Phil Windley,Kaliya Young, Doc Searls, and Heidi Nobantu Saul, also supported the refinementof this work through numerous working sessions designed to educate about,debate on, and improve this specification.
Portions of the work on this specification have been funded by the United StatesDepartment of Homeland Security's Science and Technology Directorate undercontracts HSHQDC-17-C-00019, 70RSAT20T00000010/P00001, 70RSAT20T00000029,70RSAT21T00000016/P00001, 70RSAT23T00000005, 70RSAT23C00000030,70RSAT23R00000006, 70RSAT24T00000014, 70RSAT22T00000001, and the NationalScience Foundation under NSF 22-572. The content of this specification does notnecessarily reflect the position or the policy of the U.S. Government and noofficial endorsement should be inferred.
The Working Group would like to thank the following individuals for reviewingand providing feedback on the specification (in alphabetical order by firstname or their Github handle if a name was not provided):
