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 service endpoints, which provide a set of mechanisms enabling a DID controller to prove control of the DID. Service endpoints 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 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 40 experimental implementations and a preliminary test suite that will eventually determine whether or not implementations are conformant. Readers are advised that Appendix 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 Science and Technology Directorate under contracts HSHQDC-16-R00012-H-SB2016-1-002 and HSHQDC-17-C-00019. The content of this specification does not necessarily reflect the position or the policy of the U.S. Government and no official endorsement should be inferred.

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.

Introduction

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 metadata 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.

A Simple Example

A DID is a simple text string consisting of three parts, the:

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",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }],
  "service": [{
    // used to retrieve Verifiable Credentials associated with the DID
    "id":"did:example:123456789abcdefghi#vcs",
    "type": "VerifiableCredentialService",
    "serviceEndpoint": "https://example.com/vc/"
  }]
}
      

Design Goals

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, service endpoints, and other metadata.
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.

Architecture Overview

This section provides a basic understanding of the major elements of DID architecture. Formal definitions of terms are provided in .


Diagram showing that DIDs are recorded on a Verifiable Data Registry; DIDs
resolve to DID documents; DIDs identify DID subjects; a DID controller can
modify a DID document; a DID method generates a DID; a DID method instructs a
DID resolver.
The basic components of DID architecture.
DIDs and DID URLs
A DID, or Decentralized Identifier, is a URI composed of three parts: the scheme "did:", a method identifier, and a unique, method-specific identifier generated by the DID method. DIDs are resolvable to DID documents. A DID URL extends the syntax of a basic DID to incorporate other standard URI components (path, query, fragment) in order to locate a particular resource—for example, a public key inside a DID document, or a resource available external to the DID document.
DID Subjects
The subject of a DID is, by definition, the entity identified by the DID. The DID subject may also be the DID controller. Anything can be the subject of a DID: person, group, organization, physical thing, logical thing, etc.
DID Controllers
The controller of a DID is the entity (person, organization, or autonomous software) that has the capability—as defined by a DID method—to make changes to a DID document. This capability is typically asserted by the control of a set of cryptographic keys used by software acting on behalf of the controller, though it may also be asserted via other mechanisms. Note that a DID may have more than one controller, and the DID subject can be the DID controller, or one of them.
Verifiable Data Registries
In order to be resolvable to DID documents, DIDs are typically recorded on an underlying system or network of some kind. Regardless of the specific technology used, any such system that supports recording DIDs and returning data necessary to produce DID documents is called a verifiable data registry. Examples include distributed ledgers, decentralized file systems, databases of any kind, peer-to-peer networks, and other forms of trusted data storage.
DID documents
DID documents contain metadata associated with a DID. They typically express verification methods (such as public keys) and services relevant to interactions with the DID subject. A DID document is represents an abstract data model, and can be serialized according to a particular syntax (see ). The generic properties supported in a DID document are specified in . The DID itself is the value of the `id` property. The properties present in a DID document may be updated according to the applicable operations outlined in .
DID Methods
DID methods are the mechanism by which a particular type of DID and its associated DID document are created, resolved, updated, and deactivated using a particular verifiable data registry. DID methods are defined using separate DID method specifications (see ).

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.

DID resolvers and DID resolution
A DID resolver is a software and/or hardware component that takes a DID (and associated input metadata) as input and produces a conforming DID document (and associated metadata) as output. This process is called DID resolution. The inputs and outputs of the DID resolution process are defined in . The specific steps for resolving a specific type of DID are defined by the relevant DID method specification. Additional considerations for implementing a DID resolver are discussed in [[DID-RESOLUTION]].
DID URL dereferencers and DID URL dereferencing
A DID URL dereferencer is a software and/or hardware component that takes a DID URL (and associated input metadata) as input and produces a resource (and associated metadata) as output. This process is called DID URL dereferencing. The inputs and outputs of the DID URL dereferencing process are defined in . Additional considerations for implementing a DID URL dereferencer are discussed in [[DID-RESOLUTION]].

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.

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 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 and . A serialization format for the conforming document is deterministic, bi-directional, and lossless as described in Section .

A conforming DID method is any specification that complies with the relevant normative statements in Section .

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.

Terminology

In addition to the terminology above, this specification also uses terminology from the [[INFRA]] specification to formally define the abstract data model. When [[INFRA]] terminology is used, such as string, ordered set, and map, it is linked directly to that specification.

Identifier

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.

DID Syntax

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 an ASCII lowercase string.

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 / "." / "-" / "_"
      

For requirements on DID methods relating to the DID syntax, see Section .

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.

DID URL Syntax

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 . 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]].

DID Parameters

The DID URL syntax supports a simple format for parameters based on the query component (See ). 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
relative-ref 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.
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.
version-id 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.
version-time 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.

Implementers as well as DID method specification authors MAY 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 MAY 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]].

Two example DID URLs using the service and version-time DID parameters are shown below.

did:foo:21tDAKCERh95uGgKbJNHYp?service=agent
        
did:foo:21tDAKCERh95uGgKbJNHYp?version-time=2002-10-10T17:00:00Z
        

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 ). 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.

Path

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
        

Query

A DID query is derived from a generic URI query and MUST conform to the did-query ABNF rule in Section . If a DID query is present, it MUST be used as described in Section .

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
        

Fragment

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 .

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 ). 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:

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 .

Relative DID URLs

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 . 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 . 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 , Section , and Section , 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",
    "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.

Data Model

This specification defines an abstract 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 properties, where each property consists of a property name/property value pair. The data model contains at least two different classes of properties. The first class of properties are called core properties, and are specified in section . The second class of properties are called representation properties, and are specified in section .

