Decentralized Identifier Resolution (DID Resolution) v0.3

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

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

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

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

versionTime

See versionTime 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 12. Errors).
• Proofs generated by the DID resolver, e.g., to establish trusted resolution (proof).
• Duration of the DID resolution process.
• Caching information (see Section 15.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 12. 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 10.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 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 6.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 6.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 6.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 DID URL client 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 10.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 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: «[ ... ]»
   2. didDocument: output DID document
   3. didDocumentMetadata: «[ "contentType" → output DID document media type, ... ]»

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: «[ ]»

A DID URL Client implements the following DID URL dereferencing algorithm, consisting of the following five steps:

1. Prepare to resolve the DID URL
2. Resolve the DID URL
3. Determine Retrieval Strategy
4. Retrieve the Resource
5. Use the Resource

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=files&relativeRef=%2Fmyresume%2Fdoc%3Fversion%3Dlatest

1. Select the service if its id property matches the value of the service DID parameter. If the id property or the service DID parameter or both contain relative references, the corresponding absolute URIs MUST be resolved and used for determining the match, using the rules specified in RFC3986 Section 5: Reference Resolution and in section Relative DID URLs in Decentralized Identifiers (DIDs) v1.0.
2. If the input DID URL also contains the relativeRef parameter, evaluate the Relative Ref Dereferencing Algorithm as the retrieval stategy.

When a DID URL contains a serviceType parameter use the following algorithm to determine which service should beExpand commentComment on line R1370Resolved used for dereferencing the DID URL.

did:example:1234?serviceType=pathService&relativeRef=%2Fmyresume%2Fdoc%3Fversion%3Dlatest

1. If the input DID URL contains the DID parameter serviceType: Select the service if its type property matches the value of the serviceType DID parameter.
2. If the input DID URL also contains the relativeRef parameter, evaluate the Relative Ref Dereferencing Algorithm as the retrieval stategy.

If the input DID URL contains the DID parameter relativeRef and a service of type "PathService" is selected from either the service selection algorithm or the service-type selection algorithm, set the retrieval strategy to RelativeRef and use the following retrieval algorithm.

1. For the selected DID service endpoint URL, execute the algorithm specified in RFC3986 Section 5.2 Relative Resolution and 5.3 Component Recomposition to create a retrieval URL as follows:
   1. The base URI value is the selected DID service endpoint URL.
   2. The relative reference is the value of the DID parameter relativeRef.
   3. Pass the result of Relative Resolution to Component Recomposition and set the [retrieval URL] to the result of the latter.
   Note

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

When no other dereferencing strategy applies, simply return the DID Document as the final resource.

The DID resolution algorithm involves executing the Resolve operation on a DID according to its DID method (see 7. 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 "Resolve" operation.
• A DID method might define its "Resolve" 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 "Resolve" operation.
• A DID method might execute the "Resolve" 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 "Resolve" operation is simply a trivial, local transformation process.

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

A verifiable resolution maximizes confidence in the integrity and correctness of the result of the "Resolve" 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 resolution 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 resolution 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 resolution 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 resolution 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 resolution may still be possible by using a light client that processes metadata to verify the data.

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

• An unverifiable resolution 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 resolutions, many DID methods use digital signatures, state proofs, proofs of inclusion in Merkle trees, cryptographic event logs, or other types of proof. 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 "Resolve" 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 10.2 Resolver Architectures.

The algorithms for DID resolution is defined as a the abstract function resolving.

Those algorithms are implemented by DID resolvers, are are invoked by a DID URL 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 13.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 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 result of DID resolution.

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.

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 "Resolve" operation of the applicable DID method is itself correct. See also 10.1 Method Architectures.

10.2.1 Multiple Methods

A DID resolver might support the DID resolution algorithm for multiple DID methods:

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

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

10.2.3 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 DID service endpoint URL), and the client could complete the DID URL dereferencing algorithm by Dereferencing the Fragment (i.e., a DID 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).

This section defines a DID resolver binding which exposes the DID resolution function (including all resolution options and metadata) via an HTTP(S) endpoint. See 10.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.

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 7. DID Resolution) function can be executed as follows:

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

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

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

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

   2. Set the Accept HTTP request header to application/did-resolution to request a complete 11. 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 other than accept are provided:
      1. The input DID URL 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 function at the remote DID resolver.
      Example 20

      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 resolution options other 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 21

      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
   (any other error URI)	500

6. If the DID resolution function returns a deactivated metadata property with the value true in the didDocumentMetadata or contentMetadata:
   1. The HTTP response status code MUST be 410.
7. 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 11. 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 7.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": [{
    ...
  }]
}

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

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

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