Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add normative DID Resolution section. (option #1) #263

Closed
wants to merge 8 commits into from
Closed

Add normative DID Resolution section. (option #1) #263

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
83e0c2e
Split Resolvers from Dereferencers.
msporny Apr 20, 2020
fc7a867
Add normative DID Resolution and DID URL Dereferencing sections.
jricher Apr 21, 2020
7229c50
Move DID Resolution conformance statements to conformance section.
msporny Apr 21, 2020
228f75b
Add DID Core Registries bibliography entry. Fix broken references.
msporny Apr 21, 2020
72fd371
Fix additional broken references.
msporny Apr 21, 2020
ad516a5
Editorial fixes to opening paragraph of DID Resolution.
msporny Apr 21, 2020
7c3bca8
Apply property name-value language from @jricher.
msporny May 16, 2020
db85d42
Simplify conformance statements for resolution.
msporny May 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions common.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/",
Expand Down
118 changes: 118 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -652,6 +652,10 @@ <h2>DID Resolvers</h2>
DID document</a> (and associated metadata) as output in a process
called <a>DID resolution</a>.
</p>
</section>

<section>
<h2>DID Dereferencers</h2>
<p>
The inputs and outputs of the <a>DID resolution</a> process are defined in
<a href="#did-resolution"></a>. Additional considerations for implementing a
Expand Down Expand Up @@ -735,6 +739,19 @@ <h2>Security and Privacy</h2>
when consuming non-conforming <a>DIDs</a> or <a>DID Documents</a>.
</p>

<p>
A <dfn>conforming DID resolver</dfn> MUST be capable of performing the <a>DID
resolution</a> process, as described in <a href="#did-resolution"></a>, for at
least one <a>DID method</a> and MUST return a <a>conforming DID document</a> in
at least one conformant representation.
</p>

<p>
A <dfn>conforming DID URL dereferencer</dfn> MUST implement the <a>DID URL
dereferencing</a> process, as described in <a href="#did-url-dereferencing"></a>
for at least one conformant representation.
</p>

</section>

<section>
Expand Down Expand Up @@ -2694,12 +2711,113 @@ <h1>
<h2>
DID Resolution
</h2>

<p>
The <a>DID resolution</a> process takes a <a>DID</a> and
resolution options as input, and produces a <a>DID document</a> and
resolution metadata as output. The process utilizes the "Read" operation of
the applicable <a>DID method</a>, as described in <a href="#read-verify"></a>.
The <a>DID method</a>-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:
</p>

<p>
<code>resolve ( did, input-metadata ) -> ( did-document, did-document-metadata, did-resolution-metadata )</code>
</p>

<p>
The inputs of this function are a <a>DID</a> and a set of input metadata. The
<a>DID</a> is REQUIRED. Note that if the caller of this function wishes to resolve a <a>DID URL</a>,
the caller MUST first transform the <a>DID URL</a> into a bare <a>DID</a>,
including removal of any fragment. The input metadata are a map of key-value
string pairs as described in <a href="#resolution-metadata"></a>.
The input metadata are REQUIRED but the map MAY be empty. Concrete <a>bindings</a> MUST NOT
define additional inputs to this function.
</p>

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

<dl>
<dt>accept</dt>
<dd>The MIME type of the preferred representation of the <a>DID document</a>. The <a>DID resolver</a> MAY
use this value to determine the representation of the returned <a>DID document</a> if such a
representation is supported and available.</dd>
</dl>
</p>

<p>
The <a>DID resolver</a> executes the "Read" operation of the <a>DID method</a> as described in
<a href="#read-verify"></a>. If successful, the outputs of this function MUST contain a <a>DID document</a>,
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.
</p>

<p>
The <a>DID document</a> is returned as a byte stream of a conformant representation
as determined and supported by the <a>DID resolver</a>. The caller of the <a>DID resolution</a> function
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requiring the resolver to return the DID Document as "a byte stream" could be too prescriptive. Several existing DID Document resolvers don't do this today and we should ensure that we either:

  1. Reflect reality, OR
  2. Specify something existing DID resolver implementers are willing to change to.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dlongley The goal is to say something that the resolve function gives you something that you can hand to a parse function. As per discussion last week, we might :also: want a function that's the equivalent of "Resolve and parse", where it returns the abstract data model. However, we need the underlying standalone "resolve" function before we can get there.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to define a byte stream version first, before we can build the higher layers, see:

interface mixin Body {
  readonly attribute ReadableStream? body;
  readonly attribute boolean bodyUsed;
  [NewObject] Promise<ArrayBuffer> arrayBuffer();
  [NewObject] Promise<Blob> blob();
  [NewObject] Promise<FormData> formData();
  [NewObject] Promise<any> json();
  [NewObject] Promise<USVString> text();
};

https://fetch.spec.whatwg.org/

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jricher -- as long as whatever primitives we define can be sensibly mapped to existing resolvers (or those resolvers can be sensibly changed so that they map) I'm fine with what we do. I just want to make sure we don't overlook this and create something that simply doesn't work for the present implementation reality (the spec will just be ignored if we do that).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@OR13,

The fetch spec's primitives work because they reflect the reality of how user agents are implemented. If there's no point at which there's a byte stream in DID resolver implementations, it gets weird to make that the base primitive. We don't want to create a situation where there is some other base primitive in reality that has to be converted to a byte stream to match the spec -- only to have it converted right back. This simply won't be done -- so we need to make sure that we don't create invalid primitives.

Another way of putting this is that there is no "byte stream" of a DID Document that some DID resolvers can go out and fetch from somewhere. Instead, they obtain N pieces of data related to the DID Document from M sources and then construct an "abstract DID Document" from that. Note that this constructed DID Document is not represented concretely as a byte stream ... ever. This means that the primitives for resolve as specified here don't match the lowest level implementation details of some DID resolvers. I'm happy for us to find a way around this that works for the design we're looking for, but we must consider how existing DID resolvers like this work if we're to understand the "lowest level primitives".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dlongley It's entirely possible that not everyone's DID implementation is going to implement resolve(), and that's fine. For the world you're talking about, the entire representation of DID Documents doesn't matter, either, but we've already seen there's a clear appetite for having those representations defined.

can then parse and process the <a>DID document</a> from this byte stream. The <a>DID document</a> is
REQUIRED unless an error is returned by the <a>DID resolution</a> function.
</p>

<p>
When a <a>DID document</a> is returned, the <code>DID document metadata</code> is returned as a map of
name-value properties as described in <a href="#resolution-metadata"></a>. This metadata
contains information about the input <a>DID</a> and the returned <a>DID document</a>. This metadata
typically does not change between invocations of the <a>DID resolution</a> 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.
</p>

<p class="issue" data-number="203">
The contents of the DID document metadata still needs to be defined within this document.
</p>

<p>
The <code>DID resolution metadata</code> is returned as a map of name-value properties as described in
<a href="#resolution-metadata"></a>. This metadata contains information about the results of
the resolution process. This metadata typically changes between invocations of the <a>DID resolution</a>
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:

<dl>
<dt>content-type</dt>
<dd>The mime-type of the returned conformant representation of the <a>DID document</a> if successful.
The <a>DID resolver</a> MUST supply this value when a <a>DID document</a>
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
<a>DID document</a>.</dd>

<dt>error</dt>
<dd>The error code from the resolution process. The <a>DID resolver</a> 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:

<dl>
<dt>invalid-did</dt>
<dd>The <a>DID</a> supplied to the <a>DID resolution</a> function does not
conform to valid syntax. (See <a href="#did-syntax"></a>.)</dd>

<dt>unauthorized</dt>
<dd>The caller is not authorized to resolve this <a>DID</a> with
this <a>DID resolver</a>.</dd>
</dl>

</dd>

</dl>
</p>

</section>

<section>
<h2>
DID URL Dereferencing
</h2>

</section>

<section>
Expand Down