+DID resolution is the function of processing a DID by +executing a DID method to return a DID document +and additional metadata, in a conformant representation. +A DID resolver is a software and/or hardware component that is capable of +executing the DID resolution function for at least one +DID method. +
+ ++DID URL dereferencing is the function of processing a DID URL and returning +a resource, which might or might not be a DID document, along with additional +metadata. A DID URL dereferencer is a software and/or hardware component that +is capable of executing the DID URL dereferencing function. Generally, a +DID URL dereferencer executes DID resolution on the DID portion of a +DID URL to obtain a DID document. The DID URL dereferencer then can perform +additional dereferencing on the DID document using the full DID URL, +if necessary. +
+ ++The general inputs and outputs of the DID resolution and DID URL dereferencing functions +are specified in the section of this document. Additional considerations +for the implementation of these functions are covered in [[?DID-RESOLUTION]]. +
- Adding a DID parameter to a DID URL means that the parameter becomes part of - an identifier for a resource (the DID document or other). Alternatively, the - DID resolution and the DID URL dereferencing processes can also be influenced - by passing options to a DID resolver that are not part of the DID URL. + Adding a DID parameter to a DID URL means that the parameter becomes part of + an identifier for a resource (the DID document or other). Alternatively, the + DID resolution and the DID URL dereferencing functions can also be influenced + by passing input metadata to a DID resolver that are not part of the DID URL. + (See ). Such options could for example control caching or the desired encoding of a resolution result. 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 DID resolver options + what resource is being identified, whereas DID resolution options that are not part of the DID URL should be use to control how that - resource is dereferenced. + resource is resolved or dereferenced.
@@ -1076,11 +1103,11 @@
@@ -1238,7 +1265,7 @@
DID method specifications can create intermediate representations of a
DID document that do not contain the id key, such as when a
-DID resolver is performing resolution. However, the fully resolved
+DID resolver is performing DID resolution. However, the fully resolved
DID document always contains a valid id property. The value
of id in the resolved DID document is expected to match the
DID that was resolved.
@@ -1990,7 +2017,8 @@
Producers MUST indicate which representation of a document has been used via a media type
in the document's metadata. Consumers MUST determine which representation a document is in
-via a media type in the document's metadata. Consumers MUST NOT determine the representation
+via the content-type DID resolver metadata field. (See ).
+Consumers MUST NOT determine the representation
of a document through its content alone.
-When producing and consuming DID documents that are in plain JSON (as noted by
-the document metadata), the following rules MUST be followed.
+When producing and consuming DID documents that are in plain JSON (as indicated by
+a content-type of application/json+did in the resolver metadata), the following rules MUST be followed.
-When producing and consuming DID documents that are in JSON-LD (as noted by
-the document metadata), the following rules MUST be followed.
+When producing and consuming DID documents that are in JSON-LD (as indicated by
+a content-type of application/jsonld+did in the resolver metadata), the following rules MUST be followed.
-A DID resolver is a software or hardware component with an API for -resolving DIDs of at least one DID method. It executes the read -operation for the DID method corresponding to the DID being -resolved to obtain the authoritative DID document. For more information, -see Section . +This section defines the inputs and outputs of the +DID resolution and DID URL dereferencing functions. The +exact implementation of these functions is out of scope for this specification, +but some considerations for implementors are available in [[?DID-RESOLUTION]].
- +-The interfaces and algorithms for resolving DIDs and dereferencing -DID URLs are specified in [[?DID-RESOLUTION]]. +All conformant DID resolvers MUST implement the DID resolution function +for at least one DID method and be able to return a DID document in +at least one conformant representation. All conformant DID URL dereferencers +MUST implement dereferencing for at least one conformant representation type.
++The DID resolution function resolves a DID into a DID document +by using the "Read" operation of the applicable DID method. (See .) +The details of how this process is accomplished is outside the scope of this +specification, but all implementations MUST implement a function in the form: +
+ +
+resolve ( did, input-metadata ) -> ( did-document, did-document-metadata, did-resolution-metadata )
+
+The inputs of this function are a DID and a set of input metadata. The +DID is REQUIRED. Note that if the caller of this function wishes to resolve a DID URL, +the caller MUST first transform the DID URL into a bare DID, +including removal of any fragment. The input metadata are a map of key-value +string pairs as described in . +The input metadata are REQUIRED but the map MAY be empty. Concrete bindings MUST NOT +define additional inputs to this function. +
+ ++The possible keys for the input metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRY]]. This specification +defines the following keys and values: + +
+The DID resolver executes the "Read" operation of the DID method as described in +. If successful, the outputs of this function MUST contain a DID document, +a set of metadata for the DID document (which MAY be empty), and a set of metadata for the resolution process. If +the function results in an error, the outputs MUST contain a set of metadata for the resolution process. +
+ ++The DID document is returned as a byte stream of a conformant representation +as determined and supported by the DID resolver. The caller of the DID resolution function +can then parse and process the DID document from this byte stream. The DID document is +REQUIRED unless an error is returned by the DID resolution function. +
+ +
+When a DID document is returned, the DID document metadata is returned as a map of
+key-value string pairs as described in . This metadata
+contains information about the input DID and the returned DID document. This metadata
+typically does not change between invocations of the DID resolution function. The keys and
+possible values for this metadata are defined in the DID Core Registry [[?DID-CORE-REGISTRY]].
+The DID Document metadata MAY be empty.
+
+The contents of the DID document metadata still needs to be defined within this document. +
+ +
+The DID resolution metadata is returned as a map of key-value string pairs as described in
+. This metadata contains information about the results of
+the resolution process. This metadata typically changes between invocations of the DID resolution
+function. The keys and possible values for this metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRY]]. This
+specification defines the following keys and values:
+
+
+The DID URL dereferencing function dereferences a DID URL into content +represented by that DID URL based on the DID document represented by +the DID within the DID URL. This content MAY be a DID document, a +portion of a DID document, a service endpoint, or some other data. The details of the implementation of this function +are outside the scope of this specification, but all implementations MUST provide +a function of the following form: +
+ +
+dereference ( did-url, input-options ) -> ( content, did-document-metadata, did-dereference-metadata )
+
+The inputs to this function are a DID URL and a set of input metadata. The +DID URL is REQUIRED and MAY be any valid DID URL, including a fragment. +The input metadata are a map of key-value string pairs as +described in . The input metadata are REQUIRED but +the map MAY be empty. Concrete bindings MUST NOT define additional +inputs to this function. +
+ ++The possible keys for the input metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRY]]. +
+ ++The DID URL dereferencer first MUST resolve the DID within the +DID URL into a DID document using a DID resolution process. +The DID URL dereferencer MUST parse the resulting DID document +from its conformant representation to allow for additional processing. +
+ +
+The DID URL dereferencer MUST perform any additional processing indicated
+by the DID URL, such as resolving a fragment into an element. If no additional processing is
+required by the DID URL, the DID document is returned as the
+content.
+
+The DID dereference metadata is returned as a map of key-value string pairs as described in
+. The metadata structure is REQUIRED and MUST NOT be empty.
+This metadata contains information about the results of
+the dereferencing process. This metadata typically changes between invocations of the DID URL dereferencing
+function. The keys and possible values for this metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRY]]. This
+specification defines the following keys and values:
+
+
+The content of this function's output is a byte stream of data. This byte stream MAY
+represent a DID document in a conformant representation, a portion of a DID document
+in a conformant representation, the results of calling a service
+endpoint, or something else determined by the DID method and its services.
+
+If the returned content is a DID document, the DID URL dereferencer MAY
+return an additional set of DID document metadata, as described in .
+
+Metadata structures are maps of key-value string pairs. All keys within this map +MUST be UTF-8 unicode strings. The keys of this map MUST NOT be repeated within +a given metadata structure. The keys of this map MUST be compared in a +case-insensitive way and the case MAY be transformed. The values of this map +MUST be retained as an exact string without transformation. +
+ ++All bindings MUST provide a way for the caller of the function to input or +receive the map of key-value string pairs as described in this specification. The +exact representation of these metadata structures as part of a protocol or serialization +is out of scope for this specification. For example, an HTTP-based binding can +use HTTP headers of an HTTP request to convey input metadata and HTTP headers of an +HTTP response to convey document and resolver metadata. Alternatively, a fully +JSON-based binding can use a JSON object to represent the metadata structures. +
+ +
+The keys and values MAY be transformed by the binding for transport
+in a deterministic and reversible fashion. For example, the content-type
+DID resolution metadata element could be represented as a text header
+in a binding:
+
+DID-CONTENT-TYPE: application/json+did
+
+In this example, the key content-type has had the string DID-
+prepended to it and the key text is uppercased. When returned from the function, this transformation
+would be reversed to provide the value application/json+did under the key
+content-type to the caller. Implementations of these functions MUST NOT
+require the caller to transform its inputs into the implementation's underlying
+transmission formats. In other words, the caller need not
+know the underlying representation of the metadata used by the implementation of
+the function in order to call the function.
+