Decentralized Identifier Resolution (DID Resolution) v0.3

Algorithms and guidelines for resolving DIDs and dereferencing DID URLs

W3C Editor's Draft 09 19 June 2025

Abstract

Decentralized identifiers (DIDs) are a new type of identifier for verifiable, "self-sovereign" digital identity. DIDs are fully under the control of the DID controller, independent from any centralized registry, identity provider, or certificate authority. DIDs resolve to DID Documents — simple documents that describe how to use that specific DID.

This document specifies the algorithms and guidelines for resolving DIDs and dereferencing DID URLs.

Status of This Document

This is a preview

Do not attempt to implement this version of the specification. Do not reference this version as authoritative in any way. Instead, see https://w3c.github.io/did-resolution/ for the Editor's draft.

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C standards and drafts index at https://www.w3.org/TR/.

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

This document was published by the Decentralized Identifier Working Group as an Editor's Draft.

Publication as an Editor's Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .

This document is governed by the 03 November 2023 W3C Process Document .

DID resolution is the process of obtaining a DID document for a given DID . This is one of four required operations that can be performed on any DID ("Read"; the other ones being "Create", "Update", and "Deactivate"). The details of these operations differ depending on the DID method . Building on top of DID resolution , DID URL dereferencing is the process of retrieving a representation of a resource for a given DID URL . Software and/or hardware that is able to execute these processes is called a DID resolver .

This specification defines common requirements, algorithms including their inputs and results, architectural options, and various considerations for the DID resolution and DID URL dereferencing processes.

Note that while this specification defines some base-level functionality for DID resolution, the actual steps required to communicate with a DID's verifiable data registry are defined by the applicable DID method specification.

Note

The difference between "resolving" a DID and "dereferencing" a DID URL is being thoroughly discussed by the community. For example, see this comment .

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY , MUST , MUST NOT , OPTIONAL , RECOMMENDED , REQUIRED , and SHOULD in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.

A conforming DID resolver is any algorithm realized as software and/or hardware that complies with the relevant normative statements in 4. DID Resolution .

A conforming DID URL dereferencer is any algorithm realized as software and/or hardware that complies with the relevant normative statements in 5. DID URL Dereferencing .

This section is non-normative.

This specification has three primary audiences: implementers of conformant DID methods; implementers of conformant DID resolvers; and implementers of systems and services that wish to resolve DIDs using DID resolvers. The intended audience includes, but is not limited to, software architects, data modelers, application developers, service developers, testers, operators, and user experience (UX) specialists. Other people involved in a broad range of standards efforts related to decentralized identity, verifiable credentials, and secure storage might also be interested in reading this specification.

This section defines the terms used in this specification and throughout decentralized identifier infrastructure. A link to these terms is included whenever they appear in this specification.

authenticate

Authentication is a process by which an entity can prove it has a specific attribute or controls a specific secret using one or more verification methods . With DIDs , a common example would be proving control of the cryptographic private key associated with a public key published in a DID document .

binding

A concrete mechanism through which a client invokes a DID resolver . This could be a local binding such as a local command line tool or library API, or a remote binding such as the HTTP(S) binding . See Section 7.2 Resolver Architectures .

client

Software and/or hardware that invokes a DID resolver in order to execute the DID resolution and/or DID URL dereferencing algorithms. This invocation is done via a binding . The term client does not imply any specific network topology.

decentralized identifier (DID)

A globally unique persistent identifier that does not require a centralized registration authority and is often generated and/or registered cryptographically. The generic format of a DID is defined in Decentralized Identifiers (DIDs) v1.0 . A specific DID scheme is defined in a DID method specification. Many—but not all—DID methods make use of distributed ledger technology (DLT) or some other form of decentralized network.

DID controller

An entity that has the capability to make changes to a DID document . A DID might have more than one DID controller. The DID controller(s) can be denoted by the optional


controller

property at the top level of the DID document . Note that a DID controller might be the DID subject .

DID delegate

An entity to whom a DID controller has granted permission to use a verification method associated with a DID via a DID document . For example, a parent who controls a child's DID document might permit the child to use their personal device in order to authenticate . In this case, the child is the DID delegate . The child's personal device would contain the private cryptographic material enabling the child to authenticate using the DID . However, the child might not be permitted to add other personal devices without the parent's permission.

DID document

A set of data describing the DID subject , including mechanisms, such as cryptographic public keys, that the DID subject or a DID delegate can use to authenticate itself and prove its association with the DID .

DID fragment

The portion of a DID URL that follows the first hash sign character (

). DID fragment syntax is identical to URI fragment syntax.

DID method

A definition of how a specific DID method scheme is implemented. A DID method is defined by a DID method specification, which specifies the precise operations by which DIDs and DID documents are created, resolved, updated, and deactivated. See Decentralized Identifiers (DIDs) v1.0 .

DID path

The portion of a DID URL that begins with and includes the first forward slash (

) character and ends with either a question mark (

) character, a fragment hash sign (

) character, or the end of the DID URL . DID path syntax is identical to URI path syntax. See Decentralized Identifiers (DIDs) v1.0 .

DID query

The portion of a DID URL that follows and includes the first question mark character (

). DID query syntax is identical to URI query syntax. See Decentralized Identifiers (DIDs) v1.0 .

DID resolution

The process that takes as its input a DID and a set of resolution options and returns a DID document in a conforming representation plus additional metadata. This process relies on the "Read" operation of the applicable DID method . The inputs and outputs of this process are defined in 4. DID Resolution .

DID resolver

A DID resolver is a software and/or hardware component that performs the DID resolution function by taking a DID as input and producing a conforming DID document as output.

DID resolution result

A data structure that represents the result of the DID resolution algorithm. May contain a DID document . See Section 8. DID Resolution Result .

DID scheme

The formal syntax of a decentralized identifier . The generic DID scheme begins with the prefix


did:

as defined in Decentralized Identifiers (DIDs) v1.0 . Each DID method specification defines a specific DID method scheme that works with that specific DID method . In a specific DID method scheme, the DID method name follows the first colon and terminates with the second colon, e.g.,


did:example:

DID subject

The entity identified by a DID and described by a DID document . Anything can be a DID subject: person, group, organization, physical thing, digital thing, logical thing, etc.

DID URL

A DID plus any additional syntactic component that conforms to the definition in Decentralized Identifiers (DIDs) v1.0 . This includes an optional DID path (with its leading

character), optional DID query (with its leading

character), and optional DID fragment (with its leading

character).

DID URL dereferencing

The process that takes as its input a DID URL and a set of input metadata, and returns a resource . This resource might be a DID document plus additional metadata, a secondary resource contained within the DID document , or a resource entirely external to the DID document . The process uses DID resolution to fetch a DID document indicated by the DID contained within the DID URL . The dereferencing process can then perform additional processing on the DID document to return the dereferenced resource indicated by the DID URL . The inputs and outputs of this process are defined in 5. DID URL Dereferencing .

DID URL dereferencer

A software and/or hardware system that performs the DID URL dereferencing function for a given DID URL or DID document .

DID URL dereferencing result

A data structure that represents the result of the DID URL dereferencing algorithm. May contain a DID document or other content. See Section 9. DID URL Dereferencing Result .

distributed ledger (DLT)

A non-centralized system for recording events. These systems establish sufficient confidence for participants to rely upon the data recorded by others to make operational decisions. They typically use distributed databases where different nodes use a consensus protocol to confirm the ordering of cryptographically signed transactions. The linking of digitally signed transactions over time often makes the history of the ledger effectively immutable.

resource

As defined by [ RFC3986 ]: "...the term 'resource' is used in a general sense for whatever might be identified by a URI." Similarly, any resource might serve as a DID subject identified by a DID .

representation

As defined for HTTP by [ RFC7231 ]: "information that is intended to reflect a past, current, or desired state of a given resource, in a format that can be readily communicated via the protocol, and that consists of a set of representation metadata and a potentially unbounded stream of representation data." A DID document is a representation of information describing a DID subject . See Decentralized Identifiers (DIDs) v1.0 .

local binding

A binding where the client invokes a DID resolver that runs on the same network host, e.g., via a local command line tool or library API. In this case, the DID resolver is sometimes also called a "local DID resolver ". See Section 7.2 Resolver Architectures .

remote binding

A binding where the client invokes a DID resolver that runs on a different network host, e.g., via the HTTP(S) binding . In this case, the DID resolver is sometimes also called a "remote DID resolver ". See Section 7.2 Resolver Architectures .

services

Means of communicating or interacting with the DID subject or associated entities via one or more service endpoints . Examples include discovery services, agent services, social networking services, file storage services, and verifiable credential repository services.

service endpoint

A network address, such as an HTTP URL, at which services operate on behalf of a DID subject .

unverifiable read

A low confidence implementation of a DID method's "Read" operation between the DID resolver and the verifiable data registry , to obtain the DID document . There is no guarantee about the integrity and correctness of the result. See Section 7.1 Method Architectures .

verifiable data registry