All property names in the data model are strings. All property values are expressed using one of the data types in the table below.

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 list 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]].

Extensibility

The data model supports two types of extensibility.

  1. For maximum interoperability, it is RECOMMENDED that extensions use the official W3C DID Specification Registries mechanism [[?DID-SPEC-REGISTRIES]]. The use of this mechanism for new properties or other extensions is the only specified method that ensures that two different representations will be able to work together.
  2. Representations MAY define other extensibility mechanisms including methods for decentralized extensions. Such extension mechanisms MUST support lossless conversion into any other conformant representation.

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.

Core Properties

A DID points to a DID document. DID documents are the serialization of the data model outlined in Section . 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.

For reference, the core properties found at the top level of a DID document are as follows. Properties belonging to other objects referenced in the DID document are also listed, with their respective top-level property.

As a result of the data model being defined using terminology from [[INFRA]], property values which can contain more than one item, such as lists 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.

DID Subject

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.

Identifier

The DID for a particular DID subject is denoted with the id property at the top level of a DID document.

DID documents MUST include the id property at the top level.

id
The value of id MUST be a string that conforms to the rules in Section .
{
  "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, or be populated with the equivalent canonical DID specified by the DID method, which SHOULD be used by the resolving party going forward.

A DID document can contain objects which have their own unique identifier; see, for example, . 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.

Also Known As

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
The value of alsoKnownAs MUST be a list where each item in the list is a URI conforming to [[RFC3986]].
This relationship is a statement that the subject of this identifier is also identified by one or more other identifiers.

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.

DID Controller

Authorization is the mechanism used to state how operations are performed on behalf of the DID subject. A DID controller is authorized to make changes to the respective DID document.

A DID document MAY include a controller property to indicate the DID controller(s). If so:

controller
The value of the controller property MUST be a string or an ordered set of strings that conform to the rules in Section . 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 . This is particularly important for key recovery in the case of 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 .

{
  "@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",
    "serviceEndpoint": "https://example.com/vc/"
  }]
}
      

Verification Methods

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 . 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.

verificationMethod

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 MAY 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 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 .

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 on the top level of the DID document; see Section .

{
  "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/security/v1"],
  "id": "did:example:123456789abcdefghi",
  ...
  "verificationMethod": [{
    "id": ...,
    "type": ...,
    "controller": ...,
    ...
  ]}
}
      

As well as the verificationMethod property, verification methods can be embedded in or referenced from properties associated with various verification relationships (see ). 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:

  1. Let value be the data associated with the verificationMethod property or property for a particular verification relationship and initialize result to null.
  2. If value is an object, the verification method material is embedded. Set result to value.
  3. If value is a string, the verification method is included by reference. Assume value is a URL.
    1. Dereference the URL and retrieve the verificationMethod properties associated with the URL. For example, process the verificationMethod property at the top-level of the dereferenced document.
    2. Iterating through each object, if the id property of the object matches value, set result to the object.
  4. If result does not contain at least the 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",
      "controller": "did:example:123456789abcdefghi",
      "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],

...
}
      

Key types and formats

A public key can be used as a verification method.

A verification method MUST NOT contain multiple verification material properties. For example, expressing key material in a verification method using both publicKeyJwk and publicKeyBase58 at the same time is prohibited.

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. The specific types of key formats that are supported in this specification are listed here.

When using any of the public key types described here, public key expression MUST NOT use any other key format than those listed in the Public Key Support table. For public key types that are not listed here, the type value and corresponding format property SHOULD be registered in [[?DID-SPEC-REGISTRIES]], as with any other verification method.

The Working Group is still debating whether the base encoding format used will be Base58 (Bitcoin) [[?BASE58]], base64url [[RFC7515]], or base16 (hex) [[RFC4648]]. The entries in the table below currently assume PEM and Base58 (Bitcoin), but might change to base64url and/or base16 (hex) after the group achieves consensus on this particular issue.

The Working Group is still debating whether secp256k1 Schnorr public key values will be elaborated upon in this specification and if so, how they will be expressed and encoded.

The Working Group is still debating how best to communicate support for specific verification method types.

This table defines the support for public key expression in a DID document. For each public key type, a maximum of two encoding formats is supported.
Key Type
(type value)
Support
RSA
(RsaVerificationKey2018)
RSA public key values MUST be encoded as a JWK [[RFC7517]] using the publicKeyJwk property.
ed25519
(Ed25519VerificationKey2018)
Ed25519 public key values MUST either be encoded as a JWK [[RFC7517]] using the publicKeyJwk or be encoded as the raw 32-byte public key value in Base58 Bitcoin format [[?BASE58]] using the publicKeyBase58 property.
secp256k1 Secp256k1 public key values MUST either be encoded as a JWK [[RFC7517]] using the publicKeyJwk or be encoded as the raw 33-byte public key value in Base58 Bitcoin format [[?BASE58]] using the publicKeyBase58 property.
Curve25519
(X25519KeyAgreementKey2019)
Curve25519 (also known as X25519) public key values MUST either be encoded as a JWK [[RFC7517]] using the publicKeyJwk or be encoded as the raw 32-byte public key value in Base58 Bitcoin format [[?BASE58]] using the publicKeyBase58 property.
JWK
(JsonWebKey2020)
Key types listed in JOSE, represented using [[RFC7517]] using the publicKeyJwk property.

Example:

{
  "@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",
    "controller": "did:example:123",
    "publicKeyJwk": {
      "crv": "Ed25519",
      "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ",
      "kty": "OKP",
      "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A"
    }
  }, {
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "Ed25519VerificationKey2018",
    "controller": "did:example:pqrstuvwxyz0987654321",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }],
  ...
}
        

