Decentralized Identifier Resolution (DID Resolution) v0.3

DID resolution is the process of obtaining a DID document for a given DID . This is one of four required operations that can be performed on any DID ("Read"; the other ones being "Create", "Update", and "Deactivate"). The details of these operations differ depending on the DID method . Building on top of DID resolution , DID URL dereferencing is the process of retrieving a representation of a resource for a given DID URL . Software and/or hardware that is able to execute these processes is called a DID resolver .

This specification defines common requirements, algorithms including their inputs and results, architectural options, and various considerations for the DID resolution and DID URL dereferencing processes.

Note that while this specification defines some base-level functionality for DID resolution, the actual steps required to communicate with a DID's verifiable data registry are defined by the applicable DID method specification.

Note

The difference between "resolving" a DID and "dereferencing" a DID URL is being thoroughly discussed by the community. For example, see this comment .

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 .

This section is non-normative.

This specification has three primary audiences: implementers of conformant DID methods; implementers of conformant DID resolvers; and implementers of systems and services that wish to resolve DIDs using DID resolvers. The intended audience includes, but is not limited to, software architects, data modelers, application developers, service developers, testers, operators, and user experience (UX) specialists. Other people involved in a broad range of standards efforts related to decentralized identity, verifiable credentials, and secure storage might also be interested in reading this specification.

Error


Cannot
GET
/uploads/UerFaN/terms.html

/uploads/IRHo5a/terms.html

The DID URL syntax supports a simple format for parameters (see section Query in [ DID-CORE ]). Adding a DID parameter to a DID URL means that the parameter becomes part of the identifier for a resource .

Example 1 : A DID URL with a 'versionTime' DID parameter

did:example:123?versionTime=2021-05-10T17:00:00Z

Example 2 : A DID URL with a 'service' and a 'relativeRef' DID parameter

did:example:123?service=files&relativeRef=/resume.pdf

Some DID parameters are completely independent of any specific DID method and function the same way for all DIDs . Other DID parameters are not supported by all DID methods . Where optional parameters are supported, they are expected to operate uniformly across the DID methods that do support them. The following table provides common DID parameters that function the same way across all DID methods . Support for all DID Parameters is OPTIONAL .

Parameter Name	Description
`service`	Identifies a service from the DID document by service ID. If present, the associated value MUST be an ASCII string .
`relativeRef`	A relative URI reference according to RFC3986 Section 4.2 that identifies a resource at a service endpoint , which is selected from a DID document by using the `service` parameter. If present, the associated value MUST be an ASCII string and MUST use percent-encoding for certain characters as specified in RFC3986 Section 2.1 .
`versionId`	Identifies a specific version of a DID document to be resolved (the version ID could be sequential, or a UUID , or method-specific). If present, the associated value MUST be an ASCII string .
`versionTime`	Identifies a certain version timestamp of a DID document to be resolved. That is, the most recent version of the DID document that was valid for a DID before the specified `versionTime`. If present, the associated value MUST be an ASCII string which is a valid XML datetime value, as defined in section 3.3.7 of W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes [ XMLSCHEMA11-2 ]. This datetime value MUST be normalized to UTC 00:00:00 and without sub-second decimal precision. For example: `2020-12-20T19:17:47Z`.
`hl`	A resource hash of the DID document to add integrity protection, as specified in [ HASHLINK ]. This parameter is non-normative. If present, the associated value MUST be an ASCII string .

Implementers as well as DID method specification authors might use additional DID parameters that are not listed here. For maximum interoperability, it is RECOMMENDED that DID parameters use the DID Specification Registries mechanism [ DID-SPEC-REGISTRIES ], to avoid collision with other uses of the same DID parameter with different semantics.

DID parameters might be used if there is a clear use case where the parameter needs to be part of a URL that references a resource with more precision than using the DID alone. It is expected that DID parameters are not used if the same functionality can be expressed by passing input metadata to a DID resolver .

Note : DID parameters and DID resolution

The DID resolution and the DID URL dereferencing functions can be influenced by passing 4.1 DID Resolution Options or 5.1 DID URL Dereferencing Options to a DID resolver that are not part of the DID URL . This is comparable to HTTP, where certain parameters could either be included in an HTTP URL, or alternatively passed as HTTP headers during the dereferencing process. The important distinction is that DID parameters that are part of the DID URL should be used to specify what resource is being identified , whereas input metadata that is not part of the DID URL should be used to control how that resource is resolved or dereferenced .

The DID resolution ~~functions resolve~~ function resolves a DID into a DID document by using the "Read" operation of the applicable DID method as described in Method Operations . All conforming DID resolvers implement the ~~functions~~ function below, which ~~have~~ has the following abstract ~~forms:~~ form:

~~resolve(did, resolutionOptions) → « didResolutionMetadata, didDocument, didDocumentMetadata » resolveRepresentation(did, resolutionOptions) →~~

resolve(did, resolutionOptions) →
«
didResolutionMetadata,
didDocumentStream,

didDocument,

didDocumentMetadata
»

The resolve function returns the DID document in its abstract form (a map ). The resolveRepresentation function returns a byte stream of the DID Document formatted in the corresponding representation. Figure 1 Functions resolve() and resolveRepresentation(). See also: narrative description . The upper middle part of the diagram contains a rectangle with dashed grey outline, containing two blue-outlined rectangles, one above the other. The upper, larger rectangle is labeled, in blue, "Core Properties", and contains the following INFRA notation: «[ , → « «[ , , , ]» », → « » ]» The lower, smaller rectangle is labeled, in blue, "Core Representation-specific Entries (JSON-LD)", and contains the following monospaced INFRA notation: « [ "@context" → "https://www.w3.org/ns/did/v1" ] » From the grey-outlined rectangle, three pairs of arrows extend to three different black-outlined rectangles, aligned in a horizontal row side-by-side, in the bottom half of the diagram. Each pair of arrows consists of one blue arrow pointing from the grey-outlined rectangle to the respective black-outlined rectangle, labeled "produce", and one red arrow pointing in the reverse direction, labeled "consume". The first black-outlined rectangle in the row is labeled "application/did+ld+json", and contains the following JSON-LD data: } The second rectangle in the row is labeled "application/did+json" and contains the following JSON data: } The third rectangle in the row is labeled "application/did+cbor", and contains hexadecimal data. In the left part of the diagram, in the middle, there is a box, with black outline and light gray background. This box is labeled "VERIFIABLE DATA REGISTRY" and contains a symbol representing a graph with nodes and arcs. From this box, one arrow, labeled "resolve()", extends upwards and points to the top half of the diagram where the grey-outlined rectangle is located. Another arrow, labeled "resolveRepresentation()", extends downwards and points to the bottom half of the diagram, where the row of three black-outlined rectangles is located. All conformant DID resolvers MUST implement the DID resolution ~~functions~~ function for at least one DID method and MUST be able to return a DID document in at least one conformant representation .

