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 , 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 in 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 10.1 12.3.1 HTTP(S) Binding .

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

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 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 9. 12.2 Errors ).
• Proofs generated by the DID resolver , e.g., to establish trusted resolution ( proof ).
• Duration of the DID resolution process.
• Caching information (see Section 11.2 12.4.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 9. 12.2 Errors . Additional errors SHOULD be registered in the DID Resolution Extensions [ DID-EXTENSIONS-RESOLUTION ].

proof

Some DID resolvers and DID URL dereferencers clients use proofs when executing the DID Resolution or DID URL Dereferencing functions. See 7.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 derived from 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 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 7.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 URL conforms to the did did-url rule of the DID URL 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 URL 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 authoritative DID document for the input DID URL by executing the Resolve operation, as defined by the input DID method :
   1. If the input DID does not exist, exist in the Verifiable Data Registry , 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 URL 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 : Iterate over all services , verification methods , verification relationships and any extension-defined properties in the output DID document . 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 : 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 . Update the output DID document by replacing the relative DID URLs with the resolved absolute DID URLs . Return the following result:
   1. didResolutionMetadata : «[ ... ]»
   2. didDocument : output DID document
   3. didDocumentMetadata : «[ "contentType" → output DID document media type , ... ]»

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. ]. This specification defines the following common input options: accept The media type Validate that the caller prefers for contentStream . The value MUST be expressed according to the Accept header value as defined in HTTP Semantics , Section 12.5.1 . The input DID URL dereferencer implementation SHOULD use this value conforms to determine the contentType did-url rule 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 Syntax . If not, 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 Client MUST be raised. 5.2 DID URL Dereferencing Metadata return without further processing, indicating a failure due to an https://www.w3.org/ns/did#INVALID_DID_URL This is
2. Select a metadata structure resolver 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 capable of handling the DID URL dereferencer . The possible properties within this structure and their possible values SHOULD DID's method. This could be registered in the DID Resolution Extensions a [ DID-EXTENSIONS-RESOLUTION remote resolver ]. 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 ], which would use HTTPS for communications, or a [ RFC9457 local resolver ]. This property is REQUIRED when there is an error in the dereferencing process. The errors defined in this specification can ], which does not (likely a local resolver will be found in Section 9. Errors . Additional errors invoked using standard linked library or interprocess communication). Implementers SHOULD MUST be registered in enable users to choose the DID Resolution Extensions [ DID-EXTENSIONS-RESOLUTION ]. proof Some DID resolvers and they trust for specific DID URL dereferencers use proofs when executing methods.
3. Remove any fragment part of the DID Resolution or DID URL Dereferencing functions. See 7.2 Resolver Architectures for details. to create a base DID URL dereferencing metadata MAY include a , e.g., proof did:ex:abc#key-1 property. If present, the value MUST be a set where each item is a map becomes did:ex:abc .
4. Prepare resolution options that represents a proof. The use of this property and . See the types of proofs are DID method resolve -independent. algorithm for options.

1. Call the resolve that contains metadata about function on the selected resolver, passing the prepared resolution options and the Base DID URL Dereferencing URL, to obtain the authoritative DID document process. This metadata typically does not change between invocations of for the input DID URL Dereferencing function unless .
2. Interpret the content changes, response to resolve to consider any errors or warnings. If appropriate, return without further processing and return an error. Otherwise, continue processing if the response provided enough information to do so.
3. Repeat as it represents data about necessary until the content. The sources of this metadata are final resolution result is returned. A resolver may require more input, or in some cases, the client can heuristically attempt alternate resolver options to find a more appropriate DID controller and/or document, such as requesting a version of the DID method . The possible properties within this structure and their possible values SHOULD be registered document from a particular point in the DID Resolution Extensions [ DID-EXTENSIONS-RESOLUTION ]. This specification defines no common properties. time.

1. RFC3986 Service If service parameter ], it consists of is present as a DID Parameter, use the following three steps: resolving service selection algorithm to select the DID; dereferencing appropriate service object for retrieval. The retrieval strategy is determined by the resource; and dereferencing type property of the fragment (only if selected service. If multiple service parameters are present in the input DID URL URL, stop further processing and return an error.

   contains a DID fragment ):

   5.4.1 Dereferencing the Resource
