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 #299

Closed
wants to merge 7 commits into from
Closed

Define resolution function with data types, property values, and full metadata structures #299

Changes from all commits
Commits
Show all changes
7 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
72acb94
Add requirements for representation and transformation of metadata st…
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
228 changes: 227 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

Choose a reason for hiding this comment

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

What format is the did-resolution-metadata argument? (I assume the did-document-stream is in the format that the metadata specifies.)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The did-resolution-metadata is a map of strings. It's not in any particular serialized format as it's not expected to be parsed outside of this function, just read/used. This could be a javascript hash, a python dict, or a java Map<String, String>, or any number of other hash-table-style data structures that can store strings under unique string keys. The goal was to be a simple enough data structure that we wouldn't need to agree on a serialization format -- that's why it doesn't allow arrays, objects, numbers, or other things that would need serialization/parsing rules.

Copy link
Contributor

@dlongley dlongley May 29, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

I recommend we use the Infra spec to describe these types. That will keep them abstract (i.e., conceptual/defined only by their behavior) but clear. For example, here's the definition of a map.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That would be fine with me. I would suggest doing that kind of work as a separate pull request as it's more editorial at that point.

</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,54 @@ <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.
Copy link
Contributor

Choose a reason for hiding this comment

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

Properties must be able to be any JSON type - including arrays, booleans, objects, and yes strings.

OAuth metadata contains all of these. There's no reason to believe that DID metadata won't.

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>

<p>
Properties within a <a href="metadata-structure">metadata structure</a> MAY be represented by an
implementation in a variety of ways in an underlying protocol or system.
For example, an implementation could represent a <a href="metadata-structure">metadata structure</a> with
a set of HTTP-style headers, a JSON object, or an in-memory data map.
Implementations MUST NOT require callers of functions to know the details of the underlying representation
of the <a href="metadata-structure">metadata structure</a> in order to call the function.
</p>

<p>
Properties within a <a href="metadata-structure">metadata structure</a> MAY be transformed by an
implementation in order to facilitate their transmission in an underlying protocol or implementation.
Any transformations MUST be bidirectional and lossless.
Implementations MUST NOT expose these transformations to callers of the <a>DID resolution</a> function and
MUST NOT require callers of the <a>DID resolution</a> function to know about the transformations in order to call the function.
Comment on lines +2925 to +2927
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Suggested change
Any transformations MUST be bidirectional and lossless.
Implementations MUST NOT expose these transformations to callers of the <a>DID resolution</a> function and
MUST NOT require callers of the <a>DID resolution</a> function to know about the transformations in order to call the function.
Implementations MUST accept metadata properties by their registered names as inputs and MUST produce metadata properties by their registered names as outputs, regardless of any internal transformation that could occur within the implementation.

For example, an implementation could prepend the string <code>DID-Document-</code> to the names of all <a href="did-document-metadata-properties"></a>
Copy link
Contributor

Choose a reason for hiding this comment

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

I'm having trouble groking this section, and wording like:

"MUST NOT require callers of the DID resolution function to know about the transformations in order to call the function."

I feel like this language is not necessary, so long as the response interface is defined... callers are required to understand the interface... right?

As a DID Method author, I define support for JSON / CBOR / JSON-LD... resolve returns a representation (singular)... we believe that the representation can be transformed in a lossless bi-directional manner if we believe that the contract interface and registry are all that is needed to support that....This feels like we are now saying that DID Method implementers are responsible for ensuring that resolve supports all 3... instead of relying on the registry and the WG to make that transparent.... using post resolution middleware... in other words, all DID Methods are now required to produce all representations?...

I guess what I am trying to say is: "Any transformations MUST be bidirectional and lossless. "... I would like to see a proof that its possible for at least JSON /JSON-LD/CBOR, before I see normative text saying its a requirement... I'm not sure I believe its possible.... and if its not, then we will end with 3 non interoperable DID Representations... Yikes!

Copy link
Contributor Author

Choose a reason for hiding this comment

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

So this is the metadata, not the document itself. The metadata is not in JSON/CBOR/etc. The metadata is a map of strings: so a Javascript hash object, a python dict, a java Map<String, String>, etc.

The transformation in question here is to and from that data structure into whatever underlying format there needs to be. That's one of the reasons that I think it's important for the metadata structure to be a LIMITED data structure in terms of Map[String -> String] and not objects, arrays, numbers, or anything else. This is representable in any possible underlying system in a deterministic way.

The reversible transforms basically just means that if your protocol needs to use "DID-Resolution-Content-Type" to represent a field, you can't have someone call you with "DID-Resolution-Content-Type", you have to let them call you with "content-type", and you need to return "content-type" in the resulting map. This needs to be a strict requirement, but I'm struggling how to make it normatively enforceable. Thus the "MUST NOT expose" language above as an attempt to get to that.

I think a number of people are getting lost on this point, especially that the metadata is intended to be completely independent of the underlying representation. Is there a way to rephrase this to make it more clear what's going on here?

Copy link
Contributor

Choose a reason for hiding this comment

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

This sections feels to me like it's delving a little bit too deep into the internals of the resolve function. It seems out of scope of did-core.

if your protocol needs to use "DID-Resolution-Content-Type" to represent a field, you can't have someone call you with "DID-Resolution-Content-Type", you have to let them call you with "content-type", and you need to return "content-type" in the resulting map.

Understood. However, I still question its pertinence to did-core. This belongs in a transport-specific did-resolution spec.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I can see how it can be read that way, but that's not the intent. The intent isn't to describe how any mapping can happen, but instead put limits on what a mapping can do. The real requirement here is that if a property is named foo-bar, then I should be able to call this function with a property named foo-bar and get the expected behavior (defined by the property) regardless of how the implementation represents foo-bar under the hood. I'll put in an alternative phrasing for this requirement that might capture it better.

to differentiate them in its underlying protocol, but the caller of the <a>DID resolution</a> function would refer to them only by their defined
property names without the prefix.
The details of such transformations are method-specific and are outside the scope of this specification,
but considerations for implementors are discussed in [[?DID-RESOLUTION]].
</p>

</section>

</section>
Expand Down