If a public key does not exist in the DID document, the key was revoked or is invalid. The DID document MUST NOT express revoked keys using a verification relationship. 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 .

Verification Relationships

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 MUST be explicit in the DID document. Verification methods that are not associated with a particular verification relationship MUST NOT 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]].

Authentication

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
The 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 DID 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 ) 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* authorized 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",
      "controller": "did:example:123456789abcdefghi",
      "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],
  ...
}
        

Assertion

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
The 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* authorized 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",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
  }
],
...
}
        

Key Agreement

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
The 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* authorized 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",
      "controller": "did:example:123",
      "publicKeyBase58": "9hFgmPVfmBZwRvFEyniQDBkz9LmV7gDEqytWyGZLmDXE"
    }
  ],
  ...
}
        

Capability Invocation

The `capabilityInvocation` verification relationship is used to specify a mechanism that might be used by the DID subject to invoke a cryptographic capability, such as the authorization to access an HTTP API.

capabilityInvocation
The 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* authorized 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",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],
  ...
}
        

Capability Delegation

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
The 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* authorized 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",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
    }
  ],
  ...
}
        

Service Endpoints

Service endpoints 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 for additional details. The metadata associated with services are often service-specific. For example, the metadata 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 serviceEndpoint property with a URI or a set of other properties describing the service.

One of the primary purposes of a DID document is to enable discovery of service endpoints. A service endpoint 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.

service

If a DID document includes a service property, the value of the property SHOULD be an ordered set of service endpoints, where each service endpoint is described by a set of properties. Each service endpoint MUST have id, type, and serviceEndpoint properties, and MAY include additional properties.

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 valid URI 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, OR a set of properties which describe the service endpoint further.

It is expected that the service endpoint protocol is published in an open standard specification.

{
  "service": [{
    "id": "did:example:123456789abcdefghi#openid",
    "type": "OpenIdConnectVersion1.0Service",
    "serviceEndpoint": "https://openid.example.com/"
  }, {
    "id": "did:example:123456789abcdefghi#vcr",
    "type": "CredentialRepositoryService",
    "serviceEndpoint": "https://repository.example.com/service/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#xdi",
    "type": "XdiService",
    "serviceEndpoint": "https://xdi.example.com/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#agent",
    "type": "AgentService",
    "serviceEndpoint": "https://agent.example.com/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#hub",
    "type": "IdentityHub",
    "verificationMethod": "did:example:123456789abcdefghi#key-1",
    "serviceEndpoint": {
      "@context": "https://schema.identity.foundation/hub",
      "type": "UserHubEndpoint",
      "instances": ["did:example:456", "did:example:789"]
    }
  }, {
    "id": "did:example:123456789abcdefghi#messages",
    "type": "MessagingService",
    "serviceEndpoint": "https://example.com/messages/8377464"
  }, {
    "id": "did:example:123456789abcdefghi#inbox",
    "type": "SocialWebInboxService",
    "serviceEndpoint": "https://social.example.com/83hfh37dj",
    "description": "My public social inbox",
    "spamCost": {
      "amount": "0.50",
      "currency": "USD"
    }
  }, {
    "id": "did:example:123456789abcdefghi#authpush",
    "type": "DidAuthPushModeVersion1",
    "serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefg"
  }]
}
      

For more information about security considerations regarding authentication service endpoints see Sections and .

Representations

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 DID document model (described in Sections and ); translation between any two representations is done by parsing the source format into a DID document model and then serializing the DID document 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 content-type DID resolver metadata field (see ), not through the content of the DID document alone.

Unrecognized properties MUST be preserved. An unrecognized property is any property that does not have explicit processing rules known to the consumer or producer. Consumers MUST add all properties that do not have explicit processing rules for the representation being consumed to the abstract data model using only the representation's generic type processing rules. Producers MUST serialize all properties in the abstract 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 properties 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 properties in the abstract data model using only their generic type processing rules to enable lossless conversion of representations. Similarly, producers are required to treat properties containing representation-specific syntax using generic type processing rules when producing a representation for which the property is not defined. Representations are required to define producer behavior for any such properties defined by the representation.

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 localized rules for handling properties not listed in the registry. See section for more information.

Representation Requirements

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:

  1. A representation MUST define an unambiguous encoding and decoding for all property names and all data model data types as defined in this specification. This enables anything that can be represented in the DID document data model to also be represented in a compliant representation.
  2. The representation MUST be uniquely associated with an IANA-registered MIME type.
  3. The representation MUST define fragment processing rules for its MIME type that are conformant with the fragment processing rules defined in section of this specification.
  4. The representation MAY define representation-specific syntax that can be stored as properties in the abstract data model. These properties are included when consuming or producing to aid in ensuring lossless conversion.

In order to maximize interoperability, representation specification authors SHOULD register their representation in the [[?DID-SPEC-REGISTRIES]].

JSON

This section sets out the requirements for producing and consuming DID documents that are in plain JSON (as indicated by a content-type of application/did+json in the resolver metadata).

Production

A DID document MUST be a single JSON object conforming to [[!RFC8259]]. All top-level properties of the DID document MUST be represented by using the property name as the name of the member of the JSON object. The values of properties of the data model described in Section , including all extensions, are encoded in JSON [[RFC8259]] by mapping property values to JSON types as follows:

Data Type JSON Representation Type
ordered map JSON Object, each property is represented as a member of the JSON Object with the property name as the member name and the property 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 list 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
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 properties of the DID document MUST be included in the root object. Properties MAY define additional data sub structures subject to the value representation rules in the list above.

Consumption

