Decentralized Identifier Resolution (DID Resolution) v0.3

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

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

A conforming DID resolver is any algorithm realized as software and/or hardware that complies with the relevant normative statements in 4. 3. 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. 4. DID URL Dereferencing .

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 3. 4.4.2 DID Query Parameters for the definition.

versionTime

See 3. 4.4.2 DID Query Parameters for the definition.

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 10. 9. Errors ).
• Proofs generated by the DID resolver , e.g., to establish trusted resolution ( proof ).
• Duration of the DID resolution process.
• Caching information (see Section 12.2 11.2 Caching ).
• 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 10. 9. Errors . 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 7.2 6.2 Resolver Architectures 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.

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 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 . 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 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 , 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 7.1 6.1 Method Architectures 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.

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 Decentralized Identifiers (DIDs) v1.0 .
   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 , ... ]»

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.

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 10. 9. Errors . 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 7.2 6.2 Resolver Architectures 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.

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.

The following A DID URL dereferencing algorithm 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 implemented 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 conformant DID resolver . In accordance with 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 [ RFC3986 DID-EXTENSIONS-PROPERTIES ], it consists ] supported by the DID Resolver .

This section describes the structure, constraints, and required handling of each DID URL component. These rules form the following three steps: resolving basis for the DID; 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

contentStream
:
resolved
DID
document

// 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/"
	}
]
}

Issue

// Resulting URL:

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



TODO:
Specify

// DID URLs:did:web:example.com/path/to/file.txtdid: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)

This section defines the resolved normative algorithm for dereferencing a DID document , select all services URL which fulfill into a resource. It builds on the following conditions: If rules in the input DID URL Components Handling contains section of this specification.

1. Parse the DID parameter URL service : Select into the service if its following components:
   • id did property matches the value of the
   • service path DID parameter. If the
   • id query parameters property or the (stored as a working set service qp DID parameter or both contain relative references, )
   • fragment
2. Handle Fragments:
   • As noted in the corresponding absolute URIs DID URL fragment handling section, if a DID URL contains a fragment, a DID Resolver MUST SHOULD NOT be process or interpret it. Fragment handling is the client's responsibility, based on the resolved document and used for determining the match, using its media type.
3. Resolve the rules specified in RFC3986 Section 5: Reference DID:
   1. Identify and apply DID parameters from qp that affect DID Resolution (e.g., versionId , versionTime and in section Relative ), including any DID URLs Method in -specific and DID Document Property Extension [ Decentralized Identifiers (DIDs) v1.0 DID-EXTENSIONS-PROPERTIES . If the input ] DID URL parameters contains that are understood by the DID parameter serviceType : Select Resolver .
   2. Use these to resolve the service if its type did property matches the value of the into a serviceType didDocument DID parameter. The selected services are a list called the selected services . and didResolutionMetadata .
   3. If the input resolution fails, return an error and abort dereferencing.
   4. Remove any consumed DID URL parameters contains from the DID parameter relativeRef : For each selected service : qp working set.
4. No Path Component: If the value of the no serviceEndpoint path property of is present, resolution is complete and the selected service path-handling step is a map , skip this selected service . skipped.
5. If With Path Component:
   1. Construct a target URL using the value of DID URL path resolution rules .
   2. Remove any consumed query parameters from the serviceEndpoint qp property of the selected service is a string , add this value to a list of selected service endpoint URLs . working set.
   3. If the value of the there are unused query parameters in serviceEndpoint property of the selected service is a set , qp , add all its items that are strings them to a list of selected service endpoint URLs . For each selected service endpoint URL , execute the algorithm specified in constructed URL as query parameters, ensuring they are formatted according to RFC3986 Section 5: Reference Resolution as follows: 3.4 .
   4. The base URI value is Attempt to resolve the selected service endpoint resulting URL . to retrieve the resource and metadata to be returned to the client.
   5. The relative reference is If the value resolution of the DID parameter relativeRef . URL fails, an error MUST be returned.
   6. Update If the selected service endpoint DID Resolver URL is unable to resolve the result of the "Reference Resolution" algorithm. URL, an error MUST be returned.
   Note

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

6. If Return the accept input DID dereferencing option is missing, or if its value is the Media Type of a representation of a DID document : result:
   1. Update the services in If the resolved resolution result is a DID document to contain only the selected services . Return Document , return the following result: following:
      • dereferencingMetadata : «[ ... ]» content : : the resolved DID document with selected services
      • contentMetadata : «[ contentMetadata : metadata about the resolved DID document metadata ]»
      • dereferencingMetadata : any metadata about the dereferencing process
   2. If the value of the accept input DID resolution option result is text/uri-list : Return a resource resolved via DID URL path processing, return the following result: following:
      • dereferencingMetadata : «[ ... ]» content : the resolved resource
      • content : « selected service endpoint URLs » contentType : the media type of the resolved resource
      • contentMetadata : «[ "contentType" → "text/uri-list", ... ]» dereferencingMetadata : any metadata about the dereferencing process
Otherwise, return the following result:

This section defines the input set of DID URL contains a query parameters and service types that are reserved for use within the DID path Resolution algorithm and/or and DID query : Example 6 URL dereferencing did:example:1234/custom/path?customquery The applicable process defined in this specification.

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

This use section provides illustrative examples of the DID fragment URLs is consistent with the definition of the and their corresponding dereferencing behavior.

An optional fragment identifier in [ RFC3986 ]. It identifies #fragment may be appended to any of these examples to reference a secondary resource which specific node within the returned resource. Fragment processing is a subset of performed by the primary resource (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"
		}
	]
}

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

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.

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 7.2 6.2 Resolver Architectures .

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

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 11.1 10.1 HTTP(S) Binding .

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 7.1 6.1 Method Architectures .

7.2.1 6.2.1 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 7.1 6.1 Method Architectures about verifiable read and unverifiable read implementations apply to each supported DID method individually.

7.2.2 6.2.2 Proxied Resolution

A DID resolver MAY invoke another DID resolver , which serves as a proxy that executes the DID resolution algorithm as defined in 4. 3. 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 ).

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.

Note : Comparison to DNS

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

Given the DID URL did:xyz:1234#keys-1 , a DID resolver could be invoked via local binding for Dereferencing dereferencing the Resource resource (i.e., the DID document ), and the client could complete the DID URL dereferencing algorithm by Dereferencing dereferencing the Fragment 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 dereferencing the Resource resource (i.e., a service endpoint URL), and the client could complete the DID URL dereferencing algorithm by Dereferencing dereferencing the Fragment 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 dereferencing the Resource resource (i.e., the DID document ), and the client could complete the DID URL dereferencing algorithm by Dereferencing dereferencing the Fragment fragment (i.e., a part of the DID document ).

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 6.2 Resolver Architectures .

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 4. 3. DID Resolution ) and/or DID URL dereferencing function (see 5. 4. DID URL Dereferencing ) can be executed as follows:

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

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

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

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

   2. Set the Accept HTTP request header to application/did-resolution to request a complete 8. 7. DID Resolution Result , 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 .
      Example 26 11

      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 9. 8. DID URL Dereferencing Result , 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 .
      Example 27 12

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

      Example 28 13

      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 .
      Example 29 14

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

      Example 30 15

      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 8. 7. 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 3.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 .
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 9. 8. 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 4.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 .

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

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

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

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

HTTP 200 OK
Content-Type: application/did
{
	"@context": [ "https://www.w3.org/ns/did/v1.1" ],
	"id": "did:example:123",
	"verificationMethod": [{
		...
	}],
	"service": [{
		...
	}]
}

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

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.

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, UUID s, content hashes, etc..

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

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.

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.

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.