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

Jump to bottom

Define resolution function with data types and property values #297

Closed
wants to merge 4 commits into from
Closed

Define resolution function with data types and property values #297

Changes from all commits
Commits
Show all changes
4 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
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
180 changes: 179 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 )
Copy link
Contributor

Choose a reason for hiding this comment

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

Is this syntax for these functions described somewhere? Hard to tell looking at this if this can be an async function (in languages that do that). A JavasScript implementation would probably return a Promise here. Is the output a tuple or map with named properties? Seems kind of a fuzzy description for a "MUST". In the JSON-LD API spec we used WebIDL for these API descriptions. Has some rough edges but seemed to work good enough and has some respec support. The LoadDocumentCallback API has a similar pattern to this.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Those details depend on your language. It's pretty clear in any implementation what "call a function" and "return a value" mean, and it's different for each one.

Here, we're not specifying if it's synchronous or not, so a promise-based resolution would be fine. We're also not specifying how multiple outputs are returned, so a tuple, or an encapsulating object, or a bunch of pointers will all be fine.

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 it's confusing to use language like "all conformant implementations MUST implement a function in the following form". In a spec I read this as something strict. But here it involves guessing what the ad-hoc function call description means, and understanding it can be sync/async, use tuples, objects, or pointers (for parameters and results maybe?), and I'm guessing the actual names are not required either since many languages can't handle - in identifiers. What form is it that must be followed?

</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 Down