The top-level element MUST be a JSON object. Any other data type at the top level is an error and MUST be rejected. The top-level JSON object represents the DID document, and all members of this object are properties of the DID document. The object member name is the property name, 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 a property to the ordered map with the property name being the member name and the value converted based on the JSON type and, if available, property definition, as defined here; as no order is specified by JSON Objects, no insertion order is guaranteed
JSON Array where data model property 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 property 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 property value is an datetime datetime
JSON String, where data model property value type is string or unknown string
JSON Number without a decimal or fractional component integer
JSON Number with a fractional component, or when property 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 value of the @context object member will be ignored, if present. That is, this field will not have additional processing applied to its value and will be added verbatim to the abstract data model.

JSON-LD

[[!JSON-LD11]] is a JSON-based format used to serialize Linked Data.

This section sets out the requirements for producing and consuming DID documents that are in JSON-LD (as indicated by a content-type of application/did+ld+json in the resolver metadata).

Use of the media type application/did+ld+json is pending clarification over registration of media types with multiple suffixes. The alternative will be to use application/did+jsonld if multiple suffixes cannot be registered by the time the rest of DID Core is ready for PR.

Production

The DID document MUST be serialized as a JSON document, with one additional requirement: The DID document MUST include the @context property.

@context

The JSON-LD specification defines values that are valid for this property. This property contains representation-specific syntax and therefore could be present in the abstract data model to aid in lossless conversion. If the property is present in the abstract 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 abstract data model is not valid according to the consumption rules.

The value of @context MUST be exactly one of these values.

  • The INFRA string https://www.w3.org/ns/did/v1.
    {
      "@context": "https://www.w3.org/ns/did/v1",
      ...
    }
                    
  • An INFRA list, with first item the INFRA string 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"
      ],
      ...
    }
                    

    The working group is still discussing restrictions on @base, beyond what JSON-LD allows.

All members of the @context property 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 property results in a document containing machine-readable information about the context. These URIs SHOULD be associated with a cryptographic hash of the content of the JSON-LD Context as part of registration in the DID Specification Registries [[?DID-SPEC-REGISTRIES]].

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.

Consumption

The top-level element MUST be a JSON object. Any other data type at the top level is an error and MUST be rejected. This top-level JSON object is interpreted using JSON-LD processing under the rules of the defined @context fields.

@context

The value of the @context property 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.

CBOR

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. CBOR prioritizes the simplicity of the encoder and decoder over the size of the encoded data. With specific constraints, CBOR can support all JSON data types for translation between the DID document model (described in Data Model and the Core Properties section of the DID Document).

When producing and consuming DID documents that are encoded in CBOR (as indicated by a content-type of application/did+cbor in the resolver metadata), the following rules MUST be followed.

Production

A DID document encoded in CBOR must be represented as a CBOR Map (major type 5) conforming to [[RFC7049]]. Similar to the JSON encoding of a DID document, all properties of the DID document MUST be represented by using the property name as the name of the member of the CBOR map. The values of properties of the data model described in § 5. Core Properties, including all extensions, MUST be encoded in CBOR [[RFC7049]] by mapping INFRA property values to CBOR types as follows:

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:

  • Property names MUST be represented as text string (major type 3) and contain only UTF-8 strings.
  • Undefined Values of Required Properties as defined in the Data Model that are absent from the CBOR representation SHOULD be labeled with Primitive type (major type 7) with value 23 (Undefined value).
  • Property names in each CBOR map MUST be unique.
  • Integer encoding MUST be as short as possible.
  • The expression of lengths in CBOR major types 2 through 5 MUST be as short as possible.
  • The keys in every map must be sorted lowest value to highest. Sorting is performed on the bytes of the representation of the keys. If two keys have different lengths, the shorter one sorts earlier. If two keys have the same length, the one with the lower value in (byte-wise) lexical order sorts earlier.

How to represent Floating-point values that can exceed the range or the precision IEEE 754. See issue #361.

The property name `@context` MAY be present in the CBOR representation of a DID Document and if present SHOULD be ignored as this property is reserved for JSON-LD processing.

All properties of the DID document represented in CBOR MUST be included in the root map (major type 5). Properties 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"
        

Consumption

When consuming DID Documents that are represented as CBOR and interpreting the data types with respect to the Abstract Data Model using INFRA types the following consumption rules MUST be followed:

Additional Considerations:

CBOR Extensibility

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 othere 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

DagCBOR is a further restricted subset of CBOR for representing the DID Document as a Directed Acyclic Graph model using canonical CBOR encoding as noted above 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 MUST be followed

  • Use no CBOR tags other than the CID tag (42)
            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"
                    

Converting Data between Core Representations

Transformation between various core representations SHOULD be performed through parsing and serializing via the Abstract DID Document Data Model (see and Production and Consumptions rules between core representation via the Abstract Data Model). Given that CBOR is a superset of JSON, the following non-normative advice is given for converting a DID document between CBOR and JSON.

This section conflicts with other parts of the specification, since conversion has to be defined not between any two representations directly, but rather in terms of parsing and serializing via the abstract DID document data model (see and ). The content of this section can potentially be adapted and re-used in other sections such as the one about the CBOR representation (see ).

CBOR to JSON

Most of the types in CBOR have direct analogs in JSON. The following constraints allow for lossless conversion from CBOR to JSON:

  • A CBOR integer (major type 0 or 1) becomes a JSON number.
  • A CBOR array (major type 4) becomes a JSON array.
  • A CBOR map (major type 5) becomes a JSON object. This is possible directly only if all keys are UTF-8 strings. A converter might also convert other keys into UTF-8 strings (such as by converting integers into strings containing their decimal representation); however, doing so introduces a danger of key collision.
  • CBOR Boolean False (major type 7, additional information 20) becomes a JSON false.
  • CBOR Boolean True (major type 7, additional information 21) becomes a JSON true.
  • CBOR Null (major type 7, additional information 22) becomes a JSON null.
  • A CBOR floating-point value (major type 7, additional information 25 through 27) becomes a JSON number if it is finite (that is, it can be represented in a JSON number); if the value is non-finite (NaN, or positive or negative Infinity), it is represented by the substitute value.
  • A CBOR byte string with an encoding hint (major type 6, tag number 21 through 23) is encoded as described and becomes a JSON string.

