From 83e0c2e0e3c413f124ebbace5a99c191e2c243f9 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sun, 19 Apr 2020 22:08:44 -0400 Subject: [PATCH 01/10] Split Resolvers from Dereferencers. --- index.html | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/index.html b/index.html index 53d42641..ad8b3482 100644 --- a/index.html +++ b/index.html @@ -652,6 +652,10 @@

DID Resolvers

DID document (and associated metadata) as output in a process called DID resolution.

+ + +
+

DID Dereferencers

The inputs and outputs of the DID resolution process are defined in . Additional considerations for implementing a From fc7a867d7a47a278b4edbdf16fe7db53ea59217b Mon Sep 17 00:00:00 2001 From: Justin Richer Date: Mon, 20 Apr 2020 21:56:02 -0400 Subject: [PATCH 02/10] Add normative DID Resolution and DID URL Dereferencing sections. --- index.html | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 106 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index ad8b3482..eb65be7e 100644 --- a/index.html +++ b/index.html @@ -2694,23 +2694,128 @@

implementors are available 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. +

+

DID Resolution

+ +

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

+
accept
+
The MIME type of the preferred representation of the DID document. The DID resolver MAY + use this value to determine the representation of the returned DID document if such a + representation is supported and available.
+
+

+ + +

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

+
content-type
+
The mime-type of the returned conformant representation of the DID document if successful. + The DID resolver MUST supply this value when a DID document + is returned. The caller of the resolution function MUST use this value when determining how to + parse and process the byte stream returned by this function into + DID document.
+ +
error
+
The error code from the resolution process. The DID resolver MUST supply + this value when there is an error. The possible values + this field are defined by the DID Core Registry [[?DID-CORE-REGISTRY]]. This specification defines the following + error values: + +
+
invalid-did
+
The DID supplied to the DID resolution function does not + conform to valid syntax. (See .)
+ +
unauthorized
+
The caller is not authorized to resolve this DID with + this DID resolver.
+
+ +
+ +
+

+

DID URL Dereferencing

+

Metadata Structure

-

From 7229c50fc2e2770c3b3754d0b99f12393a819647 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Mon, 20 Apr 2020 22:43:26 -0400 Subject: [PATCH 03/10] Move DID Resolution conformance statements to conformance section. --- index.html | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/index.html b/index.html index eb65be7e..9d0ce419 100644 --- a/index.html +++ b/index.html @@ -739,6 +739,21 @@

Security and Privacy

when consuming non-conforming DIDs or DID Documents.

+

+A conforming DID resolver that is conformant with this specification +MUST be capable of performing the DID resolution process, as described in + for at least one DID method and MUST +return a conforming DID document in at least one conformant +representation. +

+ +

+A conforming DID URL dereferencer that is conformant with this +specification MUST implement the DID URL dereferencing process, as +described in for at least one conformant +representation. +

+
@@ -2694,13 +2709,6 @@

implementors are available 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. -

-

DID Resolution @@ -2739,7 +2747,6 @@

-

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, @@ -2816,6 +2823,7 @@

Metadata Structure

+

From 228f75b8eae6c3f060dff4a75199c5fd6915f6e4 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Mon, 20 Apr 2020 22:49:08 -0400 Subject: [PATCH 04/10] Add DID Core Registries bibliography entry. Fix broken references. --- common.js | 10 ++++++++++ index.html | 8 ++++---- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/common.js b/common.js index d275283a..dcdf5a80 100644 --- a/common.js +++ b/common.js @@ -41,6 +41,16 @@ var ccg = { status: "FPWD", publisher: "Verifiable Claims Working Group" }, + "DID-CORE-REGISTRIES": { + title: "Decentralized Identifier Core Registries", + href: "https://w3c.github.io/did-core-registries/", + authors: [ + "Orie Steele", + "Manu Sporny" + ], + status: "ED", + publisher: "Decentralized Identifier Working Group" + }, "DID-USE-CASES": { title: "Decentralized Identifier Use Cases", href: "https://w3c.github.io/did-use-cases/", diff --git a/index.html b/index.html index 9d0ce419..29657c76 100644 --- a/index.html +++ b/index.html @@ -2736,7 +2736,7 @@

-The possible keys for the input metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRY]]. This specification +The possible keys for the input metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRIES]]. This specification defines the following keys and values:

@@ -2766,7 +2766,7 @@

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]]. +possible values for this metadata are defined in the DID Core Registry [[?DID-CORE-REGISTRIES]]. The DID Document metadata MAY be empty.

@@ -2778,7 +2778,7 @@

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 +function. The keys and possible values for this metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRIES]]. This specification defines the following keys and values:
@@ -2792,7 +2792,7 @@

