Add normative DID Resolution section. (option #1)

[msporny]

This PR adds the normative DID Resolution and DID URL Dereferencing sections to the specification.

This is a WIP, do not merge.

---

Preview | Diff

[philarcher]

This is the sort of thing that, IMO, cannot be allowed:

"The general process of DID resolution is described in § 10.1 DID Resolution . The details of implementing a DID resolver are described in the DID Resolution specification [DID-RESOLUTION]."

That's text in a normative section saying the details of how to implement this are in that document called DID-RESOLUTION. The fact that it's non-normative is completely hidden.

No.

Assume the DID-RESOLUTION doc doesn't exist. Write sections like this one to simply say "The general process of DID resolution is described in § 10.1 DID Resolution ."

Then have a separate short section called something like "Further steps on DID resolution and dereferencing" or whatever. Mark it as non-normative, and then say "further work has been done on this topic which does not form part of this specification. See [DID-RESOLUTION].

That makes a clear distinction between what is and isn't normative and that, IMO, is very necessary.

[jricher]

Some content and terminology changes suggested.

[jricher]

It's not a general process definition, suggest keeping original text and reverting this proposed change.

(Previous suggestion now OBE)

This section defines the inputs and outputs of the 
<a>DID resolution</a> and <a>DID URL dereferencing</a> functions. The
exact implementation of these functions is out of scope for this specification,
but some considerations for implementors are available in [[?DID-RESOLUTION]].

[jricher]

@philarcher Is this a better rewording of your concern? It's closer to my originally proposed text.

[philarcher]

I like this text, yes! Definite +1

[jricher]

Suggested change

	This section defines the general <a>DID resolution</a> and <a>DID URL
	dereferencing</a> processes. Implementers of <a>DID resolvers</a> and <a>DID
	Methods</a> are urged to read the DID Resolution specification
	[[?DID-RESOLUTION]] for details regarding the general processes described in
	this section.
	This section defines the inputs and outputs of the
	<a>DID resolution</a> and <a>DID URL dereferencing</a> processes. The
	exact implementation of this functionality is out of scope for this specification,
	but some considerations for implementors are discussed in [[?DID-RESOLUTION]].

[philarcher]

Again, happy with this.

[peacekeeper]

This is the sort of thing that, IMO, cannot be allowed: ...

@philarcher do you see anything wrong in this particular PR, if so, could you point to the specific line(s) that you think are problematic? Personally I think it was very useful how you originally raised your concerns about mixing normative and non-normative content, but I also believe that since then we've made good progress on separating them more clearly..

[philarcher]

@peacekeeper - Justin has suggested new text (which I think came from an earlier discussion we had on the other PR). I've indicated support for the changes he's made.

[OR13]

Make this not a draft, so that it has a chance of getting merged :)

[OR13]

@jricher I agree with your comments on the WG call, this should be merged IMO.

[dlongley]

Requiring the resolver to return the DID Document as "a byte stream" could be too prescriptive. Several existing DID Document resolvers don't do this today and we should ensure that we either:

1. Reflect reality, OR
2. Specify something existing DID resolver implementers are willing to change to.

[jricher]

@dlongley The goal is to say something that the resolve function gives you something that you can hand to a parse function. As per discussion last week, we might :also: want a function that's the equivalent of "Resolve and parse", where it returns the abstract data model. However, we need the underlying standalone "resolve" function before we can get there.

[OR13]

I think we need to define a byte stream version first, before we can build the higher layers, see:

interface mixin Body {
  readonly attribute ReadableStream? body;
  readonly attribute boolean bodyUsed;
  [NewObject] Promise<ArrayBuffer> arrayBuffer();
  [NewObject] Promise<Blob> blob();
  [NewObject] Promise<FormData> formData();
  [NewObject] Promise<any> json();
  [NewObject] Promise<USVString> text();
};

https://fetch.spec.whatwg.org/

[dlongley]

@jricher -- as long as whatever primitives we define can be sensibly mapped to existing resolvers (or those resolvers can be sensibly changed so that they map) I'm fine with what we do. I just want to make sure we don't overlook this and create something that simply doesn't work for the present implementation reality (the spec will just be ignored if we do that).

[dlongley]

@OR13,

The fetch spec's primitives work because they reflect the reality of how user agents are implemented. If there's no point at which there's a byte stream in DID resolver implementations, it gets weird to make that the base primitive. We don't want to create a situation where there is some other base primitive in reality that has to be converted to a byte stream to match the spec -- only to have it converted right back. This simply won't be done -- so we need to make sure that we don't create invalid primitives.

Another way of putting this is that there is no "byte stream" of a DID Document that some DID resolvers can go out and fetch from somewhere. Instead, they obtain N pieces of data related to the DID Document from M sources and then construct an "abstract DID Document" from that. Note that this constructed DID Document is not represented concretely as a byte stream ... ever. This means that the primitives for resolve as specified here don't match the lowest level implementation details of some DID resolvers. I'm happy for us to find a way around this that works for the design we're looking for, but we must consider how existing DID resolvers like this work if we're to understand the "lowest level primitives".

