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

Allow resolve() to return abstract DID document (option 1) #322

Closed
wants to merge 4 commits into from
Closed

Allow resolve() to return abstract DID document (option 1) #322

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e54958a
Define property values for metadata input and output structures of re…
jricher May 27, 2020
0d2e934
Make resolution abstract, make dereferencing concrete.
peacekeeper Jun 16, 2020
8d37e45
Fix references to DID-SPEC-REGISTRIES.
peacekeeper Jun 16, 2020
b854ce0
Additional minor improvements to resolution and dereferencing.
peacekeeper Jun 16, 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
271 changes: 260 additions & 11 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2995,7 +2995,8 @@ <h1>

<p>
All conformant <a>DID resolvers</a> MUST implement the <a>DID resolution</a>
function for at least one <a>DID method</a> and MUST be able to return a <a>DID
function for at least one <a>DID method</a>. All conformant
<a>DID URL dereferencers</a> MUST be able to return a <a>DID
document</a> in at least one conformant representation.
</p>

Expand All @@ -3013,7 +3014,7 @@ <h2>

<p><code>
resolve ( did, did-resolution-input-metadata ) <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-&gt; ( did-resolution-metadata, did-document-stream, did-document-metadata )
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-&gt; ( did-resolution-metadata, did-document, did-document-metadata )
</code></p>

<p>
Expand All @@ -3034,7 +3035,9 @@ <h2>
<dd>
A <a href="metadata-structure">metadata structure</a> consisting of input
options to the <code>resolve</code> function in addition to the <code>did</code>
itself. This input is REQUIRED, but the structure MAY be empty.
itself.
Properties defined by this specification are in <a href="#did-resolution-input-metadata-properties"></a>.
This input is REQUIRED, but the structure MAY be empty.
</dd>
</dl>

Expand All @@ -3052,17 +3055,16 @@ <h2>
REQUIRED and MUST NOT be empty. This metadata typically changes between
invocations of the <code>resolve</code> function as it represents data about the
resolution process itself.
Properties defined by this specification are in <a href="#did-resolution-metadata-properties"></a>.
If the resolution is not successful, this structure MUST contain an <code>error</code> property describing the error.
</dd>
<dt>
did-document-stream
did-document
</dt>
<dd>
If the resolution is successful, this MUST be a byte stream of the resolved
<a>DID document</a> in one of the conformant <a href="#representations">representations</a>. The byte
stream MAY then be parsed by the caller of the <code>resolve</code> function
into a <a>DID document</a> abstract data model, which can in turn be validated
and processed. If the resolution is unsuccessful, this value MUST be an empty
stream.
If the resolution is successful, this MUST be a <a>DID document</a> conforming to
the abstract data model, which can be validated and processed.
If the resolution is unsuccessful, this value MUST be empty.
</dd>
<dt>
did-document-metadata
Expand All @@ -3071,11 +3073,12 @@ <h2>
If the resolution is successful, this MUST be a <a
href="metadata-structure">metadata structure</a>. This structure contains
metadata about the <a>DID document</a> contained in the
<code>did-document-stream</code>. This metadata typically does not change
<code>did-document</code>. This metadata typically does not change
between invocations of the <code>resolve</code> function unless the <a>DID
document</a> changes, as it represents data about the <a>DID document</a>. If
the resolution is unsuccessful, this output MUST be an empty <a
href="metadata-structure">metadata structure</a>.
Properties defined by this specification are in <a href="#did-document-metadata-properties"></a>.
</dd>
</dl>

Expand All @@ -3089,12 +3092,258 @@ <h2>
function specified here.
</p>

<section>
<h3>
DID Resolution Input Metadata Properties
</h3>

<p>
The possible properties within the <code>did-resolution-input-metadata</code> structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
</p>
</section>

<section>
<h3>
DID Resolution Metadata Properties
</h3>

<p>
The possible properties within the <code>did-resolution-metadata</code> structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
This specification defines the following common properties.
</p>

<dl>
<dt>
error
</dt>
<dd>
The error code from the resolution process.
This property is REQUIRED when there is an error in the resolution 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:
<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>
<dt>
not-found
</dt>
<dd>
The <a>DID resolver</a> was unable to find a <code>did-document</code>
for this resolution request.
</dd>
</dl>
</dd>
</dl>

</section>

</section>

<section>
<h2>
DID URL Dereferencing
</h2>
<p>
The <a>DID URL dereferencing</a> function dereferences a <a>DID URL</a> into content
identified by that <a>DID URL</a>. This content MAY be a <a>DID document</a>, a
portion of a <a>DID document</a>, a service endpoint, or some other data.
The <a>DID URL dereferencer</a> first MUST resolve the <a>DID</a> within the <a>DID URL</a> into a <a>DID document</a> using a <a>DID resolution</a> process.
The details of the implementation of this function
are outside the scope of this specification, but all implementations MUST implement
a function which has the following abstract form:
</p>

<p><code>
dereference ( did-url, did-url-dereference-input-metadata ) <br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-&gt; ( did-url-dereference-metadata, content-stream, did-document-metadata )
</code></p>

