Make DID Resolution section concrete and testable (abstract + Typescript). #592

msporny · 2021-02-02T22:47:37Z

This PR is intended to address issue #549 by adding to the abstract functions discussed in the DID Resolution and DID URL Dereferencing sections and describing potentially conforming expressions in Typescript as concrete, testable functions. The PR uses an Typescript interface to provide an example while keeping all of what we had before. It also tries to strike a balance by providing at least one concrete realization of the interface without preventing other concrete interfaces from being realized.

There are a LOT of reformatting changes in this PR, it might be best to look at the rendered preview for this PR.

Preview | Diff

peacekeeper · 2021-02-03T10:03:05Z

index.html

-(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 implement two functions which have the following abstract
+The <a>DID resolution</a> function resolves a <a>DID</a> into a <a>DID


Suggested change

The <a>DID resolution</a> function resolves a <a>DID</a> into a <a>DID

The <a>DID resolution</a> functions resolves a <a>DID</a> into a <a>DID

@peacekeeper --
If the functions are plural, the resolve should be singular.
If the function is singular, the resolves should be plural.

Please change resolves to resolve or switch functions back to function.

Fixed via a reword.

peacekeeper · 2021-02-03T10:05:51Z

index.html

-The <code>resolve</code> function returns the <a>DID document</a> in its
-abstract form.
-The <code>resolveRepresentation</code> function returns a byte stream of the
-<a>DID Document</a> formatted in the corresponding representation.


I suggest we don't remove this paragraph, as it was just added very recently by @shigeya in #560.

yes, please.

Done in 028302a.

peacekeeper · 2021-02-03T10:26:45Z

index.html

            </dd>
        </dl>

        <p>
-The output variables of these functions are as follows:
+The return value of <code>resolve()</code> is <dfn>Resolution</dfn> which is


As we discussed on yesterday's 2021-02-02 Topic Call, the resolution and dereferencing functions really return three separate values, rather than a single map with three properties. When you dereference an HTTP URL, the HTTP body (representation of a resource) and the HTTP headers are also separate things. RFC3986 says:

the most common form of URI dereference is "retrieval": making use of a URI in order to retrieve a representation of its associated resource [...] additional information might be supplied about the resource (resource metadata)

Having said that, concrete implementations e.g. in TypeScript may choose to return a single JSON object that contains all three return values, and we could add this as an example, similar to how in the DID Resolution spec we define a JSON-LD structure that can hold all three return values.

peacekeeper · 2021-02-03T10:32:25Z

index.html

+relating to the results of the <a>DID resolution</a> process. This structure is
+REQUIRED and MUST NOT be empty. This metadata is defined by
+<a href="#did-resolution-metadata"></a>. If the resolution is successful this
+structure MUST contain a <code>contentType</code> property containing the


This line and several others in the PR now still assume that there's only one function, but there are two. Returning the contentType property in the metadata only makes sense for the resolveRepresentation() function, not for resolve().

Fixed in latest commits.

peacekeeper · 2021-02-03T10:35:21Z

index.html

-This metadata typically changes between invocations of the
-<code>resolve</code> and <code>resolveRepresentation</code> functions as it
-represents data about the resolution process itself. Properties defined by


Is there a reason for removing this? This is meant to describe the difference between didResolutionMetadata and didDocumentMetadata.

peacekeeper · 2021-02-03T10:50:17Z

index.html

+specification defines the following common properties for a
+<dfn>ResolutionOptions</dfn> <a data-cite="INFRA#maps">map</a>:


Suggested change

specification defines the following common properties for a

<dfn>ResolutionOptions</dfn> <a data-cite="INFRA#maps">map</a>:

specification defines the following common properties for the

<dfn>options</dfn> <a href="metadata-structure">metadata structure</a>:

The naming in this section should be independent of the TypeScript example.

Removed all types and examples and approached testability through a "proof by construction" rather than by providing concrete examples.

peacekeeper · 2021-02-03T10:53:23Z

index.html

+specification defines the following common properties for a
+<dfn>DereferencingOptions</dfn> <a data-cite="INFRA#maps">map</a>:


Suggested change

specification defines the following common properties for a

<dfn>DereferencingOptions</dfn> <a data-cite="INFRA#maps">map</a>:

specification defines the following common properties for the

<dfn>options</dfn> <a href="metadata-structure">metadata structure</a>:

The naming in this section should be independent of the TypeScript example.

Removed all types and examples and approached testability through a "proof by construction" rather than by providing concrete examples.

msporny · 2021-02-06T17:32:47Z

Taking a new approach for testability in PR #601.

Closing this PR in favor of that one.

TallTed · 2021-02-08T15:26:31Z

index.html

+<code><a>equivalentId</a></code> property except: a) it is associated with a
+single value rather than a ordered set, and b) the <a>DID</a> is defined to be
+the canonical ID for the <a>DID subject</a> within the scope of the containing
+<a>DID document</a>.
+              </p>


Suggested change

<code><a>equivalentId</a></code> property except: a) it is associated with a

single value rather than a ordered set, and b) the <a>DID</a> is defined to be

the canonical ID for the <a>DID subject</a> within the scope of the containing

<a>DID document</a>.

</p>

<code><a>equivalentId</a></code> property except:

</p>

<ul>

<li>

<code><a>canonicalId</a></code> is associated with a single value rather

than an ordered set

</li>

<li>

the <a>DID</a> is defined to be the canonical ID for the <a>DID subject</a>

within the scope of the containing <a>DID document</a>

</li>

</ul>

TallTed · 2021-02-08T15:28:53Z

index.html

+<code>id</code> property value and that the <code><a>canonicalId</a></code>
+value is defined by the <a>DID Method</a> to be the canonical ID for the <a>DID
+subject</a> in the scope of the containing <a>DID document</a>. A
+<code><a>canonicalId</a></code> value MUST be produced by, and a form of, the