Conforming DID resolver implementations do not alter the signature of ~~these functions~~ this function in any way. DID resolver implementations might map the resolve ~~and resolveRepresentation functions~~ function to a method-specific internal function to perform the actual DID resolution process. DID resolver implementations might implement and expose additional functions with different signatures in addition to the resolve ~~and resolveRepresentation functions~~ function specified here.

The input variables of the resolve ~~and resolveRepresentation functions~~ function are as follows:

did: This is the DID to resolve. This input is REQUIRED and the value MUST be a conformant DID as defined in Decentralized Identifiers (DIDs) v1.0 .
resolutionOptions: A metadata structure containing properties defined in 4.1 DID Resolution Options . This input is REQUIRED , but the structure MAY be empty.

~~These functions each return~~ This function returns multiple values, and no limitations are placed on how these values are returned together. The return values of resolve are didResolutionMetadata , didDocument , and didDocumentMetadata . ~~The return values of resolveRepresentation are didResolutionMetadata , didDocumentStream , and didDocumentMetadata .~~ These values are described below:

didResolutionMetadata: A metadata structure consisting of values relating to the results of the DID resolution process which typically changes between invocations of the resolve ~~and resolveRepresentation functions,~~ function, as it represents data about the resolution process itself. This structure is REQUIRED , and in the case of an error in the resolution process, this MUST NOT be empty. This metadata is defined by 4.2 DID Resolution Metadata . If ~~resolveRepresentation was called, this structure MUST contain a contentType property containing the Media Type of the representation found in the didDocumentStream . If~~ the resolution is not successful, this structure MUST contain an error property describing the error.
didDocument: If the resolution is successful, ~~and if the resolve function was called,~~ this MUST be a DID document ~~abstract data model (a map ) as described in Decentralized Identifiers (DIDs) v1.0~~ that is capable of being ~~transformed into a conforming DID Document (representation), using~~ represented in one of the ~~production rules specified by~~ conformant representations of the ~~representation.~~ Decentralized Identifiers (DIDs) v1.0 specification. The value of id in the resolved DID document MUST match the DID that was resolved. If the resolution is unsuccessful, this value MUST be empty.
didDocumentStream If the resolution is successful, and if the resolveRepresentation function was called, this MUST be a byte stream of the resolved DID document in one of the conformant representations . The byte stream might then be parsed by the caller of the resolveRepresentation function into a data model , which can in turn be validated and processed. If the resolution is unsuccessful, this value MUST be an empty stream. didDocumentMetadata: If the resolution is successful, this MUST be a metadata structure . This structure contains metadata about the DID document contained in the didDocument property. This metadata typically does not change between invocations of the resolve ~~and resolveRepresentation functions~~ function unless the DID document changes, as it represents metadata about the DID document . If the resolution is unsuccessful, this output MUST be an empty metadata structure . Properties defined by this specification are in 4.3 DID Document Metadata .

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 ~~contained in~~ of the returned didDocumentStream didDocument if such a representation is supported and available. This property is OPTIONAL ~~for the resolveRepresentation function and MUST NOT be used with the resolve function.~~ .

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.

contentType

The Media Type of the returned


didDocumentStream

didDocument

. This property is ~~REQUIRED if resolution is successful and if the resolveRepresentation function was called. This property MUST NOT be present if~~ OPTIONAL . If present, the ~~resolve function was called. The~~ value of this property MUST be an ASCII string that is the Media Type of the conformant representations . ~~The~~ In this case, the caller of the


resolveRepresentation

resolve

function MUST use this value when determining how to parse and process the


didDocumentStream
returned
by
this
function
into
the
data
model
.

didDocument

error

The error code from the resolution process. This property is REQUIRED when there is an error in the resolution process. The value of this property MUST be a single keyword ASCII string . The possible property values of this field SHOULD be registered in the DID Specification Registries [ DID-SPEC-REGISTRIES ]. This specification defines the following common error values:

invalidDid: The DID supplied to the DID resolution function does not conform to valid syntax. (See Decentralized Identifiers (DIDs) v1.0 .)
notFound: The DID resolver was unable to find the DID document resulting from this resolution request.
representationNotSupported: This error code is returned if the representation requested via the accept input metadata property is not supported by the DID method and/or DID resolver implementation.

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 . equivalentId represents a full graph merge because 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, canonicalId represents a full graph merge because 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 .

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" → "invalidDid", ... ]»
2. didDocument : null
3. didDocumentMetadata : «[ ]»
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" → "methodNotSupported", ... ]»
2. didDocument : null
3. didDocumentMetadata : «[ ]»
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" → "notFound", ... ]»
  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.
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 .
Return the following result:
1. didResolutionMetadata : «[ ... ]»
2. didDocument : output DID document
3. didDocumentMetadata : «[ "contentType" → output DID document media type , ... ]»

Issue 5 : Discuss how to treat deactivated DIDs enhancement pending-close

There is discussion how a DID that has been deactivated should be treated during the DID resolution process.

Issue 13 : Validate signatures/proofs of DID Document security

Specify how signatures/proofs on a DID document should be verified during the DID resolution process.

Issue

Should we define functionality that enables discovery of the list of DID methods or other capabilities that are supported by a DID resolver ? Or is this implementation-specific and out-of-scope for this spec? For example, see here and here .