<p>
The input variables of this function MUST be as follows:
</p>

<dl>
<dt>
did-url
</dt>
<dd>
A conformant <a>DID URL</a> as a single string. This is the <a>DID URL</a> to dereference.
This input is REQUIRED.
</dd>
<dt>
did-url-dereference-input-metadata
</dt>
<dd>
A <a href="metadata-structure">metadata structure</a> consisting of input
options to the <code>dereference</code> function in addition to the <code>did-url</code>
itself.
Properties defined by this specification are in <a href="#did-url-dereferencing-input-metadata-properties"></a>.
This input is REQUIRED, but the structure MAY be empty.
</dd>
</dl>

<p>
The output variables of this function MUST be as follows:
</p>

<dl>
<dt>
did-url-dereference-metadata
</dt>
<dd>
A <a href="metadata-structure">metadata structure</a> consisting of values
relating to the results of the <a>DID URL dereferencing</a> process. This structure is
REQUIRED and MUST NOT be empty. This metadata typically changes between
invocations of the <code>dereference</code> function as it represents data about the
dereferencing process itself.
Properties defined by this specification are in <a href="#did-url-dereferencing-metadata-properties"></a>.
If the resolution is successful, this structure MUST contain a <code>content-type</code> property containing the mime-type of the <code>content-stream</code> in this result.
If the resolution is not successful, this structure MUST contain an <code>error</code> property describing the error.
</dd>
<dt>
content-stream
</dt>
<dd>
If the dereferencing is successful, this MUST be a byte stream of the dereferenced
content. The content MAY be a <a>DID document</a> in one of the conformant
<a href="#core-representations">representations</a>. In this case, the byte
stream MAY then be parsed by the caller of the <code>dereference</code> function
into a <a>DID document</a> abstract data model, which can in turn be validated
and processed. If the dereferencing is unsuccessful, this value MUST be an empty
stream.
</dd>
<dt>
did-document-metadata
</dt>
<dd>
If the dereferencing is successful and the dereferenced content is a
<a>DID document</a>, this MUST be a <a href="metadata-structure">metadata
structure</a>. This structure contains
metadata about the <a>DID document</a> contained in the
<code>content-stream</code>. This metadata typically does not change
between invocations of the <code>dereference</code> function unless the <a>DID
document</a> changes, as it represents data about the <a>DID document</a>. If
the dereferencing is unsuccessful, or if the dereferenced content is not
a <a>DID document</a>, this output MUST be an empty
<a href="metadata-structure">metadata structure</a>.
Properties defined by this specification are in <a href="#did-document-metadata-properties"></a>.
</dd>
</dl>

<p>
<a>DID URL dereferencer</a> implementations MUST NOT alter the signature of this
function in any way. <a>DID URL dereferencer</a> implementations
MAY implement and expose additional
functions with different signatures in addition to the <code>dereference</code>
function specified here.
</p>

<section>
<h3>
DID URL Dereferencing Input Metadata Properties
</h3>

<p>
The possible properties within the <code>did-url-dereferencing-input-metadata</code> structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
This specification defines the following common properties.
</p>

<dl>
<dt>
accept
</dt>
<dd>
The MIME type of the caller's preferred representation of the <a>DID document</a> or other content identified by the <a>DID URL</a>. The <a>DID URL dereferencer</a> implementation
MAY use this value to determine the representation contained in the returned <code>content-stream</code> if such
a representation is supported and available. This property is OPTIONAL.
</dd>
</dl>
</section>

<section>
<h3>
DID URL Dereferencing Metadata Properties
</h3>

<p>
The possible properties within the <code>did-url-dereferencing-metadata</code> structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
This specification defines the following common properties.
</p>

<dl>
<dt>
content-type
</dt>
<dd>
The mime-type of the content in the returned <code>content-stream</code>.
This property is REQUIRED if dereferencing is successful and a <code>content-stream</code> is returned.
If the value of this property is the mime-type of one of the conformant <a href="#core-representations">representations</a> of a <a>DID document</a>,
then the caller of the <code>dereference</code> function MUST use this value when determining how to
parse and process the <code>content-stream</code> returned by this function into a
<a>DID document</a> abstract data model.
</dd>
<dt>
error
</dt>
<dd>
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:
<dl>
<dt>
invalid-did-url
</dt>
<dd>
The <a>DID URL</a> supplied to the <a>DID URL dereferencing</a> function does not
conform to valid syntax. (See <a href="#did-url-syntax"></a>.)
</dd>
<dt>
unauthorized
</dt>
<dd>
The caller is not authorized to dereference this <a>DID URL</a> with
this <a>DID URL dereferencer</a>.
</dd>
<dt>
not-found
</dt>
<dd>
The <a>DID URL dereferencer</a> was unable to find a <code>content-stream</code>
for this dereferencing request.
</dd>
</dl>
</dd>
</dl>

</section>

</section>

<section>
<h2>
DID Document Metadata Properties
</h2>

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

</section>

<section>
Expand Down