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

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

DID Resolution Options

This is a metadata structure that contains input options for the DID Resolution process.

The possible properties within this structure and their possible values SHOULD be registered in the DID Resolution Extensions [[?DID-EXTENSIONS-RESOLUTION]]. This specification defines the following common input options:

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 for the definition.

versionTime

See for the definition.

DID Resolution Metadata

This is a metadata structure that contains metadata about the DID Resolution process.

This metadata typically changes between invocations of the DID Resolution function 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 (`contentType`).
• Error object (`error`) (see Section ).
• Proofs generated by the DID resolver, e.g., to establish trusted resolution (proof).
• Duration of the DID resolution process.
• Caching information (see Section ).
• URLs, IP addresses, and/or other networking information about the verifiable data registry that was used during the DID resolution process.

The possible properties within this structure and their possible values SHOULD be registered in the DID Resolution Extensions [[?DID-EXTENSIONS-RESOLUTION]]. This specification defines the following common metadata properties:

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 . Additional errors SHOULD be registered in the DID Resolution Extensions [[?DID-EXTENSIONS-RESOLUTION]].

proof

Some DID resolvers and DID URL dereferencers use proofs when executing the DID Resolution or DID URL Dereferencing functions. See for details.

DID resolution metadata MAY include a proof property. If present, the value MUST be a set where each item is a map that contains a proof. The use of this property and the types of proofs are DID method-independent.

DID Document Metadata

This is a metadata structure that contains metadata about the DID Resolution process.

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 (e.g., `created`, `updated`, `nextUpdate`).
• Versioning information about the DID document (e.g., `versionId`, `nextVersionId`).
• Proofs added by the DID controller or generated by the DID method's verifiable data registry, which might be used to establish control authority or to enable verifiable reads (e.g., `proof`).
• Metadata about controllers, capabilities, delegations, etc.
• Method-specific metadata, such as block number, index, transaction hash, number of confirmations, etc., of a record in the blockchain or other verifiable data registry.

The possible properties within this structure and their possible values SHOULD be registered in the DID Document Properties Extensions [[?DID-EXTENSIONS-PROPERTIES]]. This specification defines the following common metadata 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 . 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).

equivalentId is a much stronger form of equivalence than alsoKnownAs because the equivalence MUST be guaranteed by the governing DID method. The use of equivalentId means that 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 . 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).

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, the use of canonicalId means that 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.

proof

Many DID methods use proofs when executing method operations. See for details.

DID document metadata MAY include a proof property. If present, the value MUST be a set where each item is a map that contains a proof. The use of this property and the types of proofs are DID method-specific.

DID Resolution Algorithm

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

1. 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: «[ ]»
2. 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: «[ ]»
3. 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.
4. 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 [[[DID-CORE]]].
   3. Update the output DID document by replacing the relative DID URLs with the resolved absolute DID URLs.
5. Return the following result:
   1. didResolutionMetadata: «[ ... ]»
   2. didDocument: output DID document
   3. didDocumentMetadata: «[ "contentType" → output DID document media type, ... ]»

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.

DID URL Dereferencing Options

This is a metadata structure that contains input options for the DID URL Dereferencing process.

The possible properties within this structure and their possible values SHOULD be registered in the DID Resolution Extensions [[?DID-EXTENSIONS-RESOLUTION]]. This specification defines the following common input options:

accept

The Media Type that the caller prefers for contentStream. The Media Type MUST be expressed as an ASCII string. The DID URL dereferencer 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.

DID URL Dereferencing Metadata

This is a metadata structure that contains metadata about the DID URL Dereferencing process.

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

The source of this metadata is the DID URL dereferencer.

The possible properties within this structure and their possible values SHOULD be registered in the DID Resolution Extensions [[?DID-EXTENSIONS-RESOLUTION]]. This specification defines the following common metadata properties:

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 . Additional errors SHOULD be registered in the DID Resolution Extensions [[?DID-EXTENSIONS-RESOLUTION]].

proof

Some DID resolvers and DID URL dereferencers use proofs when executing the DID Resolution or DID URL Dereferencing functions. See for details.

DID URL dereferencing metadata MAY include a proof property. If present, the value MUST be a set where each item is a map that contains a proof. The use of this property and the types of proofs are DID method-independent.

