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

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

DID Resolution Options

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 the returned didDocumentStream 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.

DID Resolution 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 DID resolution metadata properties:

contentType

The Media Type of the returned didDocumentStream. This property is REQUIRED if resolution is successful and if the resolveRepresentation function was called. This property MUST NOT be present if 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 caller of the resolveRepresentation function MUST use this value when determining how to parse and process the didDocumentStream returned by this function into the data model.

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

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.

DID Document Metadata

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

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

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.

Algorithm

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" → "invalidDid" ]»
   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" → "methodNotSupported" ]»
   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" → "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. The result of the Read operation is called the output DID document.
4. Validate that the output DID document conforms to a conformant representation of the DID document data model. If not, the DID resolver MUST raise an error.

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

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

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.

DID URL Dereferencing Options

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.

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

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

notFound

The DID URL dereferencer was unable to find the contentStream resulting from this dereferencing request.

Algorithm

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

1. 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: «[ ]»
2. Obtain the DID document for the input DID by executing the DID resolution algorithm as defined in . 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, return a null result. Otherwise, the result is called the resolved DID document.
3. If present, separate the DID fragment from the input DID URL. Execute the algorithm for , with the input DID URL adjusted accordingly.
4. If the original input DID URL contained a DID fragment, execute the algorithm for .

Examples

Given the following input DID URL:

did:example:123456789abcdefghi#keys-1

... and the following resolved DID document:

{
	"@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 algorithm is the following output resource:

{
	"@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:

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

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

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

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

Method Architectures

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

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

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:

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

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:

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

Resolver Architectures

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

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.

Proxied Resolution

A DID resolver MAY invoke another DID resolver, which serves as a proxy that executes the DID resolution algorithm as defined in .

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

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

Client-Side Dereferencing

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 Primary Resource is done by the DID resolver, and Dereferencing the Secondary Resource 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 Primary Resource (i.e., the DID document), and the client could complete the DID URL dereferencing algorithm by Dereferencing the Secondary Resource (i.e., a part of the DID document).

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 Primary Resource (i.e., the DID document), and the client could complete the DID URL dereferencing algorithm by Dereferencing the Secondary Resource (i.e., a part of the DID document).

Example: Given the DID URL did:xyz:1234?service=agent&relativeRef=%2Fsome%2Fpath%3Fquery#frag, a DID resolver could be invoked for Dereferencing the Primary Resource (i.e., a service endpoint URL), and the client could complete the DID URL dereferencing algorithm by Dereferencing the Secondary Resource (i.e., a service endpoint URL with a fragment).

Example

{
	"@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"
			}
		}
	}
}

See corresponding open issue.

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

DID Document

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

DID Resolution Metadata

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

DID Document Metadata

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

Example

{
	"@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"
			}
		}
	}
}

Content

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

DID URL Dereferencing Metadata

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.

Add more details how DID URL dereferencing metadata works.

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

Content Metadata

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.

Add more details how content metadata works.

HTTP(S) Binding

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

The HTTP(S) binding for DID resolvers requires a known HTTP(S) URL called the DID resolver HTTP(S) endpoint.

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

1. Initialize a request HTTP(S) URL with the DID resolver HTTP(S) endpoint.
1. Append the input DID or input DID URL to the request HTTP(S) URL. Certain characters MUST be percent-encoded (as specified in RFC3986 Section 2.1).
2. Encode the accept resolution option as the Accept HTTP header in the request.
3. Encode all other resolution options as query parameters in the request HTTP(S) URL.
2. Execute an HTTP GET request on the request HTTP(S) URL.
3. Dereference the input DID or input DID URL by executing the DID URL dereferencing algorithm as defined in
4. If the output of the DID URL dereferencing function contains the dereferencingMetadata property error, then the HTTP response status code MUST be set to the value that corresponds to the value of the error 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

5. If the output of the DID URL dereferencing function contains the didDocumentMetadata property deactivated with value true:
   1. The HTTP response status code MUST be 410.
6. If the output of the DID URL dereferencing function contains the didDocumentStream:
   1. If the value of the Accept HTTP header is absent or `application/did+ld+json` (or other media type of a conformant representation of a DID document):
      1. The HTTP response status code MUST be 200.
      2. The HTTP response MUST contain a Content-Type header. The value of this header MUST be `application/did+ld+json` (or other media type of a conformant representation of a DID document).
      3. The HTTP response body MUST contain the didDocumentStream, in the representation corresponding to the Accept HTTP header.
   2. If the value of the Accept HTTP header is `application/ld+json;profile="https://w3id.org/did-resolution"`:
      1. Produce a DID resolution result (see (see ) and populate it with the didDocumentStream, didResolutionMetadata, and didDocumentMetadata that are the output of the DID resolution function.
      2. The HTTP response status code MUST be 200.
      3. The HTTP response MUST contain a Content-Type header. The value of this header MUST be `application/ld+json;profile="https://w3id.org/did-resolution"`.
      4. The HTTP response body MUST contain the produced DID resolution result.
7. If the output of the DID URL dereferencing function is a service endpoint URL:
   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.

DID Resolution Examples

Given the following DID resolver HTTP(S) endpoint:

https://dev.uniresolver.io/1.0/identifiers/

And given the following input DID:

did:sov:WRfXPg8dantKVubE3HX8pw

Then the request HTTP(S) URL is:

https://dev.uniresolver.io/1.0/identifiers/did:sov:WRfXPg8dantKVubE3HX8pw

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

curl -X GET https://dev.uniresolver.io/1.0/identifiers/did:sov:WRfXPg8dantKVubE3HX8pw

Additional examples of the HTTP(S) binding:

DID URL Dereferencing Examples

Additional examples of the HTTP(S) binding:

Input

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.

Algorithm

1. Initialize a string output service endpoint URL to the value of the input service endpoint URL
2. If the output service endpoint URL has a query component, remove it.
3. If the output service endpoint URL has a fragment component, remove it.
4. Append the path component of the input DID URL to the output service endpoint URL.
5. If the input service endpoint URL has a query component, append ? plus the query to the output service endpoint URL.
6. If the input DID URL has a query component, append ? plus the query to the output service endpoint URL.
7. If the input service endpoint URL has a fragment component, append # plus the fragment to the output service endpoint URL.
8. If the input DID URL has a fragment component, append # plus the fragment to the output service endpoint URL.
9. Return the output service endpoint URL.

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.

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

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

See corresponding open issue.

Example

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

Authentication/Authorization

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

Caching

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.

See corresponding open issue.

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

Versioning

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.

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.

See corresponding open issue.

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

DID Method Governance

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

Redirect

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.

See corresponding open issue.

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

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

Proxy

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.

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

JSON Pointer