When interoperating with a text-based representation such as JSON or JSON-LD it is helpful to utilize additional sematics to aid convertion. CBOR Tags numbers 21 to 23 indicate that a byte string value in DID document represented in CBOR might require a specific encoding to represent properly in JSON.

Methods

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 .

Method Schemes

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 ).

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.

Method Operations

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 MAY:

Each DID method MUST define how authorization is implemented, including any necessary cryptographic operations.

Create

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.

Read/Verify

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.

Update

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.

Deactivate

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.

Security Requirements

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 .

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 endpoint types (see Section ) SHOULD consider the security requirements of the supported authentication protocol.

Privacy Requirements

DID method specifications MUST include their own Privacy Considerations sections, if only to point to .

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.

Resolution

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.

DID Resolution

The DID resolution functions resolve a DID into a DID document by using the "Read" operation of the applicable DID method. (See .) The details of how this process is accomplished are outside the scope of this specification, but all conformant implementations MUST 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 input variables of these functions are as follows:

did
This is the DID to resolve. This input is REQUIRED and the value MUST be a conformant DID expressed as a single string.
did-resolution-input-metadata
A metadata structure consisting of input options to the resolve and resolveRepresentation functions in addition to the did itself. Properties defined by this specification are in . This input is REQUIRED, but the structure MAY be empty.

The output variables of these functions are as follows:

did-resolution-metadata

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 .

If the resolution is successful, and if the resolveRepresentation function was called, this structure MUST contain a content-type 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.

did-document
If the resolution is successful, and if the resolve function was called, this MUST be a conforming DID document. If the resolution is unsuccessful, this value MUST be empty.
did-document-stream
If the resolution is successful, and if the resolveRepresentation function was called, this MUST be a byte stream of the resolved DID document in one of the conformant representations. The byte stream MAY then be parsed by the caller of the resolveRepresentation function into a DID document abstract data model, which can in turn be validated and processed. If the resolution is unsuccessful, this value MUST be an empty stream.
did-document-metadata
If the resolution is successful, this MUST be a metadata structure. This structure contains metadata about the DID document contained in the 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 .

DID resolver implementations MUST NOT alter the signature of these functions in any way. DID resolver implementations MAY map the resolve and resolveRepresentation functions to a method-specific internal function to perform the actual DID resolution process. DID resolver implementations MAY implement and expose additional functions with different signatures in addition to the resolve function specified here.

DID Resolution Input Metadata Properties

The possible properties within this structure and their possible values are defined by [[?DID-SPEC-REGISTRIES]]. This specification defines the following common properties.

accept
The MIME type of the caller's preferred representation of the DID document. The DID resolver implementation SHOULD use this value to determine the representation contained in the returned 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.

DID Resolution Metadata Properties

The possible properties within this structure and their possible values are defined by [[?DID-SPEC-REGISTRIES]]. This specification defines the following common properties.

content-type
The MIME type of the returned 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 the MIME type of one 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 a DID document abstract data model.
error
The error code from the resolution process. This property is REQUIRED when there is an error in the resolution process. The value of this property MUST be a single keyword string. The possible property values of this field SHOULD be registered in the DID Specification Registries [[?DID-SPEC-REGISTRIES]]. This specification defines the following error values:
invalid-did
The DID supplied to the DID resolution function does not conform to valid syntax. (See .)
not-found
The DID resolver was unable to find the DID document resulting from this resolution request.
deactivated
The DID supplied to the DID resolution function has been deactivated. (See .)

DID Document Metadata Properties

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.

created
DID document metadata SHOULD include a created property to indicate the timestamp of the Create operation. This property MAY not be supported by a given DID method. The value of the property MUST be 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".
updated
DID document metadata SHOULD include an updated property to indicate the timestamp of the last Update operation. This property MAY not be supported by a given DID method. The value of the property MUST follow the same formatting rules as the created property.

DID URL Dereferencing

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. The details of how this process is accomplished are outside the scope of this specification, but all conformant implementations MUST 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 MUST be as follows:

did-url
A conformant DID URL as a single string. This is the DID URL to dereference. To dereference a DID fragment, the complete DID URL including the DID fragment MUST be used. This input is REQUIRED.
did-url-dereferencing-input-metadata
A metadata structure consisting of input options to the dereference function in addition to the did-url itself. Properties defined by this specification are in . This input is REQUIRED, but the structure MAY be empty.

The output variables of this function MUST be as follows:

did-url-dereferencing-metadata
A metadata structure consisting of values relating to the results of the DID URL Dereferencing process. This structure is REQUIRED and in the case of an error in the dereferencing process, this MUST NOT be empty. Properties defined by this specification are in . If the dereferencing is not successful, this structure MUST contain an error property describing the error.
content-stream
If the dereferencing function was called and successful, this MUST contain a resource corresponding to the DID URL. The content-stream MAY 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-metadata
If the dereferencing is successful, this MUST be a metadata structure, but the structure MAY be empty. This structure contains metadata about the 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.

DID URL Dereferencing implementations MUST NOT alter the signature of these functions in any way. DID URL Dereferencing implementations MAY map the dereference function to a method-specific internal function to perform the actual DID URL Dereferencing process. DID URL Dereferencing implementations MAY implement and expose additional functions with different signatures in addition to the dereference function specified here.