DID URL Content Metadata

This is a metadata structure that contains metadata about the DID URL Dereferencing process.

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.

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

The possible properties within this structure and their possible values SHOULD be registered in the DID Resolution Extensions [[?DID-EXTENSIONS-RESOLUTION]]. This specification defines no common properties.

DID URL Components Handling

A DID URL consists of a DID, optionally followed by additional URL components — any combination of a path, zero or more query parameters, and/or a fragment identifier — as defined in RFC3986. This section defines how these components MUST be interpreted by DID Resolvers when dereferencing a DID URL.

The interpretation of DID URL components is conceptually similar to that of HTTP URLs having the same components:

• A DID Resolver is comparable to a web server — responsible for interpreting the request and returning a representation of the identified resource. Unlike general-purpose HTTP servers, DID Resolvers are more constrained in their behavior, typically implementing DID Method-specific resolution rules.
• A client of a DID Resolver is comparable to a web browser — responsible for constructing the DID URL and processing the response. DID Resolver clients are generally more flexible than browsers, applying deployment-specific handling of the resolved resource by media type, including metadata and fragment (if any).

The similarity ends there. DID Resolvers do not support arbitrary server logic or content negotiation. Instead, the interpretation of DID URL components is deterministic and governed by this specification, the applicable DID method specification, and any DID Document Properties Extensions [[?DID-EXTENSIONS-PROPERTIES]] supported by the DID Resolver.

This section describes the structure, constraints, and required handling of each DID URL component. These rules form the basis for the DID URL dereferencing algorithm.

		// DID URL:
		did:web:example.com/path/to/file.txt

		// DID Document service section:
		{
		"service": [
			{
			"type": "FileService",
			"serviceEndpoint": "https://example.com/",
			"prefix": "/"
			}
		]
		}

		// Resulting URL:
		https://example.com/path/to/file.txt
			

		// DID URL:
		did:webvh:example.com/whois

		// DID Document service section:
		{
		"service": [
			{
			"type": "FileService",
			"serviceEndpoint": "https://example.com/whois.vp",
			"prefix": "/whois"
			}
		]
		}

		// Resulting URL:
		https://example.com/whois.vp
			

		// DID URL:
		did:web:example.com/example/resume.pdf/<hash>

		// DID Document service section:
		{
		"service": [
			{
			"type": "ExampleVerifiedFileService",
			"serviceEndpoint": "https://example.com/example/files/",
			"prefix": "/example/"
			}
		]
		}

		// Resulting URL:
		https://example.com/example/files/resume.pdf
			

		// DID URLs:
		did:web:example.com/path/to/file.txt
		did:web:example.com/example/resume.pdf/<hash>

		// DID Document service section:
		{
		"service": [
			{
			"type": "FileService",
			"serviceEndpoint": "https://example.com/",
			"prefix": "/"
			},
			{
			"type": "ExampleVerifiedFileService",
			"serviceEndpoint": "https://example.com/example/files/",
			"prefix": "/example/"
			}
		]
		}

		// Resulting URLs:
		https://example.com/path/to/file.txt
		https://example.com/example/files/resume.pdf (with hash verification after resolution)
			

DID URL Dereferencing Algorithm

This section defines the normative algorithm for dereferencing a DID URL into a resource. It builds on the rules in the DID URL Components Handling section of this specification.

1. Parse the DID URL into the following components:
   • did
   • path
   • query parameters (stored as a working set qp)
   • fragment
2. Handle Fragments:
   • As noted in the DID URL fragment handling section, if a DID URL contains a fragment, a DID Resolver SHOULD NOT process or interpret it. Fragment handling is the client's responsibility, based on the resolved document and its media type.
3. Resolve the DID:
   1. Identify and apply DID parameters from qp that affect DID Resolution (e.g., versionId, versionTime), including any DID Method-specific and DID Document Property Extension [[?DID-EXTENSIONS-PROPERTIES]] DID parameters that are understood by the DID Resolver.
   2. Use these to resolve the did into a didDocument and didResolutionMetadata.
   3. If resolution fails, return an error and abort dereferencing.
   4. Remove any consumed DID parameters from the qp working set.