Suggested change

<code><a>canonicalId</a></code> value MUST be produced by, and a form of, the

<code><a>canonicalId</a></code> value MUST be produced by, and be a form of, the

TallTed · 2021-02-08T15:30:24Z

index.html

+as its primary ID value for the <a>DID subject</a> and treat all other
+equivalent values as secondary aliases (e.g. update corresponding primary


Suggested change

as its primary ID value for the <a>DID subject</a> and treat all other

equivalent values as secondary aliases (e.g. update corresponding primary

as its primary ID value for the <a>DID subject</a> and to treat all other

equivalent values as secondary aliases (e.g., to update corresponding primary

TallTed · 2021-02-08T15:34:53Z

bah. github brought this PR to me as if it hadn't been closed yet. obviously, ignore my last few suggestions here...

msporny added 12 commits February 1, 2021 15:45

Enable testing DID Resolution function by making it concrete.

f94c8b9

Define ResolutionResponse and ResolutionInputMetadata.

93e0911

Rename resolution input metadata to resolution options.

6c812a6

Refactor DID Resolver section.

db50e3e

Enable DID URL Dereferencing section to be testable.

8e28d06

Fix mismatched section tag in DID Resolution.

f476641

Add conformance class for DID resolver.

51dc50b

Convert WebIDL to Typescript interface example.

29d7d90

Fix did variable type in Typescript example.

91e2e37

Rename resolve to resolveRepresentation.

f8a8d97

Reintroduce abstract forms with Typescript example.

4709030

Add abstract form back into specification for dereferencing.

a936ae9

msporny requested review from brentzundel, jricher, OR13, peacekeeper and dlongley February 2, 2021 22:48

This was referenced Feb 3, 2021

Make DID Resolution section concrete and testable (WebIDL). #587

Closed

Make DID Resolution section concrete and testable (Typescript). #591

Closed

peacekeeper requested changes Feb 3, 2021

View reviewed changes

msporny added 10 commits February 5, 2021 17:56

Fix abstract definition of functions.

ec0046a

Change content-stream to contentStream.

0558f62

Remove parenthesis for resolve and resolveRepresentation.

a4e8ce5

Remove concrete interface examples.

ef39fb9

Remove dereferencing options map class.

685a769

Ensure testability of didDocument using proof by construction.

50de27f

Editorial fixes to improve readability for equivalentId.

e0da3b6

Add "At Risk" markers for equivalentId and canonicalId.

49b78c7

Update DID URL Dereferencing section to make it testable.

3c9730a

Ensure that Metadata Structure can be serialized into a testable form.

829a0bd

msporny added 2 commits February 6, 2021 12:12

Add feature at risk for nextVersionId and nextUpdate.

ea4b2ca

Add language from @shigeya back in.

028302a

msporny closed this Feb 6, 2021

msporny mentioned this pull request Feb 6, 2021

Concerns regarding testability of DID Resolution and Dereferencing #549

Closed

TallTed reviewed Feb 8, 2021

View reviewed changes

msporny mentioned this pull request Feb 11, 2021

Clean up DID Resolution section; enable testability via proof by construction #601

Merged

msporny deleted the msporny-issue-549-abstract-typescript branch February 21, 2021 21:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make DID Resolution section concrete and testable (abstract + Typescript). #592

Make DID Resolution section concrete and testable (abstract + Typescript). #592

msporny commented Feb 2, 2021 •

edited by pr-preview bot

Loading

peacekeeper Feb 3, 2021

TallTed Feb 4, 2021 •

edited

Loading

msporny Feb 6, 2021

peacekeeper Feb 3, 2021

shigeya Feb 4, 2021

msporny Feb 6, 2021

peacekeeper Feb 3, 2021

peacekeeper Feb 3, 2021

msporny Feb 6, 2021

peacekeeper Feb 3, 2021

peacekeeper Feb 3, 2021

msporny Feb 6, 2021 •

edited

Loading

peacekeeper Feb 3, 2021

msporny Feb 6, 2021

msporny commented Feb 6, 2021

TallTed Feb 8, 2021 •

edited

Loading

TallTed Feb 8, 2021

TallTed Feb 8, 2021

TallTed commented Feb 8, 2021

	The <a>DID resolution</a> function resolves a <a>DID</a> into a <a>DID
	The <a>DID resolution</a> functions resolves a <a>DID</a> into a <a>DID

		specification defines the following common properties for a
		<dfn>ResolutionOptions</dfn> <a data-cite="INFRA#maps">map</a>:

		specification defines the following common properties for a
		<dfn>DereferencingOptions</dfn> <a data-cite="INFRA#maps">map</a>:

	<code><a>canonicalId</a></code> value MUST be produced by, and a form of, the
	<code><a>canonicalId</a></code> value MUST be produced by, and be a form of, the

		as its primary ID value for the <a>DID subject</a> and treat all other
		equivalent values as secondary aliases (e.g. update corresponding primary

Make DID Resolution section concrete and testable (abstract + Typescript). #592

Make DID Resolution section concrete and testable (abstract + Typescript). #592

Conversation

msporny commented Feb 2, 2021 • edited by pr-preview bot Loading

Choose a reason for hiding this comment

TallTed Feb 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

msporny Feb 6, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

msporny commented Feb 6, 2021

TallTed Feb 8, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TallTed commented Feb 8, 2021

msporny commented Feb 2, 2021 •

edited by pr-preview bot

Loading

TallTed Feb 4, 2021 •

edited

Loading

msporny Feb 6, 2021 •

edited

Loading

TallTed Feb 8, 2021 •

edited

Loading