Define resolution function with data types

[jricher]

This adapts the DID Resolution functional definition defined by #253 into a single typed function with requirements for the function signature and implementation conformance.

This builds on #295.

---

Preview | Diff

[dlongley]

A valid DID resolver should have to implement "abstractResolve(did)". This abstract function can work across N different DID methods (N different DID Read operations). It should be described only in terms of abstract representations, not concrete ones. Additionally, a DID resolver may implement "concreteResolve(did)" which wraps "abstractResolve(did)" and outputs a DID Document (and whatever else) in a concrete representation. Note how all of this happens prior to any "parse" function that might be called after calling concreteResolve(did). I don't think "parse" is really even necessary at all here.

I think if we take this approach we can fix the conflation with the current "resolve" function mixing both abstract and concrete concepts (it needs to be split apart -- and it is insufficient to point at a particular DID Read operation as the only abstract part of this process).

[peacekeeper]

During the 2020-05-28 DID WG Topical Call (see minutes), we wanted to emphasize that we are only defining abstract functions, not their concrete implementation

[kdenhartog]

Do we want to specify whether it MUST be a DID URI or a DID URL here? In general, I've operated under the assumption resolution accepts only DID URIs and dereferencing accepts DID URLs.

[peacekeeper]

I don't think we're defining "DID URI" anywhere? Resolution takes a DID, dereferencing takes a DID URL.

[jricher]

Resolution always takes a DID.

[kdenhartog]

Just to clarify terminology first, when you're saying DID do you mean just did:example:123? That's what I meant by DID URI, so I think we'd be in alignment then. However, I found a case that would conflict with my original assumption. The case where we're referring to a specific version of a did document with the version query parameter could use some clarity for this.

For example, if I used did:example:123?version=1 would I need to parse version=1 from the identifier and pass that via the options then or could I pass the full DID URL with the version query parameter to the resolution function?

[peacekeeper]

@kdenhartog

would I need to parse version=1 from the identifier and pass that via the options then or could I pass the full DID URL with the version query parameter to the resolution function?

You can only pass a DID to resolve(). But you can pass a DID URL to dereference(). In that latter case, the DID parameters are parsed from the DID URL and then passed as did-resolution-input-metadata (aka "options") to resolve(), exactly like you said.

Example:

dereference(did-url="did:example:123?version=1", did-dereference-input-metadata=null)

will internally call

resolve(did="did:example:123", did-resolution-input-metadata=[version="1"])

See the first step in the DID URL Dereferencing algorithm section of the DID Resolution spec, which says this:

All generic DID parameters as well as method-specific DID parameters of the input DID URL MUST be passed as input metadata properties to the DID Resolution algorithm.

[msporny]

@jricher could you please process the comments from @peacekeeper so we can get this PR merged?

[peacekeeper]

@dlongley perhaps what you call abstractResolve() is really resolve(), and what you call concreteResolve() is actually dereference() ? If you try reading your own comment above with those terminology replacements, does it make sense to you?

This way, resolve() would return an abstract DID document (not a byte stream), and dereference() would return a concrete representation, which to me feels consistent with how URI dereferencing works in general.