The DID URL dereferencing function dereferences a DID URL into a resource with contents depending on the DID URL 's components, including the DID method , method-specific identifier, path, query, and fragment. This process depends on DID resolution of the DID contained in the DID URL . DID URL dereferencing might involve multiple steps (e.g., when the DID URL being dereferenced includes a fragment), and the function is defined to return the final resource after all steps are completed. The following figure depicts the relationship described above.

DIDs resolve to DID documents; DID URLs contains a DID; DID URLs dereferenced to DID document fragments or external resources. — Figure 2 1 Overview of DID URL dereference See also: narrative description .

The top left part of the diagram contains a rectangle with black outline, labeled "DID".

The bottom left part of the diagram contains a rectangle with black outline, labeled "DID URL". This rectangle contains four smaller black-outlined rectangles, aligned in a horizontal row adjacent to each other. These smaller rectangles are labeled, in order, "DID", "path", "query", and "fragment.

The top right part of the diagram contains a rectangle with black outline, labeled "DID document". This rectangle contains three smaller black-outlined rectangles. These smaller rectangles are labeled "id", "(property X)", and "(property Y)", and are surrounded by multiple series of three dots (ellipses). A curved black arrow, labeled "DID document - relative fragment dereference", extends from the rectangle labeled "(property X)", and points to the rectangle labeled "(property Y)".

The bottom right part of the diagram contains an oval shape with black outline, labeled "Resource".

A black arrow, labeled "resolves to a DID document", extends from the rectangle in the top left part of the diagram, labeled "DID", and points to the rectangle in the top right part of diagram, labeled "DID document".

A black arrow, labeled "refers to", extends from the rectangle in the top right part of the diagram, labeled "DID document", and points to the oval shape in the bottom right part of diagram, labeled "Resource".

A black arrow, labeled "contains", extends from the small rectangle labeled "DID" inside the rectangle in the bottom left part of the diagram, labeled "DID URL", and points to the rectangle in the top left part of diagram, labeled "DID".

A black arrow, labeled "dereferences to a DID document", extends from the rectangle in the bottom left part of the diagram, labeled "DID URL", and points to the rectangle in the top right part of diagram, labeled "DID document".

A black arrow, labeled "dereferences to a resource", extends from the rectangle in the bottom left part of the diagram, labeled "DID URL", and points to the oval shape in the bottom right part of diagram, labeled "Resource".

All conforming DID resolvers implement the following function which has the following abstract form:

dereference(didUrl, dereferenceOptions) →
«
dereferencingMetadata,
contentStream,
contentMetadata
»

The input variables of the dereference function are as follows:

didUrl: A conformant DID URL as a single string . This is the DID URL to dereference. To dereference a DID fragment , the complete DID URL including the DID fragment MUST be used. This input is REQUIRED .

Note : DID URL dereferencer patterns

While it is valid for any didUrl to be passed to a DID URL dereferencer, implementers are expected to refer to 5. DID URL Dereferencing to further understand common patterns for how a DID URL is expected to be dereferenced.
dereferencingOptions: A metadata structure consisting of input options to the dereference function in addition to the didUrl itself. Properties defined by this specification are in 5.1 DID URL Dereferencing Options . This input is REQUIRED , but the structure MAY be empty.

This function returns multiple values, and no limitations are placed on how these values are returned together. The return values of the dereference include dereferencingMetadata, contentStream, and contentMetadata:

dereferencingMetadata: A metadata structure consisting of values relating to the results of the DID URL dereferencing process. This structure is REQUIRED , and in the case of an error in the dereferencing process, this MUST NOT be empty. Properties defined by this specification are in 5.2 DID URL Dereferencing Metadata . If the dereferencing is not successful, this structure MUST contain an error property describing the error.
contentStream: If the dereferencing function was called and successful, this MUST contain a resource corresponding to the DID URL . The contentStream MAY be a resource such as a DID document that is serializable in one of the conformant representations , a verification method , a service , or any other resource format that can be identified via a Media Type and obtained through the resolution process. If the dereferencing is unsuccessful, this value MUST be empty.
contentMetadata: If the dereferencing is successful, this MUST be a metadata structure , but the structure MAY be empty. This structure contains metadata about the contentStream. If the contentStream is a DID document , this MUST be a didDocumentMetadata structure as described in DID Resolution . If the dereferencing is unsuccessful, this output MUST be an empty metadata structure .

Conforming DID URL dereferencing implementations do not alter the signature of these functions in any way. DID URL dereferencing implementations might map the dereference function to a method-specific internal function to perform the actual DID URL dereferencing process. DID URL dereferencing implementations might implement and expose additional functions with different signatures in addition to the dereference function specified here.

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.

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

The error code from the dereferencing process. This property is REQUIRED when there is an error in the dereferencing process. The value of this property MUST be a single keyword expressed as an ASCII string . The possible property values of this field SHOULD be registered in the DID Specification Registries [ DID-SPEC-REGISTRIES ]. This specification defines the following common error values:

invalidDidUrl: The DID URL supplied to the DID URL dereferencing function does not conform to valid syntax. (See Decentralized Identifiers (DIDs) v1.0 .)
notFound: The DID URL dereferencer was unable to find the contentStream resulting from this dereferencing request.

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

Validate that the input DID URL conforms to the did-url rule of the DID URL Syntax . If not, the DID URL dereferencer MUST return the following result:
1. dereferencingMetadata : «[ "error" → "invalidDidUrl" ]»
2. contentStream : null
3. contentMetadata : «[ ]»
Obtain the DID document for the input DID by executing the DID resolution algorithm as defined in 4. DID Resolution . All dereferencing options and all DID parameters of the input DID URL MUST be passed as resolution options to the DID Resolution algorithm.
If the input DID does not exist in the VDR, the DID URL dereferencer MUST return the following result:
1. dereferencingMetadata : «[ "error" → "notFound", ... ]»
2. contentStream : null
3. contentMetadata : «[ ]»
Otherwise, the didDocument result of the DID resolution algorithm is called the resolved DID document.
If present, separate the DID fragment from the input DID URL and continue with the adjusted input DID URL.
If the input DID URL contains no DID path and no DID query :
Example 3
```
did:example:1234
```
The DID URL dereferencer MUST return the resolved DID document and resolved 4.3 DID Document Metadata as follows:
1. dereferencingMetadata : «[ ... ]»
2. contentStream : resolved DID document
3. contentMetadata : «[ resolved DID document metadata ]»
If the input DID URL contains the DID parameter hl:
Example 4
```
did:example:1234?hl=zQmWvQxTqbG2Z9HPJgG57jjwR154cKhbtJenbyYTWkjgF3e
```
1. Issue
  
  TODO: Specify the algorithm for processing the hl DID parameter.