A system that facilitates the creation, verification, updating, and/or deactivation of decentralized identifiers and DID documents . A verifiable data registry might also be used for other cryptographically-verifiable data structures such as verifiable credentials . For more information, see the W3C Verifiable Credentials specification [ VC-DATA-MODEL ].

verification method

A set of parameters that can be used together with a process to independently verify a proof. For example, a cryptographic 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 cryptographic private key.

"Verification" and "proof" in this definition are intended to apply broadly. For example, a cryptographic public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" or "proof."

verifiable read

A high confidence implementation of a DID method's "Read" operation between the DID resolver and the verifiable data registry , to obtain the DID document . There are guarantees about the integrity and correctness of the result to the extent possible under the applicable DID method . See Section 7.1 Method Architectures .

Universally Unique Identifier (UUID)

A type of globally unique identifier defined by [ RFC4122 ]. UUIDs are similar to DIDs in that they do not require a centralized registration authority. UUIDs differ from DIDs in that they are not resolvable or cryptographically-verifiable.

Uniform Resource Identifier (URI)

The standard identifier format for all resources on the World Wide Web as defined by [ RFC3986 ]. A DID is a type of URI scheme.

The DID URL syntax supports a simple format for parameters (see section Query in [ DID-CORE ]). Adding a DID parameter to a DID URL means that the parameter becomes part of the identifier for a resource .

Example 1 : A DID URL with a 'versionTime' DID parameter

did:example:123?versionTime=2021-05-10T17:00:00Z

Example 2 : A DID URL with a 'service' and a 'relativeRef' DID parameter

did:example:123?service=files&relativeRef=/resume.pdf

Some DID parameters are completely independent of any specific DID method and function the same way for all DIDs . Other DID parameters are not supported by all DID methods . Where optional parameters are supported, they are expected to operate uniformly across the DID methods that do support them. The following table provides common DID parameters that function the same way across all DID methods . Support for all DID Parameters is OPTIONAL .

Parameter Name	Description
`service`	Identifies a service from the DID document by service ID. If present, the associated value MUST be an ASCII string .
`serviceType`	Identifies a set of one or more services from the DID document by service type. If present, the associated value MUST be an ASCII string .
`relativeRef`	A relative URI reference according to RFC3986 Section 4.2 that identifies a resource at a service endpoint , which is selected from a DID document by using the `service` parameter. If present, the associated value MUST be an ASCII string and MUST use percent-encoding for certain characters as specified in RFC3986 Section 2.1 .
`versionId`	Identifies a specific version of a DID document to be resolved (the version ID could be sequential, or a UUID , or method-specific). If present, the associated value MUST be an ASCII string .
`versionTime`	Identifies a certain version timestamp of a DID document to be resolved. That is, the most recent version of the DID document that was valid for a DID before the specified `versionTime`. 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:00 and without sub-second decimal precision. For example: `2020-12-20T19:17:47Z`.
`hl`	A resource hash of the DID document to add integrity protection, as specified in [ HASHLINK ]. This parameter is non-normative. If present, the associated value MUST be an ASCII string .

Implementers as well as DID method specification authors might use additional DID parameters that are not listed here. For maximum interoperability, it is RECOMMENDED that DID parameters use the DID Specification Registries mechanism [ DID-SPEC-REGISTRIES ], to avoid collision with other uses of the same DID parameter with different semantics.

DID parameters might be used if there is a clear use case where the parameter needs to be part of a URL that references a resource with more precision than using the DID alone. It is expected that DID parameters are not used if the same functionality can be expressed by passing input metadata to a DID resolver .

Note : DID parameters and DID resolution

The DID resolution and the DID URL dereferencing functions can be influenced by passing 4.1 DID Resolution Options or 5.1 DID URL Dereferencing Options to a DID resolver that are not part of the DID URL . 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 used to control how that resource is resolved or dereferenced .

The DID resolution function resolves a DID into a DID document by using the "Read" operation of the applicable DID method as described in Method Operations . All conforming DID resolvers implement the function below, which has the following abstract form:

resolve(did, resolutionOptions) →
«
didResolutionMetadata,
didDocument,
didDocumentMetadata
»

All conformant DID resolvers MUST implement the DID resolution function for at least one DID method and MUST be able to return a DID document in at least one conformant representation .

Conforming DID resolver implementations do not alter the signature of this function in any way. DID resolver implementations might map the resolve function to a method-specific internal function to perform the actual DID resolution process. DID resolver implementations might implement and expose additional functions with different signatures in addition to the resolve function specified here.

The input variables of the resolve function are as follows:

did: This is the DID to resolve. This input is REQUIRED and the value MUST be a conformant DID as defined in Decentralized Identifiers (DIDs) v1.0 .
resolutionOptions: A metadata structure containing properties defined in 4.1 DID Resolution Options . This input is REQUIRED , but the structure MAY be empty.

This function returns multiple values, and no limitations are placed on how these values are returned together. The return values of resolve are didResolutionMetadata , didDocument , and didDocumentMetadata . These values are described below:

didResolutionMetadata: A metadata structure consisting of values relating to the results of the DID resolution process which typically changes between invocations of the resolve function, as it represents data about the resolution process itself. This structure is REQUIRED , and in the case of an error in the resolution process, this MUST NOT be empty. This metadata is defined by 4.2 DID Resolution Metadata . If the resolution is not successful, this structure MUST contain an error property describing the error. See Section 10. Errors . Additional errors SHOULD be registered in the DID Specification Registries [ DID-SPEC-REGISTRIES ].
didDocument: If the resolution is successful, this MUST be a DID document that is capable of being represented in one of the conformant representations of the Decentralized Identifiers (DIDs) v1.0 specification. The value of id in the resolved DID document MUST match the DID that was resolved. If the resolution is unsuccessful, this value MUST be empty.
didDocumentMetadata: If the resolution is successful, this MUST be a metadata structure . This structure contains metadata about the DID document contained in the didDocument property. This metadata typically does not change between invocations of the resolve function unless the DID document changes, as it represents metadata about the DID document . If the resolution is unsuccessful, this output MUST be an empty metadata structure . Properties defined by this specification are in 4.3 DID Document Metadata .

The possible properties within this structure and their possible values are registered in the DID Specification Registries [ DID-SPEC-REGISTRIES ]. This specification defines the following common properties.

accept: The Media Type of the caller's preferred representation of the DID document . The Media Type MUST be expressed as an ASCII string . The DID resolver implementation SHOULD use this value to determine the representation of the returned didDocument if such a representation is supported and available. This property is OPTIONAL .

expandRelativeUrls: A boolean flag which instructs a DID resolver to expand relative DID URLs in the DID document to absolute DID URLs conformant with DID URL Syntax .

versionId: See 3. DID Parameters for the definition.

versionTime: See 3. DID Parameters for the definition.

contentType: The Media Type of the returned didDocument. This property is OPTIONAL . If present, the value of this property MUST be an ASCII string that is the Media Type of the conformant representations . In this case, the caller of the resolve function MUST use this value when determining how to parse and process the didDocument.
error: An error data structure defined in [ RFC9457 ]. This property is REQUIRED when there is an error in the resolution process. The errors defined by this specification and can be found in Section 10. Errors . Additional errors SHOULD be registered in the DID Specification Registries [ DID-SPEC-REGISTRIES ].

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 . The value of the property MUST be a string formatted as an XML Datetime normalized to UTC 00:00:00 and without sub-second decimal precision. For example:


2020-12-20T19:17:47Z

updated

DID document metadata SHOULD include an


updated

property to indicate the timestamp of the last Update operation for the document version which was resolved. The value of the property MUST follow the same formatting rules as the


created

property. The


updated

property is omitted if an Update operation has never been performed on the DID document . If an


updated

property exists, it can be the same value as the


created

property when the difference between the two timestamps is less than one second.

deactivated

If a DID has been deactivated , DID document metadata MUST include this property with the boolean value


true

. If a DID has not been deactivated, this property is OPTIONAL , but if included, MUST have the boolean value


false

nextUpdate

DID document metadata MAY include a


nextUpdate

property if the resolved document version is not the latest version of the document. It indicates the timestamp of the next Update operation . The value of the property MUST follow the same formatting rules as the


created

property.

versionId

DID document metadata SHOULD include a


versionId

property to indicate the version of the last Update operation for the document version which was resolved. The value of the property MUST be an ASCII string .

nextVersionId

DID document metadata MAY include a


nextVersionId

property if the resolved document version is not the latest version of the document. It indicates the version of the next Update operation . The value of the property MUST be an ASCII string .

equivalentId

A DID method can define different forms of a DID that are logically equivalent. An example is when a DID takes one form prior to registration in a verifiable data registry and another form after such registration. In this case, the DID method specification might need to express one or more DIDs that are logically equivalent to the resolved DID as a property of the DID document . This is the purpose of the equivalentId property.

