Decentralized Identifier Resolution (DID Resolution) v1

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, NOT REQUIRED, OPTIONAL, RECOMMENDED, REQUIRED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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

A conforming network-based DID resolver is a conforming DID resolver that additionally complies with the normative statements in 9.1 HTTP(S) Binding.

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

All datetime values in this specification MUST be an ASCII string which is a valid XML datetime value defined by the [VC-DATA-MODEL] in Verifiable Credentials Data Model v2.0. Additionally, timestamps used in DID Resolution MUST be adjusted to UTC without sub-second decimal precision. For example: 2020-12-20T19:17:47Z

DID URL query strings are routinely constructed, parsed, logged, cached, and compared by multiple independent components across a resolution pipeline — for example, a client, a caching proxy, a downstream resolver, and a DID method-specific resolver. Inconsistent normalization of DID URL query strings across these components can silently produce incorrect resolution results, cache poisoning, or broken interoperability. This section enumerates edge cases that implementers and DID method specification authors are encouraged to address explicitly.

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 value MUST be expressed according to the Accept header value as defined in HTTP Semantics, Section 12.5.1. The DID resolver implementation SHOULD use this value to determine the representation of the returned didDocument if such a representation is supported and available. This property is OPTIONAL.

expandRelativeUrls

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

versionId

See 3. DID Parameters for the definition.

versionTime

