Decentralized Identifier Resolution (DID Resolution) v0.3

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

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, 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 DID URL dereferencer is any algorithm realized as software and/or hardware that complies with the relevant normative statements in 5. DID URL Dereferencing.

The possible properties within this structure and their possible values are registered in the DID Specification Registries [DID-SPEC-REGISTRIES]. This specification defines the following common properties.

accept

The Media Type of the caller's preferred representation of the DID document. The Media Type MUST be expressed as an ASCII string. The DID resolver implementation SHOULD use this value to determine the representation of the returned didDocument if such a representation is supported and available. This property is OPTIONAL.

expandRelativeUrls

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

versionId

See 3. DID Parameters for the definition.

versionTime

See 3. DID Parameters for the definition.

The possible properties within this structure and their possible values are registered in the DID Specification Registries [DID-SPEC-REGISTRIES]. This specification defines the following DID resolution metadata properties:

contentType

The Media Type of the returned didDocument. This property is OPTIONAL. If present, the value of this property MUST be an ASCII string that is the Media Type of the conformant representations. In this case, the caller of the resolve function MUST use this value when determining how to parse and process the didDocument.

error

An error data structure defined in [RFC9457]. This property is REQUIRED when there is an error in the resolution process. The errors defined by this specification and can be found in Section 10. Errors. Additional errors SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].

The possible properties within this structure and their possible values SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES]. This specification defines the following common properties.

created

DID document metadata SHOULD include a created property to indicate the timestamp of the Create operation. The value of the property MUST be a string formatted as an XML Datetime normalized to UTC 00:00:00 and without sub-second decimal precision. For example: 2020-12-20T19:17:47Z.

updated

DID document metadata SHOULD include an updated property to indicate the timestamp of the last Update operation for the document version which was resolved. The value of the property MUST follow the same formatting rules as the created property. The updated property is omitted if an Update operation has never been performed on the DID document. If an updated property exists, it can be the same value as the created property when the difference between the two timestamps is less than one second.

deactivated

If a DID has been deactivated, DID document metadata MUST include this property with the boolean value true. If a DID has not been deactivated, this property is OPTIONAL, but if included, MUST have the boolean value false.

nextUpdate

DID document metadata MAY include a nextUpdate property if the resolved document version is not the latest version of the document. It indicates the timestamp of the next Update operation. The value of the property MUST follow the same formatting rules as the created property.

versionId

DID document metadata SHOULD include a versionId property to indicate the version of the last Update operation for the document version which was resolved. The value of the property MUST be an ASCII string.

nextVersionId

DID document metadata MAY include a nextVersionId property if the resolved document version is not the latest version of the document. It indicates the version of the next Update operation. The value of the property MUST be an ASCII string.

equivalentId

A DID method can define different forms of a DID that are logically equivalent. An example is when a DID takes one form prior to registration in a verifiable data registry and another form after such registration. In this case, the DID method specification might need to express one or more DIDs that are logically equivalent to the resolved DID as a property of the DID document. This is the purpose of the equivalentId property.

DID document metadata MAY include an equivalentId property. If present, the value MUST be a set where each item is a string that conforms to the rules in Section Decentralized Identifiers (DIDs) v1.0. The relationship is a statement that each equivalentId value is logically equivalent to the id property value and thus refers to the same DID subject. Each equivalentId DID value MUST be produced by, and a form of, the same DID method as the id property value. (e.g., did:example:abc == did:example:ABC)

A conforming DID method specification MUST guarantee that each equivalentId value is logically equivalent to the id property value.

A requesting party is expected to retain the values from the id and equivalentId properties to ensure any subsequent interactions with any of the values they contain are correctly handled as logically equivalent (e.g., retain all variants in a database so an interaction with any one maps to the same underlying account).

Note: Stronger equivalence

equivalentId is a much stronger form of equivalence than alsoKnownAs because the equivalence MUST be guaranteed by the governing DID method. The use of equivalentId means that the same DID document describes both the equivalentId DID and the id property DID.

If a requesting party does not retain the values from the id and equivalentId properties and ensure any subsequent interactions with any of the values they contain are correctly handled as logically equivalent, there might be negative or unexpected issues that arise. Implementers are strongly advised to observe the directives related to this metadata property.

canonicalId

The canonicalId property is identical to the equivalentId property except: a) it is associated with a single value rather than a set, and b) the DID is defined to be the canonical ID for the DID subject within the scope of the containing DID document.