4. No Path Component: If no path is present, resolution is complete and the path-handling step is skipped.
5. With Path Component:
   1. Construct a target URL using the DID URL path resolution rules.
   2. Remove any consumed query parameters from the qp working set.
   3. If there are unused query parameters in qp, add them to the constructed URL as query parameters, ensuring they are formatted according to RFC3986 Section 3.4.
   4. Attempt to resolve the resulting URL to retrieve the resource and metadata to be returned to the client.
   5. If the resolution of the URL fails, an error MUST be returned.
   6. If the DID Resolver is unable to resolve the URL, an error MUST be returned.

   Resolving an assembled URL from a path might result in a resolution cycle, which is a set of steps that result in an infinite loop. For example, a URL assembled from a path might indirectly point back through a sequence of resolutions to a previously dereferenced URL. A DID resolver is expected to detect and handle recursive cycles when resolving a URL assembled from a path, to prevent an infinite loop or other resolution failure. For further guidance, see Section Resolution Cycles.

6. Return the dereferencing result:
   1. If the resolution result is a DID Document, return the following:
      • content: the resolved DID document with selected services
      • contentMetadata: metadata about the resolved DID document
      • dereferencingMetadata: any metadata about the dereferencing process
   2. If the resolution result is a resource resolved via DID URL path processing, return the following:
      • content: the resolved resource
      • contentType: the media type of the resolved resource
      • dereferencingMetadata: any metadata about the dereferencing process

Query Parameters and Service Types

This section defines the set of DID URLquery parameters and service types that are reserved for use within the DID Resolution algorithm and DID URL dereferencing process defined in this specification.

These values are not DID Method-specific. All DID Methods that are capable of implementing these query parameters and service types SHOULD recognize and correctly process them. DID Methods that do not support the capabilities required for a specific query parameter (e.g., historical DID Document version resolution) SHOULD recognize these query parameters and return an appropriate error.

Examples

This section provides illustrative examples of DID URLs and their corresponding dereferencing behavior.

An optional fragment identifier #fragment may be appended to any of these examples to reference a specific node within the returned resource. Fragment processing is performed by the client and is not handled by the DID Resolver.

The following is the DID document that is used in all of the following examples.

{
	"@context": "https://www.w3.org/ns/did/v1",
	"id": "did:example:123456789abcdefghi",
	"versionId": "2",
	"versionTime": "2025-10-17T17:58:43Z",
	"verificationMethod": [
		{
			"id": "did:example:123456789abcdefghi#keys-1",
			"type": "Multikey",
			"controller": "did:example:123456789abcdefghi",
			"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
		}
	],
	"service": [
		{
			"type": "FileService",
			"serviceEndpoint": "https://example.com/",
			"prefix": "/"
		},
		{
			"type": "ExampleFileService",
			"serviceEndpoint": "https://example.com/files/",
			"prefix": "/example/"
		},
		{
			"type": "FileService",
			"serviceEndpoint": "https://example.com/whois.vp",
			"prefix": "/whois"
		}
	]
}
		

Method Architectures

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

Every DID method defines this method operation, i.e., how a DID resolver can obtain a DID document from a DID. The underlying data formats, protocols, technical infrastructures, and processes can vary considerably among DID methods.

Examples of DID method considerations include the following:

• A DID method might use an immutable blockchain, distributed ledger, distributed file system, peer-to-peer network, or other decentralized infrastructure as (part of) its verifiable data registry.
• A DID method might use DNS, HTTP, or web servers as (part of) its verifiable data registry.
• A DID method might use any combination of the above technical infrastructures.
• A DID method might store an actual DID document in plain-text form in a verifiable data registry and might simply retrieve that document during the "Read" operation.
• A DID method might define its "Read" operation in a more complex way that could involve intermediate, partial, or temporary DID documents, and use multi-step processes that construct the DID document "on-the-fly".
• A DID method might require interaction with remote servers or networks during execution of the "Read" operation.
• A DID method might execute the "Read" operation in an entirely local way that does not require any interaction with remote servers or networks. For example, in the [[DID-KEY]] method, the DID itself wraps a public key, and the "Read" operation is simply a trivial, local transformation process.

