search

w3c-ccg / did-spec

Please see README.md for latest version being developed by W3C DID WG.
https://w3c.github.io/did-core/
Other
124 stars 45 forks source link

Should the definition of a DID Reference be moved to the DID Resolution spec? #167

Closed mwherman2000 closed 5 years ago

mwherman2000 commented 5 years ago

Related to the discussion in https://github.com/w3c-ccg/did-spec/issues/151#issuecomment-461307974 (and the next 2 comments in that thread), should the definition of a DID Reference be removed from the DID spec and moved to the DID Resolution spec?

  1. There is already a more accurate, precise syntax for a DID Reference in the DID Resolution spec: https://w3c-ccg.github.io/did-resolution/#input-didreference

  2. The mission (charter?) of the current DID Resolution spec is given in the Introduction https://w3c-ccg.github.io/did-resolution/#introduction. It states...

    This specification defines common requirements, input parameters and output data, architectural options, and various considerations for the DID Resolution process.

Related issues:

mwherman2000 commented 5 years ago

In the inaugural DID Resolution community call today (Feb. 7, 2019), the general direction was for the detailed discussion of the DID Reference would best reside in the DID Resolution spec ...while DID References would only be referred to "conceptually" in the DID spec. To be continued...

mwherman2000 commented 5 years ago

Being discussed/answered here: https://github.com/w3c-ccg/did-resolution/issues/18#issuecomment-461663993

peacekeeper commented 5 years ago

@mwherman2000 , I feel pretty strongly that the syntax and meaning of a DID (Reference) should be defined in the main DID spec, whereas the DID Resolution spec should define how a DID (Reference) is used and processed during resolution (for example, how are path+query+fragment used to construct service endpoints).

This separation is parallel to the discussion we had about defining data model and format of a DID Document in the main DID spec, whereas the DID Resolution spec would define how a DID Document is constructed/retrieved/used during resolution.

Coincidentally, it looks like discussing the syntax will be on the agenda for the next regular CCG call: https://lists.w3.org/Archives/Public/public-credentials/2019Feb/0010.html

mwherman2000 commented 5 years ago

@peacekeeper There are two very separable concepts here:

  1. DID Document data/object model
  2. DID Resolution protocol syntax and semantics used to: a. Resolve a DID and return a DID Resolver Response containing a DID Document b. Access to the elements within a DID Document (in concordance with the DID Document data/object model)

These concepts shouldn't be scattered all of the place. There should be a coherent, understandable, explainable, justifiable pattern. What I'm hearing described on the this week's call and in your comment above doesn't meet any of these criteria.

There needs to be close correspondence between the DID Document data/object model and the DID Document Resolution protocol used to resolve a DID and, further, access the elements within a DID Document. I believe they're separate (the data/object model and the access protocol) but if they are not, then the DID Document data/object needs be moved to the DID Resolution spec (my original suggestion from this week's call).

I'm checking into the W3C charter document to see exactly how it is worded and how hamstrung we are in fixing the current situation.

mwherman2000 commented 5 years ago

Coincidentally, it looks like discussing the syntax will be on the agenda for the next regular CCG call: https://lists.w3.org/Archives/Public/public-credentials/2019Feb/0010.html

The agenda emailed out this evening says we're going to be discussing "an updated ABNF" ...it doesn't say mentioned the what/scope of the ABNF syntax either beforehand or at the start of the meeting. IMHO, we can't be jumped into details/implementation of the spec text when we don't even have a design/scope at this point.

mwherman2000 commented 5 years ago

RE: Scope of the Decentralized Identifier Working Group Charter

@peacemaker The scope of the Charter does not include protocols:

The Working Group will:

  1. Recommend a data model and syntax(es) for the expression of Decentralized Identifier Documents, including one or more core vocabularies.
  2. Recommend a way of authoring specifications for DID Methods and protocols that are conformant with the data model and syntax(es).
  3. Concentrate their efforts on the identified use cases with a particular focus on Identity and Access Management. Use cases from other industries may be included if there is significant industry participation.