[jricher]

@dlongley It's entirely possible that not everyone's DID implementation is going to implement resolve(), and that's fine. For the world you're talking about, the entire representation of DID Documents doesn't matter, either, but we've already seen there's a clear appetite for having those representations defined.

[jricher]

@OR13 I did not create this PR, @msporny did, so I don't have control over whether or not it's a draft. I can re-create the content though and I'll do that against the current master branch before the next discussion call.

[OR13]

@msporny can you make this not a draft?

[OR13]

draft implies not ready for review / comments or feedback, and definitely not ready to be merged.

[jricher]

I intend to submit a new pull request to address this.

[msporny]

draft implies not ready for review / comments or feedback, and definitely not ready to be merged.

Hmm... draft just means "don't merge, needs discussion, PR may undergo many changes before it's ready for merge", from Github's press release on the topic:

https://github.blog/2019-02-14-introducing-draft-pull-requests/

I specifically marked these as such so that 1) @jricher (and others) didn't think that this was the final form, and 2) so that other editor's wouldn't accidentally merge it if it just sat there w/ multiple positive reviews.

I'm asserting that that's an appropriate use of Draft PRs... given that it matches the definition of people that created the feature. That said, if folks in the WG don't like Draft PRs, I can avoid doing those in the future... but it does signal the wrong thing (that the expectation is that the PR is done).

[OR13]

@msporny fair point, but if the PR is not done, what parts of it need to changed for it to be done, an how do reviewers help get it to done?

based on @jricher comments, and the editors call, I am assuming we want to do this in stages, so that the comments / feedback were more focused, and easier to get consensus on smaller things.

Thats why I am being a github pest, I'm trying to get something small related to resolution merged, so that we can focus the group on resolution in byte sized chunks...

I agree that multiple approaches / PRs can be helpful as part of a creative process, but it can also create https://en.wikipedia.org/wiki/Overchoice

This may also be a case where an outline of the plan of attack on issues, could have helped make smaller PRs that could be quickly merged... something like:

A. We define an abstract interface with types for did resolution.
B. We define an algorithm for how to combine the types form A to yield valid, representation or error codes.
C. We define more error codes
D. We add minimal normative text to support the interface, types, and transformations described previously.

We might choose to skip C, and tackle it later, we might not like the interface with have at A as the final one, and we might want to change the whole thing once we see it laid out.

Its important that we be ok saying "we didn't get this right the first time, and we can change it"... otherwise we will only ever do things once, and they will never be right... perfect is the enemy of good.

It seems like @peacekeeper @jricher and @msporny have all taken stabs at getting a PR for this that can be merged, if we had to merge one right now with no further changes, which one would it be? let's work together to get that one PR ready to merge.

[msporny]

@msporny fair point, but if the PR is not done, what parts of it need to changed for it to be done, an how do reviewers help get it to done?

Part of the concept of a Draft Pull request is saying "I don't know what parts need to be changed for this to be done." ... because, I don't know what I don't know. That's different from most PRs that Editors put together, where there is a pretty clear path forward proposed in an issue and the Editors push forward on that path.

That's not the case with this DID Resolution stuff... it's all new territory for the WG, and there are a myriad of opinions on what should be in scope and out of scope.

based on @jricher comments, and the editors call, I am assuming we want to do this in stages, so that the comments / feedback were more focused, and easier to get consensus on smaller things.

Yes, that much we have agreement on. However, as @jricher mentioned yesterday, the request from the Chairs/Editors is vague enough to give anyone working on the PR heartburn.

It seems like @peacekeeper @jricher and @msporny have all taken stabs at getting a PR for this that can be merged, if we had to merge one right now with no further changes, which one would it be?

I didn't raise this on the call yesterday, because I didn't want to kick off a meta discussion... but I think that this is fundamentally the wrong question and has a chilling effect on "moving fast". Here's why:

When you tell people to focus on one PR, you don't get to see alternatives quickly. Instead, the alternatives are painfully played out in a PR, where if the original PR submitter disagrees with the changes, the alternative never becomes realized. Think of it like "speculative execution for specs", often it's faster for a processor to execute all code paths and throw away the result of the code paths that ended up not being needed. That's what raising multiple PRs simultaneously does - it helps us see the possibilities faster and then collapse the options into a single, well-informed WG decision.

Instead, what we're doing now is:

1. Requesting that we all block on @jricher's PR, having given him some vague sense of what we'd like to see him write.
2. Change the working mode of the group to bottleneck on single PRs.
3. Increasing the possibility of there being objections to the single PR and that causing further delays, thus slowing the entire process down rather than speeding it up.

In short, your suggestion removed the WGs ability to do speculative branching... and we all know what that does to the overall performance of a processor. I'm not objecting because a few others seemed to agree with the direction and you seem to have a stronger opinion on the matter than I do. I'm merely highlighting why I don't think the strategy is healthy for a WG and may have the opposite effect than what you intended.

[msporny]

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