DID URL Dereferencing Input Metadata Properties

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.

accept
The MIME type the caller prefers for 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. This property is OPTIONAL.

DID URL Dereferencing Metadata Properties

The possible properties within this structure and their possible values are defined by [[?DID-SPEC-REGISTRIES]]. This specification defines the following common properties.

content-type
The MIME type of the returned content-stream. This property is OPTIONAL if dereferencing is successful.
error
The error code from the dereferencing process. This property is REQUIRED when there is an error in the dereferencing process. The value of this property is a single keyword string. The possible property values of this field SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES]]. This specification defines the following error values:
invalid-did-url
The DID URL supplied to the DID URL Dereferencing function does not conform to valid syntax. (See .)
not-found
The DID URL dereferencer was unable to find the content-stream resulting from this dereferencing request.
deactivated
The DID in the DID URL supplied to the DID URL dereferencing function has been deactivated. (See .)

Metadata Structure

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, 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 MUST be 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": "not-found"
}
        

This example corresponds to a metadata structure of the following format:

«[
  "error" → "not-found"
]»
        

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"
]»
        

Security Considerations

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.

Choosing DID Resolvers

The DID Method Registry (see [[?DID-SPEC-REGISTRIES]] is 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.

Binding of Identity

The following sections describe binding identities to DIDs and DID documents.

Proving Control of a DID and DID Document

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:

  • DID document was not tampered with since it was timestamped.
  • DID controller(s) controlled the private key used for the signature at the time the timestamp was created.

Proving control of a DID, that is, the binding between the DID and the DID document that describes it, requires a two step process:

  1. Resolving the DID to a DID document according to its DID method specification.
  2. Verifying that the 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.

Proving Control of a Public Key

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:

  1. Send a challenge message containing a public key description from the DID document and a nonce to an appropriate service endpoint described in the DID document.
  2. Verify the signature of the response message against the public key description.

Real-World Identity

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 ).

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 [[VC-DATA-MODEL]] instead.

Authentication Service Endpoints

If a DID document publishes a service endpoint intended for authentication or authorization of the DID subject (see Section ), 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

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 ) and the target DLT system supports timestamps.

Notification of DID Document Changes

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.

Key and Signature Expiration

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 might have legitimate reasons why already-expired keys can be extended, make sure a key expiration does not prevent any further use of the key, and implementations of a resolver ought to be compatible with such extension behavior.

Key Revocation and Recovery

Section specifies the DID operations to be supported by a DID method specification, including deactivation of a DID document by replacing it with an updated DID document. It is also up to the DID method to define how revocation of cryptographic keys might occur. Additionally, 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 . 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. Further specification of this type of control is a matter for future work.

The Role of Human-Friendly Identifiers

DIDs achieve global uniqueness without the need for a central registration authority. This comes, however, at the cost of human memorability. The algorithms capable of generating globally unique identifiers automatically produce random strings of characters that have no human meaning. This demonstrates the axiom about identifiers described in Zooko's Triangle: "human-meaningful, decentralized, secure — pick any two".

There are of course many 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, Twitter handle, 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:

A draft specification for discovering a DID from domain names and email addresses using DNS lookups is available at [[?DNS-DID]].

Immutability

Many cybersecurity abuses hinge on exploiting gaps between reality and the assumptions of rational, good-faith actors. Like any ecosystem, the DID ecosystem has some potential for this to occur. Because this specification is focused on a data model instead of a protocol, it offers no opinion about many aspects of how that model is put to use. However, individual DID methods might want 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 the flexibility that the data model offers with respect to updating. A single edit to a DID document can change anything and everything except the root id property of the document. And any individual JSON object in the data model can change all of its properties except its id. But is it actually desirable for a service endpoint 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 web site often aim for an outcome where the site keeps its identifier (the host name), but gets subtle, dangerous changes 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.

The notion that immutability provides some cybersecurity benefits is particularly relevant because of caching. 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.

Encrypted Data in DID Documents

DID documents are typically publicly available. 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.

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.

Privacy Considerations

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. For example, privacy in this specification is preventative not remedial, and privacy is an embedded default. Furthermore, the decentralized identifier architecture by itself embodies Privacy by Design principle #7: "Respect for user privacy — keep it user-centric."

This section lists additional privacy considerations that implementers, delegates, and DID subjects should keep in mind.

Keep Personally-Identifiable Information (PII) Private

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 personal data. All personal data should be kept behind service endpoints under the control of the DID subject. Additional due diligence should be taken around the use of URLs in service endpoints as well to prevent leakage of unintentional personal data or correlation within a URL of a service endpoint. For example, a URL that contains a username is likely dangerous to include in a DID Document because the username is likely to be human-meaningful in a way that can unintentionally 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.

DID Correlation Risks and Pseudonymous DIDs

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.

DID Document Correlation Risks

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.

Assigning a type to the DID subject

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 ) or correlatable data (see and ) 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.

Herd Privacy

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.

Examples