This gives us the freedom to define the DID Document relevant protocols in the DID Resolution spec (per https://github.com/w3c-ccg/did-resolution/issues/18).

talltree commented 5 years ago

Michael, something that might shed clarity on all the questions you are asking is to explain that the model for the DID spec is in many ways the URI (Uniform Resource Identifier) spec, RFC 3986. https://www.ietf.org/rfc/rfc3986.txt. We have always wanted a DID to be a valid URI, so DIDs have to be valid according to the URI spec.

If you study the URI spec closely, you'll see that it defines the generic syntax for all URI schemes, but it doesn't define the concrete syntax for any specific URI scheme.

However it does define the ABNF for certain groupings of URI components, such as a URI reference (section 4.1). At the same time it does not define a specific protocol for resolving URI references because that specific protocol depends on the specific URI scheme.

That's the exact pattern we are following for DIDs:

  1. The DID spec defines the generic ABNF that must be used for all DID methods.
  2. Each DID method specification must then define its own specific ABNF (that conforms to the generic DID ABNF) and its own specific DID resolution protocol operations for that method.

In this light, I think we should refer to the spec being proposed here as the "Generic DID Resolution Specification" because, like the DID spec, it should cover all the generic features/requirements of DID resolution while leaving the specifics to DID method specifications.

mwherman2000 commented 5 years ago

If we're going to reference RFC 3986, we need to read, reference, and respect (r^3) the entire specification @talltree.

In section 1.2.2. Separating Identification from Interaction of RFC 3986, it states...

Given a URI, a system may attempt to perform a variety of operations on the resource, as might be characterized by words such as "access", "update", "replace", or "find attributes". Such operations are defined by the protocols that make use of URIs, not by this specification.

@talltree How do you interpret/want to apply the above paragraph Drummond?

For clarity, there needs to be two different and separate DID-related ABNF syntax definitions (regardless of which document they're defined in):

  1. the DID identifier (with RFC 3986 as a foundation), and
  2. the "protocol" thing (which I believe we're calling the DID-Reference or the DID Resolution protocol ...which is based on RFC 3986 as a foundation).

Point 2 above can't be ratified until we have a DID data/object model, IMO. Here's what I wrote in https://github.com/w3c-ccg/did-resolution/issues/18:

@peacekeeper I think we need to be more precise than simply saying "an ABNF syntax for the DID Reference" ...yes, it's a syntax but a syntax of what/for what? A syntax specification describes a set of rules for how a [valid] sequence of tokens is parsed and gives names to the parts. ...but you still need to define/label what the "thing" is that is being described.

How can the DID Reference [section] of the DID Resolution specification be anything other than a syntax specification for a protocol? If the DID Reference part of the DID Resolution specification doesn't describe a protocol, what is it describing? ... RE: And probably this syntax definition should be removed here, since it's already in the main DID spec.

What does this reduce the DID Resolution spec to? ...some sort of "users/programmers/maintainers guide"? If so, the entire purpose of the spec (as currently documented in Introduction of the spec) needs to be re-spec'ed.

talltree commented 5 years ago

On Sun, Feb 10, 2019 at 7:16 PM Michael Herman (Toronto) < notifications@github.com> wrote:

If we're going to reference RFC 3986 https://tools.ietf.org/html/rfc3986, we need to read, reference, and respect (r^3) the entire specification @talltree https://github.com/talltree.

In section 1.2.2. Separating Identification from Interaction https://tools.ietf.org/html/rfc3986#section-1.2.2 of RFC 3986 https://tools.ietf.org/html/rfc3986, it states...

Given a URI, a system may attempt to perform a variety of operations on the resource, as might be characterized by words such as "access", "update", "replace", or "find attributes". Such operations are defined by the protocols that make use of URIs, not by this specification.

How do you interpret/want to apply this paragraph Drummond?

Mike, this is exactly what I was saying before: protocols are not defined in the URI specification and they shouldn't be defined in the DID specification. Rather the ABNF for generic URIs is defined in RFC 3986 and the ABNF for generic DIDs should be defined in the DID spec. And, because DID resolution is relatively straightforward overall, generic DID resolution should be defined in the DID Resolution spec that Markus is proposing.

Then, in a DID method specification, the authors must define:

  1. The ABNF for DIDs that use this specific DID method.
  2. The CRUD operations for resolving a DID using this specific DID resolution method.

While #2 could use ABNF (I've seen protocol messages defined that way), I think that's more common for low-level protocols. I see most protocols being specified in JSON templates or something at that level. Markus, how are you thinking that DID method specifications should specify their CRUD operations?

peacekeeper commented 5 years ago

@talltree As you know, DID methods can vary greatly in how they work to retrieve or otherwise produce a DID Document, therefore I also think it will be hard (and not very useful) to make strong assumptions on how exactly a DID method spec should specify its CRUD operations.

Personally I also like to think of DID Resolution as a "process" rather than a "protocol" (although this distinction may be a minor technicality).

mwherman2000 commented 5 years ago

Personally I also like to think of DID Resolution as a "process" rather than a "protocol" (although this distinction may be a minor technicality).

I agree that DID Resolution is a process (albeit currently ill-defined with no specific boundaries).

However within the DID Resolution (process) specification is a spec (syntax) for a protocol: DID-References.

talltree commented 5 years ago

On Mon, Feb 11, 2019 at 7:21 AM Michael Herman (Toronto) < notifications@github.com> wrote:

Personally I also like to think of DID Resolution as a "process" rather than a "protocol" (although this distinction may be a minor technicality).

I agree that DID Resolution is a process (albeit currently ill-defined with no specific boundaries).

However within the DID Resolution specification is a spec (syntax) for a protocol: DID-References.

Michael, help me understand how did-reference, as a ABNF rule, is the "spec (syntax) for a protocol". Are we talking about the same thing? For example, in URI syntax (RFC 3986):

URI-reference = URI / relative-ref

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

relative-ref = relative-part [ "?" query ] [ "#" fragment ]

The same pattern applies to "did-reference"—it's the syntax for a complete DID that can optionally include a path, query, and/or fragment. So, with the ABNF for "did-reference" defined in the DID spec, how is "did-reference" the syntax for a protocol?

mwherman2000 commented 5 years ago

a complete DID that can optionally include a path, query, and/or fragment.

You lost me with this phrase @talltree.

  1. A DID is defined by the did rule in the ABNF PR from early today. A DID (aka did) doesn't have a path, query, and/or fragment.
  2. There is no such thing as a "complete DID". If you're referring to a DID Reference (aka did-reference), please use that term. Reference the following reference for what is a DID Reference: https://github.com/w3c-ccg/did-spec/pull/168 Click Preview
talltree commented 5 years ago

On Tue, Feb 12, 2019 at 8:29 PM Michael Herman (Toronto) < notifications@github.com> wrote:

a complete DID that can optionally include a path, query, and/or fragment.

You lost me with this phrase @talltree https://github.com/talltree.

If a DID is the did as defined in the ABNF PR from early today, then a DID cannot have a path, query, and/or fragment.

Oops, my bad, you are absolutely right. I should have said "DID reference". I fell into the same trap that happens all the time with URIs, which is not adding "reference" when you mean "any string that satisfies the full ABNF".