DID document metadata MAY include a canonicalId property. If present, the value MUST be a string that conforms to the rules in Section Decentralized Identifiers (DIDs) v1.0. The relationship is a statement that the canonicalId value is logically equivalent to the id property value and that the canonicalId value is defined by the DID method to be the canonical ID for the DID subject in the scope of the containing DID document. A canonicalId value MUST be produced by, and a form of, the same DID method as the id property value. (e.g., did:example:abc == did:example:ABC).

A conforming DID method specification MUST guarantee that the canonicalId value is logically equivalent to the id property value.

A requesting party is expected to use the canonicalId value as its primary ID value for the DID subject and treat all other equivalent values as secondary aliases (e.g., update corresponding primary references in their systems to reflect the new canonical ID directive).

Note: Canonical equivalence

canonicalId is the same statement of equivalence as equivalentId except it is constrained to a single value that is defined to be canonical for the DID subject in the scope of the DID document. Like equivalentId, the use of canonicalId means that the same DID document describes both the canonicalId DID and the id property DID.

If a resolving party does not use the canonicalId value as its primary ID value for the DID subject and treat all other equivalent values as secondary aliases, there might be negative or unexpected issues that arise related to user experience. Implementers are strongly advised to observe the directives related to this metadata property.

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

1. Validate that the input DID conforms to the did rule of the DID Syntax. If not, the DID resolver MUST return the following result:
   1. didResolutionMetadata: error object with type set to INVALID_DID
   2. didDocument: null
   3. didDocumentMetadata: «[ ]»
2. Determine whether the DID method of the input DID is supported by the DID resolver that implements this algorithm. If not, the DID resolver MUST return the following result:
   1. didResolutionMetadata: error object with type set to METHOD_NOT_SUPPORTED
   2. didDocument: null
   3. didDocumentMetadata: «[ ]»
3. Obtain the DID document for the input DID by executing the Read operation against the input DID's verifiable data registry, as defined by the input DID method:
   1. Besides the input DID, all additional resolution options of this algorithm MUST be passed to the Read operation of the input DID method.
   2. If the input DID does not exist, return the following result:
      1. didResolutionMetadata: error object with type set to NOT_FOUND
      2. didDocument: null
      3. didDocumentMetadata: «[ ]»
   3. If the input DID has been deactivated, return the following result:
      1. didResolutionMetadata: «[ ... ]»
      2. didDocument: null
      3. didDocumentMetadata: «[ "deactivated" → true, ... ]»
   4. Otherwise, the result of the Read operation is called the output DID document. This result MUST be represented in a conformant representation that corresponds to the accept input DID resolution option.
4. If the input DID resolution options contain the expandRelativeUrls option with a value of true:
   1. Iterate over all services, verification methods, and verification relationships in the output DID document.
   2. If the value of the id property of a service or verification method (including those embedded in verification relationships) is a relative DID URL, or if a verification relationship is a relative DID URL:
      1. Resolve the relative DID URL to an absolute DID URL conformant with DID URL Syntax, according to the rules of section Relative DID URLs in Decentralized Identifiers (DIDs) v1.0.
   3. Update the output DID document by replacing the relative DID URLs with the resolved absolute DID URLs.
5. Return the following result:
   1. didResolutionMetadata: «[ ... ]»
   2. didDocument: output DID document
   3. didDocumentMetadata: «[ "contentType" → output DID document media type, ... ]»

The possible properties within this structure and their possible values SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES]. This specification defines the following common properties for dereferencing options:

accept

The Media Type that the caller prefers for contentStream. The Media Type MUST be expressed as an ASCII string. The DID URL dereferencing implementation SHOULD use this value to determine the contentType of the representation contained in the returned value if such a representation is supported and available.

verificationRelationship

The verificationRelationship for which the caller expects the verificationMethod dereferenced from the DID URL to be authorized. If present, the associated value MUST be an ASCII string. If the DID URL does not dereference to a verificationMethod, or the DID document does not authorize the verificationMethod for the specified verificationRelationship, then an error MUST be raised.

The possible properties within this structure and their possible values are registered in the DID Specification Registries [DID-SPEC-REGISTRIES]. This specification defines the following common properties.

contentType

The Media Type of the returned contentStream SHOULD be expressed using this property if dereferencing is successful. The Media Type value MUST be expressed as an ASCII string.

error