DID Documents

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",
              "controller": "did:example:123",
              "publicKeyBase58": "AKJP3f7BD6W4iWEQ9jwndVTCBq8ua2Utt8EEjJ6Vxsf"
            }
          ],
          "capabilityInvocation": [
            {
              "id": "did:example:123#z6MkhdmzFu659ZJ4XKj31vtEDmjvsi5yDZG5L7Caz63oP39k",
              "type": "Ed25519VerificationKey2018",
              "controller": "did:example:123",
              "publicKeyBase58": "4BWwfeqdp1obQptLLMvPNgBw48p7og1ie6Hf9p5nTpNN"
            }
          ],
          "capabilityDelegation": [
            {
              "id": "did:example:123#z6Mkw94ByR26zMSkNdCUi6FNRsWnc2DFEeDXyBGJ5KTzSWyi",
              "type": "Ed25519VerificationKey2018",
              "controller": "did:example:123",
              "publicKeyBase58": "Hgo9PAmfeoxHG8Mn2XHXamxnnSwPpkyBHAMNF3VyXJCL"
            }
          ],
          "assertionMethod": [
            {
              "id": "did:example:123#z6MkiukuAuQAE8ozxvmahnQGzApvtW7KT5XXKfojjwbdEomY",
              "type": "Ed25519VerificationKey2018",
              "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",
              "controller": "did:example:123",
              "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
            },
            {
              "id": "did:example:123#zQ3shP2mWsZYWgvgM11nenXRTx9L1yiJKmkf9dfX7NaMKb1pX",
              "type": "EcdsaSecp256k1VerificationKey2019",
              "controller": "did:example:123",
              "publicKeyBase58": "d5cW2R53NHTTkv7EQSYR8YxaKx7MVCcchjmK5EgCNXxo",
            },
            {
              "id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
              "type": "JsonWebKey2020",
              "controller": "did:example:123",
              "publicKeyJwk": {
                "kty": "OKP",
                "crv": "Ed25519",
                "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ"
              }
            },
            {
              "id": "did:example:123#z6LSnjagzhe8Df6gZmroW3wjDd7XQLwAuYfwa4ZeTBCGFoYc",
              "type": "JsonWebKey2020",
              "controller": "did:example:123",
              "publicKeyJwk": {
                "kty": "OKP",
                "crv": "X25519",
                "x": "pE_mG098rdQjY3MKK2D5SUQ6ZOEW3a6Z6T7Z4SgnzCE"
              },
            }
            {
              "id": "did:example:123#4SZ-StXrp5Yd4_4rxHVTCYTHyt4zyPfN1fIuYsm6k3A",
              "type": "JsonWebKey2020",
              "controller": "did:example:123",
              "publicKeyJwk": {
                "kty": "EC",
                "crv": "secp256k1",
                "x": "Z4Y3NNOxv0J6tCgqOBFnHnaZhJF6LdulT7z8A-2D5_8",
                "y": "i5a2NtJoUKXkLm6q8nOEu9WOkso1Ag6FTUT6k_LMnGk"
              }
            },
            {
              "id": "did:example:123#n4cQ-I_WkHMcwXBJa7IHkYu8CMfdNcZKnKsOrnHLpFs",
              "type": "JsonWebKey2020",
              "controller": "did:example:123",
              "publicKeyJwk": {
                "kty": "RSA",
                "e": "AQAB",
                "n": "omwsC1AqEk6whvxyOltCFWheSQvv1MExu5RLCMT4jVk9khJKv8JeMXWe3bWHatjPskdf2dlaGkW5QjtOnUKL742mvr4tCldKS3ULIaT1hJInMHHxj2gcubO6eEegACQ4QSu9LO0H-LM_L3DsRABB7Qja8HecpyuspW1Tu_DbqxcSnwendamwL52V17eKhlO4uXwv2HFlxufFHM0KmCJujIKyAxjD_m3q__IiHUVHD1tDIEvLPhG9Azsn3j95d-saIgZzPLhQFiKluGvsjrSkYU5pXVWIsV-B2jtLeeLC14XcYxWDUJ0qVopxkBvdlERcNtgF4dvW4X00EHj4vCljFw"
              }
            },
            {
              "id": "did:example:123#_TKzHv2jFIyvdTGF1Dsgwngfdg3SH6TpDv0Ta1aOEkw",
              "type": "JsonWebKey2020",
              "controller": "did:example:123",
              "publicKeyJwk": {
                "kty": "EC"
                "crv": "P-256",
                "x": "38M1FDts7Oea7urmseiugGW7tWc3mLpJh6rKe7xINZ8",
                "y": "nDQW6XZ7b_u2Sy9slofYLlG03sOEoug3I0aAPQ0exs4"
              }
            },
            {
              "id": "did:example:123#8wgRfY3sWmzoeAL-78-oALNvNj67ZlQxd1ss_NX1hZY",
              "type": "JsonWebKey2020",
              "controller": "did:example:123",
              "publicKeyJwk": {
                "kty": "EC",
                "crv": "P-384",
                "x": "GnLl6mDti7a2VUIZP5w6pcRX8q5nvEIgB3Q_5RI2p9F_QVsaAlDN7IG68Jn0dS_F",
                "y": "jq4QoAHKiIzezDp88s_cxSPXtuXYFliuCGndgU4Qp8l91xzD1spCmFIzQgVjqvcP"
              }
            },
            {
              "id": "did:example:123#NjQ6Y_ZMj6IUK_XkgCDwtKHlNTUTVjEYOWZtxhp1n-E",
              "type": "JsonWebKey2020",
              "controller": "did:example:123",
              "publicKeyJwk": {
                "kty": "EC",
                "crv": "P-521",
                "x": "AVlZG23LyXYwlbjbGPMxZbHmJpDSu-IvpuKigEN2pzgWtSo--Rwd-n78nrWnZzeDc187Ln3qHlw5LRGrX4qgLQ-y",
                "y": "ANIbFeRdPHf1WYMCUjcPz-ZhecZFybOqLIJjVOlLETH7uPlyG0gEoMWnIZXhQVypPy_HtUiUzdnSEPAylYhHBTX2"
              }
            }
          ]
        }
      

Proving

These examples are for information purposes only. See W3C Verifiable Credentials Data Model for additional examples.

      {
        "@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"
        }
      }
    
{
  "@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"
  }
}
      
        {
          "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"
        }
      

