Add initial content for DID Resolution. #247
Conversation
|
@jricher should also review this (for some reason I can't tag him as reviewer). |
|
Thanks @peacekeeper will give this a thorough review in the next few days. |
There was a problem hiding this comment.
I'm not convinced that simply making the reference to the DID-RESOLUTION doc informative goes far enough. These are normative sections of the core spec that set out an abstract model with multiple references in the text to "concrete methods are defined in [[?DID-RESOLUTION]]" (or words to that effect). If we really are to continue with what in my view is the nonsense of defining parameters and an abstract resolution model but not how to actually resolve DIDs then the resolution doc needs to be referenced very sparingly. I suggest all references in the current proposed text be removed and somewhere suitable found to say, in an informative section, that further work on resolution has been done and then point to the spec there. As it stands we have the worst of all worlds:
- here are the things a resolver must do
- here are the things a resolver can do
- over there is a doc that describes stuff that for arcane reasons we're not allowed to put in here but is the de facto standard so you may as well go and do that.
If we're only defining abstract things then it must be possible to build a resolver that doesn't follow the DID-resolution doc. If that's not possible then we need to be honest and put the resolution doc on the Rec track.
So, sorry, I don't approve of this PR. Not because Markus hasn't done an excellent job (he has), but because the task set is all-but impossible.
Co-Authored-By: Brent <[email protected]>
|
From a pure standards perspective, it's impossible to have a normative section refer to an informative reference - because that act of referring to a reference from a normative section is what makes it a normative reference (not what section of the standard you list it in). |
+1, to referring to another document wrt. Resolution. This PR is definitely not what I had in mind when we had the discussion at the F2F... the PR contains large swaths of what looks like semi-normative language about DID Resolution. Yes, I understand "it's just a contract", but having looked over the PR, it raises more questions than it answers and will lead to months of discussion around Resolution where we're not even done with the core spec yet. -1 to this PR as written. I will try to go through later and provide more constructive input/feedback. |
Co-Authored-By: Brent <[email protected]>
|
I've added my own suggested changes on top of @peacekeeper 's here: peacekeeper#1 |
… made conten-type required
Co-Authored-By: Brent <[email protected]>
peacekeeper
force-pushed
the
peacekeeper-add-did-resolution
branch
from
528ee65 to
9f4ba57
Compare
|
I'm having trouble understanding how this PR moves forward... There appear to be 2 paths being proposed:
I agree with @philarcher on this one... we have the worst of both worlds. IMO, the best path forward is to remove all normative statements, and make it clear that this is just informative, and implementers can do whatever they want... I think we can expect continued objections to normative statements about resolution, from multiple companies... This is clearly scope creep. We already tripled the number of representations thanks to the last face to face... if this push to comprehend resolution normatively in did core is a result of that decision (which I suspect it is), then maybe that decision needs to be re-evaluated... we can't keep adding scope... |
| Common fields are included here. Additional <a>resolver options</a> MAY be method-independent or method-specific. | ||
| </p> | ||
| <p> | ||
| The concrete representation of <a>resolver options</a> MUST be defined by the applicable <a>binding</a> of |
There was a problem hiding this comment.
I object to the use of normative language.
|
To be clear, I feel like we either need to recharter to include resolution, or make no normative statements about it. |
Well, -1 to this, we should point implementers to the DID Resolution spec and tell them that they should track that and must eventually be conformant with it. We can give implementers a heads-up on the expected trajectory, which I don't think is controversial.
Yes, +1 to this, more specifically, I think this might work:
I think the majority of the -1 positions on this PR might be because it feels like we're expanding scope in order to say normative things about the DID Resolution process. |
|
I'd be a lot happier if all the text around resolution were made informative. It could be prefaced with comments that (in better language) conveyed that this was future work but here are some ideas that we hope to standardise soon. You can track this work at [DID-RESOLUTION]. It's the multiple instances of an informative reference in the normative text that I find so wrong. You don't find out that it's informative until you go to the references section and see that it's in an informative list - who's going to see that? The current method de facto makes the DID-resolution doc normative. The reason I'm so exercised by this is that I've just been down a very similar path. Version 1.0 of a spec I worked on did exactly that - provided normative text about an identifier mechanism with informative text about future work. Version 1.1 included all the normative definition of a resolver. And I get hung up on W3C process :-) (old habits and all that) |
|
This issue was discussed in a meeting.
View the transcriptDID Resolution Contract PRMarkus Sabadello: PR about DID Resolution: #247 Markus Sabadello: Just pasted link to new PR about DID Resolution, based on two action items, two topics that came out of F2F meeting… one of the topics was DID Resolution, general sense at F2F meeting that some parts of what is currently covered by DID Resolution spec, not in DID WG in CCG, that some content from that document should be in scope for DID Core spec. … Interface, DID Resolution… what are inputs, outputs, data structures that we want. From time to time we’ve had discussions in DID Core spec instead of DID Resolution in more detail. What’s the point of defining DID Parameters if you can’t do that in resolution? … The group wanted to include the contract… DID Resolution, Dereferencing… second topic at F2F is entire metadata discussion, when we have DID Documents but also have certain other pieces of data, didn’t know what to do with them, had this Google Doc at F2F meeting, collected properties, proofs, and other things, had ongoing discussion on go into DID Document or other data structures should go. … We’ve been trying to discuss what different buckets for those pieces of data should be. Markus Sabadello: #65 (comment) Markus Sabadello: This attempts to discuss metadata discussion and DID Resolution discussion, PR 247 - adds content to two sections in DID Core spec. … these sections have been empty to date, one of that section, DID Resolvers/Resolution - section 3 - overall architecture. Michael Jones: I wasn’t asking for a hand-crafted ical file, per se. I was asking for a working calendar invitation - to help all the WG members join the calls. Markus Sabadello: subsection called did resolvers/resolution - PR proposes content there - stating that DID Resolution isn’t a concrete protocol… abstract function that can be implemented in different ways - second section, filled by PR – section 10 … Resolution section has sections that PR adds, resolving a DID, dereferencing… PR doesn’t specify concrete data formats or protocols, abstract functions. Subsections about resolver options and metadata. Doesn’t try to define what data structures look like, JSON, CBOR, how do you express metadata in concrete network protocol, PR doesn’t say that, just says what buckets of metadata are and implements different ways. … There have already been two -1 comments, suggestions, justin added some fixes/improvements that I’ve incorporated. … given that it’s significant to input to spec, it would be good to have more discussion and review. Drummond Reed: Nice work, Markus! Daniel Burnett: This document is a starting strawman just to get discussion going Phil Archer: I see text like Implementation details and a concrete algorithm for this function can be found in [[?DID-RESOLUTION]]. Phil Archer: If I were Ivan, I wouldn’t let this PR happen - there are multiple sections that are normative in core spec that talk about resolver as this as input, that as output, that’s very close to a specification. … As copy in there, it talks about non-normative to normative pointer… we shouldn’t pretend that we’re not putting in details of resolution. I’m considering formal objection on this, it’s bad that we got into this state, either we make this normative, or it’s taken out. Justin Richer: From my perspective, this is really a good start at getting at things we talked about in AMS - it’s not fully polished, moving in right direction. Drummond Reed: I have to say I agree with Phil that we need to pull resolution into scope at some point. Justin Richer: I do think it’s viable to have the definitions of the functions in the spec w/o getting into the details. There are parts of this PR that go into too much detail, and parts that don’t go into enough detail. I’m trying to correct those w/ PRs. Think we can do a little bit more. … For example, a little too much said on “binding”. The notion of what a binding is and what a binding has to define is important, need that in order to reference this. I do think these bits should be normative - my suggestions was to make this stuff MUSTs instead of SHOULDs. Important to define what resolution output is combination of input+resolution output. … What I’m calling dereferencer/resolver, get metadata, expect it in a particular form. Markus Sabadello: Just to also confirm, this is meant to be a start - things to be improved, formal mistakes - non-normative section referencing normative section… trying to understand if this is completely wrong, workable, good direction? Should Resolution be completely out of scope? Or should it be in scope? … At F2F Meeting, thought we wanted something in between… what do we want? I don’t have a strong opinion, could work either way. Attempt to capture where consensus was. Brent Zundel: This is a good start, if you want tex to be different, propose different text. Orie Steele: We have a lot of open PRs with approvals… and a few old / stale PRs with changes requested… Manu Sporny: I think it’s a good start … I share phil’s concern and I also share justin’s concern … and I think that’s why we tried to do something in the middle … if we start talking in a strongly normative way about the resolution process I think that’s going to be a problem … resolution is not in scope for the wg … it’s not in our charter, I know some disagree … speaking as an editor, it expands our scope beyond what the group signed up to do … but at the same time I do agree that having some language in there to talk about resolution is helpful, as long as we don’t go too far down the normative rabbithole … there is also a strong argument for pointing to the did resolution spec in a non-normative way and saying you need to understand did resolution and this document explains it … we can’t use that language in the spec, i think phil would agree with that more? i would be more comfortable with that … to be clear, I think markus has done really good work, I don’t think the tetx is going to be destroyed, it’s just where should it belong … that’s going to be a discussion we end up having over the next couple of weeks … . I don’t think this needs to turn into an all or nothing thin … we just need to strike a balance … please put comments in the PR Kyle Den Hartog: Speaking from perspective on someone that’s implemented resolution, the thing I’ve cared about most is the contract – what should I be doing w/ the DID vs. DID URL, that’s why I liked how we were defining it w/ contract - question is: Why can’t we define contract to say “when you pass in DID, here’s what you get…” then change DID Resolution spec into an implementation guide. Daniel Burnett: Manu said some of what I wanted to, but we need to be careful about formally objecting. … I think we are having a proper discussion about what belongs in this group and what doesn’t, this PR is helping us have that discussion. … This PR is probably not going to make it in its current state, we’re not going to put in PR that violates charter… but we do want people to have a good discussion about this. Markus Sabadello: One quick detail, before I did this PR, we already agreed to restructuring of ToC - added two sections w/o adding content - overall architecture - new DID Resolution - please comment on PR, if you disagree on PR and content, or overall structure of spec. … Do we disagree w/ content, or having those sections at all. |
|
As mentioned on the call, for me as someone who's implemented a multi-did resolver, worked with the uniresolver, and worked with single implementation resolvers (ion resolve()) the thing I care about more when consuming any DID or DID-URL is "If I hand this DID/DID-URL to the resolve function, what can I expect back?" From an implementer's perspective, having consistency around the contract where I provide a DID-URL or DID and get back a DID Document, a DID Document with some metadata, or a subsection of a did document has proven to go a long way in terms of interoperability and the ability to support new did methods. This is irregardless of what's happening underneath. Personally, I don't care as long as I can go from What this means at a high level is that if we don't include the contract, results will diverge (they already do today which is difficult to work with) and I'll opt for not supporting did methods that don't match the pattern that I've already written the rest of my code around. This will then lead to 1 of 2 paths occurring I would conjecture.
Both seem like absolute pains that can be alleviated if we can at least get a contract. All the other details, while extremely useful for setting the mental model, are going to greatly differ depending on the properties and implementations of the verifiable data registry (e.g. DLT consensus, state proofs, transaction data) and haven't shown to have much commonality anyways. In other words, I'm greatly in favor of the direction of this PR, and I think we can avoid the "normative references informative" W3C process discussion by turning the "resolution spec" into a "resolution implementation guide" because the resolution algorithm becomes an implementation detail if we define the contract. |
|
Of course @kdenhartog "If I hand this DID/DID-URL to the resolve function, what can I expect back?" is exactly what everyone needs. Hence, IMO, we must have a normative document - a standard - that sets out exactly that. It's the mixing I don't like. Would it be possible to write code that implemented the contract but not the DID-resolution doc? If the DID-resolution doc were standardized one day, could it be any different from what it is now? I assume that the contract in the core spec constrains any future work on DID resolution to the point where what is already in that doc is, by necessity, the actual resolution standard. No, I don't write code that's useful to anyone and can't do what you're doing Kyle (I wish I could). However, as an AC Rep and former W3C team member, I can see that this half way house is a mess. |
@msporny what are you suggesting? Is it not the case that without normative language, implementers can do whatever they want? Isn't the purpose of is "RECOMMENDED" an option here or is that also normative? We should be crystal clear to implementers... I'm not seeing clarity here that is acceptable w.r.t. what this working group has taken on (we are not chartered for resolution). |
|
[I am not taking a position on the topic, just commenting on standards language]
Yes, that is indeed the case. If there is nothing normative the spells out how to do something, then implementers are free to do whatever they'd like. Even if you have something informative, the rule for writing a standard is "assume that a person will not read anything informative".
Correct.
RECOMMENDED is also normative (it's the W3C equivalent of ISO's
Then you need to put something in normative language, otherwise they are free to do whatever they want (as noted above). |
|
Seems to me, (I'll leave this upto @burnburn @brentzundel to make the official call) that at least a contract falls squarely in the realm of this charter, but I'm no expert on the nuances here in standards world. See section 1.8: https://www.w3.org/2019/09/did-wg-charter.html
This leaves me thinking we could get away with a few options (because I interpret this to mean we can define a contract):
Given 2 is a new idea, I think this is worth exploring for new reasons. The main one being it leaves the tricky bits to the method spec authors, which as far as I know are informative docs as well. I also think it falls squarely within the lines of what a good did method spec should define. After all, each method is essentially a "method" to go from a did or did-url to a did document, and the internal bits of how that achieved is vastly different for each method. With this in mind, I'm thinking option 2 is a bit more appealing because it brings the contract in, doesn't ignore the resolution method such that developers are left to do anything they wish, and helps keep the scope of the did-core spec narrow by leaving the rabbit holes to the did methods authors to resolve. Thoughts on this high level direction? |
I feel like we're already doing that mixing with did methods though, and it seems to be working out to a certain degree with evidence coming from the universal resolver.
Yeah, we commonly do this today on large software teams. It's commonly referred to as "mocking" the contract. In other words, the underlying bits don't work, but I can hardcode valid returned data to keep the work in other areas moving.
Yes, it greatly reduces the need for migration paths and support for legacy code if we can get the contract in this spec. This in turn reduces the complexity of the software, making it easier to manage, which is BCP when building security related software.
Please don't take my comment as a dismissal of your expertise @philarcher. It wasn't intended to, but after rereading it, I could see how it was interpreted that way. In fact, I consider your expertise and many others in this WG around standards to be incredibly valuable because I have very little experience in this space. In fact, I share your opinion that we should have chartered with did-resolution and it would have made work simpler. Given the situation we're in though, I was hoping my perspective may offer unique insights into the process in hopes that we can work with what we've got and keep plowing forward with a consensus shared by this group, to ultimately get to interoperable software sooner rather than later. |
|
A huge -1 to removing normative requirements around the DID resolution contracts and making this only informative. If we do that, we might as well remain silent on resolution entirely, which is the source of the mess we're trying to solve here. So to me, going informative-only is a complete non-starter. While I agree with @philarcher that we ought to have resolution fully in scope of this WG, I don't think we actually have to in order to have a workable system and useful normative requirements in the core document around resolution. I also think that the ultimatum language of "we must do resolution or we do nothing" is not helpful, as it's not looking toward other possible solutions beyond the all-or-nothing. While I'd love to fully pull resolution into scope, and I've made that argument with the chairs for many months now, I don't see it happening. But I think we can at least do something that makes this less of the proprietary black hole that it is today. The goal of the contracts is to provide something that developers on either side of the contract can count on to behave in a particular way. It doesn't dictate how that contract gets fulfilled. Could someone fulfill the did resolution contracts without actually doing "did resolution" as we define it? Yes, and that's a feature, if you ask me. It will allow an ecosystem of different approaches to develop but in a way that components are clearly defined and can count on each other to do specific things. We have DID's (and DID URLs) and DID Documents. This work is the first step of creating an abstraction layer between the two. Right now it's all hand-wavy magic beans, and you can't implement against magic beans. But if I tell you "you'll get a string (defined by this grammar over here) and a map of key-value string pairs, and you give back a byte stream (defined by a representation format here) and two maps of key-value string pairs". This is something that I can write against as a resolver implementer, and on the other side something I can write against as a client implementer. The current state of this work is bad, and we are trying to make it better. Right now we have a bunch of proprietary silos that have similar-looking things on either end of the process. We have zero interoperability, and no, implementing all the methods side by side is not interoperability. If we aren't aiming for interoperability, then what are we even doing in a working group? If we end up with lip-service compliance without any form of interoperability, then we will have failed as a community. |
Sounds like this discussion just became a special topic call. :) |
Nah. I find arguments put forward by @jricher and @kdenhartog compelling enough. I really don't like informative references in a normative section - that's really bad standards writing but if it's possible to throw away [DID-RESOLUTION] (not that I advocate that of course) and leave the normative stuff, the 'contract' in did-core, then, OK, that's a reasonable compromise. I will, however, undertake a PR to suggest that we take all the refs to [DID-RESOLUTION] out of the normative section and add in a mini informative section somewhere that links to it. That was suggested higher up this thread and seems to be acceptable to everyone?? |
|
@philarcher I am working on my own take on this topic and will submit under a new PR (I've been talking with @peacekeeper already about this, it's just not ready for public eyes yet). |
|
Good discussion, thanks for all the input. If there are formal mistakes, such as having an informal reference in a normative section, then of course that needs to be fixed! If this PR can be fixed, or if new PRs are raised that replace this one, great! One thing I'd like to know is whether we have second thoughts about the overall spec structure, which includes the two sections "3.4. DID Resolvers and DID Resolution" and "10. Resolution" (we already agreed on this structure at the F2F in Amsterdam), or if we're generally fine with having those sections but just need to work more on their content. I'd also like to continue to discuss this topic on tomorrow's DID Resolution spec call (in the CCG, not DID WG), for those who are available: https://docs.google.com/document/d/1qYBaXQMUoB86Alquu7WBtWOxsS8SMhp1fioYKEGCabE/ It may also help to review again some slides I presented a few weeks ago about the relationship between the two specs: https://docs.google.com/presentation/d/1Ccnbh_A53yzTyIIrw6ol_EakAliuo3MfxIFlGsaoKos/ |
|
I've taken the concepts from this pull request and made another pass at the content in a separate pull request, #253 |
|
Although I am commenting on the normative vs. non-normative aspect of the discussion, I do that with my W3C staff contact's hat down. (I.e., that this is not some sort of a formal W3C statement whether this PR should be allowed or not.) I think there are different aspects that we have to consider.
Personally, I do not see any issue with (1) or (2) above. Reading through the text (though I of course have no experience with DID method implementation) I do not see any dependency on the DID Resolution spec per se. (Obviously, the text should be carefully crafted to avoid any impression of dependency, but that is just an editorial issue.) Also, the contract statements are testable through a specific method implementations; ie, we can have a proper test suite as required for our CR phase later to prove that the contract specification is consistent and implementable. I think the real question is (3). For this, let me quote from what I see are the relevant part of the charter (I've removed the parts that are not relevant for the discussion):
I believe the relevant scope entry is (8). One could argue that the second part of (c) of the "out of scope" is relevant, but I do not really think it is: we are explicitly not talking about protocols here. It is of course true that these contracts are not explicitly listed in the scope section. But if, in the WG's judgement, such contracts are necessary for a proper DID Core specification, that is then all right: it is perfectly acceptable for a WG to introduce new notions and constructions if that is justified specification-wise. However, this is the text of the "law", a.k.a. the charter. There may be some issues with the intended spirit of it; I know there had been lots of discussions in the community about the ins and outs of the scope before the charter text became final, which are not necessarily well reflected in the text itself. (Caveat: I was not part of those discussions...). If in doubt, we may have to dig out the relevant discussion history to see whether we would indeed find ourselves in a "socially" dangerous territory. |
There was a problem hiding this comment.
Thanks @peacekeeper for getting this work going. It's a great first start to get the ball rolling and I can tell it definitely influenced @jricher PR. I found that this PR took more of an approach of describing a wholistic view of resolution, where as Justin's got straight to the point and defined what has to be done to be compliant. I would prefer to take some of the expressive points such as the definitions and examples and include them in Justin's PR and work from there. What's everyone's thoughts on that approach?
| (see Section <a href="#resolving-a-did"></a> and Section <a href="#dereferencing-a-did-url"></a>). | ||
| </p> | ||
| <p> | ||
| These abstract functions are implemented by <a>DID resolvers</a>. A <a>DID resolver</a> is invoked |
There was a problem hiding this comment.
I think the details from here down to line 692 are details that we could be removed from here, and would live better in an auxiliary document to this spec.
| <p class="info"> | ||
| This section defines the interfaces (or the "contracts") of the <a>DID resolution</a> | ||
| and the <a>DID URL dereferencing</a> functions, including their inputs and results. | ||
| For information about architectures, see Section <a href="#did-resolvers-and-did-resolution"></a>. |
There was a problem hiding this comment.
I'm of the opinion that it's best to avoid discussing or referencing to architecture docs in this spec. I think that comes down to an implementation detail that an implementer could choose. Alternatively if we decide to have a "resolution implementation guide" then this detail would fit well in there.
|
|
||
| <tr> | ||
| <td> | ||
| <code>did:example:1234/path</code><br> |
There was a problem hiding this comment.
I like the use of a few examples here.
| </table> | ||
|
|
||
| <p> | ||
| Implementation details and a concrete algorithm for this function can be found |
There was a problem hiding this comment.
I get the feeling getting into the implementation details here are going to be the sticky part and it's best to leave this as implied or move it to an auxiliary implementation document which doesn't make normative statements. This probably means we'd have to pull the details of the algorithm out I would suspect.
| </ul> | ||
|
|
||
| <p> | ||
| A <a>DID resolver</a> MAY support additional <var>resolver options</var>. |
There was a problem hiding this comment.
probably worth mentioning how they would go about this, and if we should use registries.
| While the concrete representation of metadata MAY be defined by the applicable <a>binding</a> of | ||
| the <a>DID resolution</a> or <a>DID URL dereferencing</a> function, the metadata | ||
| MUST be made available to the caller of the <a>DID resolution</a> or <a>DID URL dereferencing</a> | ||
| function as a map of associated plain string keys and values. |
There was a problem hiding this comment.
"plain string keys and values" => "key-value pairs". In the case of CBOR they wouldn't have strings and I think it could be confusing when considering the statements above about returning in a compliant format.
There was a problem hiding this comment.
The point is that the format on the wire is irrelevant. It would be returned to the client calling the function as a string and input as a string, or equivalent, regardless of how it's encoded underneath. You shouldn't have to know that CBOR tag "2" means "content-type", for example. The goal is to get away from the constraints and capabilities of different representations for the metadata bits. #253 tries to make this more explicit.
| data model for <a>DID documents</a> might define a special section of a document | ||
| structure that can contain metadata. In both cases, the DID resolver has to parse | ||
| whatever the representation is and make the metadata available as a map of associated | ||
| plain string keys and values. |
There was a problem hiding this comment.
plain string keys and values => key value pairs.
| <a>DID</a>. These systems are specified in the DID Resolution specification | ||
| [[DID-RESOLUTION]]. | ||
| A function that takes a <a>DID</a> plus additional options as input and returns a <a>DID document</a>, | ||
| plus optional metadata, as output. This function relies on the "Read" operation of the applicable |
There was a problem hiding this comment.
This definition looks good to me.
|
|
||
| <dd> | ||
| A function that takes a <a>DID URL</a> plus additional options as input and returns a <a>DID document</a>, | ||
| a part of a <a>DID document</a>, a service endpoint URL, or another resource, plus optional metadata, as output. |
|
@kdenhartog I'm happy to incorporate proposed changes into #253 where it makes sense. |
|
We discussed this pull request on the DID Resolution call yesterday, and we plan to close this one and continue the discussion on #253. Please comment there with anything from this pull request that needs to be captured or represented there. |
peacekeeper
added
the
pending close
Ok, thanks @peacekeeper - closing. |
Following discussions at the Amsterdam F2F meeting, the DID WG Meeting on 2020-03-10, and various DID Resolution Spec meetings, I had an action item to add initial content related to DID resolution to the DID Core Spec. This PR represents a first attempt to do that.
This is also related to the ongoing discussion about metadata.
This PR does the following:
Note that this PR does NOT do the following:
This references some new content about representations, introduced by @talltree in #241.
Addresses #198. May also address #65 and #203.
Related to #26, #27, #28.
Preview | Diff