From 46c4bb76b97fe2355b5e19e485d3b3c743b36ae5 Mon Sep 17 00:00:00 2001 From: Wayne Chang Date: Wed, 26 Aug 2020 11:59:07 -0400 Subject: [PATCH] Fill DID URL Dereferencing Section As per: https://github.com/w3c/did-core/issues/364 - Fill the DID URL Dereferencing section with abstract function, function parameters, return values, and their definitions, using language and format consistent to (and drawn from) the DID Resolution section. - Delegate the handling of DID URLs which are also DIDs to the DID Resolution process, thereby ensuring that DID URL Dereferencing is a superset of DID Resolution, just as DID URLs are a superset of DIDs. --- did-core/index.html | 185 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) diff --git a/did-core/index.html b/did-core/index.html index d426c88..beca33e 100644 --- a/did-core/index.html +++ b/did-core/index.html @@ -3376,6 +3376,191 @@

DID URL Dereferencing

+

+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, query parameters, +and fragment. When a DID URL is also a DID, this process + performs DID Resolution. The details of how this +process is accomplished are outside the scope of this specification, but all +conformant implementations MUST implement two functions which have the +following abstract forms: +

+ +

+dereference ( did-url, did-url-dereferencing-input-metadata )
+         -> ( did-url-dereferencing-metadata, content, content-metadata ) +

+ +

+The input variables of these functions MUST be as follows: +

+ +
+
+did-url +
+
+A conformant DID URL as a single string. This is the DID URL to dereference. +This input is REQUIRED. +
+
+did-url-dereferencing-input-metadata +
+
+A metadata structure consisting of input +options to the dereference function in addition to the did-url +itself. +Properties defined by this specification are in . +This input is REQUIRED, but the structure MAY be empty. +
+
+ +

+The output variables of these functions MUST be as follows: +

+ +
+
+did-url-dereferencing-metadata +
+
+A metadata structure consisting of values +relating to the results of the DID URL Dereferencing process. This +structure is REQUIRED and MUST NOT be empty. +Properties defined by this specification are in +. +If the dereferencing is not successful, this structure MUST contain an +error property describing the error. +
+
+content +
+
+If the dereferencing function was called and successful, this MUST +contain a resource corresponding to the DID URL. +Additionally, in the case that the DID URL is a DID, then this +MUST be a did-document as described in DID Resolution, +obtained through the resolution process. + +If the dereferencing is unsuccessful, this value MUST be empty. +
+
+content-metadata +
+
+If the dereferencing is successful, this MUST be a +metadata structure. This structure contains +metadata about the content. +Additionally, in the case that the DID URL is a DID, then this +MUST be a did-document-metadata as described in DID Resolution, +obtained through the resolution process. + +If the dereferencing is unsuccessful, this output MUST be an empty metadata structure. +
+
+ +

+DID URL Dereferencing implementations MUST NOT alter the signature of +these functions in any way. DID URL Dereferencing implementations MAY +map the dereference function to a method-specific internal +function to perform the actual DID URL Dereferencing process. DID +URL Dereferencing implementations MAY implement and expose additional +functions with different signatures in addition to the dereference +function specified here. +

+ +
+

+DID URL Dereferencing Input Metadata Properties +

+ +

+The possible properties within this structure and their possible values are defined by [[DID-SPEC-REGISTRIES]]. +This specification defines the following common properties. +

+ +
+
+accept +
+
+The MIME type the caller prefers for content. The DID URL +Dereferencing implementation SHOULD use this value to determine the +representation contained in the returned value if such a representation is +supported and available. This property is OPTIONAL. +
+
+
+ +
+

+DID URL Dereferencing Metadata Properties +

+ +

+The possible properties within this structure and their possible values are defined by [[DID-SPEC-REGISTRIES]]. +This specification defines the following common properties. +

+ +
+
+content-type +
+
+The MIME type of the returned content. +This property is REQUIRED if dereferencing is successful. +
+
+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 is a single keyword string. +The possible property values of this field are defined by [[DID-SPEC-REGISTRIES]]. +This specification defines the following error values: +
+
+invalid-url +
+
+The DID URL supplied to the DID URL Dereferencing function does not +conform to valid syntax. (See .) +
+
+unauthorized +
+
+The caller is not authorized to dereference this DID URL with +this DID URL dereferencer. +
+
+not-found +
+
+The DID URL dereferencer was unable to return the content +resulting from this dereferencing request. +
+
+
+
+ +
+ +
+

+DID URL Dereferencing Metadata Properties +

+ +

+The possible properties within this structure and their possible values are defined by [[DID-SPEC-REGISTRIES]]. +This specification defines the following common properties. +

+ +
+ +