Encrypting

These examples are for information purposes only, it is considered a best practice to avoid dislosing unnecessary information in JWE headers.

        {
          "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"
        }
      

Current Issues

The list of issues below are under active discussion and are likely to result in changes to this specification.

Cheap DIDs and the option to migrate DIDs between ledgers using standard DID Deprecation Registries
Registry handling
Privacy Considerations - Specifically call out GDPR
Horizontal Review: Internationalization self test
Horizontal Review: Accessibility self test
Specification needs to be compliant with WCAG 2.0
Horizontal Review: offer review opportunity to TAG
Include discussion of eIDAS levels-of-assurance
Uses of terms defined in the specification should be links to their definitions
Public key "id" and "type" members duplicate JWK "kid" and "kty" members
Underspecified semantics of "updated" property
Clarification on what DIDs might identify
How to treat unknown properties
IETF did+ld+json media type registration
Should did-core restrict the use of JWK?
How to mitigate the single source of failure wrt/ "Trust into the Universal Resolver"?
Added DID resolution and dereferencing contracts.
Put key points up front
Added CBOR section
PING Horizontal Review
Horizontal Review Tracking
Define simple type-less resolution function
Define resolution function with data types
Define resolution function with data types and property values
Define resolution function with data types, property values, and simple metadata structures
Define resolution function with data types, property values, and full metadata structures
Define resolution function with data types, property values, and full metadata structures, without transformation

IANA Considerations

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.

application/did+json

Type name:
application
Subtype name:
did+json
Required parameters:
None
Optional parameters:
None
Encoding considerations:
See RFC 8259, section 11.
Security considerations:
See RFC 8259, section 12 [[RFC8259]].
Interoperability considerations:
Not Applicable
Published specification:
http://www.w3.org/TR/did-core/
Applications that use this media type:
Any application that requires an identifier that is decentralized, persistent, cryptographically verifiable, and resolvable. Applications typically consist of cryptographic identity systems, decentralized networks of devices, and websites that issue or verify W3C Verifiable Credentials.
Additional information:
Magic number(s):
Not Applicable
File extension(s):
.did
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
Ivan Herman <ivan@w3.org>
Intended usage:
Common
Restrictions on usage:
None
Author(s):
Drummond Reed, Manu Sporny, Markus Sabadello, Dave Longley, Christopher Allen
Change controller:
W3C

Fragment identifiers used with application/did+json are treated according to the rules defined in .

application/did+ld+json

Use of the media type application/did+ld+json is pending clarification over registration of media types with multiple suffixes. The alternative will be to use application/did+jsonld if multiple suffixes cannot be registered by the time the rest of DID Core is ready for PR.

Type name:
application
Subtype name:
did+ld+json
Required parameters:
None
Optional parameters:
None
Encoding considerations:
See RFC 8259, section 11.
Security considerations:
See JSON-LD 1.1, Security Considerations [[JSON-LD11]].
Interoperability considerations:
Not Applicable
Published specification:
http://www.w3.org/TR/did-core/
Applications that use this media type:
Any application that requires an identifier that is decentralized, persistent, cryptographically verifiable, and resolvable. Applications typically consist of cryptographic identity systems, decentralized networks of devices, and websites that issue or verify W3C Verifiable Credentials.
Additional information:
Magic number(s):
Not Applicable
File extension(s):
.did
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
Ivan Herman <ivan@w3.org>
Intended usage:
Common
Restrictions on usage:
None
Author(s):
Drummond Reed, Manu Sporny, Markus Sabadello, Dave Longley, Christopher Allen
Change controller:
W3C

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]].

application/did+cbor

Type name:
application
Subtype name:
did+cbor
Required parameters:
None
Optional parameters:
None
Encoding considerations:
See RFC 7049, section 4.2.
Security considerations:
See RFC 7049, section 10 [[RFC7049]].
Interoperability considerations:
Not Applicable
Published specification:
http://www.w3.org/TR/did-core/
Applications that use this media type:
Any application that requires an identifier that is decentralized, persistent, cryptographically verifiable, and resolvable. Applications typically consist of cryptographic identity systems, decentralized networks of devices, and websites that issue or verify W3C Verifiable Credentials.
Additional information:
Magic number(s):
Not Applicable
File extension(s):
.did
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
Ivan Herman <ivan@w3.org>
Intended usage:
Common
Restrictions on usage:
None
Author(s):
Drummond Reed, Manu Sporny, Markus Sabadello, Dave Longley, Christopher Allen
Change controller:
W3C

Fragment identifiers used with application/did+cbor are treated according to the rules defined in .

application/did+dag+cbor

Type name:
application
Subtype name:
did+dag+cbor
Required parameters:
None
Optional parameters:
None
Encoding considerations:
See RFC 7049, section 4.2.
Security considerations:
See RFC 7049, section 10 [[RFC7049]].
Interoperability considerations:
Not Applicable
Published specification:
http://www.w3.org/TR/did-core/
Applications that use this media type:
Any application that requires an identifier that is decentralized, persistent, cryptographically verifiable, and resolvable. Applications typically consist of cryptographic identity systems, decentralized networks of devices, and websites that issue or verify W3C Verifiable Credentials.
Additional information:
Magic number(s):
Not Applicable
File extension(s):
.did
Macintosh file type code(s):
TEXT
Person & email address to contact for further information:
Ivan Herman <ivan@w3.org>
Intended usage:
Common
Restrictions on usage:
None
Author(s):
Drummond Reed, Manu Sporny, Markus Sabadello, Dave Longley, Christopher Allen
Change controller:
W3C

Fragment identifiers used with application/did+dag+cbor are treated according to the rules defined in .