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 #2) #286

Closed
wants to merge 10 commits into from
Closed

Add normative DID Resolution section. (option #2) #286

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
10 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
9a7cad0
Refactor Resolution PR into Resolution Algorithm with subsections.
msporny May 17, 2020
108da3d
Trivial nit wrt a reference
philarcher May 18, 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
201 changes: 201 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,196 @@ <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.
</p>

<section>
<h3>
Generic DID Resolution Algorithm
Copy link
Contributor

Choose a reason for hiding this comment

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

Is there a particular reason why we need the term "Generic" here, would "DID Resolution Algorithm" suffice?

Copy link
Contributor

Choose a reason for hiding this comment

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

@tplooker Actually, I am strong proponent of constantly reinforcing that the DID spec defines generic DID syntax and generic DID resolution because that makes it clear that it is up to DID method specifications to define specific DID syntax (their own method name and method-specific identifier) and specific DID resolution operations (how their specific DID method performs the CRUD operations). @rhiaro and I are trying to use the same "generic/specific" terminology in our rewrite of the frontmatter sections (PRs coming shortly).

</h3>

<p>
The generic DID resolution algorithm takes a <a>conforming DID</a>
Copy link
Contributor

Choose a reason for hiding this comment

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

Same comment w.r.t the above, about the usage of "Generic"

Copy link
Contributor

Choose a reason for hiding this comment

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

@tplooker See my reply above.

(<em>did</em>) and resolution options (<em>resolutionOptions</em>) as input and
produces a <a>conforming DID Document</a> (<em>didDocument</em>), DID Document
Metadata (<em>didDocumentMetadata</em>), and resolution metadata
(<em>resolutionMetadata</em>) as output.
<p>

<p>
Any errors encountered during the execution of this algorithm MUST be expressed
using the <strong>error</strong> property in <em>resolutionMetadata</em>.
</p>

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

<ol>
<li>
Ensure that the <em>did</em> conforms to <a href="#generic-did-syntax"></a>.
If the <em>did</em> does not conform, an <code>invalid did</code> error MUST be
returned.
</li>
<li>
Ensure that the each value in <em>resolutionOptions</em> conforms to <a
href="#resolution-options"></a>. If an option does not conform, an <code>invalid
resolution option</code> error MUST be returned.
</li>
<li>
Execute the <a>DID method</a>-specific "Read" operation, from the concrete
<a>binding</a>, as described in <a href="#read-verify"></a> using the
<em>did</em> and <em>resolutionOptions</em> as input. If the operation
operation is unsuccessful, a <code>resolution failure</code> error MUST be
returned.
</li>
<li>
If successful, store the resulting <a>DID document</a>
(<em>didDocument</em>), the DID Document Metadata
(<em>didDocumentMetadata</em>), and the resolution metadata
(<em>resolutionMetadata</em>).
</li>
<li>
Ensure that <em>didDocument</em> is a <a>conforming DID document</a>. If the
<em>didDocument</em> does not conform, an <code>invalid did document</code>
Copy link
Member

@kdenhartog kdenhartog May 18, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

Can we talk about what a "conforming" did document would be or would that fall out of scope? For example, would did:example:123 => { "@id":"did:example:456" } be consider valid even though the returned did document is valid, but doesn't match the input identifier?

Copy link
Member Author

@msporny msporny May 21, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

Can we talk about what a "conforming" did document would be or would that fall out of scope?

The specification defines what a "conforming DID Document" is... so yes, it's in scope.

For example, would did:example:123 => { "@id":"did:example:456" } be consider valid even though the returned did document is valid, but doesn't match the input identifier?

Per the current spec, it's invalid because of @id -- we don't allow that use because it goes against what the JSON-only folks want.

That the id doesn't map to the DID Document is valid as there is no normative requirement in the spec that states that the resulting DID Document MUST contain an id that matches the DID that was sent as the input of the DID Resolution process -- a DID Method can choose to give you back something totally different. I'm not saying that this is right or wrong... that's just what the spec states today, IIRC.

error MUST be returned.
</li>
<li>
Ensure that the each value in <em>didDocumentMetadata</em> conforms to
<a href="#did-document-metadata"></a>. If an option does not conform, an
<code>invalid did document metadata</code> error MUST be returned.
</li>
<li>
Ensure that the each value in <em>didResolutionMetadata</em> conforms to <a
href="#resolution-metadata"></a>. If an option does not conform, an
<code>invalid did resolution metadata</code> error MUST be returned.
</li>
<li>
Return the <a>conforming DID document</a> (<em>didDocument</em>), the DID
Document Metadata (<em>didDocumentMetadata</em>), and the resolution metadata
(<em>resolutionMetadata</em>).
</li>
</ol>
</section>

<section>
<h3>
Resolution Options
</h3>
<p>
This specification defines the following properties that can be passed as
resolution options into <a href="#generic-did-resolution-algorithm"></a>:
</p>

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

<p>
Additional properties that can be passed to the DID Resolution algorithm
are defined in the DID Core Registries [[?DID-CORE-REGISTRIES]].
</p>
</section>

<section>
<h3>
DID Document Metadata
</h3>

<p>
When a <a>DID document</a> is returned as a part of <a
href="#generic-did-resolution-algorithm"></a>, the corresponding metadata
associated with the <a>DID document</a> is also returned. This metadata
contains information about the input <a>DID</a> and the returned <a>DID
document</a>. The metadata typically does not change between invocations of the
<a href="#generic-did-resolution-algorithm"></a>. This section defines common
DID Document Metadata properties:
</p>

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

<p>
Additional DID Document Metadata properties can be found in
[[DID-CORE-REGISTRIES]].
</p>
</section>

<section>
<h3>
Resolution Metadata
</h3>

<p>
DID resolution metadata is returned as a part of the <a
href="#generic-did-resolution-algorithm"></a>. This metadata contains
information about the results of the resolution process and typically changes
between invocations of the <a href="#generic-did-resolution-algorithm"></a>.
</p>

<p>
This specification defines the following properties that can be passed as
resolution options into the <a href="#generic-did-resolution-algorithm"></a>:
</p>

<dl>
<dt>content-type</dt>
<dd>
The MIME type of the returned <a>conforming DID document</a>. The <a>DID
resolver</a> MUST provide this value when a <a>DID document</a> is returned. The
value MUST be used when determining how to parse and process the representation
returned by the <a href="#generic-did-resolution-algorithm"></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. Additional values for this field are defined
in 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>
Additional Resolution Metadata properties can be found in
[[DID-CORE-REGISTRIES]].
</p>
</section>
</section>

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

</section>

<section>
Expand Down