If the input DID URL contains the DID parameter service and optionally the relativeRef DID parameter:
Example 5
```
did:example:1234?service=files&relativeRef=%2Fmyresume%2Fdoc%3Fversion%3Dlatest
```
1. From the resolved DID document, select the service endpoint whose id property contains a fragment which matches the value of the service DID parameter of the input DID URL. This is called the input service endpoint.
2. Execute the Service Endpoint Construction algorithm:
  1. Read the value of the serviceEndpoint property of the input service endpoint. This is called the input service endpoint URL.
  2. Pass the input DID URL and input service endpoint URL to the Service Endpoint Construction algorithm.
  3. The result is called the output service endpoint URL.
3. Return the following result:
  1. dereferencingMetadata : «[ ... ]»
  2. content : output service endpoint URL
  3. contentMetadata : «[ "contentType" → "text/uri-list", ... ]»
Otherwise, if the input DID URL contains a DID path and/or DID query :
Example 6
```
did:example:1234/custom/path?customquery
```
1. The applicable DID method MAY specify how to dereference the DID path and/or DID query of the input DID URL.
  Example 7
```
did:example:1234/resources/1234
```
2. An extension specification MAY specify how to dereference the DID path of the input DID URL.
  Example 8
```
did:example:1234/whois
```
3. An extension specification MAY specify how to dereference the DID query of the input DID URL.
  Example 9
```
did:example:1234?transformKey=JsonWebKey
```
4. The client MAY be able to dereference the input DID URL in an application-specific way.
If neither this algorithm, nor the applicable DID method , nor an extension, nor the client is able to dereference the input DID URL, return the following result:
1. dereferencingMetadata : «[ "error" → "notFound" ]»
2. contentStream : null
3. contentMetadata : «[ ]»

Issue 85 : Request service by type enhancement pr-exists

There have been discussions whether in addition to the DID parameter service, there could also be a DID parameter serviceType to select services based on their type rather than ID. See comments by Dave Longley about serviceType.

If the input DID URL contains a DID fragment , then dereferencing of the fragment is dependent on the media type ([ RFC2046 ]) of the resource, i.e., on the result of 5.3.1 Dereferencing the Resource .

If the result of 5.3.1 Dereferencing the Resource is an output service endpoint URL, and the input DID URL contains a DID fragment :
Example 10
```
did:example:1234?service=files&relativeRef=%2Fmyresume%2Fdoc%3Fversion%3Dlatest#intro
```
1. If the output service endpoint URL contains a fragment component, raise an error.
2. Append the DID fragment to the output service endpoint URL. In other words, the output service endpoint URL "inherits" the DID fragment of the input DID URL.
3. Return the output service endpoint URL.
Otherwise, dereference the DID fragment as defined by the media type ([ RFC2046 ]) of the resource. For example, if the resource is a representation of a DID document with media type application/did, then the fragment is treated according to the rules associated with the JSON-LD 1.1: application/ld+json media type [JSON-LD11].

Note

This use of the DID fragment is consistent with the definition of the fragment identifier in [ RFC3986 ]. It identifies a secondary resource which is a subset of the primary resource (the DID document ).

Note

