Add normative DID Resolution section. (option #2)

[msporny]

This PR refactors PR #263 by doing the following things:

• Takes a less-prosey / more algorithmic approach to establish how the inputs are provided and checked to the DID Resolution process and how the outputs are received and validated from the DID Resolution process.
• Further aligns how properties defined in DID Core are reflected in DID Spec Registries.
• Splits the resolution options, DID document metadata, and resolution metadata sections into their own subsections and points to the DID Spec Registries in each to ensure the normative requirements flow down from the top-level algorithm.
• Uses stronger and more accurate, testable normative wording while clarifying and/or eliminating some redundant statements.

This is a WIP, do not merge.

Human readable preview is here:

https://pr-preview.s3.amazonaws.com/w3c/did-core/pull/286.html#did-resolution

---

Preview | Diff

[tplooker]

Is there a particular reason why we need the term "Generic" here, would "DID Resolution Algorithm" suffice?

[talltree]

@tplooker Actually, I am strong proponent of constantly reinforcing that the DID spec defines generic DID syntax and generic DID resolution because that makes it clear that it is up to DID method specifications to define specific DID syntax (their own method name and method-specific identifier) and specific DID resolution operations (how their specific DID method performs the CRUD operations). @rhiaro and I are trying to use the same "generic/specific" terminology in our rewrite of the frontmatter sections (PRs coming shortly).

[tplooker]

Same comment w.r.t the above, about the usage of "Generic"

[talltree]

@tplooker See my reply above.

[rhiaro]

Just a note that since @talltree and I have been working on the intro, we have moved the Architecture overview into a subsection of the Introduction.. which I think makes it non-normative. We keep the subsections for resolution and URL dereferencing; I've only been following the DID resolution discussion enough to know that there's a lot of tension around what is and isn't normative, so I'm mentioning this in case it being part of the intro changes the substance of the content added to the architecture section significantly. Perhaps something we just figure out once the intro editorial work is finished. (Or perhaps this doesn't matter at all :)

[peacekeeper]

Hmm I understand the goal is to have more testable wording, but this PR introduces an actual algorithm, when I thought the idea was to only define the contract/interface? Note that we already have such an algorithm in [[?DID-RESOLUTION]]: https://w3c-ccg.github.io/did-resolution/#resolving

[kdenhartog]

Can we talk about what a "conforming" did document would be or would that fall out of scope? For example, would did:example:123 => { "@id":"did:example:456" } be consider valid even though the returned did document is valid, but doesn't match the input identifier?

[msporny]

Can we talk about what a "conforming" did document would be or would that fall out of scope?

The specification defines what a "conforming DID Document" is... so yes, it's in scope.

For example, would did:example:123 => { "@id":"did:example:456" } be consider valid even though the returned did document is valid, but doesn't match the input identifier?

Per the current spec, it's invalid because of @id -- we don't allow that use because it goes against what the JSON-only folks want.

That the id doesn't map to the DID Document is valid as there is no normative requirement in the spec that states that the resulting DID Document MUST contain an id that matches the DID that was sent as the input of the DID Resolution process -- a DID Method can choose to give you back something totally different. I'm not saying that this is right or wrong... that's just what the spec states today, IIRC.

[jricher]

This is not a re-statement of the pull request in #263 or #253, it's more of an alternative approach. As such, there are several key gaps that I think still need to be addressed before this could be used.

• This PR places the burden on parsing and validation inside the resolution function. The original goal of the resolution function was to fetch a document, which would then be parsed and validated higher up the stack. Placing parsing internal to this draws the line in the wrong place.
• As a consequence of the above, this PR does not state that the document is returned as a byte stream, but instead as a "did document" which is a nebulous construct. This is not testable.
• This PR does not state that input options and output metadata are a common format, nor does it make any statement on what that format would be. If the representation of any of these is implementaiton specific or representation specific, then this cannot be interoperable.
• This PR backs off on several normative requirements around the behavior of the function in different situations.
• The algorithm introduced here steps too deeply into the Resolution territory without defining what an appropriate abstract interface to the resolution process would be. The original goal of the function definition was to provide just such an abstraction and this does not fulfill that goal.

I will say that this PR makes good progress on being more prescriptive of error handling and a couple other small items, but overall it is not moving in the right direction.

[peacekeeper]

@jricher I mostly agree with your points but am not sure about the first one. My understanding has also been that the resolve() function includes certain (method-independent) parsing and validation steps.

[jricher]

@peacekeeper Parsing and validation of the input DID and input options, yes. These need to be method-independent, for the sake of having a common function. But not parsing and validation of the output. It should generate valid output, but it shouldn't parse the document or output metadata. Otherwise, we can't define a method-independent way of describing the results of the function, and it's not meaningful.

[msporny]

Closing since the group is now converging on attempting to get PRs #295, #296, #297, #298, #299, and #300 into the spec.