See 3. DID Parameters for the definition.

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 8. Errors).
• Proofs generated by the DID resolver, e.g., to establish trusted resolution (proof).
• Duration of the DID resolution process.
• Caching information (see Section 10.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 is defined in [RFC9457]. The errors defined by this specification can be found in Section 8. Errors. Additional errors SHOULD be registered in the DID Resolution Extensions [DID-EXTENSIONS-RESOLUTION], together with the URL that their defining specification gives them (see Section 8. Errors).

proof

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

DID resolution metadata MAY include a proof property. If present, the value MUST be a set where each item is a map that represents 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. DID document metadata attested to by the DID controller comes with no inherent guarantee of accuracy. Clients are advised to proceed with caution when relying on DID document metadata to inform business logic.

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 resolution (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 represented in the datetime format as defined in 3.1 Datetime.

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 be represented in the datetime format as defined in 3.1 Datetime. 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 be represented in the datetime format as defined in 3.1 Datetime.

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.

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

A DID resolver implements the following DID resolution algorithm.

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 https://www.w3.org/ns/did#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 https://www.w3.org/ns/did#METHOD_NOT_SUPPORTED
   2. didDocument: null
   3. didDocumentMetadata: «[ ]»
3. Determine whether the input DID resolution options are 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 https://www.w3.org/ns/did#FEATURE_NOT_SUPPORTED
   2. didDocument: null
   3. didDocumentMetadata: «[ ]»
4. Determine whether the input DID resolution options are valid. If not, the DID resolver MUST return the following result:
   1. didResolutionMetadata: error object with type set to https://www.w3.org/ns/did#INVALID_OPTIONS
   2. didDocument: null
   3. didDocumentMetadata: «[ ]»
5. Obtain the DID document for the input DID by executing the Resolve operation, as defined by the input DID method:
   1. If the input DID does not exist, return the following result:
      1. didResolutionMetadata: error object with type set to https://www.w3.org/ns/did#NOT_FOUND
      2. didDocument: null
      3. didDocumentMetadata: «[ ]»
   2. If the input DID has been deactivated, return the following result:
      1. didResolutionMetadata: «[ ... ]»
      2. didDocument: null
      3. didDocumentMetadata: «[ "deactivated" → true, ... ]»
   3. Otherwise, the result of the Resolve operation is called the output DID document. This result MUST be represented in a conformant representation.
6. If the input DID resolution options contain the expandRelativeUrls option with a value of true:
   1. Iterate over all services, verification methods, verification relationships and any extension-defined properties in the output DID document.
   2. For each item, if the item is an object and the value of the id property 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.
7. Return the following result:
   1. didResolutionMetadata: «[ "contentType" → output DID document media type, ... ]»
   2. didDocument: output DID document
   3. didDocumentMetadata: «[ ... ]»

If the DID resolver encounters any unexpected errors during the execution of the DID Resolution algorithm, it MUST return the following result:

1. didResolutionMetadata: error object with type set to https://www.w3.org/ns/did#INTERNAL_ERROR
2. didDocument: null
3. didDocumentMetadata: «[ ]»

1. Prepare for Resolution
2. Resolve the DID
3. Determine Handling Strategy
4. Invoke the Handler
5. Use the Handler Result

5.1.3 Determine Handling Strategy

After successfully resolving the DID document and accompanying metadata, the next step is to determine the appropriate strategy for handling the DID URL. This involves analyzing the contents of the DID resolution result, including the DID document and its metadata, along with the path and query components of the DID URL, to determine the method for retrieving the resource.

Using the result from resolution, execute the following steps starting with the Services Step until a handling strategy is determined. End processing as soon as a strategy is set.

1. Services Step

   If service is present as a DID query Parameter, first check whether multiple service parameters are present in the DID URL. If there are, raise an error DEREFERENCING_ERROR_MULTIPLE_SERVICE_PARAMETERS and continue to the Default DID Document step. If there is just one service parameter, use the service selection algorithm to select the appropriate service object. Then, if there is no matching service object, raise an error DEREFERENCING_ERROR_SERVICE_NOT_FOUND and continue to the Default DID Document Step. If the selected object's service type has defined a handling strategy, set the strategy to that. If the service type does not define a handling strategy, set strategy to the Default Service Handler Strategy. Otherwise, continue with the PathHandlers Step.

2. PathHandlers Step

   If the DID URL contains a non-empty path part, then use the PathHandler Path Matching Algorithm to select a path handler object. If no path handler objects are selected, continue to the Document Properties step. If there are multiple handler objects selected, raise an error DEREFERENCING_ERROR_MULTIPLE_MATCHING_PATH_HANDLERS and continue to the Default DID Document Step. If the sole selected path handling object has a secondary type that defines a handler strategy, set the strategy to that strategy. If it doesn't, raise an error DEREFERENCING_ERROR_PATH_HANDLER_HANDLER_NOT_DEFINED and continue to the Default DID Document Step.

3. Document Properties Step

   If the DID document contains any properties known to define a handler strategy, check whether any of those properties apply to the DID URL. If not, continue with the Method-Specific Step. If the DID document contains multiple properties that apply to the DID URL, raise an error DEREFERENCING_ERROR_MULTIPLE_DOCUMENT_PROPERTIES and continue to the Default DID Document Step. If the DID document contains a single property with a known handler strategy that applies to the DID URL, set the strategy to the strategy defined by that property. Otherwise, continue to the Method-Specific Step.

4. Method-Specific Step

   If the DID method defines a method-specific handler strategy, check whether that handler applies to the DID URL. If it does, set the handler strategy to that specified by the DID method. If there is no applicable method-specific handler strategy, continue with the Query Parameters Step.

5. Query Parameters Step

   If there are query parameters that require a specific handling strategy, check to see if there are more than one. If there are, then raise an error DEREFERENCING_ERROR_MULTIPLE_QUERY_PARAMETERS and continue to the Default DID Document Step. If there is only one such query parameter, set the strategy to that defined by the query parameter specification. Otherwise, continue with the Metadata Step.

   Not all query parameters will change the handling strategy. For example, versionTime and versionId only change the resolution result, but do not impact the dereferencing step.

6. Metadata Step

   If either the DID resolution metadata or DID document metadata contain any properties known to define a handler strategy, check to see if any of those properties apply to the DID URL. If there is only one such property, set the strategy to the strategy defined by that property. If there are multiple applicable properties, raise an error DEREFERENCING_ERROR_MULTIPLE_METADATA_PROPERTIES and continue to the Default DID Document Step. Otherwise, continue to Default DID Document Step.

7. Default DID Document Step If no other handler strategy has been determined, set the strategy to Return DID Document.

When a DID URL contains a service parameter use the following algorithm to determine which service should be used for dereferencing the DID URL.

did:example:1234?service=%23files

1. Select the service from the DID document whose id property matches the value of the service DID query parameter. If either the id property or the service DID parameter or both contain relative references, the corresponding absolute URIs MUST be computed and used for determining the match, using the rules specified in RFC3986 Section 5: Reference Resolution and in section Relative DID URLs in Decentralized Identifiers (DIDs) v1.0.
2. If no service matches, stop further processing and raise an error DEREFERENCING_ERROR_SERVICE_NOT_FOUND; no service is selected.
3. If more than one service matches, stop further processing and raise an error DEREFERENCING_ERROR_MULTIPLE_MATCHING_SERVICES; no service is selected.
4. If a single service matches, that service is selected. Continue with the Services Step.

If a selected service lacks a type with a specific handler, or if the service's only type value is PathHandler, use this default handler strategy. When invoked, execute the following algorithm.

Consider the following DID URL and DID Document section:

    did:example:abc/image.png?service=#FileServer
  
service : [{
  "id":"#FileServer",
  "path":"/",
  "serviceEndpoint": [
    "https://example.com/didimages/",
    "https://example.com/otherImages/",
    "https://example.com/lastImages/"]
...
}]

1. Select Service Endpoint If serviceEndpoint is a single value, use it. If serviceEndpoint is instead an array, randomly pick one of the service's serviceEndpoint values as a starting point. Since each value in the array is expected to resolve to the same set of resources (and any given DID URL triggering that service will retrieve the same resource from any of the endpoints), successfully dereferencing any one of them is sufficient. Implementations MUST keep track of each endpoint as it is attempted, so that each is exercised until either a successful result is returned or the complete set of endpoints has been attempted. In other words raise a failure error DEREFERENCING_ERROR_NO_SERVICE_ENDPOINTS_SUCCEED only after all of the endpoints fail.

   serviceEndpoint = "https://example.com/didimages/"

2. Determine Resource Path Construct the resource path by extracting the non-matching part of the DID URL and appending it to the path of the serviceEndpoint. First extract the non-matching part of the DID URL path as the pathExtension. The pathExtension in the above example is "image.png", after stripping the service's path value of "/" from the path part of the DID URL /image.png.

   pathExtension = "image.png";

   Append the pathExtension to the path part of the serviceEndpoint to define the resourcePath.

   resourcePath = /didimages/image.png

3. Normalize Path Normalize the resulting ResourcePath to create a NormalizedResourcePath by removing dot segments, as defined in [RFC3986] Section 5.2.4 Remove Path Segments. Then test the resulting NormalizedResourcePath to see if the leftmost characters of the NormalizedResourcePath match the leftmost characters of the path part of the serviceEndpoint. If they do not match, raise an error DEREFERENCE_ERROR_PATH_NORMALIZATION_ERROR.
4. Construct Resource URLs Replace the path part in the selected serviceEndpoint with the Normalized Resource Path, leaving all other elements of the service endpoint URLs the same.

   ResourceUrl = https://example.com/didimages/image.png

5. Dereference Resource URL Dereference the resulting ResourceUrl according to its scheme. For example, for an https URL, perform a GET operation on that URL.

When a DID Document contains a path and one or more objects with a type of PathHandler use the following algorithm to determine which object and handler should be used for dereferencing the DID URL.

1. Of those objects with a type PathHandler, select the object whose path property has the longest complete match from the beginning of the path part of the DID URL. The entire value of the path property must be present in the path part of the DID URL.
   Given the DID URL did:example:1234/image.png and the following three PathHandling objects
   Example 5

   service : [{
     "id":"#PathServiceRoot",
     "type":["PathHandler", "PathService"],
     "path":"/"
     ...
   },{
     "id":"#PathServiceImage",
     "type":["PathHandler", "PathService"],
     "path":"/image"
     ...
   }],
   linkedResource : [{
     "id":"#SecuredImage",
     "type":["PathHandler", "LinkedResource"],
     "path":"/image.png"
     ...
   }]

   In this scenario, the linkedResource with id SecuredImage would be selected and it's handling strategy would be defined by the LinkedResource specification.

2. If two or more objects have the same length match, stop processing and return an error DEREFERENCING_ERROR_MULTIPLE_MATCHING_PATH_HANDLERS.

When invoking this handler, simply return the DID Document retrieved from Resolve, including any dereferencing errors that may have been raised.

Dereferencing may produce several distinct errors, described below. Clients SHOULD use these errors when appropriate.

DEREFERENCING_ERROR_FAILED

A generic or unclassified internal error occurred, causing the overall dereferencing process to fail. (Use the Handler Result)

DEREFERENCING_ERROR_HANDLER_NOT_FOUND

No handler is available for the indicated handling strategy. (Invoke the Handler)

DEREFERENCING_ERROR_MULTIPLE_DOCUMENT_PROPERTIES

The dereferencing process encountered multiple conflicting document properties when attempting to dereference the DID URL. (Document Properties Step)

DEREFERENCING_ERROR_MULTIPLE_MATCHING_PATH_HANDLERS

The dereferencing process found multiple distinct path handlers that match the requested path. (PathHandlers Step)

DEREFERENCING_ERROR_MULTIPLE_METADATA_PROPERTIES

Resolution Metadata contains multiple conflicting properties, preventing a definitive selection for dereferencing. (Metadata Step)

DEREFERENCING_ERROR_MULTIPLE_QUERY_PARAMETERS

The DID URL contains multiple, incompatible query parameters. (Query Parameters Step)

DEREFERENCING_ERROR_MULTIPLE_SERVICE_PARAMETERS

The DID URL contains multiple service parameters. (Sevices Parameter Step)

DEREFERENCING_ERROR_MULTIPLE_MATCHING_SERVICES

The dereferencing process identified multiple matching service endpoints based on the URL parameters, preventing an unambiguous selection. (Services Step, Service Selection Algorithm)

DEREFERENCING_ERROR_NO_SERVICE_ENDPOINTS_SUCCEED

Valid service endpoints were identified and network interactions were attempted, but none of the requests returned a successful response. (Default Service Handler)

DEREFERENCE_ERROR_PATH_NORMALIZATION_ERROR

The DID URL contains a path that normalizes to a URL outside the perview of the selected service endpoint. The DID URL path overwrote the path part of the service endpoint. (Default Service Handling Algorithm)

DEREFERENCING_ERROR_PATH_HANDLER_HANDLER_NOT_DEFINED

The DID URL contains a path and the DID Document contains a matching PathHandler object, but no appropriate handler is defined or registered within the dereferencing environment to process it. (PathHandlers Step)

DEREFERENCING_ERROR_RESOLUTION_ERROR

The dereferencing process failed because the underlying identifier resolution process encountered an error before dereferencing could be completed. (Resolve the DID)

DEREFERENCING_ERROR_SERVICE_NOT_FOUND

The specific service referenced during the dereferencing process (e.g., via a service query parameter) was not found in the resolved document. (Services Step)

This section defines a DID resolver binding which exposes the DID resolution function (including all resolution options and metadata) via an HTTP(S) endpoint.

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.

All conforming DID resolvers MUST implement the GET version of the HTTPS binding and MAY implement the POST version. All HTTPS bindings MUST use TLS. Use of DNS names in certificates is NOT REQUIRED; resolvers MAY use TLS certificates issued for IP addresses.

Using this binding, the DID resolution function (see 4. DID Resolution) can be executed as follows:

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

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

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

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

   2. Set the Accept HTTP request header to application/did-resolution to request a complete 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 HTTP(S) GET binding:
   1. If any other resolution 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 function at the remote DID resolver.
      Example 15

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

4. For the HTTP(S) POST binding:
   1. If any other resolution 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 function at the remote DID resolver.
      Example 16

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

5. If the DID resolution function returns an error metadata property in the didResolutionMetadata, then the HTTP response status code MUST correspond to the type property of the error object, according to the following table:

   error type URI	HTTP status code
   https://www.w3.org/ns/did#INVALID_DID	400
   https://www.w3.org/ns/did#INVALID_DID_URL	400
   https://www.w3.org/ns/did#INVALID_OPTIONS	400
   https://www.w3.org/ns/did#NOT_FOUND	404
   https://www.w3.org/ns/did#REPRESENTATION_NOT_SUPPORTED	406
   https://www.w3.org/ns/did#INVALID_DID_DOCUMENT	500
   https://www.w3.org/ns/did#METHOD_NOT_SUPPORTED	501
   https://www.w3.org/ns/did#FEATURE_NOT_SUPPORTED	501
   https://www.w3.org/ns/did#INTERNAL_ERROR	500

   If the type property of the error object does not appear in the table above, then the HTTP response status code is determined by the implementation.

6. If the DID resolution function returns a deactivated metadata property with the value true in the didDocumentMetadata:
   1. The HTTP response status code MUST be 410, even if a step below requires a different status code.
7. For the DID resolution function:
   1. If the value of the Content-Type HTTP response header is application/did-resolution:
      1. If the function is successful, the HTTP response status code MUST be 200.
      2. The HTTP body MUST contain a DID resolution result (see 7. DID Resolution Result) that is the result of the DID resolution function.
   2. Otherwise, if the function is successful and returns a didDocument:
      1. The HTTP response status code MUST be 200.
      2. The HTTP response MUST contain a Content-Type HTTP response header. Its value MUST be the value of the contentType metadata property in the didResolutionMetadata (see 4.2 DID Resolution Metadata).
      3. The HTTP response body MUST contain the didDocument that is the result of the DID resolution function, in the representation corresponding to the Content-Type HTTP response header.

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, 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 URL dereferencer client dereferences identifiers and linked resources in a DID document — especially fields like verificationMethod, controller, or alsoKnownAs — it might encounter a dereferencing 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 URL dereferencer can also encounter such a situation when dereferencing a DID URL that references a DID service endpoint.

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

DID URL dereferencers 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 to decrease the possibilities of correlation and profiling. Techniques for obfuscation include Oblivious HTTP, using a trusted proxy to execute the resolution requests, and using a trusted cache.

Different DID methods have different additional privacy implications and considerations depending on the design decisions and underlying VDR of the method. Implementers are advised to review the privacy considerations of the specific DID methods they intend to support. Designers of DID methods are encouraged to follow the W3C Threat Modeling Guide to produce a threat model, to help implementers understand the privacy implications of the method design.