This behavior of the DID fragment is analogous to the handling of a fragment in an HTTP URL in the case when dereferencing it returns an HTTP 3xx (Redirection) response with a Location header (see section 7.1.2 of [ RFC7231 ].

Given the following input DID URL:

Example 11

did:example:123456789abcdefghi#keys-1

... and the following resolved DID document:

Example 12

{
	"@context": "https://www.w3.org/ns/did/v1",
	"id": "did:example:123456789abcdefghi",
	"verificationMethod": [{
		"id": "did:example:123456789abcdefghi#keys-1",
		"type": "Ed25519VerificationKey2018",
		"controller": "did:example:123456789abcdefghi",
		"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
	}],
	"service": [{
		"id": "did:example:123456789abcdefghi#agent",
		"type": "AgentService",
		"serviceEndpoint": "https://agent.example.com/8377464"
	}, {
		"id": "did:example:123456789abcdefghi#messages",
		"type": "MessagingService",
		"serviceEndpoint": "https://example.com/messages/8377464"
	}]
}

... then the result of the 5. DID URL Dereferencing algorithm is the following output resource:

Example 13

{
	"@context": "https://www.w3.org/ns/did/v1",
	"id": "did:example:123456789abcdefghi#keys-1",
	"type": "Ed25519VerificationKey2018",
	"controller": "did:example:123456789abcdefghi",
	"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
}

Given the following input DID URL and the same resolved DID document as above:

Example 14

did:example:123456789abcdefghi?service=messages&relativeRef=%2Fsome%2Fpath%3Fquery#frag

... then the result of the 5. DID URL Dereferencing algorithm is the following output service endpoint URL:

Example 15

https://example.com/messages/8377464/some/path?query#frag

Diagram showing how a DID URL can be dereferenced to a service endpoint URL — Figure 3 2 Dereferencing a DID URL to a service endpoint URL.

Issue

Change the diagram and/or examples to make them consistent.

Input and output metadata is often involved during the DID Resolution , DID URL dereferencing , and other DID-related processes. The structure used to communicate this metadata MUST be a map of properties. Each property name MUST be a string . Each property value MUST be a string , map , list , set , boolean , or null . The values within any complex data structures such as maps and lists MUST be one of these data types as well. All metadata property definitions registered in the DID Specification Registries [ DID-SPEC-REGISTRIES ] MUST define the value type, including any additional formats or restrictions to that value (for example, a string formatted as a date or as a decimal integer). It is RECOMMENDED that property definitions use strings for values. The entire metadata structure MUST be serializable according to the JSON serialization rules in the [ INFRA ] specification. Implementations MAY serialize the metadata structure to other data formats.

All implementations of functions that use metadata structures as either input or output are able to fully represent all data types described here in a deterministic fashion. As inputs and outputs using metadata structures are defined in terms of data types and not their serialization, the method for representation is internal to the implementation of the function and is out of scope of this specification.

The following example demonstrates a JSON-encoded metadata structure that might be used as DID resolution input metadata .

Example 16 : JSON-encoded DID resolution input metadata example

{
"accept": "application/did+ld+json"

}

This example corresponds to a metadata structure of the following format:

Example 17 : DID resolution input metadata example

«[
"accept" → "application/did+ld+json"
]»

The next example demonstrates a JSON-encoded metadata structure that might be used as DID resolution metadata if a DID was not found.

Example 18 : JSON-encoded DID resolution metadata example

{
"error": "notFound"

}

This example corresponds to a metadata structure of the following format:

Example 19 : DID resolution metadata example

«[
"error" → "notFound"
]»

The next example demonstrates a JSON-encoded metadata structure that might be used as DID document metadata to describe timestamps associated with the DID document .

Example 20 : JSON-encoded DID document metadata example

{
"created": "2019-03-23T06:35:22Z",
"updated": "2023-08-10T13:40:06Z"

}

This example corresponds to a metadata structure of the following format:

Example 21 : DID document metadata example

«[
"created" → "2019-03-23T06:35:22Z",
"updated" → "2023-08-10T13:40:06Z"
]»

Issue

TODO: Describe how DID resolvers are implemented and used, describe the relevance of DID methods . Explain the difference between "method architectures" and "resolver architectures".

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

Note

The mechanics of the "Read" operation can vary considerably between DID methods . In particular, no assumption should be made that:

... an immutable blockchain is used as (part of) the verifiable data registry .
... interaction with a remote network is required during execution of the "Read" operation.
... an actual DID document is stored in plain-text on a verifiable data registry , or that the DID document can simply be retrieved via a standard protocol such as HTTP(S). While some DID methods may define their "Read" operation this way, others may define more complex multi-step processes that involve on-the-fly construction of a "virtual" DID document .

Issue

As an example, mention what it means to "resolve" peer/off-ledger/microledger/edgechain DIDs (for instance, see [ DID-PEER ] and here ).

Issue

As an example, mention what it means to "resolve" DIDs that are simply wrapped public keys (for instance, see [ DID-KEY ] and here ).

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 :

Diagram showing a 'verifiable read' implementation of a DID method. — Figure 4 3 A verifiable read implementation of a DID method .

Diagram showing an 'unverifiable read' implementation of a DID method. — Figure 5 4 An unverifiable read implementation of a DID method .

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.

Note

The guarantees associated with a verifiable read are still always limited by the architectures, protocols, cryptography, and other aspects of the underlying verifiable data registry . The strongest forms of verifiable read implementations are considered those that do not require any interaction with a remote network at all (for example, see [ DID-KEY ]), or that minimize dependencies on specific network infrastructure and reduce the "root of trust" to proven entropy and cryptography alone (for example, see [ KERI ]).

Issue

TODO: Describe how a client can potentially verify the result of a "Read" operation independently even if it does not trust the DID resolver (e.g., using state proofs).

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

Diagram showing a DID resolver that supports multiple DID methods. — Figure 6 5 A DID resolver that supports multiple DID methods .

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

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

Those algorithms are implemented by DID resolvers . A DID resolver is invoked by a client via a binding . Bindings define how the abstract functions are realized using concrete programming or communication interfaces. It is possible to distinguish between local bindings (such as a local command line tool or library API) and remote bindings (such as the HTTP(S) binding ).

Diagram showing a DID resolver with a 'local binding'. — Figure 7 6 A local binding for a DID resolver .

Diagram showing a DID resolver with a 'remote binding'. — Figure 8 7 A remote binding for a DID resolver .

Issue 28 : 'remote' vs 'local' DID Resolvers

TODO: Describe local bindings vs. remote bindings , and implications for privacy, security and trust.

Also describe mitigations against potential downsides of remote bindings , e.g.:

A DID resolver's remote binding can use a trusted channel such as VPN or TLS with mutual authentication.
A DID resolver can add a data integrity proof (see [ DATA-INTEGRITY ]) to a DID document and/or the DID resolution result . Discuss what this does and doesn't achieve. Also see Proving Control and Binding .
A client could query multiple DID resolvers over a remote binding and compare results.

Issue

TODO: Discuss DID resolution in constrained user agents such as mobile apps and browsers.

The following diagram shows how the resolve() and resolveRepresentation() functions use production and consumption rules of DID document representation can apply in an architecture that involves both a local resolver and a remote resolver. Figure 9 Production and consumption in an architecture that involves both a local and a remote DID resolver .

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

Diagram showing two DID resolvers, one invoked via 'local binding', the other invoked via 'remote binding'. — Figure 10 8 A client invokes a DID resolver via local binding which invokes another DID resolver via remote binding , which in turn supports resolving multiple DID methods .

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

Different parts of the DID URL dereferencing algorithm may be performed by different components of a Resolver Architecture .

Specifically, when a DID URL with a DID fragment is dereferenced, then Dereferencing the Resource is done by the DID resolver , and Dereferencing the Fragment is done by the client .

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

Diagram showing client-side dereferencing of a DID URL by a DID resolver and a client — Figure 11 9 Client-side dereferencing of a DID URL by a DID resolver and a client .

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

Diagram showing client-side dereferencing of a DID URL by two DID resolvers and a client — Figure 12 10 Client-side dereferencing (in combination with Proxied Resolution ) of a DID URL by two DID resolvers and a client .

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

This section defines a data structure that represents the result of the algorithm described in 4. DID Resolution . A DID resolution result contains a DID document as well as DID resolution metadata and DID document metadata .

The media type of this data structure is defined to be application/ld+json;profile="https://w3id.org/did-resolution".

Example 22 : Example DID resolution result

{
	"@context": "https://w3id.org/did-resolution/v1",
	"didDocument": {
		"@context": "https://www.w3.org/ns/did/v1",
		"id": "did:example:123456789abcdefghi",
		"authentication": [{
			"id": "did:example:123456789abcdefghi#keys-1",
			"type": "Ed25519VerificationKey2018",
			"controller": "did:example:123456789abcdefghi",
			"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
		}],
		"service": [{
			"id":"did:example:123456789abcdefghi#vcs",
			"type": "VerifiableCredentialService",
			"serviceEndpoint": "https://example.com/vc/"
		}]
	},
	"didResolutionMetadata": {
		"contentType": "application/did+ld+json",
		"retrieved": "2024-06-01T19:73:24Z",
	},
	"didDocumentMetadata": {
		"created": "2019-03-23T06:35:22Z",
		"updated": "2023-08-10T13:40:06Z",
		"method": {
			"nymResponse": {
				"result": {
					"data": "{\"dest\":\"WRfXPg8dantKVubE3HX8pw\",\"identifier\":\"V4SGRU86Z58d6TV7PBUe6f\",\"role\":\"0\",\"seqNo\":11,\"txnTime\":1524055264,\"verkey\":\"H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV\"}",
					"type": "105",
					"txnTime": 1.524055264E9,
					"seqNo": 11.0,
					"reqId": 1.52725687080231475E18,
					"identifier": "HixkhyA4dXGz9yxmLQC4PU",
					"dest": "WRfXPg8dantKVubE3HX8pw"
				},
				"op": "REPLY"
			},
			"attrResponse": {
				"result": {
					"identifier": "HixkhyA4dXGz9yxmLQC4PU",
					"seqNo": 12.0,
					"raw": "endpoint",
					"dest": "WRfXPg8dantKVubE3HX8pw",
					"data": "{\"endpoint\":{\"xdi\":\"http://127.0.0.1:8080/xdi\"}}",
					"txnTime": 1.524055265E9,
					"type": "104",
					"reqId": 1.52725687092557056E18
				},
				"op": "REPLY"
			}
		}
	}
}

Issue 23 : The did is not a url for the did, but for a resolution structure which as yet has no name pending-close

See corresponding open issue.

Issue

Need to define how this data structure works exactly, and whether it always contains a DID document or can also contain other results.

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 code (the error metadata property).
Duration of the DID resolution process.
Caching information about the DID document (see Section 13.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 13.3 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 ].

Issue

For certain data, it may be debatable whether it should be part of the DID document (i.e., data that describes the DID Subject), or whether it is metadata (i.e., data about the DID document or about the DID resolution process). For example the URL of the "Continuation DID document" in the BTCR method.

This section defines a data structure that represents the result of the algorithm described in 5. DID URL Dereferencing . A DID URL dereferencing result contains arbitrary content as well as DID resolution metadata and content metadata .

Issue 69 : DID Resolution Result for DID URL Dereferencing enhancement pending-close

See corresponding open issue.

The media type of this data structure is defined to be application/ld+json;profile="https://w3id.org/did-resolution".

Example 23 : Example DID URL dereferencing result

{
	"@context": "https://w3id.org/did-resolution/v1",
	"content": {
		"@context": "https://www.w3.org/ns/did/v1",
		"id": "did:example:123456789abcdefghi",
		"authentication": [{
			"id": "did:example:123456789abcdefghi#keys-1",
			"type": "Ed25519VerificationKey2018",
			"controller": "did:example:123456789abcdefghi",
			"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
		}],
		"service": [{
			"id":"did:example:123456789abcdefghi#vcs",
			"type": "VerifiableCredentialService",
			"serviceEndpoint": "https://example.com/vc/"
		}]
	},
	"didUrlDereferencingMetadata": {
		"contentType": "application/did+ld+json",
		"retrieved": "2024-06-01T19:73:24Z",
	},
	"contentMetadata": {
		"created": "2019-03-23T06:35:22Z",
		"updated": "2023-08-10T13:40:06Z",
		"method": {
			"nymResponse": {
				"result": {
					"data": "{\"dest\":\"WRfXPg8dantKVubE3HX8pw\",\"identifier\":\"V4SGRU86Z58d6TV7PBUe6f\",\"role\":\"0\",\"seqNo\":11,\"txnTime\":1524055264,\"verkey\":\"H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV\"}",
					"type": "105",
					"txnTime": 1.524055264E9,
					"seqNo": 11.0,
					"reqId": 1.52725687080231475E18,
					"identifier": "HixkhyA4dXGz9yxmLQC4PU",
					"dest": "WRfXPg8dantKVubE3HX8pw"
				},
				"op": "REPLY"
			},
			"attrResponse": {
				"result": {
					"identifier": "HixkhyA4dXGz9yxmLQC4PU",
					"seqNo": 12.0,
					"raw": "endpoint",
					"dest": "WRfXPg8dantKVubE3HX8pw",
					"data": "{\"endpoint\":{\"xdi\":\"http://127.0.0.1:8080/xdi\"}}",
					"txnTime": 1.524055265E9,
					"type": "104",
					"reqId": 1.52725687092557056E18
				},
				"op": "REPLY"
			}
		}
	}
}

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.

Issue

Add more details how DID URL dereferencing metadata works.

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.

Issue

Add more details how content metadata works.

If an invalid DID is detected during DID Resolution , the value of the DID Resolution Metadata error property MUST be invalidDid as defined in section 4.2 DID Resolution Metadata .

If an invalid DID URL is detected during DID Resolution or DID URL dereferencing , the value of the DID Resolution or DID URL Dereferencing Metadata error property MUST be invalidDidUrl as defined in section 5.2 DID URL Dereferencing Metadata .

If during DID Resolution or DID URL dereferencing a DID or DID URL doesn't exist, the value of the DID Resolution or DID URL dereferencing Metadata error property MUST be notFound as defined in sections 4.2 DID Resolution Metadata and 5.2 DID URL Dereferencing Metadata .

If a DID document representation is not supported during DID Resolution or DID URL dereferencing , the value of the DID Resolution Metadata error property MUST be representationNotSupported as defined in section 4.2 DID Resolution Metadata .

If a DID method is not supported during DID Resolution or DID URL dereferencing , the value of the DID Resolution or DID URL Dereferencing Metadata error property MUST be methodNotSupported .

When an unexpected error occurs during DID Resolution or DID URL dereferencing , the value of the DID Resolution or DID URL Dereferencing Metadata error property MUST be internalError .

If an invalid public key value is detected during DID Resolution or DID URL dereferencing , the value of the DID Resolution or DID URL Dereferencing Metadata error property MUST be invalidPublicKey .

If the byte length of rawPublicKeyBytes does not match the expected public key length for the associated multicodecValue during DID Resolution or DID URL dereferencing , the value of the DID Resolution or DID URL Dereferencing Metadata error property MUST be invalidPublicKeyLength .

If an invalid public key type is detected during DID Resolution or DID URL dereferencing , the value of the DID Resolution or DID URL Dereferencing Metadata error property MUST be invalidPublicKeyType .

If an unsupported public key type is detected during DID Resolution or DID URL dereferencing , the value of the DID Resolution or DID URL Dereferencing Metadata error property MUST be unsupportedPublicKeyType .

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

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:

Initialize a request HTTP(S) URL with the DID resolver HTTP(S) endpoint.
Example 24
```
https://resolver.example/1.0/identifiers/
```
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/ld+json;profile="https://w3id.org/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
```
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/ld+json;profile="https://w3id.org/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
```
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 .

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
`invalidDid`	`400`
`invalidDidUrl`	`400`
`notFound`	`404`
`representationNotSupported`	`406`
`methodNotSupported`	`501`
`internalError`	`500`
(any other value)	`500`

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.
For the DID resolution function:
1. If the value of the Content-Type HTTP response header is application/ld+json;profile="https://w3id.org/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.
For the DID URL dereferencing function:
1. If the value of the Content-Type HTTP response header is application/ld+json;profile="https://w3id.org/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 output 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.

See here for an OpenAPI definition.

Given the following DID resolver HTTP(S) endpoint:

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

And given the following input DID:

did:sov:WRfXPg8dantKVubE3HX8pw

Then the request HTTP(S) URL is:

https://resolver.example/1.0/identifiers/did:sov:WRfXPg8dantKVubE3HX8pw

The HTTP(S) binding can be invoked as follows:

Example 29 : Example curl call to a DID resolver via HTTP(S) binding

curl
-X
GET
https://resolver.example/1.0/identifiers/did:sov:WRfXPg8dantKVubE3HX8pw

Additional examples of the HTTP(S) binding:

Diagram showing the invocation of resolve() over HTTPS — Figure 14 12 Invocation of ~~resolveRepresentation()~~ resolve() over HTTP(S).

Additional examples of the HTTP(S) binding:

Diagram showing the invocation of dereference() over HTTPS — Figure 16 14 Invocation of dereference() over HTTP(S).

This section defines the inputs and the algorithm of Service Endpoint Construction , which returns a service endpoint URL as output. This algorithm is used when service endpoints are selected during DID URL dereferencing (see 5. DID URL Dereferencing ).

In this section, path, query, and fragment are understood as defined in [ RFC3986 ].

The inputs of the Service Endpoint Construction algorithm are an input DID URL and an input service endpoint URL.

The requirements for the inputs of the Service Endpoint Construction algorithm are as follows:

The input DID URL and input service endpoint URL MAY both have a path component.
The input DID URL and input service endpoint URL MUST NOT both have a query component.
The input DID URL and input service endpoint URL MUST NOT both have a fragment component.
The input service endpoint URL MUST be an HTTP(S) URL.

Initialize a string output service endpoint URL to the value of the input service endpoint URL
If the output service endpoint URL has a query component, remove it.
If the output service endpoint URL has a fragment component, remove it.
Append the path component of the input DID URL to the output service endpoint URL.
If the input service endpoint URL has a query component, append ? plus the query to the output service endpoint URL.
If the input DID URL has a query component, append ? plus the query to the output service endpoint URL.
If the input service endpoint URL has a fragment component, append # plus the fragment to the output service endpoint URL.
If the input DID URL has a fragment component, append # plus the fragment to the output service endpoint URL.
Return the output service endpoint URL.

Issue

We could potentially allow query components on both the input DID URL and input service endpoint URL, if they both contain lists of key/value parameters that can be merged.

Issue

Details of the Service Endpoint Construction algorithm have been discussed in April 2019 on the CCG mailing list, e.g., here or here .

Issue

Instead of defining our own algorithm, we could potentially re-use the "Relative Resolution" algorithm defined in [ RFC3986 ].

Issue 61 : Service Endpoint Construction inconsistency bug pr-exists

See corresponding open issue.

Given the following input service endpoint URL:

https://example.com/messages/8377464

And given the following input DID URL:

did:example:123456789abcdefghi?service=messages&relativeRef=%2Fsome%2Fpath%3Fquery#frag

Then the output service endpoint URL is:

https://example.com/messages/8377464/some/path?query#frag

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.

Issue 38 : Restricted access/Authentication/Authorization enhancement

The spec should clarify whether or not conformant resolvers MUST be public or MAY restrict access via some authentication and authorization scheme.

The current language doesn't make it clear if authentication is just out of scope or if it is disallowed.

Issue

Explain that DIDs are not necessarily globally resolvable, such as pairwise or N-wise "peer" DIDs.

See [ RFC3339 ]: URIs have a global scope and are interpreted consistently regardless of context, though the result of that interpretation may be in relation to the end-user's context.

An advanced idea is that the result of DID resolution could be contextual or depend on policies, see this comment .

Issue

A related topic is whether (parts of) DID document could be encrypted, e.g., w3c/did-core/issues/25 . Also see the use of the fragment in the IPID DID method.

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.

Issue 10 : need TTL construct? enhancement

See corresponding open issue.

Issue

Perhaps we can re-use caching mechanisms of other protocols such as HTTP.

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.

Note

While most DID methods support the Update operation, there is no requirement for DID methods to keep all previous DID document versions, therefore not all DID methods support versioning.

Issue 12 : Design versioning features pending-close

See corresponding open issue.

Issue 8 : Discover DIDs from other identifiers

There is discussion on the relationship between DID resolution and resolution of non-DID identifiers such as domain names, HTTP URIs, or e-mail addresses. This includes the questions how DIDs can be discovered from non-DID identifiers, and how links between identifiers can be verifiable.

Issue 6 : DID method governance pending-close

Describe which methods a DID resolver should support, and potential implications.

Note

This section lists additional DID URL dereferencing features that are under discussion and have not yet been incorporated into the algorithm.

A service endpoint may have a serviceEndpoint property with a value that is itself a DID. This is interpreted as a "DID redirect" from the input DID to another. In this case, a "child" DID resolution process can be launched to get to a "final" service endpoint.

The follow-redirect resolution option can be supplied by a client as a hint to instruct whether redirects should be followed. This resolution option is OPTIONAL .

Issue 7 : Support DIDs as serviceEndpoint? enhancement pending-close

See corresponding open issue.

Issue 36 : Portable DID resolution

DID redirects could not only apply to a single service endpoint, but to an entire DID document, therefore enabling portability use cases.

Example 30

{
   "id": "did:example:123456789abcdefghi#hub1",
   "type": "HubService",
   "serviceEndpoint": "did:example:xyz"
}

A DID document may contain a "proxy" service type which would provide a mapping that needs to be followed in order to resolve to a final service URL.

Issue 35 : Support "proxy" service type? enhancement pending-close

Keeping track of a proposal here w3c-ccg/did-spec#90 (comment) that a DID Document could contain a "proxy" service type which would provide a mapping that needs to be followed in order to resolve to a final service URL.

Example 31

{
   "id": "did:example:123456789abcdefghi",
   "type": "ProxyService",
   "serviceEndpoint": "https://mydomain.com/proxy"
}

Issue

Several ways of selecting parts of a DID document are being discussed, including the use of JSON pointer.

See corresponding PRs here and here .

[DID-CORE]: Decentralized Identifiers (DIDs) v1.0 . Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed. W3C. 19 July 2022. W3C Recommendation. URL: https://www.w3.org/TR/did-core/
[INFRA]: Infra Standard . Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2046]: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types . N. Freed; N. Borenstein. IETF. November 1996. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2046
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels . S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC3986]: Uniform Resource Identifier (URI): Generic Syntax . T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words . B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[XMLSCHEMA11-2]: W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes . David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/