An error data structure defined in [RFC9457]. This property is REQUIRED when there is an error in the dereferencing process. The errors defined in this specification can be found in Section 10. Errors. Additional errors SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].

The following DID URL dereferencing algorithm MUST be implemented by a conformant DID resolver. In accordance with [RFC3986], it consists of the following three steps: resolving the DID; dereferencing the resource; and dereferencing the fragment (only if the input DID URL contains a DID fragment):

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

Depending on the exact nature of the DID method's "Read" operation, the interaction between a DID resolver and the verifiable data registry may be implemented as a verifiable read or unverifiable read:

A verifiable read maximizes confidence in the integrity and correctness of the result of the "Read" operation ‐ to the extent possible under the applicable DID method. It can be implemented in a variety of ways, for example:

• A "Read" operation may be considered "Verifiable" if access to the verifiable data registry is possible via a local, trusted network host. In the case of blockchain-based DID methods, a blockchain full node may be run on a local network host in order to implement a verifiable read.
• The DID resolver may be remotely connected to the verifiable data registry but have some method to verify the contents of the response of the "Read" operation. In the case of blockchain-based DID methods, even if direct access to a blockchain full node is not available, a verifiable read may still be possible by running a light client that processes metadata to verify that the result of the "Read" operation hasn't been tampered with.
• A verifiable read may be implemented if access to the verifiable data registry happens via a remote network host that is considered trusted because it is run on a personal device in the home and accessed via a secure channel.

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

• A "Read" operation may be considered "Unverifiable" if access to the verifiable data registry happens via a remote, untrusted intermediary. In the case of blockchain-based DID methods, a remote blockchain explorer API operated by an third party may be used to look up data from the blockchain.

Whether or not a verifiable read is possible depends not only on a DID method itself, but also on the way how a DID resolver implements it. DID methods MAY define multiple different ways of implementing their "Read" operation(s) and SHOULD offer guidance on how to implement a verifiable read in at least one way.

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

7.2.1 Multiple Methods

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

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

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

Note

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

Given the DID URL did:xyz:1234#keys-1, a DID resolver could be invoked via local binding, which invokes another DID resolver via remote binding for Dereferencing the Resource (i.e., the DID document), and the client could complete the DID URL dereferencing algorithm by Dereferencing the Fragment (i.e., a part of the DID document).

A DID document associated with a DID. The result of 4. DID Resolution.

This is a metadata structure (see section Metadata Structure in [DID-CORE]) that contains metadata about the DID Resolution process.

This metadata typically changes between invocations of the DID Resolution functions 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 (the contentType metadata property).
• Error object (the error metadata property).
• Duration of the DID resolution process.
• Caching information about the DID document (see Section 12.2 Caching).
• Various URLs, IP addresses or other network information that was used during the DID resolution process.
• Proofs added by a DID resolver (e.g., to establish trusted resolution).

See also section DID Resolution Metadata in [DID-CORE].

This is a metadata structure (see section Metadata Structure in [DID-CORE]) that contains metadata about a DID Document.

This metadata typically does not change between invocations of the DID Resolution function unless the DID document changes, as it represents data about the DID document.

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

Examples of DID Document Metadata include:

• Timestamps when the DID and its associated DID document were created or updated (the created and updated metadata properties).
• Metadata about controllers, capabilities, delegations, etc.
• Versioning information about the DID document (see Section 12.4 Versioning).
• Proofs added by a DID controller (e.g., to establish control authority).

DID Document Metadata may also include method-specific metadata, e.g.:

• State proofs from the verifiable data registry.
• Block number, index, transaction hash, number of confirmations, etc. of a record in the blockchain or other verifiable data registry.

See also section DID Document Metadata in [DID-CORE].

Arbitrary content associated with a DID URL. The result of 5. DID URL Dereferencing.

This is a metadata structure (see section Metadata Structure in [DID-CORE]) that contains metadata about the DID URL Dereferencing process.

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

See also section DID URL Dereferencing Metadata in [DID-CORE].

This is a metadata structure (see section Metadata Structure in [DID-CORE]) that contains metadata about the content.

This metadata typically does not change between invocations of the DID URL Dereferencing function unless the content changes, as it represents data about the content.

This section defines a DID resolver binding which exposes the DID resolution and/or DID URL dereferencing functions (including all resolution/dereferencing options and metadata) via an HTTP(S) endpoint. See 7.2 Resolver Architectures.

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

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

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

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

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

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

   2. Set the Accept HTTP request header to application/did-resolution" in order to request a complete 8. DID Resolution Result, OR
   3. set the Accept HTTP request header to the value of the accept resolution option.
   4. If any other resolution options 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.
         Example 26

         https://resolver.example/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2