DID document metadata MAY include an equivalentId property. If present, the value MUST be a set where each item is a string that conforms to the rules in Section Decentralized Identifiers (DIDs) v1.0 . The relationship is a statement that each equivalentId value is logically equivalent to the id property value and thus refers to the same DID subject . Each equivalentId DID value MUST be produced by, and a form of, the same DID method as the id property value. (e.g., did:example:abc == did:example:ABC )

A conforming DID method specification MUST guarantee that each equivalentId value is logically equivalent to the id property value.

A requesting party is expected to retain the values from the id and equivalentId properties to ensure any subsequent interactions with any of the values they contain are correctly handled as logically equivalent (e.g., retain all variants in a database so an interaction with any one maps to the same underlying account).

Note : Stronger equivalence

equivalentId is a much stronger form of equivalence than alsoKnownAs because the equivalence MUST be guaranteed by the governing DID method . equivalentId represents a full graph merge because the same DID document describes both the equivalentId DID and the id property DID .

If a requesting party does not retain the values from the id and equivalentId properties and ensure any subsequent interactions with any of the values they contain are correctly handled as logically equivalent, there might be negative or unexpected issues that arise. Implementers are strongly advised to observe the directives related to this metadata property.

canonicalId

The canonicalId property is identical to the equivalentId property except: a) it is associated with a single value rather than a set, and b) the DID is defined to be the canonical ID for the DID subject within the scope of the containing DID document .

DID document metadata MAY include a canonicalId property. If present, the value MUST be a string that conforms to the rules in Section Decentralized Identifiers (DIDs) v1.0 . The relationship is a statement that the canonicalId value is logically equivalent to the id property value and that the canonicalId value is defined by the DID method to be the canonical ID for the DID subject in the scope of the containing DID document . A canonicalId value MUST be produced by, and a form of, the same DID method as the id property value. (e.g., did:example:abc == did:example:ABC ).

A conforming DID method specification MUST guarantee that the canonicalId value is logically equivalent to the id property value.

A requesting party is expected to use the canonicalId value as its primary ID value for the DID subject and treat all other equivalent values as secondary aliases (e.g., update corresponding primary references in their systems to reflect the new canonical ID directive).

Note : Canonical equivalence

canonicalId is the same statement of equivalence as equivalentId except it is constrained to a single value that is defined to be canonical for the DID subject in the scope of the DID document . Like equivalentId, canonicalId represents a full graph merge because the same DID document describes both the canonicalId DID and the id property DID .

If a resolving party does not use the canonicalId value as its primary ID value for the DID subject and treat all other equivalent values as secondary aliases, there might be negative or unexpected issues that arise related to user experience. Implementers are strongly advised to observe the directives related to this metadata property.

The following DID resolution algorithm MUST be implemented by a conformant DID resolver .

Validate that the input DID conforms to the did rule of the DID Syntax . If not, the DID resolver MUST return the following result:
1. didResolutionMetadata : error object with type set to INVALID_DID
2. didDocument : null
3. didDocumentMetadata : «[ ]»
Determine whether the DID method of the input DID is supported by the DID resolver that implements this algorithm. If not, the DID resolver MUST return the following result:
1. didResolutionMetadata : error object with type set to METHOD_NOT_SUPPORTED
2. didDocument : null
3. didDocumentMetadata : «[ ]»
Obtain the DID document for the input DID by executing the Read operation against the input DID 's verifiable data registry , as defined by the input DID method:
1. Besides the input DID, all additional resolution options of this algorithm MUST be passed to the Read operation of the input DID method.
2. If the input DID does not exist, return the following result:
  1. didResolutionMetadata : error object with type set to NOT_FOUND
  2. didDocument : null
  3. didDocumentMetadata : «[ ]»
3. If the input DID has been deactivated, return the following result:
  1. didResolutionMetadata : «[ ... ]»
  2. didDocument : null
  3. didDocumentMetadata : «[ "deactivated" → true, ... ]»
4. Otherwise, the result of the Read operation is called the output DID document. This result MUST be represented in a conformant representation that corresponds to the accept input DID resolution option.
If the input DID resolution options contain the expandRelativeUrls option with a value of true:
1. Iterate over all services , verification methods , and verification relationships in the output DID document.
2. If the value of the id property of a service or verification method (including those embedded in verification relationships ) is a relative DID URL , or if a verification relationship is a relative DID URL :
  1. Resolve the relative DID URL to an absolute DID URL conformant with DID URL Syntax , according to the rules of section Relative DID URLs in Decentralized Identifiers (DIDs) v1.0 .
3. Update the output DID document by replacing the relative DID URLs with the resolved absolute DID URLs .
Return the following result:
1. didResolutionMetadata : «[ ... ]»
2. didDocument : output DID document
3. didDocumentMetadata : «[ "contentType" → output DID document media type , ... ]»

Issue 5 : Discuss how to treat deactivated DIDs enhancement pending-close

There is discussion how a DID that has been deactivated should be treated during the DID resolution process.

Issue 13 : Validate signatures/proofs of DID Document security

Specify how signatures/proofs on a DID document should be verified during the DID resolution process.

Issue

Should we define functionality that enables discovery of the list of DID methods or other capabilities that are supported by a DID resolver ? Or is this implementation-specific and out-of-scope for this spec? For example, see here and here .

The DID URL dereferencing function dereferences a DID URL into a resource with contents depending on the DID URL 's components, including the DID method , method-specific identifier, path, query, and fragment. This process depends on DID resolution of the DID contained in the DID URL . DID URL dereferencing might involve multiple steps (e.g., when the DID URL being dereferenced includes a fragment), and the function is defined to return the final resource after all steps are completed. The following figure depicts the relationship described above.

DIDs resolve to DID documents; DID URLs contains a DID; DID URLs dereferenced to DID document fragments or external resources. — Figure 1 Overview of DID URL dereference See also: narrative description .

The top left part of the diagram contains a rectangle with black outline, labeled "DID".

The bottom left part of the diagram contains a rectangle with black outline, labeled "DID URL". This rectangle contains four smaller black-outlined rectangles, aligned in a horizontal row adjacent to each other. These smaller rectangles are labeled, in order, "DID", "path", "query", and "fragment.

The top right part of the diagram contains a rectangle with black outline, labeled "DID document". This rectangle contains three smaller black-outlined rectangles. These smaller rectangles are labeled "id", "(property X)", and "(property Y)", and are surrounded by multiple series of three dots (ellipses). A curved black arrow, labeled "DID document - relative fragment dereference", extends from the rectangle labeled "(property X)", and points to the rectangle labeled "(property Y)".

The bottom right part of the diagram contains an oval shape with black outline, labeled "Resource".

A black arrow, labeled "resolves to a DID document", extends from the rectangle in the top left part of the diagram, labeled "DID", and points to the rectangle in the top right part of diagram, labeled "DID document".

A black arrow, labeled "refers to", extends from the rectangle in the top right part of the diagram, labeled "DID document", and points to the oval shape in the bottom right part of diagram, labeled "Resource".

A black arrow, labeled "contains", extends from the small rectangle labeled "DID" inside the rectangle in the bottom left part of the diagram, labeled "DID URL", and points to the rectangle in the top left part of diagram, labeled "DID".

A black arrow, labeled "dereferences to a DID document", extends from the rectangle in the bottom left part of the diagram, labeled "DID URL", and points to the rectangle in the top right part of diagram, labeled "DID document".

A black arrow, labeled "dereferences to a resource", extends from the rectangle in the bottom left part of the diagram, labeled "DID URL", and points to the oval shape in the bottom right part of diagram, labeled "Resource".

All conforming DID resolvers implement the following function which has the following abstract form:

dereference(didUrl, dereferenceOptions) →
«
dereferencingMetadata,
contentStream,
contentMetadata
»

The input variables of the dereference function are as follows:

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

Note : DID URL dereferencer patterns

While it is valid for any didUrl to be passed to a DID URL dereferencer, implementers are expected to refer to 5. DID URL Dereferencing to further understand common patterns for how a DID URL is expected to be dereferenced.
dereferencingOptions: A metadata structure consisting of input options to the dereference function in addition to the didUrl itself. Properties defined by this specification are in 5.1 DID URL Dereferencing Options . This input is REQUIRED , but the structure MAY be empty.

This function returns multiple values, and no limitations are placed on how these values are returned together. The return values of the dereference include dereferencingMetadata, contentStream, and contentMetadata:

dereferencingMetadata: 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 5.2 DID URL Dereferencing Metadata . If the dereferencing is not successful, this structure MUST contain an error property describing the error. See Section 10. Errors .
contentStream: If the dereferencing function was called and successful, this MUST contain a resource corresponding to the DID URL . The contentStream MAY be a resource such as a DID document that is serializable in one of the conformant representations , a verification method , a service , or any other resource format that can be identified via a Media Type and obtained through the resolution process. If the dereferencing is unsuccessful, this value MUST be empty.
contentMetadata: If the dereferencing is successful, this MUST be a metadata structure , but the structure MAY be empty. This structure contains metadata about the contentStream. If the contentStream is a DID document , this MUST be a didDocumentMetadata structure as described in DID Resolution . If the dereferencing is unsuccessful, this output MUST be an empty metadata structure .