[DATA-INTEGRITY]: Verifiable Credential Data Integrity 1.0 . Dave Longley; Manu Sporny. W3C Verifiable Credentials Working Group. CRD. URL: https://www.w3.org/TR/vc-data-integrity/
[DID-KEY]: The did:key Method . Manu Sporny; Dmitri Zagidulin; Dave Longley. 09 June 2020. unofficial. URL: https://w3c-ccg.github.io/did-method-key/
[DID-PEER]: Peer DID Method Specification . Oskar Deventer; Christian Lundkvist; Márton Csernai; Kyle Den Hartog; Markus Sabadello; Sam Curren; Dan Gisolfi; Mike Varley; Sven Hammann; John Jordan; Lovesh Harchandani; Devin Fisher; Tobias Looker; Brent Zundel; Stephen Curran. 10 July 2020. W3C Editor's Draft. URL: https://identity.foundation/peer-did-method-spec/
[DID-SPEC-REGISTRIES]: Decentralized Identifier Extensions . Manu Sporny; Markus Sabadello. W3C. 19 February 2025. W3C Working Group Note. URL: https://www.w3.org/TR/did-extensions/
[HASHLINK]: Cryptographic Hyperlinks . Manu Sporny. IETF. December 2018. Internet-Draft. URL: https://tools.ietf.org/html/draft-sporny-hashlink-05
[KERI]: Key Event Receipt Infrastructure (KERI) . Samuel M. Smith. July 2019. URL: https://arxiv.org/abs/1907.02143
[RFC3339]: Date and Time on the Internet: Timestamps . G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC7231]: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content . R. Fielding, Ed.; J. Reschke, Ed. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html

