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

Define resolution function with data types, property values, and full metadata structures, without transformation #300

Closed
wants to merge 6 commits into from
Closed

Define resolution function with data types, property values, and full metadata structures, without transformation #300

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8515500
Define simple type-less resolution function.
jricher May 27, 2020
7169f00
Add data types to all function inputs and outputs.
jricher May 27, 2020
b7699e0
Add requirements around signature for function.
jricher May 27, 2020
db3383d
Define property values for metadata input and output structures of re…
jricher May 27, 2020
1b2f152
Add simple definition for metadata structure.
jricher May 27, 2020
bd6f62c
Add requirements for metadata structure properties.
jricher May 27, 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
205 changes: 204 additions & 1 deletion index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2687,13 +2687,191 @@ <h1>
This section defines the inputs and outputs of the <a>DID resolution</a> and
<a>DID URL dereferencing</a> processes. The exact implementation of these
functions is out of scope for this specification, but some considerations for
implementors are available in [[?DID-RESOLUTION]].
implementors are discussed in [[?DID-RESOLUTION]].
</p>

<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 document</a> in
at least one conformant representation.
</p>

<section>
<h2>
DID Resolution
</h2>
<p>
The <a>DID resolution</a> function resolves a <a>DID</a> into a <a>DID document</a>
by using the "Read" operation of the applicable <a>DID method</a>. (See <a href="#read-verify"></a>.)
The details of how this process is accomplished are outside the scope of this
specification, but all conformant implementations MUST implement a function in the following form:
</p>

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

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

<dl>
<dt>
did
</dt>
<dd>
A conformant <a>DID</a> as a single string. This is the <a>DID</a> to resolve.
This input is REQUIRED.
</dd>
<dt>
did-resolution-input-metadata
</dt>
<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.
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>

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

<dl>
<dt>
did-resolution-metadata
</dt>
<dd>
A <a href="metadata-structure">metadata structure</a> consisting of values relating to the results of the <a>DID resolution</a> process.
This structure is 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 successful, this structure MUST contain a <code>content-type</code> property containing the mime-type <a>representation</a> of the <code>did-document-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>
did-document-stream
</dt>
<dd>
If the resolution is successful, this MUST be a byte stream of the resolved <a>DID document</a> in a single conformant <a>representation</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.
</dd>
<dt>
did-document-metadata
</dt>
<dd>
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 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>

<p>
<a>DID resolver</a> implementations MUST NOT alter the signature of this function in any way. <a>DID resolver</a>
implementations MAY map the <code>resolve</code> function to a method-specific internal function to perform the
actual <a>DID resolution</a> process. <a>DID resolver</a> implementations <a>DID resolver</a> implementations MAY implement
and expose additional functions with different signatures in addition to the <code>resolve</code> function specified here.
</p>

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

<p>
The possible properties within this structure and their possible values are defined by [[DID-CORE-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>. The <a>DID resolver</a> implementation
MAY use this value to determine the representation contained in the returned <code>did-document-stream</code> if such
a representation is supported and available. This property is OPTIONAL.
</dd>
</dl>
</section>

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

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

<dl>
<dt>
content-type
</dt>
<dd>
The mime-type of the returned conformant representation of the contained in the returned <code>did-document-stream</code>.
This property is REQUIRED if resolution is successful and a <code>did-document-stream</code> is returned.
The caller of the <code>resolve</code> function MUST use this value when determining how to
parse and process the <code>did-document-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 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 the DID Core Registry [[DID-CORE-REGISTRY]].
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 return the <a>DID document</a>
resulting from this resolution request.
</dd>
</dl>
</dd>
</dl>

</section>

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

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

</section>

</section>

<section>
Expand All @@ -2706,6 +2884,31 @@ <h2>
<h2>
Metadata Structure
</h2>

<p>
A <a href="metadata-structure">metadata structure</a> is a common and interoperable data structure used to
communicate information alongside a <a>DID</a> and <a>DID document</a>, and is specifically
used for the <a>DID resolution</a> function definition in this specification.
Use of a <a href="metadata-structure">metadata structure</a> is intended to compliment the information available
within a <a>DID</a> or <a>DID document</a>, and therefore is best suited to carrying
metadata as an input or output to the function process.
</p>

<p>
A <a href="metadata-structure">metadata structure</a> consists of a set of properties.
Each property has a single name and a single value.
The name of the property MUST be a single string.
Property names MUST be unique within a given set.
Each property name MUST map unambiguously to a single value within the set.
Property names MUST be compared by the exact byte value.
The value of a property MUST be a single string.
The value of a property MAY be an empty string.
Properties with null or equivalent values MUST be treated as
equivalent to omitted properties within a given set.
Property values MAY be repeated under different property names within a given set.
Property definitions MAY impose additional constraints on the property value, so long as
those constraints allow for unambiguous representation as a single string.
</p>
</section>

</section>
Expand Down