Conforming DID URL dereferencing implementations do not alter the signature of these functions in any way. DID URL dereferencing implementations might map the dereference function to a method-specific internal function to perform the actual DID URL dereferencing process. DID URL dereferencing implementations might implement and expose additional functions with different signatures in addition to the dereference function specified here.

accept: The Media Type that the caller prefers for contentStream. The Media Type MUST be expressed as an ASCII string . The DID URL dereferencing implementation SHOULD use this value to determine the contentType of the representation contained in the returned value if such a representation is supported and available.

verificationRelationship: The verificationRelationship for which the caller expects the verificationMethod dereferenced from the DID URL to be authorized. If present, the associated value MUST be an ASCII string . If the DID URL does not dereference to a verificationMethod, or the DID document does not authorize the verificationMethod for the specified verificationRelationship, then an error MUST be raised.

contentType: The Media Type of the returned contentStream SHOULD be expressed using this property if dereferencing is successful. The Media Type value MUST be expressed as an ASCII string .
error: An error data structure defined in [ RFC9457 ]. This property is REQUIRED when there is an error in the dereferencing process. The errors defined in this specification can be found in Section 10. Errors . Additional errors SHOULD be registered in the DID Specification Registries [ DID-SPEC-REGISTRIES ].

The following DID URL dereferencing algorithm MUST be implemented by a conformant DID resolver . In accordance with [ RFC3986 ], it consists of the following three steps: resolving the DID; dereferencing the resource; and dereferencing the fragment (only if the input DID URL contains a DID fragment ):

Validate that the input DID URL conforms to the did-url rule of the DID URL Syntax . If not, the DID URL dereferencer MUST return the following result:
1. dereferencingMetadata : error object with type set to INVALID_DID_URL
2. contentStream : null
3. contentMetadata : «[ ]»
Obtain the DID document for the input DID by executing the DID resolution algorithm as defined in 4. DID Resolution . All dereferencing options and all DID parameters of the input DID URL MUST be passed as resolution options to the DID Resolution algorithm.
If the input DID does not exist in the VDR, the DID URL dereferencer MUST return the following result:
1. dereferencingMetadata : error object with type set to NOT_FOUND
2. contentStream : null
3. contentMetadata : «[ ]»
Otherwise, the didDocument result of the DID resolution algorithm is called the resolved DID document.
If present, separate the DID fragment from the input DID URL and continue with the adjusted input DID URL.
If the input DID URL contains no DID path and no DID query :
Example 3
```
did:example:1234
```
The DID URL dereferencer MUST return the resolved DID document and resolved 4.3 DID Document Metadata as follows:
1. dereferencingMetadata : «[ ... ]»
2. contentStream : resolved DID document
3. contentMetadata : «[ resolved DID document metadata ]»
If the input DID URL contains the DID parameter hl:
Example 4
```
did:example:1234?hl=zQmWvQxTqbG2Z9HPJgG57jjwR154cKhbtJenbyYTWkjgF3e
```
Issue

TODO: Specify the algorithm for processing the hl DID parameter.
If the input DID URL contains the DID parameter service and/or the DID parameter serviceType, and optionally the DID parameter relativeRef:
Example 5
```
did:example:1234?service=files&relativeRef=%2Fmyresume%2Fdoc%3Fversion%3Dlatest
```
1. From the resolved DID document, select all services which fulfill the following conditions:
  1. If the input DID URL contains the DID parameter service: Select the service if its id property matches the value of the service DID parameter. If the id property or the service DID parameter or both contain relative references, the corresponding absolute URIs MUST be resolved and used for determining the match, using the rules specified in RFC3986 Section 5: Reference Resolution and in section Relative DID URLs in Decentralized Identifiers (DIDs) v1.0 .
  2. If the input DID URL contains the DID parameter serviceType: Select the service if its type property matches the value of the serviceType DID parameter.
  The selected services are a list called the selected services.
2. If the input DID URL contains the DID parameter relativeRef:
  1. For each selected service:
    1. If the value of the serviceEndpoint property of the selected service is a map , skip this selected service.
    2. If the value of the serviceEndpoint property of the selected service is a string , add this value to a list of selected service endpoint URLs.
    3. If the value of the serviceEndpoint property of the selected service is a set , add all its items that are strings to a list of selected service endpoint URLs.
  2. For each selected service endpoint URL, execute the algorithm specified in RFC3986 Section 5: Reference Resolution as follows:
    1. The base URI value is the selected service endpoint URL.
    2. The relative reference is the value of the DID parameter relativeRef.
    3. Update the selected service endpoint URL to the result of the "Reference Resolution" algorithm.
3. If the accept input DID dereferencing option is missing, or if its value is the Media Type of a representation of a DID document :
  1. Update the services in the resolved DID document to contain only the selected services.
  2. Return the following result:
    1. dereferencingMetadata : «[ ... ]»
    2. content : resolved DID document with selected services
    3. contentMetadata : «[ resolved DID document metadata ]»
4. If the value of the accept input DID resolution option is text/uri-list :
  1. Return the following result:
    1. dereferencingMetadata : «[ ... ]»
    2. content : « selected service endpoint URLs »
    3. contentMetadata : «[ "contentType" → "text/uri-list", ... ]»
5. Otherwise, return the following result:
  1. dereferencingMetadata : error object with type set to REPRESENTATION_NOT_SUPPORTED
  2. content : null
  3. contentMetadata : «[ ]»
Otherwise, if the input DID URL contains a DID path and/or DID query :
Example 6
```
did:example:1234/custom/path?customquery
```
1. The applicable DID method MAY specify how to dereference the DID path and/or DID query of the input DID URL.
  Example 7
```
did:example:1234/resources/1234
```
2. An extension specification MAY specify how to dereference the DID path of the input DID URL.
  Example 8
```
did:example:1234/whois
```
3. An extension specification MAY specify how to dereference the DID query of the input DID URL.
  Example 9
```
did:example:1234?transformKey=JsonWebKey
```
4. The client MAY be able to dereference the input DID URL in an application-specific way.
If neither this algorithm, nor the applicable DID method , nor an extension, nor the client is able to dereference the input DID URL, return the following result:
1. dereferencingMetadata : error object with type set to NOT_FOUND
2. contentStream : null
3. contentMetadata : «[ ]»

Issue 85 : Request service by type enhancement pending-close pr-exists

There have been discussions whether in addition to the DID parameter service, there could also be a DID parameter serviceType to select services based on their type rather than ID. See comments by Dave Longley about serviceType.

If the input DID URL contains a DID fragment , then dereferencing of the fragment is dependent on the media type ([ RFC2046 ]) of the resource, i.e., on the result of 5.3.1 Dereferencing the Resource .

If the result of 5.3.1 Dereferencing the Resource is an output DID document, and the input DID URL dereferencing options contain the verificationRelationship option:
1. Let verificationRelationship be the value of the verificationRelationship option.
2. Let verificationMethod be the result of dereferencing the DID fragment from the output DID document according to the rules of the media type of the DID document.
3. If verificationMethod is not a conforming verification method , an error MUST be raised and SHOULD convey an error type of INVALID_VERIFICATION_METHOD .
4. If verificationMethod is not associated, either by reference (URL) or by value (object), with the verification relationship array in the output DID document identified by verificationRelationship, an error MUST be raised and SHOULD convey an error type of INVALID_RELATIONSHIP_FOR_VERIFICATION_METHOD .
5. Return the verificationMethod.
If the result of 5.3.1 Dereferencing the Resource is a selected service endpoint URL, and the input DID URL contains a DID fragment :
Example 10
```
did:example:1234?service=files&relativeRef=%2Fmyresume%2Fdoc%3Fversion%3Dlatest#intro
```
1. If the selected service endpoint URL contains a fragment component, raise an error.
2. Append the DID fragment to the select service endpoint URL. In other words, the select service endpoint URL "inherits" the DID fragment of the input DID URL.
3. Return the select service endpoint URL.
Otherwise, dereference the DID fragment as defined by the media type ([ RFC2046 ]) of the resource. For example, if the resource is a representation of a DID document with media type application/did, then the fragment is treated according to the rules associated with the JSON-LD 1.1: application/ld+json media type [JSON-LD11].

Note

This use of the DID fragment is consistent with the definition of the fragment identifier in [ RFC3986 ]. It identifies a secondary resource which is a subset of the primary resource (the DID document ).

Note

This behavior of the DID fragment is analogous to the handling of a fragment in an HTTP URL in the case when dereferencing it returns an HTTP 3xx (Redirection) response with a Location header (see section 7.1.2 of [ RFC7231 ]).

Given the following input DID URL:

Example 11

did:example:123456789abcdefghi#keys-1

... and the following resolved DID document:

Example 12