error
The error code from the resolution process. The DID resolver MUST supply this value when there is an error. The possible values - this field are defined by the DID Core Registry [[?DID-CORE-REGISTRY]]. This specification defines the following + this field are defined by the DID Core Registry [[?DID-CORE-REGISTRIES]]. This specification defines the following error values:
From 72fd3714abdb981ce74a8d1f188f92a21efc7780 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Mon, 20 Apr 2020 22:50:12 -0400 Subject: [PATCH 05/10] Fix additional broken references. --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 29657c76..e080485c 100644 --- a/index.html +++ b/index.html @@ -2767,7 +2767,7 @@

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-REGISTRIES]]. -The DID Document metadata MAY be empty. +The DID Document metadata MAY be empty.

From ad516a598099724dd8f6e8d8826d73c8a4a9e28d Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Mon, 20 Apr 2020 23:32:13 -0400 Subject: [PATCH 06/10] Editorial fixes to opening paragraph of DID Resolution. --- index.html | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index e080485c..28c5647c 100644 --- a/index.html +++ b/index.html @@ -2715,10 +2715,13 @@

-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: +The DID resolution process takes a DID and +resolution options as input, and produces a DID document and +resolution metadata as output. The process utilizes the "Read" operation of +the applicable DID method, as described in . +The DID method-specific details of how this process is accomplished is +outside the scope of this specification, but all implementations MUST implement +a function in the form:

From 7c3bca88cf9cd36ebe9ace895a8ecf7903f53472 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sat, 16 May 2020 14:20:39 -0400 Subject: [PATCH 07/10] Apply property name-value language from @jricher. Co-authored-by: Justin Richer --- index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index 28c5647c..6c846484 100644 --- a/index.html +++ b/index.html @@ -2739,8 +2739,8 @@

-The possible keys for the input metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRIES]]. This specification -defines the following keys and values: +The possible properties for the input metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRIES]]. This specification +defines the following keys and values for these properties:

accept
@@ -2766,7 +2766,7 @@

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 +name-value properties 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-REGISTRIES]]. @@ -2778,10 +2778,10 @@

-The DID resolution metadata is returned as a map of key-value string pairs as described in +The DID resolution metadata is returned as a map of name-value properties 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-REGISTRIES]]. This +function. The property names and possible values for this metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRIES]]. This specification defines the following keys and values:

From db85d42b1df17959dda7c5feebac93bb0e7055f8 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sun, 17 May 2020 15:33:37 -0400 Subject: [PATCH 08/10] Simplify conformance statements for resolution. --- index.html | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/index.html b/index.html index 6c846484..f196b6a7 100644 --- a/index.html +++ b/index.html @@ -740,19 +740,17 @@

Security and Privacy

-A conforming DID resolver that is conformant with this specification -MUST be capable of performing the DID resolution process, as described in - for at least one DID method and MUST -return a conforming DID document in at least one conformant -representation. +A conforming DID resolver MUST be capable of performing the DID +resolution process, as described in , for at +least one DID method and MUST return a conforming DID document in +at least one conformant representation.

-A conforming DID URL dereferencer that is conformant with this -specification MUST implement the DID URL dereferencing process, as -described in for at least one conformant -representation. -

+A conforming DID URL dereferencer MUST implement the DID URL +dereferencing process, as described in +for at least one conformant representation. +

From 9a7cad0c33cc47e7b835d16403f0de4bb01d07d5 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sun, 17 May 2020 17:52:41 -0400 Subject: [PATCH 09/10] Refactor Resolution PR into Resolution Algorithm with subsections. --- index.html | 231 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 157 insertions(+), 74 deletions(-) diff --git a/index.html b/index.html index f196b6a7..557c00e7 100644 --- a/index.html +++ b/index.html @@ -2713,104 +2713,187 @@

-The DID resolution process takes a DID and -resolution options as input, and produces a DID document and -resolution metadata as output. The process utilizes the "Read" operation of -the applicable DID method, as described in . -The DID method-specific details of how this process is accomplished is -outside the scope of this specification, but all implementations MUST implement -a function in the form: +The DID resolution process takes a DID and resolution options as +input, and produces a DID document and resolution metadata as output. The +process utilizes the "Read" operation of the applicable DID method, as +described in . The DID method-specific details +of how this process is accomplished is outside the scope of this specification.

-

-resolve ( did, input-metadata ) -> ( did-document, did-document-metadata, did-resolution-metadata ) -

+
+

+Generic DID Resolution Algorithm +

+ +

+The generic DID resolution algorithm takes a conforming DID +(did) and resolution options (resolutionOptions) as input and +produces a conforming DID Document (didDocument), DID Document +Metadata (didDocumentMetadata), and resolution metadata +(resolutionMetadata) as output. +

+ +

+Any errors encountered during the execution of this algorithm MUST be expressed +using the error property in resolutionMetadata. +

+ +

+When resolving a DID to a DID document, the following algorithm, +or one producing an equivalent result, MUST be used: +