Based on the above considerations combined with the nature of a DID method's "Read" operation, the interaction between a DID resolver and the verifiable data registry could be considered either a verifiable read or an unverifiable read:

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. This can be accomplished in a number of ways, such as the following:

• A verifiable read can be accomplished if access to the verifiable data registry is possible in a local, trusted network environment.
  • For example, in blockchain-based DID methods, a verifiable read might be accomplished if a blockchain full node is deployed on a local server.
• If access to the verifiable data registry happens via a remote server, a verifiable read might still be accomplished if the remote server is trusted, and if it can be accessed via a secure channel.
• If access to the verifiable data registry happens via a remote server, a verifiable read might be accomplished if the DID resolver has some way of verifying the DID document and DID document metadata returned by the DID method.
  • For example, in blockchain-based DID methods, even if direct access to a blockchain full node is not available, a verifiable read may still be possible by using a light client that processes metadata to verify the data.

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

• An unverifiable read takes place if access to the verifiable data registry happens via a remote, untrusted intermediary.
  • For example, 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 a DID resolver implements that DID method. DID methods MAY allow multiple ways of implementing their "Read" operation, and SHOULD offer guidance regarding at least one way to implement a verifiable read.

The guarantees associated with a verifiable read are always limited by the architecture(s), protocol(s), cryptographic element(s), and other aspects of the DID method's underlying verifiable data registry. The forms of verifiable read implementation that are considered strongest are those that require no interaction with any remote network (for example, see [[DID-KEY]]), and those that minimize dependencies on specific network infrastructure, reducing the "root of trust" to proven entropy and cryptography (for example, see [[KERI]]).

To enable verifiable reads, many DID methods use digital signatures, state proofs, proofs of inclusion in Merkle trees, cryptographic event logs, or other types of proofs. If a DID method uses such proofs, it MUST specify in its DID method specification how they are used for verification of the correctness of the result of a "Read" operation.

A DID method MAY also include such proofs in the DID document itself, or in a proof property of the DID document metadata. This can potentially enable a client to independently verify the results of a DID Resolution process, even if it does not trust the DID resolver.

Note that proofs originating from the DID method are DID method-specific and must be understood within the technology of the applicable DID method. A simple signature on a DID document or DID document metadata does not necessarily prove control of a DID, nor guarantee that the DID document is the correct one for the DID. These proofs help to verify the integrity and authenticity of the results of a DID Resolution process as far as the DID method itself is concerned. However, they do not guarantee that the binding between a client and the DID resolver is secure. See also .

Resolver Architectures

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

Those algorithms are implemented by DID resolvers and DID URL dereferencers, which are invoked by a client via a binding. Bindings define how the abstract functions are accessed using concrete programming or communication interfaces.

Examples of bindings include the following:

• A DID resolver might be invoked within an application by calling a software library or SDK.
• A DID resolver might be invoked as a command line tool.
• A DID resolver might be invoked over an HTTP(S) API or other network protocol, e.g., see .

Based on the above considerations combined with the nature of the binding, the interaction between a client and the DID resolver or DID URL dereferencer could be considered either a local binding or a remote binding:

Whenever possible, local bindings are preferred, as they minimize dependencies on third parties and intermediaries, reduce security risks, and maximize confidence in the integrity and correctness of the results of the DID resolution and DID URL dereferencing functions.

In some cases, it might not be possible to use a local binding; for example, in constrained IoT (Internet of Things) environments, or when a DID method requires complex infrastructure, or when many different DID methods should be supported.

If a client uses a remote binding, the following considerations apply:

• The remote binding SHOULD use a trusted instance of a DID resolver, ideally under the control of the client itself (e.g., self-hosted).
• The remote binding SHOULD use a secure channel such as VPN and/or TLS with mutual authentication.
• The client could query multiple DID resolvers over a remote binding and compare results.

A DID resolver MAY also include proofs in a proof property of the DID resolution metadata. This inclusion can potentially enable a client to independently verify the results of a DID Resolution process, as long as it trusts the DID resolver.

Note that proofs originating from a DID resolver are DID method-independent and can be universally applied by a DID resolver, across all DID methods. These proofs help to verify the integrity and authenticity of the results of a DID Resolution process as far as the DID resolver itself is concerned. However, they do not guarantee that the result from the "Read" operation of the applicable DID method is itself correct. See also .