{
	"@context":[
		"https://www.w3.org/ns/did/v1.1",
		"https://didcomm.org/messaging/contexts/v2",
		"https://identity.foundation/linked-vp/contexts/v1"
	],
	"id": "did:example:123456789abcdefghi",
	"verificationMethod": [{
		"id": "did:example:123456789abcdefghi#keys-1",
		"type": "Multikey",
		"controller": "did:example:123456789abcdefghi",
		"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
	}],
	"service": [{
		"id": "did:example:123456789abcdefghi#messages",
		"type": "DIDCommMessaging",
		"serviceEndpoint": "https://example.com/messages/8377464"
	}, {
		"id": "did:example:123456789abcdefghi#linkedvp",
		"type": "LinkedVerifiablePresentation",
		"serviceEndpoint": "https://example.com/verifiable-presentation.jsonld"
	}]
}

... then the result of the 5. DID URL Dereferencing algorithm is the following output resource:

Example 13

{
	"@context": "https://www.w3.org/ns/did/v1.1",
	"id": "did:example:123456789abcdefghi#keys-1",
	"type": "Multikey",
	"controller": "did:example:123456789abcdefghi",
	"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}

Diagram showing how a DID URL can be dereferenced to a verification method — Figure 2 Dereferencing a DID URL to a verification method.

Given the following input DID URL:

Example 14

did:example:123456789abcdefghi?service=messages&relativeRef=%2Fsome%2Fpath%3Fquery#frag

... and the same resolved DID document as in the previous section.

... then the result of the 5. DID URL Dereferencing algorithm is the following selected service endpoint URL:

Example 15

https://example.com/messages/8377464/some/path?query#frag

Diagram showing how a DID URL can be dereferenced to a service endpoint URL — Figure 3 Dereferencing a DID URL to a service endpoint URL.

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 , set , boolean , or null . The values within any complex data structures such as maps and lists MUST be one of these data types as well. All metadata property definitions registered in the DID Specification Registries [ DID-SPEC-REGISTRIES ] 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. The entire metadata structure MUST be serializable according to the JSON serialization rules in the [ INFRA ] specification. Implementations MAY serialize the metadata structure to other data formats.

All implementations of functions that use metadata structures as either input or output are able to fully represent all data types described here in a deterministic fashion. As inputs and outputs using metadata structures are defined in terms of data types and not their serialization, the method for representation is internal to the implementation of the function and is out of scope of this specification.

The following example demonstrates a JSON-encoded metadata structure that might be used as DID resolution input metadata .

Example 16 : JSON-encoded DID resolution input metadata example

{
"accept": "application/did+ld+json"

}

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

Example 17 : DID resolution input metadata example

«[
"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.

Example 18 : JSON-encoded DID resolution metadata example

{
"error": "notFound"

}

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

Example 19 : DID resolution metadata example

«[
"error" → "notFound"
]»

The next example demonstrates a JSON-encoded metadata structure that might be used as DID document metadata to describe timestamps associated with the DID document .

Example 20 : JSON-encoded DID document metadata example

{
"created": "2019-03-23T06:35:22Z",
"updated": "2023-08-10T13:40:06Z"

}

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

Example 21 : DID document metadata example

«[
"created" → "2019-03-23T06:35:22Z",
"updated" → "2023-08-10T13:40:06Z"
]»

Issue

TODO: Describe how DID resolvers are implemented and used, describe the relevance of DID methods . Explain the difference between "method architectures" and "resolver architectures".

The DID resolution algorithm involves executing the Read operation on a DID according to its DID method (see 4. DID Resolution ).

Note

The mechanics of the "Read" operation can vary considerably between DID methods . In particular, no assumption should be made that:

... an immutable blockchain is used as (part of) the verifiable data registry .
... interaction with a remote network is required during execution of the "Read" operation.
... an actual DID document is stored in plain-text on a verifiable data registry , or that the DID document can simply be retrieved via a standard protocol such as HTTP(S). While some DID methods may define their "Read" operation this way, others may define more complex multi-step processes that involve on-the-fly construction of a "virtual" DID document .

Issue

As an example, mention what it means to "resolve" peer/off-ledger/microledger/edgechain DIDs (for instance, see [ DID-PEER ] and here ).

Issue

As an example, mention what it means to "resolve" DIDs that are simply wrapped public keys (for instance, see [ DID-KEY ] and here ).

Depending on the exact nature of the DID method's "Read" operation, the interaction between a DID resolver and the verifiable data registry may be implemented as a verifiable read or unverifiable read :

Diagram showing a 'verifiable read' implementation of a DID method. — Figure 4 A verifiable read implementation of a DID method .

Diagram showing an 'unverifiable read' implementation of a DID method. — Figure 5 An unverifiable read implementation of a DID method .

A verifiable read maximizes confidence in the integrity and correctness of the result of the "Read" operation ‐ to the extent possible under the applicable DID method . It can be implemented in a variety of ways, for example:

A "Read" operation may be considered "Verifiable" if access to the verifiable data registry is possible via a local, trusted network host. In the case of blockchain-based DID methods , a blockchain full node may be run on a local network host in order to implement a verifiable read .
The DID resolver may be remotely connected to the verifiable data registry but have some method to verify the contents of the response of the "Read" operation. In the case of blockchain-based DID methods , even if direct access to a blockchain full node is not available, a verifiable read may still be possible by running a light client that processes metadata to verify that the result of the "Read" operation hasn't been tampered with.
A verifiable read may be implemented if access to the verifiable data registry happens via a remote network host that is considered trusted because it is run on a personal device in the home and accessed via a secure channel.

An unverifiable read does not have such guarantees and is therefore less desirable, for example:

A "Read" operation may be considered "Unverifiable" if access to the verifiable data registry happens via a remote, untrusted intermediary. In the case of blockchain-based DID methods , a remote blockchain explorer API operated by an third party may be used to look up data from the blockchain.

Whether or not a verifiable read is possible depends not only on a DID method itself, but also on the way how a DID resolver implements it. DID methods MAY define multiple different ways of implementing their "Read" operation(s) and SHOULD offer guidance on how to implement a verifiable read in at least one way.

Note

The guarantees associated with a verifiable read are still always limited by the architectures, protocols, cryptography, and other aspects of the underlying verifiable data registry . The strongest forms of verifiable read implementations are considered those that do not require any interaction with a remote network at all (for example, see [ DID-KEY ]), or that minimize dependencies on specific network infrastructure and reduce the "root of trust" to proven entropy and cryptography alone (for example, see [ KERI ]).

Issue

TODO: Describe how a client can potentially verify the result of a "Read" operation independently even if it does not trust the DID resolver (e.g., using state proofs).

The algorithms for DID resolution and DID URL dereferencing are defined as abstract functions (see 4. DID Resolution and 5. DID URL Dereferencing ).

Those algorithms are implemented by DID resolvers . A DID resolver is invoked by a client via a binding . Bindings define how the abstract functions are realized using concrete programming or communication interfaces. It is possible to distinguish between local bindings (such as a local command line tool or library API) and remote bindings (such as the HTTP(S) binding ).

Diagram showing a DID resolver with a 'local binding'. — Figure 6 A local binding for a DID resolver .

Diagram showing a DID resolver with a 'remote binding'. — Figure 7 A remote binding for a DID resolver .

Issue 28 : 'remote' vs 'local' DID Resolvers editorial

TODO: Describe local bindings vs. remote bindings , and implications for privacy, security and trust.

Also describe mitigations against potential downsides of remote bindings , e.g.:

A DID resolver's remote binding can use a trusted channel such as VPN or TLS with mutual authentication.
A DID resolver can add a data integrity proof (see [ DATA-INTEGRITY ]) to a DID document and/or the DID resolution result . Discuss what this does and doesn't achieve. Also see Proving Control and Binding .
A client could query multiple DID resolvers over a remote binding and compare results.

Issue

TODO: Discuss DID resolution in constrained user agents such as mobile apps and browsers.

A DID resolver MUST support the DID resolution algorithm for at least one DID method and MAY support it for multiple DID methods :

Diagram showing a DID resolver that supports multiple DID methods. — Figure 8 A DID resolver that supports multiple DID methods .

In this case, the above considerations in 7.1 Method Architectures about verifiable read and unverifiable read implementations apply to each supported DID method individually.

A DID resolver MAY invoke another DID resolver , which serves as a proxy that executes the DID resolution algorithm as defined in 4. DID Resolution .

The first DID resolver then acts as a client and chooses a suitable binding for invoking the second DID resolver . For example, a DID resolver may be invoked via a local binding (such as a command line tool), which in turn invokes another DID resolver via a remote binding (such as the HTTP(S) binding ).

Diagram showing two DID resolvers, one invoked via 'local binding', the other invoked via 'remote binding'. — Figure 9 A client invokes a DID resolver via local binding , which invokes another DID resolver via remote binding , which in turn reads from a DID method .

Note

This is similar to a "stub resolver" invoking a "recursive resolver" in DNS architecture, although the concepts are not entirely comparable (DNS Resolution uses a single concrete protocol, whereas DID resolution is an abstract function realized by different DID methods and different bindings ).

Different parts of the DID URL dereferencing algorithm may be performed by different components of a Resolver Architecture .

Specifically, when a DID URL with a DID fragment is dereferenced, then Dereferencing the Resource is done by the DID resolver , and Dereferencing the Fragment is done by the client .

Given the DID URL did:xyz:1234#keys-1, a DID resolver could be invoked via local binding for Dereferencing the Resource (i.e., the DID document ), and the client could complete the DID URL dereferencing algorithm by Dereferencing the Fragment (i.e., a part of the DID document ).

Diagram showing client-side dereferencing of a DID URL by a DID resolver and a client — Figure 10 Client-side dereferencing of a DID URL by a DID resolver and a client .

Given the DID URL did:xyz:1234?service=agent&relativeRef=%2Fsome%2Fpath%3Fquery#frag, a DID resolver could be invoked for Dereferencing the Resource (i.e., a service endpoint URL), and the client could complete the DID URL dereferencing algorithm by Dereferencing the Fragment (i.e., a service endpoint URL with a fragment).

Given the DID URL did:xyz:1234#keys-1, a DID resolver could be invoked via local binding , which invokes another DID resolver via remote binding for Dereferencing the Resource (i.e., the DID document ), and the client could complete the DID URL dereferencing algorithm by Dereferencing the Fragment (i.e., a part of the DID document ).

Diagram showing client-side dereferencing of a DID URL by two DID resolvers and a client — Figure 12 Client-side dereferencing (in combination with Proxied Resolution ) of a DID URL by two DID resolvers and a client .

This section defines a data structure that represents the result of the algorithm described in 4. DID Resolution . A DID resolution result contains a DID document as well as DID resolution metadata and DID document metadata .

The media type of this data structure is defined to be application/ld+json;profile="https://w3id.org/did-resolution".

Example 22 : Example DID resolution result

{
	"@context": "https://w3id.org/did-resolution/v1",
	"didDocument": {
		"@context": "https://www.w3.org/ns/did/v1",
		"id": "did:example:123456789abcdefghi",
		"authentication": [{
			"id": "did:example:123456789abcdefghi#keys-1",
			"type": "Ed25519VerificationKey2018",
			"controller": "did:example:123456789abcdefghi",
			"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
		}],
		"service": [{
			"id":"did:example:123456789abcdefghi#vcs",
			"type": "VerifiableCredentialService",
			"serviceEndpoint": "https://example.com/vc/"
		}]
	},
	"didResolutionMetadata": {
		"contentType": "application/did+ld+json",
		"retrieved": "2024-06-01T19:73:24Z",
	},
	"didDocumentMetadata": {
		"created": "2019-03-23T06:35:22Z",
		"updated": "2023-08-10T13:40:06Z",
		"method": {
			"nymResponse": {
				"result": {
					"data": "{\"dest\":\"WRfXPg8dantKVubE3HX8pw\",\"identifier\":\"V4SGRU86Z58d6TV7PBUe6f\",\"role\":\"0\",\"seqNo\":11,\"txnTime\":1524055264,\"verkey\":\"H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV\"}",
					"type": "105",
					"txnTime": 1.524055264E9,
					"seqNo": 11.0,
					"reqId": 1.52725687080231475E18,
					"identifier": "HixkhyA4dXGz9yxmLQC4PU",
					"dest": "WRfXPg8dantKVubE3HX8pw"
				},
				"op": "REPLY"
			},
			"attrResponse": {
				"result": {
					"identifier": "HixkhyA4dXGz9yxmLQC4PU",
					"seqNo": 12.0,
					"raw": "endpoint",
					"dest": "WRfXPg8dantKVubE3HX8pw",
					"data": "{\"endpoint\":{\"xdi\":\"http://127.0.0.1:8080/xdi\"}}",
					"txnTime": 1.524055265E9,
					"type": "104",
					"reqId": 1.52725687092557056E18
				},
				"op": "REPLY"
			}
		}
	}
}

Issue 23 : The did is not a url for the did, but for a resolution structure which as yet has no name pending-close

See corresponding open issue.

Issue

Need to define how this data structure works exactly, and whether it always contains a DID document or can also contain other results.

A DID document associated with a DID . The result of 4. DID Resolution .

This is a metadata structure (see section Metadata Structure in [ DID-CORE ]) that contains metadata about the DID Resolution process.

This metadata typically changes between invocations of the DID Resolution functions as it represents data about the resolution process itself.

The source of this metadata is the DID resolver.

Examples of DID Resolution Metadata include:

Media type of the returned content (the contentType metadata property).
Error object (the error metadata property).
Duration of the DID resolution process.
Caching information about the DID document (see Section 12.2 Caching ).
Various URLs, IP addresses or other network information that was used during the DID resolution process.
Proofs added by a DID resolver (e.g., to establish trusted resolution).

See also section DID Resolution Metadata in [ DID-CORE ].

This is a metadata structure (see section Metadata Structure in [ DID-CORE ]) that contains metadata about a DID Document .

This metadata typically does not change between invocations of the DID Resolution function unless the DID document changes, as it represents data about the DID document .

The sources of this metadata are the DID controller and/or the DID method .

Examples of DID Document Metadata include:

Timestamps when the DID and its associated DID document were created or updated (the created and updated metadata properties).
Metadata about controllers, capabilities, delegations, etc.
Versioning information about the DID document (see Section 12.3 Versioning ).
Proofs added by a DID controller (e.g., to establish control authority).

DID Document Metadata may also include method-specific metadata, e.g.:

State proofs from the verifiable data registry .
Block number, index, transaction hash, number of confirmations, etc. of a record in the blockchain or other verifiable data registry .

See also section DID Document Metadata in [ DID-CORE ].

Issue

For certain data, it may be debatable whether it should be part of the DID document (i.e., data that describes the DID Subject), or whether it is metadata (i.e., data about the DID document or about the DID resolution process). For example the URL of the "Continuation DID document" in the BTCR method.

This section defines a data structure that represents the result of the algorithm described in 5. DID URL Dereferencing . A DID URL dereferencing result contains arbitrary content as well as DID resolution metadata and content metadata .

Issue 69 : DID Resolution Result for DID URL Dereferencing enhancement pending-close

See corresponding open issue.

The media type of this data structure is defined to be application/ld+json;profile="https://w3id.org/did-resolution".

Example 23 : Example DID URL dereferencing result

{
	"@context": "https://w3id.org/did-resolution/v1",
	"content": {
		"@context": "https://www.w3.org/ns/did/v1",
		"id": "did:example:123456789abcdefghi",
		"authentication": [{
			"id": "did:example:123456789abcdefghi#keys-1",
			"type": "Ed25519VerificationKey2018",
			"controller": "did:example:123456789abcdefghi",
			"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
		}],
		"service": [{
			"id":"did:example:123456789abcdefghi#vcs",
			"type": "VerifiableCredentialService",
			"serviceEndpoint": "https://example.com/vc/"
		}]
	},
	"didUrlDereferencingMetadata": {
		"contentType": "application/did+ld+json",
		"retrieved": "2024-06-01T19:73:24Z",
	},
	"contentMetadata": {
		"created": "2019-03-23T06:35:22Z",
		"updated": "2023-08-10T13:40:06Z",
		"method": {
			"nymResponse": {
				"result": {
					"data": "{\"dest\":\"WRfXPg8dantKVubE3HX8pw\",\"identifier\":\"V4SGRU86Z58d6TV7PBUe6f\",\"role\":\"0\",\"seqNo\":11,\"txnTime\":1524055264,\"verkey\":\"H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV\"}",
					"type": "105",
					"txnTime": 1.524055264E9,
					"seqNo": 11.0,
					"reqId": 1.52725687080231475E18,
					"identifier": "HixkhyA4dXGz9yxmLQC4PU",
					"dest": "WRfXPg8dantKVubE3HX8pw"
				},
				"op": "REPLY"
			},
			"attrResponse": {
				"result": {
					"identifier": "HixkhyA4dXGz9yxmLQC4PU",
					"seqNo": 12.0,
					"raw": "endpoint",
					"dest": "WRfXPg8dantKVubE3HX8pw",
					"data": "{\"endpoint\":{\"xdi\":\"http://127.0.0.1:8080/xdi\"}}",
					"txnTime": 1.524055265E9,
					"type": "104",
					"reqId": 1.52725687092557056E18
				},
				"op": "REPLY"
			}
		}
	}
}

Arbitrary content associated with a DID URL . The result of 5. DID URL Dereferencing .

This is a metadata structure (see section Metadata Structure in [ DID-CORE ]) that contains metadata about the DID URL Dereferencing process.

This metadata typically changes between invocations of the DID URL Dereferencing functions as it represents data about the dereferencing process itself.

Issue

Add more details how DID URL dereferencing metadata works.

See also section DID URL Dereferencing Metadata in [ DID-CORE ].

This is a metadata structure (see section Metadata Structure in [ DID-CORE ]) that contains metadata about the content.

This metadata typically does not change between invocations of the DID URL Dereferencing function unless the content changes, as it represents data about the content.

Issue

Add more details how content metadata works.

The algorithms described in this specification throw specific types of errors. Implementers might find it useful to convey these errors to other libraries or software systems. This section provides specific URLs and descriptions for the errors, such that an ecosystem implementing technologies described by this specification might interoperate more effectively when errors occur. Additionally, this specification uses some errors defined in Section 3.5 Processing Errors of the [ CID ] specification.

Implementers SHOULD use [ RFC9457 ] to encode the error data structure. If [ RFC9457 ] is used:

The type value of the error object MUST be a URL. Where the values listed in the section below do not define a URL, the values MUST be prepended with the URL https://www.w3.org/ns/did#.
The title value SHOULD provide a short but specific human-readable string for the error.
The detail value SHOULD provide a longer human-readable string for the error.

INVALID_DID: An invalid DID was detected during DID Resolution . See Section 4.4 DID Resolution Algorithm .
INVALID_DID_DOCUMENT: The DID document was malformed. See Section 4.4 DID Resolution Algorithm .
NOT_FOUND: The DID resolver was unable to find the DID document resulting from this resolution request. See Section 4.4 DID Resolution Algorithm .
REPRESENTATION_NOT_SUPPORTED: The representation requested via the accept input metadata property is not supported by the DID method and/or DID resolver implementation. See Section 4.4 DID Resolution Algorithm .
INVALID_DID_URL: An invalid DID URL was detected during DID URL dereferencing . See Section 5.3 DID URL Dereferencing Algorithm
METHOD_NOT_SUPPORTED: The DID method of the DID is not supported by the DID resolver . See Section 4.4 DID Resolution Algorithm .
INVALID_OPTIONS: One or more of the options provided for DID Resolution or DID URL dereferencing are invalid.
INTERNAL_ERROR: An unexpected error occured during DID Resolution or DID URL dereferencing .
https://w3id.org/security#INVALID_PUBLIC_KEY: An invalid public key value is detected during DID Resolution or DID URL dereferencing .
https://w3id.org/security#INVALID_PUBLIC_KEY_LENGTH: The byte length of rawPublicKeyBytes did not match the expected public key length for the associated multicodecValue during DID Resolution or DID URL dereferencing .
https://w3id.org/security#INVALID_PUBLIC_KEY_TYPE: An invalid public key type was detected during DID Resolution or DID URL dereferencing .
https://w3id.org/security#UNSUPPORTED_PUBLIC_KEY_TYPE: An unsupported public key type was detected during DID Resolution or DID URL dereferencing .

This section defines bindings for the abstract algorithms in sections 4. DID Resolution and 5. DID URL Dereferencing .

This section defines a DID resolver binding which exposes the DID resolution and/or DID URL dereferencing functions (including all resolution/dereferencing options and metadata) via an HTTP(S) endpoint. See 7.2 Resolver Architectures .

The HTTP(S) binding is a remote binding . It requires a known HTTP(S) URL where a remote DID resolver can be invoked. This URL is called the DID resolver HTTP(S) endpoint

Using this binding, the DID resolution function (see 4. DID Resolution ) and/or DID URL dereferencing function (see 5. DID URL Dereferencing ) can be executed as follows:

Initialize a request HTTP(S) URL with the DID resolver HTTP(S) endpoint.
Example 24
```
https://resolver.example/1.0/identifiers/
```
For the DID resolution function:
1. Append the input DID to the request HTTP(S) URL.
  Example 25
```
https://resolver.example/1.0/identifiers/did:example:1234
```
2. Set the Accept HTTP request header to application/ld+json;profile="https://w3id.org/did-resolution" in order to request a complete 8. DID Resolution Result , OR
3. set the Accept HTTP request header to the value of the accept resolution option.
4. If any other resolution options are provided:
  1. The input DID MUST be URL-encoded (as specified in RFC3986 Section 2.1 ).
  2. Encode all resolution options except accept as query parameters in the request HTTP(S) URL.
    Example 26
```
https://resolver.example/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2
```
For the DID URL dereferencing function:
1. Append the input DID URL to the request HTTP(S) URL.
  Example 27
```
https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf
```
2. Set the Accept HTTP request header to application/ld+json;profile="https://w3id.org/did-url-dereferencing" in order to request a complete 9. DID URL Dereferencing Result , OR
3. set the Accept HTTP request header to the value of the accept dereferencing option.
4. If any other dereferencing options are provided:
  1. The input DID URL MUST be URL-encoded (as specified in RFC3986 Section 2.1 ).
  2. Encode all dereferencing options except accept as query parameters in the request HTTP(S) URL.
    Example 28
```
https://resolver.example/1.0/identifiers/did%3Aexample%3A1234%3Fservice%3Dfiles%26relativeRef%3D%2Fresume.pdf?option1=value1&option2=value2
```
Execute an HTTP GET request on the request HTTP(S) URL. This invokes the DID resolution or DID URL dereferencing function at the remote DID resolver .

If the DID resolution or DID URL dereferencing function returns an error metadata property in the didResolutionMetadata or dereferencingMetadata , then the HTTP response status code MUST correspond to the value of the error metadata property, according to the following table:

error	HTTP status code
`INVALID_DID`	`400`
`INVALID_DID_URL`	`400`
`INVALID_OPTIONS`	`400`
`NOT_FOUND`	`404`
`REPRESENTATION_NOT_SUPPORTED`	`406`
`INVALID_DID_DOCUMENT`	`500`
`METHOD_NOT_SUPPORTED`	`501`
`INVALID_PUBLIC_KEY`	`500`
`INVALID_PUBLIC_KEY_LENGTH`	`500`
`INVALID_PUBLIC_KEY_TYPE`	`500`
`UNSUPPORTED_PUBLIC_KEY_TYPE`	`501`
`INTERNAL_ERROR`	`500`
(any other value)	`500`

If the DID resolution or DID URL dereferencing function returns a deactivated metadata property with the value true in the didDocumentMetadata or contentMetadata :
1. The HTTP response status code MUST be 410.
For the DID resolution function:
1. If the value of the Content-Type HTTP response header is application/ld+json;profile="https://w3id.org/did-resolution":
  1. The HTTP body MUST contain a DID resolution result (see 8. DID Resolution Result ) that is the result of the DID resolution function.
2. If the function is successful and returns a didDocument :
  1. The HTTP response status code MUST be 200.
  2. The HTTP response MUST contain a Content-Type HTTP response header. Its value MUST be the value of the contentType metadata property in the didResolutionMetadata (see 4.2 DID Resolution Metadata ).
  3. The HTTP response body MUST contain the didDocument that is the result of the DID resolution function, in the representation corresponding to the Content-Type HTTP response header.
For the DID URL dereferencing function:
1. If the value of the Content-Type HTTP response header is application/ld+json;profile="https://w3id.org/did-url-dereferencing":
  1. The HTTP body MUST contain a DID URL dereferencing result (see 9. DID URL Dereferencing Result ) that is the result of the DID URL dereferencing function.
2. If the function is successful and returns a contentStream and a contentType metadata property with the value text/uri-list in the dereferencingMetadata :
  1. The HTTP response status code MUST be 303.
  2. The HTTP response MUST contain an Location header. The value of this header MUST be the selected service endpoint URL.
  3. the HTTP response body MUST be empty.
3. If the function is successful and returns a contentStream with any other contentType :
  1. The HTTP response status code MUST be 200.
  2. The HTTP response MUST contain a Content-Type HTTP response header. Its value MUST be the value of the contentType metadata property in the dereferencingMetadata (see 5.2 DID URL Dereferencing Metadata ).
  3. The HTTP response body MUST contain the contentStream that is the result of the DID URL dereferencing function, in the representation corresponding to the Content-Type HTTP response header.

See here for an OpenAPI definition.

Given the following DID resolver HTTP(S) endpoint:

https://resolver.example/1.0/identifiers/

And given the following input DID:

did:sov:WRfXPg8dantKVubE3HX8pw

Then the request HTTP(S) URL is:

https://resolver.example/1.0/identifiers/did:sov:WRfXPg8dantKVubE3HX8pw

The HTTP(S) binding can be invoked as follows:

Example 29 : Example curl call to a DID resolver via HTTP(S) binding

curl
-X
GET
https://resolver.example/1.0/identifiers/did:sov:WRfXPg8dantKVubE3HX8pw

Additional examples of the HTTP(S) binding:

Diagram showing the invocation of resolve() over HTTPS — Figure 13 Invocation of resolve() over HTTP(S).

Additional examples of the HTTP(S) binding:

Diagram showing the invocation of dereference() over HTTPS — Figure 15 Invocation of dereference() over HTTP(S).

DID resolution and DID URL dereferencing do not involve any authentication or authorization functionality. Similar to DNS resolution, anybody can perform the process, without requiring any credentials or non-public knowledge.

Issue 38 : Restricted access/Authentication/Authorization enhancement

The spec should clarify whether or not conformant resolvers MUST be public or MAY restrict access via some authentication and authorization scheme.

The current language doesn't make it clear if authentication is just out of scope or if it is disallowed.

Issue

Explain that DIDs are not necessarily globally resolvable, such as pairwise or N-wise "peer" DIDs.

See [ RFC3339 ]: URIs have a global scope and are interpreted consistently regardless of context, though the result of that interpretation may be in relation to the end-user's context.

An advanced idea is that the result of DID resolution could be contextual or depend on policies, see this comment .

Issue

A related topic is whether (parts of) DID document could be encrypted, e.g., w3c/did-core/issues/25 . Also see the use of the fragment in the IPID DID method.

A DID resolver may maintain a generic cache of DID documents . It may also maintain caches specific to certain DID methods .

The noCache resolution option can be used to request a certain kind of caching behavior.

This resolution option is OPTIONAL .

Possible values of this property are:

"false" (default value): Caching of DID documents is allowed.
"true": Request that caching is disabled and a fresh DID document is retrieved from the verifiable data registry .

Caching behavior can be controlled by configuration of the DID resolver , by the noCache resolution option, or by contents of the DID document (e.g., a cacheMaxTtl field), or by a combination of these properties.

Issue 10 ~~: need TTL construct? enhancement~~

See corresponding open issue.

Issue

Perhaps we can re-use caching mechanisms of other protocols such as HTTP.

If a versionId or versionTime DID parameter is provided, the DID resolution algorithm returns a specific version of the DID document .

The DID parameters versionId and versionTime are mutually exclusive.

The use of the versionId DID parameter is specific to the DID method . Its possible values may include sequential numbers, random UUIDs, content hashes, etc..

DID document metadata MAY contain a versionId property that changes with each Update operation that is performed on a DID document.

Note

While most DID methods support the Update operation, there is no requirement for DID methods to keep all previous DID document versions, therefore not all DID methods support versioning.

Issue 12 : Design versioning features pending-close

See corresponding open issue.

Issue 8 : Discover DIDs from other identifiers

There is discussion on the relationship between DID resolution and resolution of non-DID identifiers such as domain names, HTTP URIs, or e-mail addresses. This includes the questions how DIDs can be discovered from non-DID identifiers, and how links between identifiers can be verifiable.

Issue

TODO: Define privacy considerations for DID resolution

~~Issue 95~~

DID resolvers ~~: Minimizing~~ and DID URL dereferencers will be able to log requests to their services for resolution and dereferencing. Over time, these logs could be used to track and profile the ~~extent of profiling of requestors~~ clients making requests for these services. To mitigate this privacy ~~ready-for-pr There~~ risk, clients should make such requests to services they trust, for example, because of an existing business relationship or because the service is ~~discussion about minimizing~~ running on infrastructure they control. Clients can also take steps to obfuscate their requests to a service in order to limit the ~~extent of profiling~~ possibilities of ~~requesters from DID Resolvers.~~ correlation and profiling.

Note

This section lists additional DID URL dereferencing features that are under discussion and have not yet been incorporated into the algorithm.

A service endpoint may have a serviceEndpoint property with a value that is itself a DID. This is interpreted as a "DID redirect" from the input DID to another. In this case, a "child" DID resolution process can be launched to get to a "final" service endpoint.

The follow-redirect resolution option can be supplied by a client as a hint to instruct whether redirects should be followed. This resolution option is OPTIONAL .

Issue 7 : Support DIDs as serviceEndpoint? enhancement pending-close

See corresponding open issue.

Issue 36 : Portable DID resolution

DID redirects could not only apply to a single service endpoint, but to an entire DID document, therefore enabling portability use cases.

Example 30

{
   "id": "did:example:123456789abcdefghi#hub1",
   "type": "HubService",
   "serviceEndpoint": "did:example:xyz"
}

A DID document may contain a "proxy" service type which would provide a mapping that needs to be followed in order to resolve to a final service URL.

Issue 35 : Support "proxy" service type? enhancement pending-close

Keeping track of a proposal here w3c-ccg/did-spec#90 (comment) that a DID Document could contain a "proxy" service type which would provide a mapping that needs to be followed in order to resolve to a final service URL.

Example 31

{
   "id": "did:example:123456789abcdefghi",
   "type": "ProxyService",
   "serviceEndpoint": "https://mydomain.com/proxy"
}

Issue

Several ways of selecting parts of a DID document are being discussed, including the use of JSON pointer.

See corresponding PRs here and here .

[CID]: Controlled Identifiers v1.0 . Michael Jones; Manu Sporny. W3C. 15 May 2025. W3C Recommendation. URL: https://www.w3.org/TR/cid-1.0/
[DID-CORE]: Decentralized Identifiers (DIDs) v1.0 . Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed. W3C. 19 July 2022. W3C Recommendation. URL: https://www.w3.org/TR/did-core/
[INFRA]: Infra Standard . Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2046]: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types . N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2046
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels . S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC3986]: Uniform Resource Identifier (URI): Generic Syntax . T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC4122]: A Universally Unique IDentifier (UUID) URN Namespace . P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4122
[RFC7231]: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content . R. Fielding, Ed.; J. Reschke, Ed. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words . B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC9457]: Problem Details for HTTP APIs . M. Nottingham; E. Wilde; S. Dalal. IETF. July 2023. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc9457
[VC-DATA-MODEL]: Verifiable Credentials Data Model v1.1 . Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog. W3C. 3 March 2022. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model/
[XMLSCHEMA11-2]: W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes . David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/