2. Validate that the input Service Type If serviceType parameter is present as a DID URL Parameter, use the service-type selection algorithm conforms to select the did-url rule appropriate service object for retrieval. The retrieval strategy is determined by the type property of the DID URL Syntax . selected service.
3. Property If not, the DID URL dereferencer document contains any properties known to affect dereferencing, the retrieval strategy is determined by that property. For example, linkedResource property uses its own retrieval strategy as described at Linked Resource MUST return in the following result: dereferencingMetadata : error object with type set to [ https://www.w3.org/ns/did#INVALID_DID_URL DID-EXTENSIONS-PROPERTIES contentStream : null contentMetadata : «[ ]» ] specification. If the did document contains multiple properties that affect dereferencing, stop further processing and return an error.
4. Obtain Document Metadata If the DID document for metadata contains any properties known to affect dereferencing, the input DID retrieval strategy is determined by executing the DID resolution algorithm that property. For example, linkedResourceMetadata property uses its own retrieval strategy as defined described in 4. DID Resolution . All dereferencing options and all DID parameters of the input DID URL Linked Resource MUST be passed as resolution options to specification. If the DID Resolution algorithm. did document metadata contains multiple properties that affect dereferencing, stop further processing and return an error.

5. Method Specific If the input DID does not exist in method defines a method-specific dereferencing strategy, use the VDR, retrieval strategy specified by the DID URL dereferencer MUST return the following result: method.
6. dereferencingMetadata : error object with type If no other strategy has been determined, set the retrieval strategy to https://www.w3.org/ns/did#NOT_FOUND Return DID Document and use the Return DID Document Dereferencing Algorithm

1. Otherwise, Execute the didDocument result of determined retrieval strategy using the DID resolution associated retrieval algorithm is called to get the resolved DID document . If present, separate resource referred to by the DID fragment from URL.

   In the input simplest case, retrieval is a simple HTTPS GET on a Retrieval URL. However, some DID URL methods or properties may provide a means for retrieving a resource from on-chain data rather than from a web service.

1. Use the final resource. This may mean displaying the resource based on it media type; it may also include scrolling a view of that resource to display an element indicated by a fragment. It may also mean returning the entire DID document or a subset of it to a calling process. The DID URL dereferencer MUST return client knows which of these options is appropriate based on the context in which the resolved DID document URL is being dereferenced.

If the value of the serviceEndpoint property of the selected service input DID URL is a string , add this value to a list of selected contains the DID service endpoint parameter URLs . If the value of the serviceEndpoint relativeRef property and a service of the type "PathService" is selected from either the service selection algorithm is a set or the service-type selection algorithm , add all its items that are strings set the retrieval strategy to a list of selected DID service endpoint URLs . RelativeRef and use the following retrieval algorithm.

1. For each the selected DID service endpoint URL , execute the algorithm specified in RFC3986 Section 5: Reference 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. Update Pass the selected DID service endpoint result of Relative Resolution to Component Recomposition and set the [ retrieval URL ] to the result of the "Reference Resolution" algorithm. latter.
   Note

   Resolving a DID service endpoint — particularly —particularly one that is itself a DID — might 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 .

The DID resolution algorithm involves executing the Resolve operation on a DID according to its DID method (see 4. 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 7.2 11.2 Resolver Architectures .

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

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

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

7.2.1 11.2.1 Multiple Methods

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

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

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

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

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

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

INVALID_DID

An invalid DID was detected during DID Resolution . See Section 4.4 DID Resolution Algorithm .

https://www.w3.org/ns/did#INVALID_DID

INVALID_DID_DOCUMENT

The DID document was malformed. See Section 4.4 DID Resolution Algorithm .

https://www.w3.org/ns/did#INVALID_DID_DOCUMENT

NOT_FOUND

The DID resolver was unable to find the DID document resulting from this resolution request. See Section 4.4 DID Resolution Algorithm .

https://www.w3.org/ns/did#NOT_FOUND

REPRESENTATION_NOT_SUPPORTED

The representation requested via the accept input metadata property is not supported by the DID method and/or DID resolver implementation. See Section 4.4 DID Resolution Algorithm .

https://www.w3.org/ns/did#REPRESENTATION_NOT_SUPPORTED

INVALID_DID_URL

An invalid DID URL was detected during DID URL dereferencing . See Section 5.4 6. DID URL Dereferencing Algorithm

https://www.w3.org/ns/did#INVALID_DID_URL

METHOD_NOT_SUPPORTED

The DID method of the DID is not supported by the DID resolver . See Section 4.4 DID Resolution Algorithm .

https://www.w3.org/ns/did#METHOD_NOT_SUPPORTED

INVALID_OPTIONS

One or more of the options provided for DID Resolution or DID URL dereferencing are invalid.

https://www.w3.org/ns/did#INVALID_OPTIONS

INTERNAL_ERROR

An unexpected error occured during DID Resolution or DID URL dereferencing .

https://www.w3.org/ns/did#INTERNAL_ERROR

FEATURE_NOT_SUPPORTED

The DID resolver does not support the requested feature. The value of the detail field SHOULD provide a longer description of the feature that is not supported by the resolver.

https://www.w3.org/ns/did#FEATURE_NOT_SUPPORTED

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

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

This section contains a variety of security considerations that people using DID Resolution in production settings are advised to consider. Readers are urged to familiarize themselves with the general security advice provided in the Security Considerations section of the Decentralized Identifiers specification before reading this section.

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

This section details the privacy considerations specific to DID Resolution. Readers are urged to familiarize themselves with the general privacy advice provided in the Privacy Considerations section of the Decentralized Identifiers specification before reading this section.