Multiple Methods

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

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

Proxied Resolution

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

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

When using proxied resolution, a "downstream" resolver SHOULD preserve all DID resolution metadata and DID document metadata from an "upstream" resolver in a transparent manner, including any proofs that may be present. In this process, the "downstream" resolver MAY add its own DID resolution metadata, including any metadata about the proxied resolution process itself.

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

Examples

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

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

Example

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

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

Example

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

HTTP(S) Binding

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 .

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

This binding is generally considered a remote binding, but could also be a local binding if the HTTP(S) endpoint is run in a local environment, such as on localhost.

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

1. Initialize a request HTTP(S) URL with the DID resolver HTTP(S) endpoint.

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

2. For the DID resolution function:
   1. Append the input DID to the request HTTP(S) URL.

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

   2. Set the Accept HTTP request header to `application/did-resolution` to request a complete , OR
   3. set the Accept HTTP request header to the value of the accept resolution option to request only the didDocument value of the result.
3. For the DID URL dereferencing function:
   1. Append the input DID URL to the request HTTP(S) URL.

      https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf

   2. Set the Accept HTTP request header to `application/did-url-dereferencing` to request a complete , OR
   3. set the Accept HTTP request header to the value of the accept dereferencing option to request only the contentStream value of the result.
4. For the HTTP(S) GET binding:
   1. If any other resolution options or dereferencing options than accept 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.
   2. 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.

      GET https://resolver.example/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2 HTTP/1.1
      Accept: application/did-resolution
      

      GET https://resolver.example/1.0/identifiers/did%3Aexample%3A1234%3Fservice%3Dfiles%26relativeRef%3D%2Fresume.pdf?option1=value1&option2=value2 HTTP/1.1
      Accept: application/did-url-dereferencing
      

5. For the HTTP(S) POST binding:
   1. If any other resolution options or dereferencing options than accept are provided:
      1. Encode all resolution options except accept as a JSON structure in the HTTP request's POST body.
   2. Execute an HTTP POST request on the request HTTP(S) URL. This invokes the DID resolution or DID URL dereferencing function at the remote DID resolver.

      POST https://resolver.example/1.0/identifiers/did:example:1234 HTTP/1.1
      Accept: application/did-resolution
      
      {
          "option1": "value1",
          "option2": "value2"
      }

      POST https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf HTTP/1.1
      Accept: application/did-url-dereferencing
      
      {
          "option1": "value1",
          "option2": "value2"
      }

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

7. 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.
8. For the DID resolution function:
   1. If the value of the Content-Type HTTP response header is `application/did-resolution`:
      1. The HTTP body MUST contain a DID resolution result (see ) 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 ).
      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.
9. For the DID URL dereferencing function:
   1. If the value of the Content-Type HTTP response header is `application/did-url-dereferencing`:
      1. The HTTP body MUST contain a DID URL dereferencing result (see ) 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 ).
      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 corresponding to the HTTP(S) binding.

DID Resolution Examples

Given the following DID resolver HTTP(S) endpoint:

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

And given the following input DID:

did:example:123

Then the request HTTP(S) URL is:

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

Example: Returning a DID Resolution Result

The resolve() function can be invoked over the HTTP(S) binding as follows:

GET https://resolver.example/1.0/identifiers/did:example:123 HTTP/1.1
Accept: application/did-resolution

The response is as follows:

HTTP 200 OK
Content-Type: application/did-resolution

{
	"didDocument": {
		"@context": [ "https://www.w3.org/ns/did/v1.1" ],
		"id": "did:example:123",
		"verificationMethod": [{
			...
		}],
		"service": [{
			...
		}]
	},
	"didResolutionMetadata": {
		"contentType": "application/did"
	},
	"didDocumentMetadata": {
		...
	}
}

Example: Returning a DID Document

The resolve() function can be invoked over the HTTP(S) binding as follows:

GET https://resolver.example/1.0/identifiers/did:example:123 HTTP/1.1
Accept: application/did

The response is as follows:

HTTP 200 OK
Content-Type: application/did