+ +
    +
  1. +Ensure that the did conforms to . +If the did does not conform, an invalid did error MUST be +returned. +
    2. +
  2. +Ensure that the each value in resolutionOptions conforms to . If an option does not conform, an invalid +resolution option error MUST be returned. +
    3. +
  3. +Execute the DID method-specific "Read" operation, from the concrete +binding, as described in using the +did and resolutionOptions as input. If the operation +operation is unsuccessful, a resolution failure error MUST be +returned. +
    4. +
  4. +If successful, store the resulting DID document +(didDocument), the DID Document Metadata +(didDocumentMetadata), and the resolution metadata +(resolutionMetadata). +
    5. +
  5. +Ensure that didDocument is a conforming DID document. If the +didDocument does not conform, an invalid did document +error MUST be returned. +
    6. +
  6. +Ensure that the each value in didDocumentMetadata conforms to +. If an option does not conform, an +invalid did document metadata error MUST be returned. +
    7. +
  7. +Ensure that the each value in didResolutionMetadata conforms to . If an option does not conform, an +invalid did resolution metadata error MUST be returned. +
    8. +
  8. +Return the conforming DID document (didDocument), the DID +Document Metadata (didDocumentMetadata), and the resolution metadata +(resolutionMetadata). +
    9. +
+
+ +
+

+Resolution Options +

+

+This specification defines the following properties that can be passed as +resolution options into : +

+ +
+
accept
+
+The MIME type of the preferred representation of the DID document. The +DID resolver MUST use this value to generate the representation of the +returned DID document if such a representation is supported and +available. If the MIME type representation is not available, a DID +resolver SHOULD produce an alternate representation. +
+

-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. +Additional properties that can be passed to the DID Resolution algorithm +are defined in the DID Core Registries [[?DID-CORE-REGISTRIES]].

+
+ +
+

+DID Document Metadata +

-The possible properties for the input metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRIES]]. This specification -defines the following keys and values for these properties: +When a DID document is returned as a part of , the corresponding metadata +associated with the DID document is also returned. This metadata +contains information about the input DID and the returned DID +document. The metadata typically does not change between invocations of the +. This section defines common +DID Document Metadata properties: +

-
-
accept
-
The MIME type of the preferred representation of the DID document. The DID resolver MAY - use this value to determine the representation of the returned DID document if such a - representation is supported and available.
-
+

+The contents of the DID document metadata still needs to be defined within this document.

-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. +Additional DID Document Metadata properties can be found in +[[DID-CORE-REGISTRIES]].

+
+ +
+

+Resolution Metadata +

-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. +DID resolution metadata is returned as a part of the . This metadata contains +information about the results of the resolution process and typically changes +between invocations of the .

-When a DID document is returned, the DID document metadata is returned as a map of -name-value properties 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-REGISTRIES]]. -The DID Document metadata MAY be empty. +This specification defines the following properties that can be passed as +resolution options into the :

-

-The contents of the DID document metadata still needs to be defined within this document. -

+
+
content-type
+
+The MIME type of the returned conforming DID document. The DID +resolver MUST provide this value when a DID document is returned. The +value MUST be used when determining how to parse and process the representation +returned by the . +
-

-The DID resolution metadata is returned as a map of name-value properties 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 property names and possible values for this metadata are defined by the DID Core Registry [[?DID-CORE-REGISTRIES]]. This -specification defines the following keys and values: +

error
+
+The error code from the resolution process. The DID resolver MUST supply +this value when there is an error. Additional values for this field are defined +in the DID Core Registry [[?DID-CORE-REGISTRIES]]. This specification defines the +following error values:
-
content-type
-
The mime-type of the returned conformant representation of the DID document if successful. - The DID resolver MUST supply this value when a DID document - is returned. The caller of the resolution function MUST use this value when determining how to - parse and process the byte stream returned by this function into - DID document.
- -
error
-
The error code from the resolution process. The DID resolver MUST supply - this value when there is an error. The possible values - this field are defined by the DID Core Registry [[?DID-CORE-REGISTRIES]]. This specification defines the following - error values: - -
-
invalid-did
-
The DID supplied to the DID resolution function does not - conform to valid syntax. (See .)
- -
unauthorized
-
The caller is not authorized to resolve this DID with - this DID resolver.
-
- -
- +
invalid-did
+
+The DID supplied to the DID resolution function does not conform +to valid syntax. (See .) +
+ +
unauthorized
+
+The caller is not authorized to resolve this DID with this DID +resolver.
-

+
+
+

+Additional Resolution Metadata properties can be found in +[[DID-CORE-REGISTRIES]]. +

+
From 108da3d7d7093e6b38c1da7015b2341f31d58e6b Mon Sep 17 00:00:00 2001 From: Phil Archer Date: Mon, 18 May 2020 09:07:55 +0100 Subject: [PATCH 10/10] Trivial nit wrt a reference The reference to DID-RESOLUTION in line 1006 was only in single square brackets, not double. So this PR just doubles up those [] characters. --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 557c00e7..90e2c2c1 100644 --- a/index.html +++ b/index.html @@ -1003,7 +1003,7 @@

Generic DID URL Parameters

Additional considerations for processing these parameters are discussed in -[?DID-RESOLUTION]. +[[?DID-RESOLUTION]].