[DATA-INTEGRITY]: Verifiable Credential Data Integrity 1.0 . Dave Longley; Manu Sporny. W3C Verifiable Credentials Working Group. CRD. URL: https://www.w3.org/TR/vc-data-integrity/
[DID-KEY]: The did:key Method . Manu Sporny; Dmitri Zagidulin; Dave Longley. 09 June 2020. unofficial. URL: https://w3c-ccg.github.io/did-method-key/
[DID-PEER]: Peer DID Method Specification . Oskar Deventer; Christian Lundkvist; Márton Csernai; Kyle Den Hartog; Markus Sabadello; Sam Curren; Dan Gisolfi; Mike Varley; Sven Hammann; John Jordan; Lovesh Harchandani; Devin Fisher; Tobias Looker; Brent Zundel; Stephen Curran. 10 July 2020. W3C Editor's Draft. URL: https://identity.foundation/peer-did-method-spec/
[DID-SPEC-REGISTRIES]: Decentralized Identifier Extensions . Manu Sporny; Markus Sabadello. W3C. 19 February 2025. W3C Working Group Note. URL: https://www.w3.org/TR/did-extensions/
[HASHLINK]: Cryptographic Hyperlinks . Manu Sporny. IETF. December 2018. Internet-Draft. URL: https://tools.ietf.org/html/draft-sporny-hashlink-05
[KERI]: Key Event Receipt Infrastructure (KERI) . Samuel M. Smith. July 2019. URL: https://arxiv.org/abs/1907.02143
[RFC3339]: Date and Time on the Internet: Timestamps . G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339

