Copyright © 2021 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
Decentralized identifiers (DIDs) are a new type of identifier that enables verifiable, decentralized digital identity. A DID identifies any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) that the controller of the DID decides that it identifies. In contrast to typical, federated identifiers, DIDs have been designed so that they may be decoupled from centralized registries, identity providers, and certificate authorities. Specifically, while other parties might be used to help enable the discovery of information related to a DID, the design enables the controller of a DID to prove control over it without requiring permission from any other party. DIDs are URIs that associate a DID subject with a DID document allowing trustable interactions associated with that subject.
Each DID document can express cryptographic material, verification methods, or services, which provide a set of mechanisms enabling a DID controller to prove control of the DID. Services enable trusted interactions associated with the DID subject. A DID document might contain the DID subject itself, if the DID subject is an information resource such as a data model.
This document specifies a common data model, a URL format, and a set of operations for DIDs, DID documents, and DID methods.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This specification is under active development and implementers are advised against implementing the specification unless they are directly involved with the W3C DID Working Group. There are use cases [DID-USE-CASES] in active development that establish requirements for this document.
At present, there exist 80 experimental implementations and a preliminary test suite that will eventually determine whether or not implementations are conformant. Readers are advised that Appendix § A. Current Issues contains a list of concerns and proposed changes that will most likely result in alterations to this specification.
Comments regarding this document are welcome. Please file issues directly on GitHub, or send them to public-did-wg@w3.org ( subscribe, archives).
Portions of the work on this specification have been funded by the United States Department of Homeland Security's (US DHS) Science and Technology Directorate under contracts HSHQDC-16-R00012-H-SB2016-1-002, and HSHQDC-17-C-00019, as well as the US DHS Silicon Valley Innovation Program under contracts 70RSAT20T00000010, 70RSAT20T00000029, 70RSAT20T00000030. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.
Portions of the work on this specification have also been funded by the European Union's StandICT.eu program under sub-grantee contract number CALL05/19.
Work on this specification has also been supported by the Rebooting the Web of Trust community facilitated by Christopher Allen, Shannon Appelcline, Kiara Robles, Brian Weller, Betty Dhamers, Kaliya Young, Kim Hamilton Duffy, Manu Sporny, Drummond Reed, Joe Andrieu, and Heather Vescent.
This document was published by the Decentralized Identifier Working Group as a Working Draft. This document is intended to become a W3C Recommendation.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-did-wg@w3.org (archives).
Publication as a Working Draft does not imply endorsement by the W3C Membership.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 15 September 2020 W3C Process Document.
This section is non-normative.
As individuals and organizations, many of us use globally unique identifiers in a wide variety of contexts. They serve as communications addresses (telephone numbers, email addresses, usernames on social media), ID numbers (for passports, drivers licenses, tax IDs, health insurance), and product identifiers (serial numbers, barcodes, RFIDs). Resources on the Internet are identified by globally unique identifiers in the form of MAC addresses; URIs (Uniform Resource Identifiers) are used for resources on the Web and each web page you view in a browser has a globally unique URL (Uniform Resource Locator).
The vast majority of these globally unique identifiers are not under our control. They are issued by external authorities that decide who or what they identify and when they can be revoked. They are useful only in certain contexts and recognized only by certain bodies (not of our choosing). They may disappear or cease to be valid with the failure of an organization. They may unnecessarily reveal personal information. And in many cases they can be fraudulently replicated and asserted by a malicious third-party ("identity theft").
The Decentralized Identifiers (DIDs) defined in this specification are a new type of globally unique identifier designed to enable individuals and organizations to generate our own identifiers using systems we trust, and to prove control of those identifiers (authenticate) using cryptographic proofs (for example, digital signatures).
Because we control the generation and assertion of these identifiers, each of us can have as many DIDs as we need to respect our desired separation of identities, personas, and contexts (in the everyday sense of these words). We can scope the use of these identifiers to the most appropriate contexts. We can interact with other people, institutions or systems that require us to identify ourselves (or things we control) while maintaining control over how much personal or private data should be revealed, and without depending on a central authority to guarantee the continued existence of the identifier.
This specification does not presuppose any particular technology or cryptography to underpin the generation, persistence, resolution or interpretation of DIDs. Rather, it defines: a) the generic syntax for all DIDs, and b) the generic requirements for performing the four basic CRUD operations (create, read, update, deactivate) on the information associated with a DID (called the DID document).
This enables implementers to design specific types of DIDs to work with the computing infrastructure they trust (e.g., distributed ledger, decentralized file system, distributed database, peer-to-peer network). The specification for a specific type of DID is called a DID method. Implementers of applications or systems using DIDs can choose to support the DID methods most appropriate for their particular use cases.
This specification is for:
DID methods can also be developed for identifiers registered in federated or centralized identity management systems. Indeed, almost all types of identifier systems can add support for DIDs. This creates an interoperability bridge between the worlds of centralized, federated, and decentralized identifiers.
This section is non-normative.
A DID is a simple text string consisting of three parts, the:
did
)
did:example:123456789abcdefghi
The example DID above resolves to a DID document. A DID document contains information associated with the DID, such as ways to cryptographically authenticate the DID controller, as well as services that can be used to interact with the DID subject.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", "authentication": [{ // used to authenticate as did:...fghi "id": "did:example:123456789abcdefghi#keys-1", "type": "Ed25519VerificationKey2018", // external (property value) "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" }], "service": [{ // used to retrieve Verifiable Credentials associated with the DID "id":"did:example:123456789abcdefghi#vcs", "type": "VerifiableCredentialService", // external (property value) "serviceEndpoint": "https://example.com/vc/" }] }
This section is non-normative.
Decentralized Identifiers are a component of larger systems, such as the Verifiable Credentials ecosystem [VC-DATA-MODEL], which drove the design goals for this specification. These design goals are summarized here.
Goal | Description |
---|---|
Decentralization | Eliminate the requirement for centralized authorities or single point failure in identifier management, including the registration of globally unique identifiers, public verification keys, services, and other information. |
Control | Give entities, both human and non-human, the power to directly control their digital identifiers without the need to rely on external authorities. |
Privacy | Enable entities to control the privacy of their information, including minimal, selective, and progressive disclosure of attributes or other data. |
Security | Enable sufficient security for requesting parties to depend on DID documents for their required level of assurance. |
Proof-based | Enable DID controllers to provide cryptographic proof when interacting with other entities. |
Discoverability | Make it possible for entities to discover DIDs for other entities, to learn more about or interact with those entities. |
Interoperability | Use interoperable standards so DID infrastructure can make use of existing tools and software libraries designed for interoperability. |
Portability | Be system- and network-independent and enable entities to use their digital identifiers with any system that supports DIDs and DID methods. |
Simplicity | Favor a reduced set of simple features to make the technology easier to understand, implement, and deploy. |
Extensibility | Where possible, enable extensibility provided it does not greatly hinder interoperability, portability, or simplicity. |
This section provides a basic understanding of the major elements of DID architecture. Formal definitions of terms are provided in § 2. Terminology.
id
property. The properties present in a DID document may be updated according to
the applicable operations outlined in § 7. Methods.
Conceptually, the relationship between this specification and a DID method specification is similar to the relationship between the IETF generic URI specification ([RFC3986]) and a specific URI scheme ([IANA-URI-SCHEMES] (such as the http: and https: schemes specified in [RFC7230]). It is also similar to the relationship between the IETF generic URN specification ([RFC8141]) and a specific URN namespace definition (such as the UUID URN namespace defined in [RFC4122]). The difference is that a DID method specification, as well as defining a specific DID scheme, also specifies the methods creating, resolving, updating, and deactivating DIDs and DID documents using a specific type of verifiable data registry.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This document contains examples that contain JSON, CBOR, and JSON-LD content.
Some of these examples contain characters that are invalid, such as inline
comments (//
) and the use of ellipsis (...
) to denote
information that adds little value to the example. Implementers are cautioned to
remove this content if they desire to use the information as valid JSON, CBOR,
or JSON-LD.
Some examples contain terms (both property names and values) that are not
defined in this specification, for illustrative purposes. These are indicated
with a comment (// external (property name|value)
). Such terms,
when used in a DID document, are expected to be registered in the DID
Specification Registries [DID-SPEC-REGISTRIES] with links to both a formal
definition and JSON-LD context.
Interoperability of implementations for DIDs and DID documents will be tested by evaluating an implementation's ability to create and parse DIDs and DID documents that conform to the specification. Interoperability for producers and consumers of DIDs and DID documents is provided by ensuring the DIDs and DID documents conform. Interoperability for DID method specifications is provided by the details in each DID method specification. It is understood that, in the same way that a web browser is not required to implement all known URI schemes, conformant software that works with DIDs is not required to implement all known DID methods (however, all implementations of a given DID method must be interoperable for that method).
A conforming DID is any concrete expression of the rules specified in Section § 3. Identifier which complies with relevant normative statements in that section.
A conforming DID document is any concrete expression of the data model described in this specification which complies with the relevant normative statements in Sections § 4. Data Model and § 5. Core Properties. A serialization format for the conforming document is deterministic, bi-directional, and lossless as described in Section § 6. Representations.
A conforming DID method is any specification that complies with the relevant normative statements in Section § 7. Methods.
A conforming producer is any algorithm realized as software and/or hardware and conforms to this specification if it generates conforming DIDs or conforming DID Documents. A conforming producer MUST NOT produce non-conforming DIDs or DID documents.
A conforming consumer is any algorithm realized as software and/or hardware and conforms to this specification if it consumes conforming DIDs or conforming DID documents. A conforming consumer MUST produce errors when consuming non-conforming DIDs or DID documents.
This section is non-normative.
This section defines the terms used in this specification and throughout decentralized identifier infrastructure. A link to these terms is included whenever they appear in this specification.
controller
property at the top level of the DID
document. Note that one DID controller might be the DID subject.
#
). DID fragment syntax is identical to URI fragment syntax.
/
) character and ends with either a question mark (?
)
character or a fragment hash sign (#
) character (or the end of the
DID URL). DID path syntax is identical to URI path syntax. See
§ 3.2.2 Path.
?
). DID query syntax is identical to URI query
syntax. See § 3.2.3 Query.
did:
as defined in § 3.1 DID Syntax.
Each DID method specification must define a specific DID
scheme that works with that specific DID method. In a specific DID method
scheme, the DID method name must follow the first colon and terminate with the
second colon, e.g., did:example:
/
character), optional DID query
(with its leading ?
character), and optional DID fragment
(with its leading #
character).
A set of parameters that can be used together with a process or protocol to independently verify a proof. For example, a public key can be used as a verification method with respect to a digital signature; in such usage, it verifies that the signer possessed the associated private key.
"Verification" and "proof" in this definition are intended to apply broadly. For example, a public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" or "proof."
An expression of the relationship between the DID subject and a verification method. An example of a verification relationship is § 5.2.4.1 Authentication.
In addition to the terminology above, this specification also uses terminology from the [INFRA] specification to formally define the data model. When [INFRA] terminology is used, such as string, ordered set, and map, it is linked directly to that specification.
This section describes the formal syntax for DIDs and DID URLs. The term "generic" is used to differentiate the syntax defined here from syntax defined by specific DID methods in their respective specifications.
The generic DID scheme is a URI scheme conformant with [RFC3986].
The DID scheme name MUST be an ASCII lowercase string.
The DID method name MUST be a string which consists of ASCII lowercase characters and ASCII digits.
The following is the ABNF definition using the syntax in [RFC5234], which
defines ALPHA
and DIGIT
. All other rule names not
defined in this ABNF are defined in [RFC3986].
did = "did:" method-name ":" method-specific-id method-name = 1*method-char method-char = %x61-7A / DIGIT method-specific-id = *( *idchar ":" ) 1*idchar idchar = ALPHA / DIGIT / "." / "-" / "_"
This ABNF does not currently permit an empty method-specific-id
string. Some DID methods have expressed an interest in providing
resolution of an DID with an empty method-specific-id
string,
for example to enable discovery of a DID document describing a
verifiable data registry by resolving the DID method name alone.
The Working Group is requesting feedback during the Candidate Recommendation
stage on whether or not an empty method-specific-id
string is
of interest to implementers. This feature may change as a result of that feedback.
For requirements on DID methods relating to the DID syntax, see Section § 7.1 Method Schemes.
A DID is expected to be persistent and immutable. That is, a DID is bound exclusively and permanently to its one and only subject. Even after a DID is deactivated, it is intended that it never be repurposed.
Ideally, a DID would be a completely abstract decentralized identifier (like a UUID) that could be bound to multiple underlying verifiable data registries over time, thus maintaining its persistence independent of any particular system. However, registering the same identifier on multiple verifiable data registries makes it extremely difficult to identify the authoritative version of a DID document if the contents diverge between the different verifiable data registries. It also greatly increases implementation complexity for developers.
To avoid these issues, developers should refer to the Decentralized Characteristics Rubric [DID-RUBRIC] to decide which DID method best addresses the needs of the use case.
A DID URL always identifies a resource to be located. It can be used, for example, to identify a specific part of a DID document.
This following is the ABNF definition using the syntax in [RFC5234]. It
builds on the did
scheme defined in § 3.1 DID Syntax. The
path-abempty
,
query
, and
fragment
components are identical to the ABNF rules defined in [RFC3986].
did-url = did path-abempty [ "?" query ] [ "#" fragment ]
This specification reserves the semicolon (;
) character for
possible future use as a sub-delimiter for parameters as described in
[MATRIX-URIS].
The DID URL syntax supports a simple format for parameters
based on the query
component (See § 3.2.3 Query). Adding
a DID parameter to a DID URL means that the parameter becomes part of
the identifier for a resource.
Some DID parameters are completely independent of of any specific DID method, and function the same way for all DIDs. Other DID parameters are not necessarily supported by all DID methods. Where optional parameters are supported, they are expected to operate uniformly across the DID methods that do support them. Requirements which enable this are detailed in the following table.
Parameter Name | Description |
---|---|
service
|
Identifies a service from the DID document by service ID. Support for this parameter is REQUIRED. The associated value MUST be an ASCII string. |
relativeRef
|
A relative URI reference according to RFC3986 Section 4.2
that identifies a resource at a service endpoint, which is selected from
a DID document by using the service parameter. Support for
this parameter is REQUIRED. The associated value MUST be an ASCII string and MUST use percent-encoding for certain characters
as specified in RFC3986 Section 2.1.
|
versionId
|
Identifies a specific version of a DID document to be resolved (the version ID could be sequential, or a UUID, or method-specific). Support for this parameter is OPTIONAL. If present, the associated value MUST be an ASCII string. |
versionTime
|
Identifies a certain version timestamp of a DID document to be resolved. That is, the DID document that was valid for a DID at a certain time. Support for this parameter is OPTIONAL. If present, the associated value MUST be an ASCII string which is a valid XML datetime value, as defined in section 3.3.7 of W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes [XMLSCHEMA11-2]. This datetime value MUST be normalized to UTC 00:00, as indicated by the trailing "Z". |
hl
|
A resource hash of the DID document to add integrity protection, as specified in [HASHLINK]. This parameter is non-normative. Support for this parameter is OPTIONAL. If present, the associated value MUST be an ASCII string. |
resource
|
Indicates that the resource to be dereferenced is the DID Subject, rather
than the DID Document. This parameter is used to retrieve an information
resource identified by a DID. Support for this parameter is OPTIONAL.
If present, the associated value MUST be the
ASCII string true .
|
Implementers as well as DID method specification authors might use additional DID parameters that are not listed here. For maximum interoperability, it is RECOMMENDED that DID parameters use the official W3C DID Specification Registries mechanism [DID-SPEC-REGISTRIES], to avoid collision with other uses of the same DID parameter with different semantics.
DID parameters might be used if there is a clear use case where the parameter needs to be part of a URI that can be used as a link, or as a resource in RDF / JSON-LD documents.
It is expected that DID parameters will not be used if the same functionality can be expressed by passing input metadata to a DID resolver.
Additional considerations for processing these parameters are discussed in [DID-RESOLUTION].
Some example DID URLs using DID parameters are shown below.
did:foo:21tDAKCERh95uGgKbJNHYp?service=agent
did:foo:21tDAKCERh95uGgKbJNHYp?versionTime=2002-10-10T17:00:00Z
did:foo:21tDAKCERh95uGgKbJNHYp?resource=true
The DID resolution and the DID URL dereferencing functions can be influenced by passing input metadata to a DID resolver that are not part of the DID URL. (See § 8.1.1 DID Resolution Input Metadata Properties). This is comparable to HTTP, where certain parameters could either be included in an HTTP URL, or alternatively passed as HTTP headers during the dereferencing process. The important distinction is that DID parameters that are part of the DID URL should be used to specify what resource is being identified, whereas input metadata that is not part of the DID URL should be use to control how that resource is resolved or dereferenced.
A DID path is identical to a generic URI path and MUST conform to the
path-abempty
ABNF rule in
[RFC3986].
A DID method specification MAY specify ABNF rules for DID paths that are more restrictive than the generic rules in this section.
did:example:123456/path
A DID query is derived from a generic URI query and MUST conform to the
did-query
ABNF rule in Section §
3.2 DID URL Syntax. If a DID query is present, it MUST be used
as described in Section § 3.2.1 DID Parameters.
A DID method specification MAY specify ABNF rules for DID queries that are more restrictive than the generic rules in this section.
did:example:123456?query=true
A DID fragment is used as method-independent reference into a DID document or external resource.
DID fragment syntax and semantics are identical to a generic URI fragment and MUST conform to RFC 3986, section 3.5.
For information about how to dereference a DID fragment, see § 8.2 DID URL Dereferencing.
A DID method specification MAY specify ABNF rules for DID fragments that are more restrictive than the generic rules in this section.
In order to maximize interoperability, implementers are urged to ensure that DID fragments are interpreted in the same way across representations (as described in § 6. Representations). For example, while JSON Pointer [RFC6901] can be used in a DID fragment, it will not be interpreted in the same way across representations.
For example:
did:example:123#public-key-0
did:example:123#agent
did:example:123?service=agent&relativeRef=/credentials#degree
Additional semantics for fragment identifiers, which are compatible with and layered upon the semantics in this section, are described for JSON-LD representations in Section § B.2 application/did+ld+json.
A relative DID URL is any URL value in a DID document that does not start
with did:<method-name>:<method-specific-id>
. More
specifically, it is any URL value that does not start with the ABNF defined in
Section § 3.1 DID Syntax. The contents of the URL typically
refers to a resource in the same DID document. Relative DID URLs
MAY contain relative path components, query parameters, and fragment
identifiers.
When resolving a relative DID URL reference, the algorithm specified in RFC3986 Section 5: Reference Resolution MUST
be used. The base URI value is the DID that is
associated with the DID subject, see Section § 5.2.1 DID Subject.
The scheme is did
. The authority
is a combination of <method-name>:<method-specific-id>
, and
the path, query, and fragment
values are those defined in Section § 3.2.2 Path, Section § 3.2.3 Query, and Section § 3.2.4 Fragment, respectively.
Relative DID URLs are often used to identify verification methods and services in a DID Document without having to use absolute URLs, which tend to be more verbose than necessary.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", "verificationMethod": [{ "id": "did:example:123456789abcdefghi#key-1", "type": "Ed25519VerificationKey2018", // external (property value) "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" }, ...], "authentication": [ // a relative DID URL used to reference a verification method above "#key-1" ] }
In the example above, the relative DID URL value will be transformed to an
absolute DID URL value of did:example:123456789abcdefghi#key-1
.
This specification defines a data model for DID documents that is capable of being serialized into multiple concrete representations. This section provides a high-level description of the data model, how different types of properties are expressed in the data model, and instructions for extending the data model.
A DID document consists of a map of entries, where each entry consists of an entry key/entry value pair. The data model contains at least two different classes of entries. The first class of entries are called properties, and are specified in section § 5. Core Properties. The second class are representation-specific entries, and are specified in section § 6. Representations.
All entry keys in the data model are strings. All entry values are expressed using one of the abstract data types in the table below while each representation specifies the concrete serialization format of each data type.
Data Type | Considerations |
---|---|
ordered map | A finite ordered sequence of key/value pairs, with no key appearing twice as specified in [INFRA]. |
list | A finite ordered sequence of items as specified in [INFRA]. |
ordered set | A finite ordered sequence of items that does not contain the same item twice as specified in [INFRA]. |
datetime |
A date and time value that is capable of losslessly expressing all values
expressible by a dateTime as specified in
[XMLSCHEMA11-2].
|
string | A sequence of code units often used to represent human readable language as specified in [INFRA]. |
integer | A real number without a fractional component as specified in [XMLSCHEMA11-2]. To maximize interoperability, implementers are urged to heed the advice regarding integers in RFC7159, Section 6: Numbers. |
double | A value that is often used to approximate arbitrary real numbers as specified in [XMLSCHEMA11-2]. To maximize interoperability, implementers are urged to heed the advice regarding doubles in RFC7159, Section 6: Numbers. |
boolean | A value that is either true or false as defined in [INFRA]. |
null | A value that is used to indicate the lack of a value as defined in [INFRA]. |
The data model supports two types of extensibility.
It is always possible for two specific implementations to agree out-of-band to use a mutually understood extension or representation that is not recorded in the DID Core Registries [DID-SPEC-REGISTRIES]; interoperability between such implementations and the larger ecosystem will be less reliable.
A DID points to a DID document. DID documents are the serialization of the data model. The following sections define the properties in a DID document, including whether these properties are required or optional. These properties describe relationships between the DID subject and the value of the property.
This document defines three classes of core properties:
Some of the properties (e.g., id
or type
) are present in different classes but with possible differences in the associated constraints. Hence their repeated presence in the tables in Section § 5.1 Property Summary.
As a result of the data model being defined using terminology from [INFRA], property values which can contain more than one item, such as maps and sets, are explicitly ordered. For the purposes of this specification, unless otherwise stated, ordering is not important and implementations are not expected to produce or consume deterministically ordered values.
Property | Usage constraints | Value constraints |
---|---|---|
id |
REQUIRED | A string that conforms to the rules in Section § 3.1 DID Syntax. |
alsoKnownAs |
OPTIONAL | An ordered set of strings that conform to the rules of [RFC3986] for URIs. |
controller |
OPTIONAL | A string or an ordered set of strings that conform to the rules in Section § 3.1 DID Syntax. |
verificationMethod |
OPTIONAL |
An ordered set of either Verification Method maps (see § 5.1.2 Core Properties for a Verification Method) or strings that conform to the rules of [RFC3986] for URIs. The URI values SHOULD also conform to the rules in Section § 3.2 DID URL Syntax. |
authentication |
OPTIONAL |
An ordered set of either Verification Method maps (see § 5.1.2 Core Properties for a Verification Method) or strings that conform to the rules of [RFC3986] for URIs. The URI values SHOULD also conform to the rules in Section § 3.2 DID URL Syntax. |
assertionMethod |
OPTIONAL |
An ordered set of either Verification Method maps (see § 5.1.2 Core Properties for a Verification Method) or strings that conform to the rules of [RFC3986] for URIs. The URI values SHOULD also conform to the rules in Section § 3.2 DID URL Syntax. |
keyAgreement |
OPTIONAL |
An ordered set of either Verification Method maps (see § 5.1.2 Core Properties for a Verification Method) or strings that conform to the rules of [RFC3986] for URIs. The URI values SHOULD also conform to the rules in Section § 3.2 DID URL Syntax. |
capabilityInvocation |
OPTIONAL |
An ordered set of either Verification Method maps (see § 5.1.2 Core Properties for a Verification Method) or strings that conform to the rules of [RFC3986] for URIs. The URI values SHOULD also conform to the rules in Section § 3.2 DID URL Syntax. |
capabilityDelegation |
OPTIONAL |
An ordered set of either Verification Method maps (see § 5.1.2 Core Properties for a Verification Method) or strings that conform to the rules of [RFC3986] for URIs. The URI values SHOULD also conform to the rules in Section § 3.2 DID URL Syntax. |
service |
OPTIONAL | An ordered set of Service maps (see § 5.1.3 Core Properties for a Service). |
Property | Usage constraints | Value constraints |
---|---|---|
id |
REQUIRED | A string that conforms to the rules of [RFC3986] for URIs and which SHOULD also conform to the rules in Section § 3.2 DID URL Syntax. |
controller |
REQUIRED | A string or an ordered set of strings that conform to the rules in Section § 3.1 DID Syntax. |
type |
REQUIRED | A string or an ordered set of strings. |
publicKeyJwk |
OPTIONAL | A map representing a JSON Web Key that conforms to [RFC7517]. This value MUST NOT contain "d", or any other members of the private information class as described in Registration Template. |
publicKeyBase58 |
OPTIONAL | A string that conforms to a base58btc encoded public key. |
As an extra constraint on the publicKeyJwk
and publicKeyBase58
properties, while both of these properties are OPTIONAL, a particular Verification Method MUST contain exactly one of the two.
Property | Usage constraints | Value constraints |
---|---|---|
id |
REQUIRED | when used on a Service: a string that conforms to the rules of [RFC3986] for URIs. |
type |
REQUIRED | A string or an ordered set of strings. |
|
OPTIONAL | A string that conform to the rules of [RFC3986] for URIs, a map, or an ordered set composed of a one or more strings that conform to the rules of [RFC3986] for URI-s and/or maps. |
The DID subject is the entity that the DID document is about. That is, it is the entity identified by the DID and described by the DID document.
The DID for a particular DID subject is denoted with the
id
property in the DID document.
DID documents MUST include the id
property in the
the topmost map in the
data model.
id
MUST be a string that conforms to the rules in Section § 3.1 DID Syntax.
{ "id": "did:example:21tDAKCERh95uGgKbJNHYp" }
DID method specifications can create intermediate representations of a
DID document that do not contain the id
property,
such as when a DID resolver is performing DID resolution.
However, the fully resolved DID document always contains a valid
id
property. The value of id
in the
resolved DID document MUST match the DID that was
resolved.
A DID document can contain objects which have their own unique
identifier; see, for example, § 5.2.3 Verification Methods. Such other
objects also use the id
property to denote the identifier of
the object in question. The id
property only denotes the
DID of the DID subject when it is present at the top
level of a DID document.
A DID subject can have multiple identifiers for different purposes, or
at different times. The assertion that two or more DIDs (or other types
of URI) identify the same DID subject can be made using the
alsoKnownAs
property.
DID documents MAY include the alsoKnownAs
property.
alsoKnownAs
MUST be an
ordered set where each item in the set is a
URI conforming to [RFC3986].
Applications might choose to consider two identifiers related by
alsoKnownAs
to be equivalent if the
alsoKnownAs
relationship is reciprocated in the reverse
direction. It is best practice not to consider them equivalent in the
absence of this inverse relationship. In other words, the presence of an
alsoKnownAs
assertion does not prove that this assertion
is true. Therefore it is strongly advised that a requesting party obtain
independent verification of an alsoKnownAs
assertion.
Given that the DID subject might use different identifiers for different purposes, an expectation of strong equivalence between the two identifiers, or merging the graphs of the two corresponding DID documents, is not necessarily appropriate, even with a reciprocal relationship.
A DID controller is an entity that is authorized to make changes to a DID document. The process of authorizing a DID controller is defined by the DID Method.
A DID document MAY include a controller
property to
indicate the DID controller(s). If so:
controller
property MUST be a string or an ordered set of strings that conform to the rules in Section § 3.1 DID Syntax. The corresponding DID document(s) SHOULD
contain verification relationships that explicitly permit the use of
certain verification methods for specific purposes.
When a controller
property is present in a
DID Document, its value expresses one or more DIDs. Any
verification methods contained in the DID Documents for those
DIDs SHOULD be accepted as authoritative, such that proofs that satisfy
those verification methods are to be considered equivalent to proofs provided
by the DID Subject.
Note that Authorization is separate from § 5.2.4.1 Authentication. This is particularly important for key recovery in the case of cryptographic key loss, when the subject no longer has access to their keys, or key compromise, where the DID controller's trusted third parties need to override malicious activity by an attacker. See Section § 9. Security Considerations.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", "controller": "did:example:bcehfew7h32f32h7af3", "service": [{ // used to retrieve Verifiable Credentials associated with the DID "type": "VerifiableCredentialService",// external (property value) "serviceEndpoint": "https://example.com/vc/" }] }
A DID document can express verification methods, such as cryptographic keys, which can be used to authenticate or authorize interactions with the DID subject or associated parties. The information expressed often includes globally unambiguous identifiers and public key material, which can be used to verify digital signatures. For example, a public key can be used as a verification method with respect to a digital signature; in such usage, it verifies that the signer possessed the associated private key.
Verification methods might take many parameters. An example of this is a set of five cryptographic keys from which any three are required to contribute to a threshold signature. Methods need not be cryptographic.
In order to maximize interoperability, support for public keys as verification methods is restricted: see § 5.2.3.1 Verification method types. For other types of verification method, the verification method SHOULD be registered in the [DID-SPEC-REGISTRIES].
A DID document MAY include a verificationMethod
property.
If a DID document includes a verificationMethod
property,
the value of the property MUST be an ordered
set of verification methods, where each verification method is described by
a map containing properties. The properties
MUST include the id
, type
, controller
,
and specific verification method properties, and MAY include additional
properties.
The value of the id
property for a verification method MUST
be a URI. When more than one verification method is present, the value of
verificationMethod
MUST NOT contain multiple entries with
the same id
. If the value of verificationMethod
contains multiple entries with the same id
, a DID document
processor MUST produce an error.
In the case where a verification method is a public key, the value of the
id
property might be structured as a
compound key. This is
especially useful for integrating with existing key management systems and key
formats such as JWK [RFC7517]. It is RECOMMENDED that JWK kid
values are set to the public key fingerprint [RFC7638]. It is RECOMMENDED
that verification methods that use JWKs to represent their public keys utilize
the value of kid
as their fragment identifier. See the first key
in Example 16
for an example of a public key with a compound key identifier.
The value of the type
property MUST be exactly one verification
method type. In order to maximize global interoperability, the
verification method type SHOULD be registered in the
[DID-SPEC-REGISTRIES].
The value of the controller
property MUST be a string that conforms to the rules in Section § 3.1 DID Syntax.
A verification method MUST contain verification material, such as publicKeyJwk or publicKeyBase58.
A verification method MUST NOT contain multiple verification material
properties for the same material. For example, expressing key material in a
verification method using both publicKeyJwk
and
publicKeyBase58
at the same time is prohibited.
The semantics of the controller
property are the same when the
subject of the relationship is the DID document as when the subject
of the relationship is a verification method, such as a public key. Since a
key (for example) can't control itself, and the key controller cannot be
inferred from the DID document, it is necessary to explicitly express
the identity of the controller of the key. The difference is that the value of
controller
for a verification method is not necessarily
a DID controller. DID controller(s) are expressed using the
controller
property at the highest level of the
DID document (the topmost map in
the data model); see
§ 5.2.2 DID Controller.
{
"@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/v1"],
"id": "did:example:123456789abcdefghi",
...
"verificationMethod": [{
"id": ...,
"type": ...,
"controller": ...,
"publicKeyJwk": ...
}, {
"id": ...,
"type": ...,
"controller": ...,
"publicKeyBase58": ...
}]
}
As well as the verificationMethod
property, verification
methods can be embedded in or referenced from properties associated with
various verification relationships (see
§ 5.2.4 Verification Relationships). Referencing verification methods
allows them to be used with more than one verification relationship.
The steps to use when processing a verification method in a DID document are:
verificationMethod
property or property for a particular
verification relationship and initialize result to
null
.
verificationMethod
properties associated with the URL. For example, process the
verificationMethod
property in the topmost
map of the dereferenced document.
id
property of the
object matches value, set result to the object.
id
,
type
, and controller
properties, as well as any
mandatory public cryptographic material, as determined by the type
property of result, throw an error.
{ ... "authentication": [ // this key is referenced, it may be used with more than one verification relationship "did:example:123456789abcdefghi#keys-1", // this key is embedded and may *only* be used for authentication { "id": "did:example:123456789abcdefghi#keys-2", "type": "Ed25519VerificationKey2018", // external (property value) "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" } ], ... }
A public key can be used as a verification method.
This specification strives to limit the number of formats for expressing public key material in a DID document to the fewest possible, to increase the likelihood of interoperability. The fewer formats that implementers have to implement, the more likely it will be that they will support all of them. This approach attempts to strike a delicate balance between ease of implementation and supporting formats that have historically had broad deployment.
A suite definition is responsible for specifying the verification method
type
and proof type
. For example, see
JSON Web Signature 2020 and
Ed25519 Signature 2018
. For all registered and supported verification method types available for DIDs,
please see [DID-SPEC-REGISTRIES].
{ "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/v1"], "id": "did:example:123456789abcdefghi", ... "verificationMethod": [{ "id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A", "type": "JsonWebKey2020", // external (property value) "controller": "did:example:123", "publicKeyJwk": { "crv": "Ed25519", // external (property name) "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ", // external (property name) "kty": "OKP", // external (property name) "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A" // external (property name) } }, { "id": "did:example:123456789abcdefghi#keys-1", "type": "Ed25519VerificationKey2018", // external (property value) "controller": "did:example:pqrstuvwxyz0987654321", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" }], ... }
The DID document does not express revoked keys using a verification relationship.
If a referenced verification method is not in the DID Document used to dereference it, then that verification method is considered invalid or revoked.
Each DID method specification is expected to detail how revocation is performed and tracked.
Caching and expiration of the keys in a DID document is entirely the responsibility of DID resolvers and requesting parties. For more information, see Section § 8. Resolution.
A verification relationship expresses the relationship between the DID subject and a verification method.
Different verification relationships enable the associated verification methods to be used for different purposes. It is up to a verifier to ascertain the validity of a verification attempt by checking that the verification method used is contained in the appropriate verification relationship property of the DID Document.
The verification relationship between the DID subject and the
verification method is explicit in the DID document.
Verification methods that are not associated with a particular
verification relationship cannot be used for that verification
relationship. For example, a verification method in the value of
the authentication
property cannot be used to engage in
key agreement protocols with the DID subject—the value of the
keyAgreement
property needs to be used for that.
This specification defines several verification relationships below. A DID document MAY include any of these, or other properties, to express a specific verification relationship. In order to maximize global interoperability, any such properties used SHOULD be registered in [DID-SPEC-REGISTRIES].
The authentication
verification relationship is used to specify how the
DID subject is expected to be authenticated, such as for the purposes of
logging into a website.
authentication
property is OPTIONAL. If present, the associated
value MUST be an ordered set of one or more
verification methods. Each verification method MAY be embedded or
referenced.
If authentication is established, it is up to the DID method or other application to decide what to do with that information. A particular DID method could decide that authenticating as a DID controller is sufficient to, for example, update or delete the DID document. Another DID method could require different keys, or a different verification method entirely, to be presented in order to update or delete the DID document than that used to authenticate. In other words, what is done after the authentication check is out of scope for the data model, but DID methods and applications are expected to define this themselves.
This is useful to any authentication verifier that needs
to check to see if an entity that is attempting to authenticate is, in
fact, presenting a valid proof of authentication. When a verifier
receives some data (in some protocol-specific format) that contains a proof
that was made for the purpose of "authentication", and that says that an
entity is identified by the DID, then that verifier checks to
ensure that the proof can be verified using a verification method (e.g.,
public key) listed under authentication
in the
DID Document.
Note that the verification method indicated by the
authentication
property of a DID document can only
be used to authenticate the DID subject. To authenticate
a different DID controller, the entity associated with the value of
controller
(see Section § 5.2.2 DID Controller) needs to
authenticate with its own DID document and attached
authentication
verification relationship.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", ... "authentication": [ // this method can be used to authenticate as did:...fghi "did:example:123456789abcdefghi#keys-1", // this method can be used to authenticate as did:...fghi "did:example:123456789abcdefghi#biometric-1", // this method is *only* approved for authentication, it may not // be used for any other proof purpose, so its full description is // embedded here rather than using only a reference { "id": "did:example:123456789abcdefghi#keys-2", "type": "Ed25519VerificationKey2018", // external (property value) "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" } ], ... }
The assertionMethod
verification relationship is used to specify how
the DID subject is expected to express claims, such as for the purposes
of issuing a Verifiable Credential [VC-DATA-MODEL].
assertionMethod
property is OPTIONAL. If present, the
associated value MUST be an ordered set of
one or more verification methods. Each verification method MAY be
embedded or referenced.
An example of when this property is useful is during the processing of a
verifiable credential by a verifier. During validation, a verifier checks to
see if a verifiable credential has been signed by the DID Subject by
checking that the verification method used to assert the proof is
associated with the assertionMethod
property in the
corresponding DID Document.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", ... "assertionMethod": [ // this method can be used to assert statements as did:...fghi "did:example:123456789abcdefghi#keys-1", // this method is *only* approved for assertion of statements, it may not // be used for any other verification relationship, so its full description is // embedded here rather than using only a reference { "id": "did:example:123456789abcdefghi#keys-2", "type": "Ed25519VerificationKey2018", // external (property value) "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" } ], ... }
The keyAgreement
verification relationship is used to specify how
to encrypt information to the DID subject, such as for the purposes
of establishing a secure communication channel with the recipient.
keyAgreement
property is OPTIONAL. If present, the associated
value MUST be an ordered set of one or more
verification methods. Each verification method MAY be embedded or
referenced.
An example of when this property is useful is when encrypting a message intended for the DID Subject. In this case, the counterparty uses the public cryptographic key information in the verification method to wrap a decryption key for the recipient.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", ... "keyAgreement": [ // this method can be used to perform key agreement as did:...fghi "did:example:123456789abcdefghi#keys-1", // this method is *only* approved for key agreement usage, it may not // be used for any other verification relationship, so its full description is // embedded here rather than using only a reference { "id": "did:example:123#zC9ByQ8aJs8vrNXyDhPHHNNMSHPcaSgNpjjsBYpMMjsTdS", "type": "X25519KeyAgreementKey2019", // external (property value) "controller": "did:example:123", "publicKeyBase58": "9hFgmPVfmBZwRvFEyniQDBkz9LmV7gDEqytWyGZLmDXE" } ], ... }
The capabilityInvocation
verification relationship is used to specify
a verification method that might be used by the DID subject to
invoke a cryptographic capability, such as the authorization to update the
DID Document or the authorization to access an HTTP API.
capabilityInvocation
property is OPTIONAL. If present, the
associated value MUST be an ordered set of
one or more verification methods. Each verification method MAY be
embedded or referenced.
An example of when this property is useful is when a DID subject
chooses to invoke their capability to start a vehicle through the combined
usage of a verification method and the StartCar
capability. In this example, the vehicle would be the verifier and
would need to verify that the verification method exists in the
capabilityInvocation
property.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", ... "capabilityInvocation": [ // this method can be used to invoke capabilities as did:...fghi "did:example:123456789abcdefghi#keys-1", // this method is *only* approved for capability invocation usage, it may not // be used for any other verification relationship, so its full description is // embedded here rather than using only a reference { "id": "did:example:123456789abcdefghi#keys-2", "type": "Ed25519VerificationKey2018", // external (property value) "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" } ], ... }
The capabilityDelegation
verification relationship is used to specify
a mechanism that might be used by the DID subject to delegate
a cryptographic capability to another party, such as delegating the
authority to access a specific HTTP API to a subordinate.
capabilityDelegation
property is OPTIONAL. If present, the
associated value MUST be an ordered set of
one or more verification methods. Each verification method MAY be
embedded or referenced.
An example of when this property is useful is when a DID Subject
chooses to grant their capability to start a vehicle through the combined
usage of a verification method and the StartCar
capability
to a party other than themselves.
{ "@context": "https://www.w3.org/ns/did/v1", "id": "did:example:123456789abcdefghi", ... "capabilityDelegation": [ // this method can be used to perform capability delegation as did:...fghi "did:example:123456789abcdefghi#keys-1", // this method is *only* approved for granting capabilities it may not // be used for any other verification relationship, so its full description is // embedded here rather than using only a reference { "id": "did:example:123456789abcdefghi#keys-2", "type": "Ed25519VerificationKey2018", // external (property value) "controller": "did:example:123456789abcdefghi", "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" } ], ... }
Services are used in DID documents to express ways of communicating with the DID subject or associated entities. Services listed in the DID document can contain information about privacy preserving messaging services, or more public information, such as social media accounts, personal websites, and email addresses although this is discouraged. See § 10.1 Keep Personally-Identifiable Information (PII) Private for additional details. The information associated with services are often service-specific. For example, the information associated with an encrypted messaging service can express how to initiate the encrypted link before messaging begins.
Pointers to services are expressed using the service
property. Each service has its own id
and type
properties, as well as a
property with a
URI or a set of other properties describing the service.
serviceEndpoint
One of the primary purposes of a DID document is to enable discovery of services. A services can be any type of service the DID subject wants to advertise, including decentralized identity management services for further discovery, authentication, authorization, or interaction.
A DID document MAY include a service
property.
If a DID document includes a service
property, the value
of the property MUST be an ordered set
of services, where each service is described by a set
of properties. Each service MUST have id
,
type
, and
properties, and MAY
include additional properties.
serviceEndpoint
The value of the id
property MUST be a URI.
The value of service
MUST NOT contain multiple entries with the
same id
. In this case, a DID document processor MUST
produce an error.
The value of the serviceEndpoint
property MUST be a
string, a map,
or an ordered set composed of a one or more
strings and/or
maps. All string
values MUST be valid URIs conforming to [RFC3986] and normalized
according to the rules in section 6 of [RFC3986] and to any normalization
rules in its applicable URI scheme specification. Extension
specifications for services MAY further restrict the properties associated
with the extension.
It is expected that the service protocol is published in an open standard specification.
{ "service": [{ "id":"did:example:123#linked-domain", "type": "LinkedDomains", // external (property value) "serviceEndpoint": "https://bar.example.com" }, { "id": "did:example:123456789abcdefghi#openid", "type": "OpenIdConnectVersion1.0Service", // external (property value) "serviceEndpoint": "https://openid.example.com/" }, { "id": "did:example:123456789abcdefghi#vcr", "type": "CredentialRepositoryService", // external (property value) "serviceEndpoint": "https://repository.example.com/service/8377464" }, { "id": "did:example:123456789abcdefghi#xdi", "type": "XdiService", // external (property value) "serviceEndpoint": "https://xdi.example.com/8377464" }, { "id": "did:example:123456789abcdefghi#agent", "type": "AgentService", // external (property value) "serviceEndpoint": "https://agent.example.com/8377464" }, { "id": "did:example:123456789abcdefghi#messages", "type": "MessagingService", // external (property value) "serviceEndpoint": "https://example.com/messages/8377464" }, { "id": "did:example:123456789abcdefghi#inbox", "type": "SocialWebInboxService", // external (property value) "serviceEndpoint": "https://social.example.com/83hfh37dj", "description": "My public social inbox", // external (property name) "spamCost": { // external (property name) "amount": "0.50", // external (property name) "currency": "USD" // external (property name) } }, { "id": "did:example:123456789abcdefghi#authpush", "type": "DidAuthPushModeVersion1", // external (property value) "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefg" }] }
For more information about security considerations regarding authentication services see Sections § 7.1 Method Schemes and § 5.2.4.1 Authentication.
All concrete representations of a DID document are serialized using a deterministic mapping that is able to be unambiguously parsed into the data model defined in this specification. All serialization methods MUST define rules for the bidirectional translation of a DID document both into and out of the representation in question. An implementation MUST NOT convert between representations without first parsing to a data model (described in Sections § 4. Data Model and § 5. Core Properties); translation between any two representations is done by parsing the source representation into the data model and then serializing the data model into the target representation.
Although syntactic mappings are provided for JSON, JSON-LD, and CBOR here, applications and services MAY use any other data representation syntax that is capable of expressing the data model, such as XML or YAML.
Producers MUST indicate which representation of a document has been used via a
media type in the document's metadata. Consumers MUST determine the
representation of a DID document via the contentType
DID
resolver metadata field (see § 8.1 DID Resolution), not
through the content of the DID document alone.
Unrecognized entries in the data model MUST be preserved. An unrecognized entry is any entry that does not have explicit processing rules known to the consumer or producer. Consumers MUST add all entries that do not have explicit processing rules for the representation being consumed to the data model using only the representation's generic type processing rules. Producers MUST serialize all entries in the data model that do not have explicit processing rules for the representation being produced using only the representation's generic type processing rules.
Note that entries that contain representation-specific syntax will only have special processing rules defined by a single representation. Consumers of a different representation are required to include these entries in the data model using only their generic type processing rules to enable lossless conversion of representations. Similarly, producers are required to treat entries containing representation-specific syntax using generic type processing rules when producing a representation for which the entry is not defined. Representations are required to define producer behavior for any such entries defined by the representation.
It is RECOMMENDED that representations use the lexical representation of registered data types. For example, JSON and JSON-LD use the XML Schema dateTime lexical representation to represent datetimes. A representation MAY choose to represent the data types differently. For example, some CBOR-based representations express datetime values using integers to represent the number of seconds since the Unix epoch.
The production and consumption rules in this section apply to all implementations seeking to be fully compatible with independent implementations of the specification. Deployments of this specification MAY use a custom agreed-upon representation, including rules agreed to by a pair of producers and consumers for handling properties not listed in the registry. See section § 4.1 Extensibility for more information.
The data model provided in this specification supports being serialized into a variety of existing representations. Some applications might require the creation of a new representation. All representations require the following:
In order to maximize interoperability, representation specification authors SHOULD register their representation in the [DID-SPEC-REGISTRIES].
This section sets out the requirements for producing and consuming DID
documents that are in plain JSON (as indicated by a
contentType
of application/did+json
in the resolver
metadata).
A DID document MUST be a single JSON object conforming to [RFC8259]. All entries of the DID document data model described in § 4. Data Model MUST be represented by using the entry key as the name of the member of the JSON object. The values of entries, including all extensions, are encoded in JSON [RFC8259] by mapping entry values to JSON types as follows:
Data Type | JSON Representation Type |
---|---|
ordered map | JSON Object, each entry is represented as a member of the JSON Object with the entry key as the member name and the entry value according to its type, as defined in this section |
list | JSON Array, each element of the list is added, in order, as a value of the array according to its type, as defined in this section |
ordered set | JSON Array, each element of the set is added, in order, as a value of the array according to its type, as defined in this section |
datetime |
JSON String formatted as an
XML Datetime normalized to
UTC 00:00:00 and without sub-second decimal precision. For example:
2020-12-20T19:17:47Z .
|
string | JSON String |
integer | JSON Number without a decimal or fractional component |
double | JSON Number with a fractional component |
boolean | JSON Boolean |
null | JSON null literal |
Implementers producing JSON are advised to ensure that their algorithms are aligned with the JSON serialization rules in the [INFRA] specification.
All entries of the DID document MUST be included in the root object. Entries MAY define additional data sub structures subject to the value representation rules in the list above.
The topmost element MUST be a JSON object. Any other data type at the topmost level is an error and MUST be rejected. The topmost JSON object represents the DID document, and all members of this object are entries of the DID document. The object member name is the entry key, and the member value is interpreted as follows:
JSON Representation Type | Data Type |
---|---|
JSON Object | ordered map, each member of the JSON Object is added as an entry to the ordered map with the entry key being the member name and the value converted based on the JSON type and, if available, entry definition, as defined here; as no order is specified by JSON Objects, no insertion order is guaranteed |
JSON Array where data model entry value is a list or unknown | list, each value of the JSON Array is added to the list in order, converted based on the JSON type of the array value, as defined here |
JSON Array where data model entry value is an ordered set | ordered set, each value of the JSON Array is added to the ordered set in order, converted based on the JSON type of the array value, as defined here |
JSON String where data model entry value is an datetime | datetime |
JSON String, where data model entry value type is string or unknown | string |
JSON Number without a decimal or fractional component | integer |
JSON Number with a fractional component, or when entry value is a double regardless of inclusion of fractional component | double |
JSON Boolean | boolean |
JSON null literal | null |
Implementers consuming JSON are advised to ensure that their algorithms are aligned with the JSON consumption rules in the [INFRA] specification.
Note that the @context
object member, if present, will not have
additional processing applied to its value, which will be added verbatim to the
data model.
JSON-LD is a JSON-based format used to serialize
Linked Data.
This section establishes the requirements for producing and consuming DID
documents that are expressed as JSON-LD. JSON-LD DID documents
are indicated by a contentType
resolver metadata field that is
set to application/did+ld+json
.
Use of the media type application/did+ld+json
is pending
clarification over the registration of
media types with multiple suffixes. The alternative will be to use
application/ld+json
with an expected profile parameter of
https://www.w3.org/ns/did/json-ld-profile
if multiple suffixes
cannot be registered by the time the rest of DID Core is ready for W3C
Proposed Recommendation.
The following application-specific modifications are made by this specification to the JSON-LD specification [JSON-LD11] to ease interoperability between JSON and JSON-LD implementations:
@id
and @type
keywords are aliased to
id
and type
respectively, enabling developers
to use this specification as idiomatic JSON.
id
that refers to the DID subject MUST be a valid
DID and not any other kind of IRI.
The DID document MUST be serialized according to the
production rules for JSON, with one additional
requirement: The DID document MUST include the @context
entry.
The JSON-LD
specification defines values that are valid for this entry. This entry
contains representation-specific syntax and therefore could be present in the data model to aid in lossless conversion. If the entry
is present in the data model, it MUST be used during
production unless either an alternative @context
value is
explicitly provided to the producer or if the value from the data model is not
valid according to the consumption rules.
The value of @context
MUST be exactly one of these values.
https://www.w3.org/ns/did/v1
.
{
"@context": "https://www.w3.org/ns/did/v1",
...
}
https://www.w3.org/ns/did/v1
, and subsequent items of
type INFRA string or
INFRA map.
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://example.com/blockchain-identity/v1"
],
...
}
All members of the @context
entry SHOULD exist in the DID
specification registries [DID-SPEC-REGISTRIES] in order to achieve
interoperability across different representations. If a member does not exist
in the DID specification registries, then the DID document might not be
interoperable across representations.
It is RECOMMENDED that dereferencing each URI value of the
@context
entry results in a document containing
machine-readable information about the context. Note that further expectations
of additional JSON-LD contexts are described as part of the DID specification
registries registration process.
Producers SHOULD NOT produce DID documents that contain properties not
defined via the @context
. Properties that are not defined via the
@context
MAY be dropped by Consumers.
The DID document MUST be deserialized as a JSON document according to
the consumption rules for JSON, with one additional
requirement: The DID document MUST include the @context
entry and be processed according to the rules below.
The value of the @context
entry conforms to the
JSON-LD Production Rules. If more than one
URI is provided, the URIs MUST be interpreted as an
ordered set.
Consumers SHOULD drop all properties from a DID document that are not
defined via the @context
.
Like Javascript Object Notation (JSON) [RFC8259], Concise Binary Object Representation (CBOR) [RFC7049] defines a set of formatting rules for the portable representation of structured data. CBOR is a more concise, machine-readable, language-independent data interchange format that is self-describing and has built-in semantics for interoperability.
The following sections outline the rules for producing and consuming
DID documents that are expressed in CBOR as indicated by a
contentType
of application/did+cbor
in the resolver
metadata.
A DID document MUST be a single CBOR Map conforming to [RFC7049]. All topmost entries of the DID document MUST be represented by using the entry key as the name of the key of the CBOR Map. The values of entries of the data model described in Section § 4. Data Model, including all extensions, are encoded in CBOR [RFC7049] by mapping entry values to CBOR types as follows:
Data Type | CBOR Representation Type |
---|---|
ordered map | CBOR map (major type 5), each entry is represented as a member of the CBOR Map with the entry key as the key and the entry value according to its type, as defined in this section |
list | CBOR array (major type 4), each element of the list is added, in order, as a value of the array according to its type, as defined in this section |
ordered set | CBOR array (major type 4), each element of the list is added, in order, as a value of the array according to its type, as defined in this section |
datetime |
CBOR string (major type 5) formatted as
an XML Datetime normalized to
UTC 00:00 and without sub-second decimal precision. For example:
2020-12-20T19:17:47Z .
|
string | CBOR string (major type 5) |
integer | CBOR integer (major type 0 or 1), choosing the shortest byte representation |
double | CBOR floating-point number (major type 7). All floating point values MUST be encoded as 64-bits (additional type value 27), even for integral values. |
boolean | CBOR simple value (major type 7, subtype 24) with a simple value of 21 (True) or 20 (False) |
null | CBOR simple value (major type 7, subtype 24) with a simple value of 22 (Null) |
To produce a deterministic canonical CBOR representation of a DID document and faciliate maximal lossless compatiblity with other core representations via the Abstract Data Model the following constraints of a CBOR representation of a DID Document model MUST be followed:
All entries of the DID document represented in CBOR MUST be included in the root map (major type 5). Entries MAY define additional data sub structures represented as nested CBOR maps (major type 5) and is subject to the value representation rules in the lists above and conformance to section § 4.3 Extensibility.
A2626964781E6469643A6578616D706C653A313233343536373839616263 6465666768696E61757468656E7469636174696F6E81A462696478256469 643A6578616D706C653A313233343536373839616263646566676869236B 6579732D316474797065781A45643235353139566572696669636174696F 6E4B6579323031386A636F6E74726F6C6C6572781E6469643A6578616D70 6C653A3132333435363738396162636465666768696F7075626C69634B65 79426173653538782C483343324156764C4D7636676D4D4E616D33755641 6A5A70666B634A437744776E5A6E367A3377586D715056
A2 # map(2) 62 # text(2) 6964 # "id" 78 1E # text(30) 6469643A6578616D706C653A313233343536373839616263646566676869 # "did:example:123456789abcdefghi" 6E # text(14) 61757468656E7469636174696F6E # "authentication" 81 # array(1) A4 # map(4) 62 # text(2) 6964 # "id" 78 25 # text(37) 6469643A6578616D706C653A313233343536373839616263646566676869236B6579732D31 # "did:example:123456789abcdefghi#keys-1" 64 # text(4) 74797065 # "type" 78 1A # text(26) 45643235353139566572696669636174696F6E4B657932303138 # "Ed25519VerificationKey2018" 6A # text(10) 636F6E74726F6C6C6572 # "controller" 78 1E # text(30) 6469643A6578616D706C653A313233343536373839616263646566676869 # "did:example:123456789abcdefghi" 6F # text(15) 7075626C69634B6579426173653538 # "publicKeyBase58" 78 2C # text(44) 483343324156764C4D7636676D4D4E616D337556416A5A70666B634A437744776E5A6E367A3377586D715056 # "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
The topmost element MUST be a CBOR map (major type 5). Any other data type at the highest level of the DID document (the topmost map in the data model) is an error and MUST be rejected. The topmost CBOR map represents the DID document, and all data items of this map are entries of the DID document. The data item key is the entry key, and the data item value is interpreted as follows:
CBOR Representation Type | Data Type |
---|---|
CBOR map (major type 5) | ordered map, each data item of the CBOR map is added as an entry to the ordered map with the entry key being the data item name and the value converted based on the CBOR type and, if available, entry definition, as defined here; as no order can be enforced for general CBOR maps, no insertion order is guaranteed. |
CBOR array (major type 4), where the data model entry value is a list or unknown | list, each value of the CBOR array is added to the list in order, converted based on the CBOR type of the array value, as defined in this table |
CBOR array (major type 4), where the data model entry value is an ordered set | ordered set, each value of the CBOR array is added to the ordered set in order, converted based on the CBOR type of the array value as defined in this table |
CBOR string (major type 5) where the data model entry value is a datetime | datetime |
CBOR string (major type 5), where the data model entry value type is string or unknown | string |
CBOR integer (major type 0 or 1), choosing the shortest byte representation | integer |
CBOR floating-point number (major type 7). | double |
CBOR simple value (major type 7, subtype 24) with a simple value of 21 (True) or 20 (False) | boolean |
CBOR simple value (major type 7, subtype 24) with a simple value of 22 (Null) | null |
Additional Considerations:
@context
, or represented in the DID
spec registries or be explicitly documented as an extension of the DID
document conformant to § 4.3 Extensibility MUST be
preserved by default and represented as major type 3 (UTF-8 String)
In CBOR, one point of extensibility is with the use of CBOR tags. [RFC7049] defines a basic set of data types, as well as a tagging mechanism that enables extending the set of data types supported via the IANA CBOR Tag Registry. This allows for tags to enhance the semantic description of the data that follows. Extensibility with CBOR tags also facilitates lossless conversion to other core representations. CBOR Tags number 21 to 23 indicate that a following byte string might require a specific encoding when interoperating with a text-based representation such as JSON. These tags are useful when an encoder knows that the byte string data it is writing is likely to be later converted to a particular text-based usage such as JSON. These three tag numbers suggest conversions to three of the base data encodings defined in [RFC4648]. Tag number 21 suggests conversion to base64url encoding (Section 5 of [RFC4648]), where padding is not used (see Section 3.2 of [RFC4648]); that is, all trailing equals signs ("=") are removed from the encoded string. Tag number 22 suggests conversion to classical base64 encoding (Section 4 of [RFC4648] ), with padding as defined in [RFC4648]. For both base64url and base64, padding bits are set to zero (see Section 3.5 of [RFC4648] ), and encoding is performed without the inclusion of any line breaks, whitespace, or other additional characters. Tag number 23 suggests conversion to base16 (hex) encoding, with uppercase alphabetics (see Section 8 of [RFC4648]). Note that, for all three tag numbers, the encoding of the empty byte string is the empty text string of other representations.
DagCBOR is a further restricted subset of CBOR for representing the DID Document as a Directed Acyclic Graph model using canonical CBOR encoding with additional constraints. DagCBOR requires that there exist a single way of encoding any given object, and that encoded forms contain no superfluous data that may be ignored or lost in a round-trip decode/encode.
When producing and consuming DID Documents representing in DagCBOR the following rules are followed:
a5 # map(5) 62 # text(2) 6964 # "id" 78 40 # text(64) 6469643a6578616d706c653a313244334b6f6f574d4864727a6377706a6264725a7335474771455241766367715833623564707550745061396f743639796577 # "did:example:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew" 65 # text(5) 70726f6f66 # "proof" d8 2a # tag(42) 58 26 # bytes(38) 000190011b20a7f3a13d0dafa9b8b640fee52173c27b9a66ff27f6669b3be73fc0ee6849e2ce # "\x00\x01\x90\x01\e \xA7\xF3\xA1=\r\xAF\xA9\xB8\xB6@\xFE\xE5!s\xC2{\x9Af\xFF'\xF6f\x9B;\xE7?\xC0\xEEhI\xE2\xCE" 68 # text(8) 40636f6e74657874 # "@context" 78 1c # text(28) 68747470733a2f2f7777772e77332e6f72672f6e732f6469642f7631 # "https://www.w3.org/ns/did/v1" 6e # text(14) 61757468656e7469636174696f6e # "authentication" 81 # array(1) 78 83 # text(131) 6469643a6578616d706c653a313244334b6f6f574d4864727a6377706a6264725a7335474771455241766367715833623564707550745061396f7436397965773b6b65792d69643d6261667972656963756274783577716f336e6f73633463617a726b63746668776436726577657a6770776f6534737769726c733465626468733269 # "did:example:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew;key-id=bafyreicubtx5wqo3nosc4cazrkctfhwd6rewezgpwoe4swirls4ebdhs2i" 72 # text(18) 766572696669636174696f6e4d6574686f64 # "verificationMethod" 81 # array(1) 78 40 # text(64) 6469643a6578616d706c653a313244334b6f6f574d4864727a6377706a6264725a7335474771455241766367715833623564707550745061396f743639796577 # "did:example:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew"
DID methods provide the means to implement this specification on different verifiable data registries. New DID methods are defined in their own specifications, so that interoperability between different implementations of the same DID method is ensured. This section specifies the requirements on any DID method, which are met by the DID method's associated specification.
For adding properties to a DID document which are specific to a particular DID method, see § 4.1 Extensibility.
A DID method specification MUST define exactly one method-specific
DID scheme, identified by exactly one method name (see the
method-name
rule in Section § 3.1 DID Syntax).
The authors of a new DID method specification are expected to use a method name that is unique among all DID method names known to them at the time of publication.
Because there is no central authority for allocating or approving DID method names, there is no way to know for certain if a specific DID method name is unique. To help with this challenge, a non-authoritative list of known DID method names and their associated specifications is maintained in the DID Methods Registry, which is part of [DID-SPEC-REGISTRIES].
Authors of new DID method specifications are encouraged to add their method names to the DID Method Registry so that other implementors and members of the community have a place to see an overview of existing DID methods.
The DID method specification MUST specify how to generate the
method-specific-id
component of a DID.
Case sensitivity and normalization of the value of the
method-specific-id
rule MUST be defined by the DID method
specification.
The method-specific-id
value MUST be able to be generated without
the use of a centralized registry service.
The method-specific-id
value SHOULD be globally unique by itself.
Any DID generated by the method MUST be globally unique.
If needed, a method-specific DID scheme MAY define multiple
method-specific-id
formats.
The method-specific-id
format MAY include colons. The use of
colons MUST comply syntactically with the method-specific-id
ABNF
rule.
The meaning of colons in the method-specific-id
is entirely
method-specific. Colons might be used by DID methods for establishing
hierarchically partitioned namespaces, for identifying specific instances or
parts of the verifiable data registry, or for other purposes.
Implementers are advised to avoid assuming any meanings or
behaviors associated with a colon that are generically applicable to all
DID methods.
This section sets out the requirements for DID method specifications with regards to operations that can be performed on a DID document.
Determining the authority of a party to carry out the operations is method-specific. For example, a DID method might:
controller
property.
authentication
to decide whether an update/deactivate
operation is allowed.
capabilityInvocation
could be used to verify the invocation of a capability to update the DID
Document.
Each DID method MUST define how authorization to perform DID method operations is implemented, including any necessary cryptographic operations.
The DID method specification MUST specify how a DID controller creates a DID and its associated DID document on the verifiable data registry, including all cryptographic operations necessary to establish proof of control.
The DID method specification MUST specify how a DID resolver uses a DID to request a DID document from the verifiable data registry, including how the DID resolver can verify the authenticity of the response.
The DID method specification MUST specify how a DID controller can update a DID document on the verifiable data registry, including all cryptographic operations necessary to establish proof of control, or state that updates are not possible.
An update to a DID is any change, after creation, in the data used to produce a DID document. DID Method implementers are responsible for defining what constitutes an update, and what properties of the DID document are supported by a given DID method. For example, an update operation which replaces key material without changing it could be a valid update that does not result in changes to the DID document.
The DID method specification MUST specify how a DID controller can deactivate a DID on the verifiable data registry, including all cryptographic operations necessary to establish proof of deactivation, or state that deactivation is not possible.
DID method specifications MUST include their own Security Considerations sections. This section MUST consider all the requirements mentioned in section 5 of [RFC3552] (page 27) for the DID operations defined in the specification.
At least the following forms of attack MUST be considered: eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle. Potential denial of service attacks MUST be identified as well.
This section MUST discuss, per Section 5 of [RFC3552], residual risks (such as the risks from compromise in a related protocol, incorrect implementation, or cipher) after threat mitigation was deployed.
This section MUST provide integrity protection and update authentication for all operations required by Section § 7.2 Method Operations.
If the technology involves authentication, particularly user-host authentication, the security of the authentication method MUST be clearly specified.
DID methods MUST discuss the policy mechanism by which DIDs are proven to be uniquely assigned. A DID fits the functional definition of a URN, as defined in [RFC8141]. That is, a DID is a persistent identifier that is assigned once to a resource and never reassigned to a different resource. This is particularly important in a security context because a DID might be used to identify a specific party subject to a specific set of authorization rights.
Method-specific endpoint authentication MUST be discussed. Where DID methods make use of DLTs with varying network topology, sometimes offered as light node or thin client implementations to reduce required computing resources, the security assumptions of the topology available to implementations of the DID method MUST be discussed.
If the protocol incorporates cryptographic protection mechanisms, the DID method specification MUST clearly indicate which portions of the data are protected and what the protections are, and SHOULD give an indication to what sorts of attacks the cryptographic protection is susceptible. For example, integrity only, confidentiality, endpoint authentication, and so on.
Data which is to be held secret (keying material, random seeds, and so on) SHOULD be clearly labeled.
DID method specifications SHOULD explain and specify the implementation of signatures on DID documents, if applicable.
Where DID methods make use of peer-to-peer computing resources, such as with all known DLTs, the expected burdens of those resources SHOULD be discussed in relation to denial of service.
DID methods that introduce new authentication service types (see Section § 5.2.5 Services) SHOULD consider the security requirements of the supported authentication protocol.
DID method specifications MUST include their own Privacy Considerations sections, if only to point to § 10. Privacy Considerations.
The DID method specification's Privacy Considerations section MUST discuss any subsection of Section 5 of [RFC6973] that could apply in a method-specific manner. The subsections to consider are: surveillance, stored data compromise, unsolicited traffic, misattribution, correlation, identification, secondary use, disclosure, exclusion.
The Working Group is unsure if there will be enough implementation experience for the DID Resolution section. We are seeking feedback from the implementation community as to whether they prefer to do all of this work now, or if they would prefer that this section is, or parts of the section are, rewritten to be non-normative, or published as a NOTE and taken up in a future W3C DID Resolution Working Group. If there is support for rewriting a subset of the DID Resolution section, or publishing any part of it as a NOTE during the W3C Candidate Recommendation process, this section will be modified and/or published as a NOTE appropriately before the DID Core specification proceeds to the W3C Proposed Recommendation stage.
This section defines the inputs and outputs of DID resolution and DID URL dereferencing. These functions are defined in an abstract way. Their exact implementation is out of scope for this specification, but some considerations for implementors are discussed in [DID-RESOLUTION].
All conformant DID resolvers MUST implement the DID resolution functions for at least one DID method and MUST be able to return a DID document in at least one conformant representation.
The DID resolution functions resolve a DID into a DID document by using the "Read" operation of the applicable DID method. (See § 7.2.2 Read/Verify.) The details of how this process is accomplished are outside the scope of this specification, but all conformant implementations implement two functions which have the following abstract forms:
resolve ( did, did-resolution-input-metadata )
-> ( did-resolution-metadata, did-document, did-document-metadata )
resolveRepresentation ( did, did-resolution-input-metadata )
-> ( did-resolution-metadata, did-document-stream, did-document-metadata )
The resolve
function returns the DID document in its
abstract form.
The resolveRepresentation
function returns a byte stream of the
DID Document formatted in the corresponding representation.
The input variables of these functions are as follows:
resolve
and resolveRepresentation
functions in addition to the did
itself. Properties defined by this
specification are in § 8.1.1 DID Resolution Input Metadata Properties.
This input is REQUIRED, but the structure MAY be empty.
The output variables of these functions are as follows:
A metadata structure consisting of values relating to the results of the DID resolution process. This structure is REQUIRED and MUST NOT be empty.
This metadata typically changes between invocations of the
resolve
and resolveRepresentation
functions as it
represents data about the resolution process itself. Properties defined by
this specification are in § 8.1.2 DID Resolution Metadata Properties.
If the resolution is successful, and if the resolveRepresentation
function was called, this structure MUST contain a contentType
property containing the mime-type of the did-document-stream
in
this result. If the resolution is not successful, this structure MUST contain
an error
property describing the error.
resolve
function was
called, this MUST be a conforming DID document. If the resolution is
unsuccessful, this value MUST be empty.
resolveRepresentation
function was called, this MUST be a byte stream of the resolved DID
document in one of the conformant
representations. The byte stream might then be
parsed by the caller of the resolveRepresentation
function into a
data model, which can in turn be validated and
processed. If the resolution is unsuccessful, this value MUST be an empty
stream.
did-document
or did-document-stream
. This metadata
typically does not change between invocations of the resolve
function unless the DID document changes, as it represents data about
the DID document. If the resolution is unsuccessful, this output MUST
be an empty metadata structure. Properties
defined by this specification are in § 8.1.3 DID Document Metadata Properties.
Conforming DID resolver implementations do not alter the signature of
these functions in any way. DID resolver implementations might map the
resolve
and resolveRepresentation
functions to a
method-specific internal function to perform the actual DID resolution
process. DID resolver implementations might implement and expose
additional functions with different signatures in addition to the
resolve
function specified here.
The possible properties within this structure and their possible values are defined by [DID-SPEC-REGISTRIES]. This specification defines the following common properties.
did-document-stream
if such a representation is supported and
available. This property is OPTIONAL. It is only used if the
resolveRepresentation
function is called and MUST be ignored if the
resolve
function is called.
The possible properties within this structure and their possible values are defined by [DID-SPEC-REGISTRIES]. This specification defines the following common properties.
did-document-stream
. This property is
REQUIRED if resolution is successful and if the
resolveRepresentation
function was called. This property MUST NOT
be present if the resolve
function was called. The value of this
property MUST be an ASCII string that is the MIME
type of the conformant representations. The
caller of the resolveRepresentation
function MUST use this value
when determining how to parse and process the did-document-stream
returned by this function into the data model.
accept
input metadata property is not supported by the DID method
and/or DID resolver implementation.
The possible properties within this structure and their possible values SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES]. This specification defines the following common properties.
DID document metadata SHOULD include a created
property to indicate
the timestamp of the Create operation. The value of the
property MUST be a string formatted as an XML Datetime normalized to UTC 00:00:00
and without sub-second decimal precision. For example:
2020-12-20T19:17:47Z
.
DID document metadata SHOULD include an updated
property to
indicate the timestamp of the last Update operation for
the document version which was resolved. The value of the property MUST follow
the same formatting rules as the created
property. The
updated
property is omitted if an Update operation has never been
performed on the DID document. If an updated
property exists, it
can be the same value as the created
property when the difference
between the two timestamps is less than one second.
DID document metadata SHOULD include a nextUpdate
property if
the resolved document version is not the latest version of the document. It
indicates the timestamp of the next Update operation.
The value of the property MUST follow the same formatting rules as the
created
property.
DID document metadata SHOULD include a versionId
property to
indicate the version of the last Update operation for the
document version which was resolved. The value of the property MUST be an ASCII string.
DID document metadata SHOULD include a nextVersionId
property if
the resolved document version is not the latest version of the document. It
indicates the version of the next Update operation. The
value of the property MUST be an ASCII string.
A DID Method can define different forms of a DID that are logically
equivalent. An example is when a DID takes one form prior to registration in a
verifiable data registry and another form after such registration. In this case,
the DID Method specification may need to express one or more DIDs that
are logically equivalent to the resolved DID as a property of the DID document.
This is the purpose of the equivalentId
property.
equivalentId
MUST be an ordered set where each item in the list is a string that conforms to the rules in Section § 3.1 DID Syntax.
equivalentId
value
is logically equivalent to the id
property value and thus
identifies the same DID subject.
equivalentId
DID value MUST be produced by, and a form
of, the same DID Method as the id
property value. (e.g.
did:example:abc
== did:example:ABC
)
equivalentId
value is logically equivalent to the
id
property value.
id
and
equivalentId
properties to ensure any subsequent
interactions with any of the values they contain are correctly handled as
logically equivalent (e.g. retain all variants in a database so an interaction
with any one maps to the same underlying account). The
testability of requesting parties is currently under debate and normative
statements related to requesting parties may be downgraded in the future from a
MUST to a SHOULD/MAY or similar language.
equivalentId
is a much stronger form of equivalence than
alsoKnownAs
because the equivalence MUST be guaranteed by
the governing DID method. equivalentId
represents a full
graph merge because the same DID document describes both the
equivalentId
DID and the id
property DID.
If a resolving party does not retain the values from the id
and
equivalentId
properties and ensure any subsequent
interactions with any of the values they contain are correctly handled as
logically equivalent, there might be negative or unexpected issues that
arise. Implementers are strongly advised to observe the
directives related to this metadata property.
The canonicalId
property is identical to the
equivalentId
property except: a) it accepts only a single
value rather than a list, and b) that DID is defined to be the canonical ID for
the DID subject within the scope of the containing DID document.
canonicalId
MUST be a string that conforms to the rules in Section § 3.1 DID Syntax.
canonicalId
value
is logically equivalent to the id
property value and that the
canonicalId
value is defined by the DID Method to be
the canonical ID for the DID subject in the scope of the containing DID
document.
canonicalId
value MUST be produced by, and a form of, the
same DID Method as the id
property value. (e.g.
did:example:abc
== did:example:ABC
)
canonicalId
value is logically equivalent to the
id
property value.
canonicalId
value
as its primary ID value for the DID subject and treat all other equivalent
values as secondary aliases. (e.g. update corresponding primary references in
their systems to reflect the new canonical ID directive). The testability of requesting parties is currently under debate and
normative statements related to requesting parties may be downgraded in the
future from a MUST to a SHOULD/MAY or similar language.
canonicalId
is the same statement of equivalence as
equivalentId
except it is constrained to a single value that
is defined to be canonical for the DID subject in the scope of the DID document.
Like equivalentId
, canonicalId
represents a full graph merge because the same DID document describes both the
canonicalId
DID and the id
property DID.
If a resolving party does not use the canonicalId
value
as its primary ID value for the DID subject and treat all other equivalent
values as secondary aliases, there might be negative or unexpected issues that
arise related to user experience. Implementers are strongly advised to observe the
directives related to this metadata property.
The DID URL dereferencing function dereferences a DID URL into a resource with contents depending on the DID URL's components, including the DID method, method-specific identifier, path, query, and fragment. This process depends on DID resolution of the DID contained in the DID URL. DID URL dereferencing might involve multiple steps (e.g., when the DID URL being dereferenced includes a fragment), and the function is defined to return the final resource after all steps are completed. The details of how this process is accomplished are outside the scope of this specification, but all conformant implementations implement a function which has the following abstract form:
dereference ( did-url, did-url-dereferencing-input-metadata )
-> ( did-url-dereferencing-metadata, content-stream, content-metadata )
The input variables of this function are as follows:
dereference
function in addition to the
did-url
itself. Properties defined by this specification are in
§ 8.2.1 DID URL Dereferencing Input Metadata Properties. This input is
REQUIRED, but the structure MAY be empty.
The output variables of this function are as follows:
error
property describing the error.
dereferencing
function was called and successful, this MUST
contain a resource corresponding to the DID URL.
The content-stream
SHOULD be a DID document in one of the
conformant representations obtained through
the resolution process.
If the dereferencing is unsuccessful, this value MUST be empty.
content-stream
.
If the content-stream
is a DID document, this MUST be a
did-document-metadata
structure as described in DID
Resolution.
If the dereferencing is unsuccessful, this output MUST be an empty metadata structure.
Conforming DID URL Dereferencing implementations do not alter the
signature of these functions in any way. DID URL Dereferencing
implementations might map the dereference
function to a
method-specific internal function to perform the actual DID URL
Dereferencing process. DID URL Dereferencing implementations might
implement and expose additional functions with different signatures in addition
to the dereference
function specified here.
The possible properties within this structure and their possible values SHOULD be registered in the [DID-SPEC-REGISTRIES]. This specification defines the following common properties.
content-stream
. The DID
URL Dereferencing implementation SHOULD use this value to determine the
representation contained in the returned value if such a representation is
supported and available.
The possible properties within this structure and their possible values are defined by [DID-SPEC-REGISTRIES]. This specification defines the following common properties.
content-stream
SHOULD be expressed
using this property if dereferencing is successful.
content-stream
resulting from this dereferencing request.
Input and output metadata is often involved during the DID Resolution, DID URL Dereferencing, and other DID-related processes. The structure used to communicate this metadata MUST be a map of properties. Each property name MUST be a string. Each property value MUST be a string, map, list, ordered set, boolean, or null. The values within any complex data structures such as maps and lists MUST be one of these data types as well. All metadata property definitions MUST define the value type, including any additional formats or restrictions to that value (for example, a string formatted as a date or as a decimal integer). It is RECOMMENDED that property definitions use strings for values.
All implementations of functions that use metadata structures as either input or output are able to fully represent all data types described here in a deterministic fashion. As inputs and outputs using metadata structures are defined in terms of data types and not their serialization, the method for representation is internal to the implementation of the function and is out of scope of this specification.
The following example demonstrates a JSON-encoded metadata structure that might be used as DID resolution input metadata.
{
"accept": "application/did+ld+json"
}
This example corresponds to a metadata structure of the following format:
«[
"accept" → "application/did+ld+json"
]»
The next example demonstrates a JSON-encoded metadata structure that might be used as DID resolution metadata if a DID was not found.
{
"error": "notFound"
}
This example corresponds to a metadata structure of the following format:
«[
"error" → "notFound"
]»
The next example demonstrates a JSON-encoded metadata structure that might be used as DID document metadata to describe timestamps associated with the DID document.
{
"created": "2019-03-23T06:35:22Z",
"updated": "2023-08-10T13:40:06Z"
}
This example corresponds to a metadata structure of the following format:
«[
"created" → "2019-03-23T06:35:22Z",
"updated" → "2023-08-10T13:40:06Z"
]»
This section is non-normative.
During the Working Draft stage, this section focuses on security topics that should be important in early implementations. The editors are seeking feedback on threats and threat mitigations that should be reflected in this section or elsewhere in the spec. DIDs are designed to operate under the general Internet threat model used by many IETF standards. We assume uncompromised endpoints, but anticipate that messages could be read or corrupted on the network.
The DID Method Registry (see [DID-SPEC-REGISTRIES]) contains an informative list of DID method names and their corresponding DID method specifications. Implementors need to bear in mind that there is no central authority to mandate which DID method specification is to be used with any specific DID method name, but can use the DID Method Registry to make an informed decision when choosing which DID resolver implementations to use.
The following sections describe binding identities to DIDs and DID documents.
Signatures and verifiable timestamps allow DID documents to be cryptographically verifiable.
By itself, a verified signature on a self-signed DID document does not prove control of a DID. It only proves that the:
Proving control of a DID, that is, the binding between the DID and the DID document that describes it, requires a two step process:
id
property of the resulting DID
document matches the DID that was resolved.
It should be noted that this process proves control of a DID and DID document regardless of whether the DID document is signed.
Signatures on DID documents are optional. DID method specifications are expected to explain and specify their implementation if applicable.
There are two methods for proving control of the private key corresponding to a public key description in the DID document: static and dynamic.
The static method is to sign the DID document with the private key. This proves control of the private key at a time no later than the DID document was registered. If the DID document is not signed, control of a public key described in the DID document can still be proven dynamically as follows:
A DID and DID document do not inherently carry any PII (personally-identifiable information).
It can be useful to express a binding of DID to a person's or company's real world identity, in a way that is provably asserted by a trusted authority such as a government. This can enable interactions that can be considered legally valid under one or more jurisdictions; establishing such bindings has to be carefully balanced against privacy considerations (see § 10. Privacy Considerations).
The process of binding a DID to something in the real world, such as a person or a company, for example using verifiable credentials with the same subject as that DID, is out of scope for this specification. For more information, see the Verifiable Credentials Data Model [VC-DATA-MODEL].
If a DID document publishes a service intended for authentication or authorization of the DID subject (see Section § 5.2.5 Services), it is the responsibility of the service endpoint provider, subject, or requesting party to comply with the requirements of the authentication protocols supported at that service endpoint.
Non-repudiation of DIDs and DID document updates is supported under the assumption that the subject:
Non-repudiation is further supported if timestamps are included (see Section § 8.1.3 DID Document Metadata Properties) and the target DLT system supports timestamps.
One mitigation against unauthorized changes to a DID document is monitoring and actively notifying the DID subject when there are changes. This is analogous to helping prevent account takeover on conventional username/password accounts by sending password reset notifications to the email addresses on file.
In the case of a DID, there is no intermediary registrar or account provider to generate such notifications. However, if the verifiable data registry on which the DID is registered directly supports change notifications, a subscription service can be offered to DID controllers. Notifications could be sent directly to the relevant service endpoints listed in an existing DID.
If a DID controller chooses to rely on a third-party monitoring service (other than the verifiable data registry itself), this introduces another vector of attack.
In a decentralized identifier architecture, there are no centralized authorities to enforce key or signature expiration policies. Therefore DID resolvers and requesting parties need to validate that keys were not expired at the time they were used. Because some use cases have legitimate reasons why already-expired keys can be extended, make sure key expiration does not prevent any further use of the key. Implementations of a resolver ought to be compatible with such extension behavior.
It is up to DID methods to define how revocation of cryptographic keys might occur. DID method specifications are also expected to enable support for a quorum of trusted parties to enable key recovery. Some of the facilities to do so are suggested in Section § 5.2.2 DID Controller. Not all DID method specifications will recognize control from DIDs registered using other DID methods and they might restrict third-party control to DIDs that use the same method. Access control and key recovery in a DID method specification can also include a time lock feature to protect against key compromise by maintaining a second track of control for recovery.
DIDs achieve global uniqueness without the need for a central registration authority. This comes at the cost of human memorability. The algorithms capable of generating globally unique identifiers produce random strings of characters that have no human meaning (see also Zooko's Triangle).
There are use cases where it is desirable to discover a DID when starting from a human-friendly identifier. For example, a natural language name, a domain name, or a conventional address for a DID controller, such as a mobile telephone number, email address, social media username, or blog URL. However, the problem of mapping human-friendly identifiers to DIDs (and doing so in a way that can be verified and trusted) is outside the scope of this specification.
Solutions to this problem should be defined in separate specifications that reference this specification. It is strongly recommended that such specifications carefully consider the:
Many cybersecurity abuses hinge on exploiting gaps between reality and the assumptions of rational, good-faith actors. Immutability of DID documents can provide some security benefits. Individual DID methods ought to consider constraints that would eliminate behaviors or semantics they do not need. The more locked down a DID method is, while providing the same set of features, the less it can be manipulated by malicious actors.
As an example, consider that a single edit to a DID document can change
anything except the root id
property of the document. But
is it actually desirable for a service to change its
type
after it is defined? Or for a key to change its value? Or
would it be better to require a new id
when certain
fundamental properties of an object change? Malicious takeovers of a website
often aim for an outcome where the site keeps its identifier (the host name),
but is subtly changed underneath. If certain properties of the site were
required by the specification to be immutable (for example, the ASN
associated with its IP address), such attacks might be much harder and more
expensive to carry out, and anomaly detection would be easier.
For DID methods tied to a global source of truth, a direct, just-in-time lookup of the latest version of a DID document is always possible. However, it seems likely that layers of cache might eventually sit between a DID resolver and that source of truth. If they do, believing the attributes of an object in the DID document to have a given state when they are actually subtly different might invite exploits. This is particularly true if some lookups are of a full DID document, and others are of partial data where the larger context is assumed.
Encryption algorithms have been known to fail due to advances in cryptography and computing power. Implementers are advised to assume that any encrypted data placed in a DID document might eventually be made available in clear text to the same audience to which the encrypted data is available. This is particularly pertinent if the DID document is public.
Encrypting all or parts of DID documents is not an appropriate means to protect data in the long term. Similarly, placing encrypted data in DID documents is not an appropriate means to include personally identifiable information.
Given the caveats above, if encrypted data is included in a DID document, implementers are advised to not encrypt with the public keys of entities that do not wish to be correlated with the DID.
The three equivalence properties—alsoKnownAs
, equivalentId
, and
canonicalId
—are subject to special security considerations
related to attacks against DIDs that are asserted to be equivalent.
The equivalentId
and canonicalId
properties that constrain equivalence assertions to variants of a single DID
produced by the same DID method (e.g. did:foo:123
≡
did:foo:hash(123)
) can be trusted to the extent the requesting party
trusts the DID method (and a conforming producer) itself.
The alsoKnownAs
property that permits an equivalence
assertion to URIs that are not governed by the same DID method (or may
not be DIDs at all) cannot be trusted without performing verification steps
outside of the governing DID method. See additional guidence in
§ 5.2.1.2 Also Known As.
As with any other sensitive properties in the DID Document (e.g. public key references), parties relying on any equivalence statement in a DID Document should guard against the values of these properties being substituted by an attacker after the proper verification has been performed. Any write access to a DID document stored in memory or disk after verification has been performed is an attack vector that will circumvent verification unless the DID document is re-verified.
DID documents which include external JSON-LD contexts (see § 6.3 JSON-LD ) or any other links to external machine-readable content are vulnerable to tampering.
DID document consumers can cache local static copies of JSON-LD contexts and/or verify the integrity of external contexts against the cryptographic hash for the context as registered in the DID specification registries (see the registration process for more detail) [DID-SPEC-REGISTRIES].
Additional information about the security context of authentication events
is often required for compliance reasons, especially in regulated areas
such as the financial and public sectors. Examples include but are not
limited to protection of secret keys, the identity proofing process, and the
form-factor of the authenticator. For example,
Payment services (PSD 2) and
eIDAS introduce such requirements to the security context. Level of
Assurance (LoA) frameworks are classified and defined by, for example,
eIDAS,
NIST 800-63-3 and
ISO/IEC 29115:2013, including their requirements for the security
context, and making recommendations on how to achieve them. This might
include strong user authentication and FIDO2/WebAuthn can be potential
implementations. A LoA represents the level of confidence that an entity is in
fact that entity. Some regulated use cases require the implementation of a
certain LoA. Since verification relationships such as
assertionMethod
and authentication
might be
used in some of these use cases, information about the applied security context
might need to be expressed and provided to a verifier. Whether and
how to encode this information in the DID document data model is
out of scope for this specification, but it should be noted that the
DID document data model can be extended if necessary (see
Extensibility section). Section
Privacy Considerations remains
applicable for such extensions.
This section is non-normative.
It is critically important to apply the principles of Privacy by Design [PRIVACY-BY-DESIGN] to all aspects of the decentralized identifier architecture, because DIDs and DID documents are, by design, administered directly by the DID controller(s). There is no registrar, hosting company, or other intermediate service provider to recommend or apply additional privacy safeguards. The authors of this specification have applied all seven Privacy by Design principles throughout its development. Privacy in this specification is preventative not remedial, and privacy is an embedded default.
If a DID method specification is written for a public verifiable data registry where all DIDs and DID documents are publicly available, it is critical that DID documents contain no personally-identifiable information.
Personally-identifiable information can instead be placed behind service endpoints under control of the DID subject or DID controller. Due diligence should be taken around the use of URLs in service endpoints to prevent leakage of personal data or correlation within a URL of a service endpoint. For example, a URL that contains a username is dangerous to include in a DID Document because the username is likely to be human-meaningful in a way that can reveal information that the DID subject did not consent to sharing. With this privacy architecture, personal data can be exchanged on a private, peer-to-peer basis using communications channels identified and secured by public key descriptions in DID documents. This also enables DID subjects and requesting parties to implement the GDPR right to be forgotten, because no personal data is written to an immutable distributed ledger.
Like any type of globally unique identifier, DIDs might be used for correlation. DID controllers can mitigate this privacy risk by using pairwise unique DIDs, that is, sharing a different private DID for every relationship. In effect, each DID acts as a pseudonym. A pseudonymous DID need only be shared with more than one party when the DID subject explicitly authorizes correlation between those parties. If pseudonymous DIDs are the default, then the only need for a public DID (a DID published openly or shared with a large number of parties) is when the DID subject explicitly desires public identification.
The anti-correlation protections of pseudonymous DIDs are easily defeated if the data in the corresponding DID documents can be correlated. For example, using same public key descriptions or bespoke service endpoints in multiple DID documents can provide as much correlation information as using the same DID. Therefore the DID document for a pseudonymous DID also needs to use pairwise unique public keys. It might seem natural to also use pairwise unique service endpoints in the DID document for a pseudonymous DID. However, unique endpoints allow all traffic between two DIDs to be isolated perfectly into unique buckets, where timing correlation and similar analysis is easy. Therefore, a better strategy for endpoint privacy might be to share an endpoint among thousands or millions of DIDs controlled by many different subjects. See also § 10.5 Herd Privacy.
It is dangerous to add properties to the DID document that can be used to indicate, explicitly or through inference, what type or nature of thing the DID subject is, particularly if the DID subject is a person.
Not only do such properties potentially result in personally identifiable information (see § 10.1 Keep Personally-Identifiable Information (PII) Private) or correlatable data (see § 10.2 DID Correlation Risks and Pseudonymous DIDs and § 10.3 DID Document Correlation Risks) being present in the DID document, but they can be used for grouping particular DIDs in such a way that they are included in or excluded from certain operations or functionalities.
Including type information in a DID Document can result in personal privacy harms even for DID Subjects that are non-person entities, such as IoT devices. The aggregation of such information around a DID Controller could serve as a form of digital fingerprint and this is best avoided.
To minimize these risks, all properties in a DID document ought to be for expressing cryptographic material, endpoints, or verification methods related to using the DID.
When a DID subject is indistinguishable from others in the herd, privacy is available. When the act of engaging privately with another party is by itself a recognizable flag, privacy is greatly diminished.
DIDs and DID methods need to work to improve herd privacy, particularly for those who legitimately need it most. Choose technologies and human interfaces that default to preserving anonymity and pseudonymity. To reduce digital fingerprints, share common settings across requesting party implementations, keep negotiated options to a minimum on wire protocols, use encrypted transport layers, and pad messages to standard lengths.
The ability for a controller to optionally state at least one service endpoint in the DID document increases their control and agency. Each additional endpoint in the DID document adds privacy risk either due to correlation (e.g., across endpoint descriptions) or because the services are not protected by an authorization mechanism, or both.
The degree of additional privacy risk caused by using multiple service endpoints in one DID document can be difficult to estimate. Privacy harms are typically unintended consequences. DIDs can identify documents, services, schemas, and other things that may be associated with individual people, households, clubs, and employers — and correlation of their service endpoints could become a powerful surveillance and inference tool.
DID documents are often public and will be stored and indexed efficiently by their very standards-based nature. This risk is worse if DID documents are published to immutable Verifiable Data Registries. Access to a history of the DID documents referenced by a DID represents a form of traffic analysis made more efficient through the use of standards.
Examples of service endpoints in DID documents come in three broad categories:
For the first category, consider non-DID publication mechanisms with only a single service endpoint. In some cases, the publication mechanism might reference a DID Document with no service endpoints at all. For the second category, prefer using only one service that points to an authorization server, mediator, or proxy that can provide herd privacy. For the third category, avoid the use of multiple service endpoints for a DID because some of these (e.g., an authorization server) are likely to be reused with other, related DIDs. Place correlatable service endpoints behind a privacy-preserving mechanism, if possible, or introduce a mediator or proxy as a sole service endpoint in order to obscure related devices and documents through herd privacy.
This section is non-normative.
This section is non-normative.
See did-spec-registries for optional extensions and other verifcation method types.
These examples are for information purposes only, it is considered a best practice to avoid using the same verification method for multiple purposes.
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:example:123",
"authentication": [
{
"id": "did:example:123#z6MkecaLyHuYWkayBDLw5ihndj3T1m6zKTGqau3A51G7RBf3",
"type": "Ed25519VerificationKey2018", // external (property value)
"controller": "did:example:123",
"publicKeyBase58": "AKJP3f7BD6W4iWEQ9jwndVTCBq8ua2Utt8EEjJ6Vxsf"
}
],
"capabilityInvocation": [
{
"id": "did:example:123#z6MkhdmzFu659ZJ4XKj31vtEDmjvsi5yDZG5L7Caz63oP39k",
"type": "Ed25519VerificationKey2018", // external (property value)
"controller": "did:example:123",
"publicKeyBase58": "4BWwfeqdp1obQptLLMvPNgBw48p7og1ie6Hf9p5nTpNN"
}
],
"capabilityDelegation": [
{
"id": "did:example:123#z6Mkw94ByR26zMSkNdCUi6FNRsWnc2DFEeDXyBGJ5KTzSWyi",
"type": "Ed25519VerificationKey2018", // external (property value)
"controller": "did:example:123",
"publicKeyBase58": "Hgo9PAmfeoxHG8Mn2XHXamxnnSwPpkyBHAMNF3VyXJCL"
}
],
"assertionMethod": [
{
"id": "did:example:123#z6MkiukuAuQAE8ozxvmahnQGzApvtW7KT5XXKfojjwbdEomY",
"type": "Ed25519VerificationKey2018", // external (property value)
"controller": "did:example:123",
"publicKeyBase58": "5TVraf9itbKXrRvt2DSS95Gw4vqU3CHAdetoufdcKazA"
}
]
}
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:example:123",
"verificationMethod": [
{
"id": "did:example:123#ZC2jXTO6t4R501bfCXv3RxarZyUbdP2w_psLwMuY6ec",
"type": "Ed25519VerificationKey2018", // external (property value)
"controller": "did:example:123",
"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
},
{
"id": "did:example:123#zQ3shP2mWsZYWgvgM11nenXRTx9L1yiJKmkf9dfX7NaMKb1pX",
"type": "EcdsaSecp256k1VerificationKey2019", // external (property value)
"controller": "did:example:123",
"publicKeyBase58": "d5cW2R53NHTTkv7EQSYR8YxaKx7MVCcchjmK5EgCNXxo",
},
{
"id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"type": "JsonWebKey2020", // external (property value)
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "OKP", // external (property name)
"crv": "Ed25519", // external (property name)
"x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ" // external (property name)
}
},
{
"id": "did:example:123#z6LSnjagzhe8Df6gZmroW3wjDd7XQLwAuYfwa4ZeTBCGFoYc",
"type": "JsonWebKey2020", // external (property value)
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "OKP", // external (property name)
"crv": "X25519", // external (property name)
"x": "pE_mG098rdQjY3MKK2D5SUQ6ZOEW3a6Z6T7Z4SgnzCE" // external (property name)
},
}
{
"id": "did:example:123#4SZ-StXrp5Yd4_4rxHVTCYTHyt4zyPfN1fIuYsm6k3A",
"type": "JsonWebKey2020", // external (property value)
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "secp256k1", // external (property name)
"x": "Z4Y3NNOxv0J6tCgqOBFnHnaZhJF6LdulT7z8A-2D5_8", // external (property name)
"y": "i5a2NtJoUKXkLm6q8nOEu9WOkso1Ag6FTUT6k_LMnGk" // external (property name)
}
},
{
"id": "did:example:123#n4cQ-I_WkHMcwXBJa7IHkYu8CMfdNcZKnKsOrnHLpFs",
"type": "JsonWebKey2020", // external (property value)
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "RSA", // external (property name)
"e": "AQAB", // external (property name)
"n": "omwsC1AqEk6whvxyOltCFWheSQvv1MExu5RLCMT4jVk9khJKv8JeMXWe3bWHatjPskdf2dlaGkW5QjtOnUKL742mvr4tCldKS3ULIaT1hJInMHHxj2gcubO6eEegACQ4QSu9LO0H-LM_L3DsRABB7Qja8HecpyuspW1Tu_DbqxcSnwendamwL52V17eKhlO4uXwv2HFlxufFHM0KmCJujIKyAxjD_m3q__IiHUVHD1tDIEvLPhG9Azsn3j95d-saIgZzPLhQFiKluGvsjrSkYU5pXVWIsV-B2jtLeeLC14XcYxWDUJ0qVopxkBvdlERcNtgF4dvW4X00EHj4vCljFw" // external (property name)
}
},
{
"id": "did:example:123#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw",
"type": "JsonWebKey2020", // external (property value)
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "P-256", // external (property name)
"x": "38M1FDts7Oea7urmseiugGW7tWc3mLpJh6rKe7xINZ8", // external (property name)
"y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4" // external (property name)
}
},
{
"id": "did:example:123#8wgRfY3sWmzoeAL-78-oALNvNj67ZlQxd1ss_NX1hZY",
"type": "JsonWebKey2020", // external (property value)
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "P-384", // external (property name)
"x": "GnLl6mDti7a2VUIZP5w6pcRX8q5nvEIgB3Q_5RI2p9F_QVsaAlDN7IG68Jn0dS_F", // external (property name)
"y": "jq4QoAHKiIzezDp88s_cxSPXtuXYFliuCGndgU4Qp8l91xzD1spCmFIzQgVjqvcP" // external (property name)
}
},
{
"id": "did:example:123#NjQ6Y_ZMj6IUK_XkgCDwtKHlNTUTVjEYOWZtxhp1n-E",
"type": "JsonWebKey2020", // external (property value)
"controller": "did:example:123",
"publicKeyJwk": {
"kty": "EC", // external (property name)
"crv": "P-521", // external (property name)
"x": "AVlZG23LyXYwlbjbGPMxZbHmJpDSu-IvpuKigEN2pzgWtSo--Rwd-n78nrWnZzeDc187Ln3qHlw5LRGrX4qgLQ-y", // external (property name)
"y": "ANIbFeRdPHf1WYMCUjcPz-ZhecZFybOqLIJjVOlLETH7uPlyG0gEoMWnIZXhQVypPy_HtUiUzdnSEPAylYhHBTX2" // external (property name)
}
}
]
}
This section is non-normative.
These examples are for information purposes only. See W3C Verifiable Credentials Data Model for additional examples.
{ // external (all terms in this example)
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://w3id.org/citizenship/v1"
],
"type": [
"VerifiableCredential",
"PermanentResidentCard"
],
"credentialSubject": {
"id": "did:example:123",
"type": [
"PermanentResident",
"Person"
],
"givenName": "JOHN",
"familyName": "SMITH",
"gender": "Male",
"image": "data:image/png;base64,iVBORw0KGgo...kJggg==",
"residentSince": "2015-01-01",
"lprCategory": "C09",
"lprNumber": "000-000-204",
"commuterClassification": "C1",
"birthCountry": "Bahamas",
"birthDate": "1958-08-17"
},
"issuer": "did:example:456",
"issuanceDate": "2020-04-22T10:37:22Z",
"identifier": "83627465",
"name": "Permanent Resident Card",
"description": "Government of Example Permanent Resident Card.",
"proof": {
"type": "Ed25519Signature2018",
"created": "2020-04-22T10:37:22Z",
"proofPurpose": "assertionMethod",
"verificationMethod": "did:example:456#key-1",
"jws": "eyJjcml0IjpbImI2NCJdLCJiNjQiOmZhbHNlLCJhbGciOiJFZERTQSJ9..BhWew0x-txcroGjgdtK-yBCqoetg9DD9SgV4245TmXJi-PmqFzux6Cwaph0r-mbqzlE17yLebjfqbRT275U1AA"
}
}
{ // external (all terms in this example)
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.gov/credentials/3732",
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"issuer": { "id": "did:example:123" },
"issuanceDate": "2020-03-10T04:24:12.164Z",
"credentialSubject": {
"id": "did:example:456",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
},
"proof": {
"type": "JsonWebSignature2020",
"created": "2020-02-15T17:13:18Z",
"verificationMethod": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"proofPurpose": "assertionMethod",
"jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..Y0KqovWCPAeeFhkJxfQ22pbVl43Z7UI-X-1JX32CA9MkFHkmNprcNj9Da4Q4QOl0cY3obF8cdDRdnKr0IwNrAw"
}
}
{ // external (all terms in this example)
"protected": {
"kid": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"alg": "EdDSA"
},
"payload": {
"iss": "did:example:123",
"sub": "did:example:456",
"vc": {
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.gov/credentials/3732",
"type": [
"VerifiableCredential",
"UniversityDegreeCredential"
],
"issuer": {
"id": "did:example:123"
},
"issuanceDate": "2020-03-10T04:24:12.164Z",
"credentialSubject": {
"id": "did:example:456",
"degree": {
"type": "BachelorDegree",
"name": "Bachelor of Science and Arts"
}
}
},
"jti": "http://example.gov/credentials/3732",
"nbf": 1583814252
},
"signature": "qSv6dpZJGFybtcifLwGf4ujzlEu-fam_M7HPxinCbVhz9iIJCg70UMeQbPa1ex6BmQ2tnSS7F11FHnMB2bJRAw"
}
This section is non-normative.
These examples are for information purposes only, it is considered a best practice to avoid dislosing unnecessary information in JWE headers.
{ // external (all terms in this example)
"ciphertext": "3SHQQJajNH6q0fyAHmw...",
"iv": "QldSPLVnFf2-VXcNLza6mbylYwphW57Q",
"protected": "eyJlbmMiOiJYQzIwUCJ9",
"recipients": [
{
"encrypted_key": "BMJ19zK12YHftJ4sr6Pz1rX1HtYni_L9DZvO1cEZfRWDN2vXeOYlwA",
"header": {
"alg": "ECDH-ES+A256KW",
"apu": "Tx9qG69ZfodhRos-8qfhTPc6ZFnNUcgNDVdHqX1UR3s",
"apv": "ZGlkOmVsZW06cm9wc3RlbjpFa...",
"epk": {
"crv": "X25519",
"kty": "OKP",
"x": "Tx9qG69ZfodhRos-8qfhTPc6ZFnNUcgNDVdHqX1UR3s"
},
"kid": "did:example:123#zC1Rnuvw9rVa6E5TKF4uQVRuQuaCpVgB81Um2u17Fu7UK"
}
}
],
"tag": "xbfwwDkzOAJfSVem0jr1bA"
}
The list of issues below are under active discussion and are likely to result in changes to this specification.
Decentralized extension
is not discussedupdated
property's initial value is not defined clearlyversionId
and key revocation@context
property values in DID DocumentsresolveStream
)?This section will be submitted to the Internet Engineering Steering Group (IESG) for review, approval, and registration with IANA when this specification becomes a W3C Proposed Recommendation.
Fragment identifiers used with application/did+json are treated according to the rules defined in § 3.2.4 Fragment.
Use of the media type application/did+ld+json
is pending
clarification over the registration of
media types with multiple suffixes. The alternative will be to use
application/ld+json
with an expected profile parameter of
https://www.w3.org/ns/did/json-ld-profile
if multiple suffixes
cannot be registered by the time the rest of DID Core is ready for W3C
Proposed Recommendation. Discussion is happening in the
IETF media-types mailing list.
Fragment identifiers used with application/did+ld+json are treated according to the rules associated with the JSON-LD 1.1: application/ld+json media type [JSON-LD11].
Fragment identifiers used with application/did+cbor are treated according to the rules defined in § 3.2.4 Fragment.
Fragment identifiers used with application/did+dag+cbor are treated according to the rules defined in § 3.2.4 Fragment.