3. For the DID URL dereferencing function:
   1. Append the input DID URL to the request HTTP(S) URL.
      Example 27

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

   2. Set the Accept HTTP request header to application/did-url-dereferencing" in order to request a complete 9. DID URL Dereferencing Result, OR
   3. set the Accept HTTP request header to the value of the accept dereferencing option.
   4. If any other dereferencing options are provided:
      1. The input DID URL MUST be URL-encoded (as specified in RFC3986 Section 2.1).
      2. Encode all dereferencing options except accept as query parameters in the request HTTP(S) URL.
         Example 28

         https://resolver.example/1.0/identifiers/did%3Aexample%3A1234%3Fservice%3Dfiles%26relativeRef%3D%2Fresume.pdf?option1=value1&option2=value2

4. Execute an HTTP GET request on the request HTTP(S) URL. This invokes the DID resolution or DID URL dereferencing function at the remote DID resolver.
5. If the DID resolution or DID URL dereferencing function returns an error metadata property in the didResolutionMetadata or dereferencingMetadata, then the HTTP response status code MUST correspond to the value of the error metadata property, according to the following table:

   error	HTTP status code
   INVALID_DID	400
   INVALID_DID_URL	400
   INVALID_OPTIONS	400
   NOT_FOUND	404
   REPRESENTATION_NOT_SUPPORTED	406
   INVALID_DID_DOCUMENT	500
   METHOD_NOT_SUPPORTED	501
   INVALID_PUBLIC_KEY	500
   INVALID_PUBLIC_KEY_LENGTH	500
   INVALID_PUBLIC_KEY_TYPE	500
   UNSUPPORTED_PUBLIC_KEY_TYPE	501
   INTERNAL_ERROR	500
   (any other value)	500

6. If the DID resolution or DID URL dereferencing function returns a deactivated metadata property with the value true in the didDocumentMetadata or contentMetadata:
   1. The HTTP response status code MUST be 410.
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 8. DID Resolution Result) that is the result of the DID resolution function.
   2. If the function is successful and returns a didDocument:
      1. The HTTP response status code MUST be 200.
      2. The HTTP response MUST contain a Content-Type HTTP response header. Its value MUST be the value of the contentType metadata property in the didResolutionMetadata (see 4.2 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.
8. For the DID URL dereferencing function:
   1. If the value of the Content-Type HTTP response header is application/did-url-dereferencing":
      1. The HTTP body MUST contain a DID URL dereferencing result (see 9. DID URL Dereferencing Result) that is the result of the DID URL dereferencing function.
   2. If the function is successful and returns a contentStream and a contentType metadata property with the value text/uri-list in the dereferencingMetadata:
      1. The HTTP response status code MUST be 303.
      2. The HTTP response MUST contain an Location header. The value of this header MUST be the selected service endpoint URL.
      3. the HTTP response body MUST be empty.
   3. If the function is successful and returns a contentStream with any other contentType:
      1. The HTTP response status code MUST be 200.
      2. The HTTP response MUST contain a Content-Type HTTP response header. Its value MUST be the value of the contentType metadata property in the dereferencingMetadata (see 5.2 DID URL Dereferencing Metadata).
      3. The HTTP response body MUST contain the contentStream that is the result of the DID URL dereferencing function, in the representation corresponding to the Content-Type HTTP response header.

Given the following DID resolver HTTP(S) endpoint:

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

And given the following input DID:

did:example:123

Then the request HTTP(S) URL is:

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

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

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

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

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

DID resolution and DID URL dereferencing do not involve any authentication or authorization functionality. Similar to DNS resolution, anybody can perform the process, without requiring any credentials or non-public knowledge.

A DID resolver may maintain a generic cache of DID documents. It may also maintain caches specific to certain DID methods.

The noCache resolution option can be used to request a certain kind of caching behavior.

This resolution option is OPTIONAL.

Possible values of this property are:

• "false" (default value): Caching of DID documents is allowed.
• "true": Request that caching is disabled and a fresh DID document is retrieved from the verifiable data registry.

Caching behavior can be controlled by configuration of the DID resolver, by the noCache resolution option, or by contents of the DID document (e.g., a cacheMaxTtl field), or by a combination of these properties.

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.

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.