Decentralized Identifier Resolution (DID Resolution) v0.3

Algorithms and guidelines for resolving DIDs and dereferencing DID URLs

Abstract

Status of This Document

1. Introduction

1.1 Conformance

1.2 Audience

2. Terminology

3. DID Parameters

4. DID Resolution

4.1 DID Resolution Options

4.2 DID Resolution Metadata

4.3 DID Document Metadata

4.4 DID Resolution Algorithm

5. DID URL Dereferencing

5.1 DID URL Dereferencing Options

5.2 DID URL Dereferencing Metadata

5.3 DID URL Dereferencing Algorithm

5.3.1 Dereferencing the Resource

5.3.2 Dereferencing the Fragment

5.4 Examples

5.4.1 Example: Dereferencing to verification method

5.4.2 Example: Dereferencing to service endpoint URL

6. Metadata Structure

7. DID Resolution Architectures

7.1 Method Architectures

7.2 Resolver Architectures

7.2.1 Multiple Methods

7.2.2 Proxied Resolution

7.2.3 Client-Side Dereferencing

7.3 Examples

8. DID Resolution Result

8.1 Example

8.2 DID Document

8.3 DID Resolution Metadata

8.4 DID Document Metadata

9. DID URL Dereferencing Result

9.1 Example

9.2 Content

9.3 DID URL Dereferencing Metadata

9.4 Content Metadata

10. Errors

11. Bindings

11.1 HTTP(S) Binding

11.2 DID Resolution Examples

11.3 DID URL Dereferencing Examples

12. Security Considerations

12.1 Authentication/Authorization

12.2 Caching

12.3 Versioning

12.4 Non-DID Identifiers

13. Privacy Considerations

13.1 Non-DID Identifiers Profiling of DID Resolution and Dereferencing Requesters

14. Future Work

14.1 Redirect

14.2 Proxy

14.3 JSON Pointer

A. DID Resolution Resources

B. References

B.1 Normative references

B.2 Informative references