{
	"@context": [ "https://www.w3.org/ns/did/v1.1" ],
	"id": "did:example:123",
	"verificationMethod": [{
		...
	}],
	"service": [{
		...
	}]
}

DID URL Dereferencing Examples

Example: Returning a DID URL Dereferencing Result

The dereference() function can be invoked over the HTTP(S) binding as follows:

GET https://resolver.example/1.0/identifiers/did:example:123?versionId=2 HTTP/1.1
Accept: application/did-url-dereferencing

The response is as follows:

HTTP 200 OK
Content-Type: application/did-url-dereferencing

{
	"content": {
		"@context": [ "https://www.w3.org/ns/did/v1.1" ],
		"id": "did:example:123",
		"verificationMethod": [{
			...
		}],
		"service": [{
			...
		}]
	},
	"dereferencingMetadata": {
		"contentType": "application/did"
	},
	"contentMetadata": {
		...
	}
}

Example: Returning a resource

The dereference() function can be invoked over the HTTP(S) binding as follows:

GET https://resolver.example/1.0/identifiers/did:example:123?versionId=2 HTTP/1.1
Accept: application/did

The response is as follows:

HTTP 200 OK
Content-Type: application/did

{
	"@context": [ "https://www.w3.org/ns/did/v1.1" ],
	"id": "did:example:123",
	"verificationMethod": [{
		...
	}],
	"service": [{
		...
	}]
}

Authentication/Authorization

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.

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.

Caching

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.

Resolvers that implement noCache might be more vulnerable to denial of service attacks, as malicious clients can bypass caching to force expensive network requests and resource consumption. Clients requesting resolution with noCache expect that some resolvers will reject resolution requests that bypass caching. Resolvers that deny resolution without caching MUST respond with a FEATURE_NOT_SUPPORTED error that makes it clear that bypassing the cache was not permitted so the client can attempt to resolve without using noCache.

See corresponding open issue.

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

JSON-LD Context Integrity

If JSON-LD Context files are fetched from a remote location, an attacker could alter the context file (for example, by compromising the server or intercepting the request via a man-in-the-middle attack).

Therefore, any DID resolver which performs remote retrieval of JSON-LD Context URLs is strongly advised to use a registry of context files and corresponding hashes (or a functionally equivalent mechanism) to help ensure end-to-end security. Implementations are expected to throw errors if the cryptographic hash value for a resource does not match the expected hash value.

Versioning

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.

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.

VDR Network Forks

DID methods that use a distributed system (such as a distributed ledger) as a VDR (verifiable data registry) need to manage the potential that network forks may occur. Therefore, the specification of a DID method that uses a distributed system as a VDR SHOULD specify a means by which the VDR they are using can be disambiguated from such forks.

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

Resolution Cycles

When a DID resolver client dereferences identifiers and linked resources in a DID document — especially fields like verificationMethod, controller, or alsoKnownAs — it might encounter a resolution cycle. These can occur when a DID document references another DID (or URL) that eventually leads back to a previously dereferenced identifier, forming a loop. A DID resolver can also encounter such a situation when dereferencing a DID URL that references a service endpoint.

did:example:alice
	└── verificationMethod.controller → did:example:bob
		└── verificationMethod.controller → did:example:alice

DID resolvers and their clients that perform recursive dereferencing are expected to expect, detect, and handle such cycles.

Security and performance risks: If cycles are not detected and mitigated, recursive dereferencing could lead to:

• Infinite loops or stack overflows in software.
• Resource exhaustion (e.g., memory, network, or CPU).
• Denial-of-service (DoS) vulnerabilities in clients or intermediaries.

Mitigation guidance: Components that recursively follow external DID document references are encouraged to track identifiers that have already been dereferenced and to detect when a cycle has occurred and take appropriate action. In addition, developers might wish to limit recursion depth or breadth to reduce the potential attack surface.

Profiling of DID Resolution and Dereferencing Requesters

DID resolvers 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 clients making requests for these services. To mitigate this privacy risk, clients should make such requests to services they trust, for example, because of an existing business relationship or because the service is running on infrastructure they control. Clients can also take steps to obfuscate their requests to a service in order to limit the possibilities of correlation and profiling.