Decentralized Identifier Resolution (DID Resolution) v0.3

Algorithms and guidelines for resolving DIDs and dereferencing DID URLs

Abstract

Status of This Document

1. Introduction

1.1 Conformance

1.2 Audience

2. Terminology

3. DID Parameters

4. DID Resolution

4.1 DID Resolution Options

4.2 DID Resolution Metadata

4.3 DID Document Metadata

4.4 Algorithm

5. DID URL Dereferencing

5.1 DID URL Dereferencing Options

5.2 DID URL Dereferencing Metadata

5.3 Algorithm

5.3.1 Dereferencing the Resource

5.3.2 Dereferencing the Fragment

5.4 Examples

6. Metadata Structure

7. DID Resolution Architectures

7.1 Method Architectures

7.2 Resolver Architectures

7.2.1 Proxied Resolution

7.2.2 Client-Side Dereferencing

8. DID Resolution Result

8.1 Example

8.2 DID Document

8.3 DID Resolution Metadata

8.4 DID Document Metadata

9. DID URL Dereferencing Result

9.1 Example

9.2 Content

9.3 DID URL Dereferencing Metadata

9.4 Content Metadata

10. Errors

10.1 invalidDid

10.2 invalidDidUrl

10.3 notFound

10.4 representationNotSupported

10.5 methodNotSupported

10.6 internalError

10.7 invalidPublicKey

10.8 invalidPublicKeyLength

10.9 invalidPublicKeyType

10.10 unsupportedPublicKeyType

11. Bindings

11.1 HTTP(S) Binding

11.2 DID Resolution Examples

11.3 DID URL Dereferencing Examples

12. Service Endpoint Construction

12.1 Input

12.2 Algorithm

12.3 Example

13. Security and Privacy Considerations

13.1 Authentication/Authorization

13.2 Caching

13.3 Versioning

13.4 Non-DID Identifiers

13.5 DID Method Governance

14. Future Work

14.1 Redirect

14.2 Proxy

14.3 JSON Pointer

A. DID Resolution Resources

B. References

B.1 Normative references

B.2 Informative references