Update ABNF to use matrix parameters (new)

[peacekeeper]

This updates the ABNF and introduces matrix parameters, based on discussions on the mailing list as well as the DID Spec and DID Resolution Spec Weekly Meetings and the resulting Proposal for Revisions to Decentralized Identifiers Section of DID Spec.

This is a new PR that replaces the earlier #187. In this new one, only the matrix parameter concept itself is introduced, but concrete matrix parameters will be proposed and discussed in separate PRs.

Separate PRs for concrete matrix parameters: #190, #191, #192, #193, #194, #195, #196

Fixes #85. Fixes #90. Fixes #170. Fixes #177.
Replaces #106. Replaces #168.
Related to #185.

---

Preview | Diff

[mrinalwadhwa]

1. Unless I'm misunderstanding, this rule feels more complicated than it needs to be:
   If we change idchar to include : then a simpler version that would have the same effect:

method-specific-id = *idchar
idchar             = ALPHA / DIGIT / "." / "-" / "_" / ":"

2. This rule means method-specific-id can be blank, is that ok? Maybe we want to require atleast one char:

method-specific-id = 1*idchar
idchar             = ALPHA / DIGIT / "." / "-" / "_" / ":"

3. Maybe the intent is to highlight the notion of : separated sub-method names in the grammar. If so, then this makes sense. I feel the atleast one char restriction would still makes sense:

method-specific-id = 1*idchar *( ":" 1*idchar )
idchar             = ALPHA / DIGIT / "." / "-" / "_"

[talltree]

@mrinalwadhwa You are exactly right that, although the rule could have been simpler, we were wanting to highlight the possibility of using sub-method names in the grammar. Also, there was a specfic request to allow consecutive colons. That also means that the method-specific-id can be blank, however that also satisfies a request for DID method names by themselves to have DID documents, so that was intentional as well.

[mrinalwadhwa]

got it, thank you for clarifying @talltree

[msporny]

Fixes #85. Fixes #90. Fixes #170. Fixes #177.

I double checked these and agree that those issues would be addressed with this PR.

[msporny]

A couple of minor comments.

[msporny]

The DID URL thing makes me uneasy because I feel like developers that use it won't be precise and therefore there will be confusion surrounding the difference between a DID and a DID URL. The confusion is only problematic if the distinction is important, and it may not be that important.

In any case, my concern isn't enough to block the PR... just voicing that I'm concerned about the nuance here and think it may lead to confusion 5 years from now.

[peacekeeper]

On the other hand, I felt like it had been a source of confusion in the last few months to NOT have separate terms here. People said "DID" and sometimes meant only the "naked" / "bare" DID, and sometimes they meant the whole DID+path+query+fragment. We also had the term "DID reference" previously. I used the new terms "DID" and "DID URL" at a meetup last week and thought it worked well with the (quite technical) audience.

[msporny]

Adding terminology has costs. Sometimes it's clear that those costs are worth it... sometimes it's not clear.

Here's the conversation I'm concerned about:

Speaker: So, as we can see did:example:1234 is a URL that can be dereferenced to...

Developer: Wait, that's not a DID URL, that's just a DID... you have to add something like a path or query or matrix parameter to it for it to be a URL.

Speaker: No, it's a URL, you can dereference it and get a DID Document.

Developer: Then why don't you call it a DID URL? I mean, you can dereference it and get a DID Document... that's the definition of a URL, isn't it!?

Do you see the problem we're creating for ourselves? :)

[talltree]

@msporny Yes, I see the problem clearly, as did other folks attending the DID Spec calls. It was in fact a conscious decision to separate the terms (and the ABNF rules) for DID and DID URL for this reason: a DID document may or may not be considered a resource as meant the term "URL" (Uniform Resource Locator).

I know that might sound strange, but let me explain. The analogy we used in our discussion was the resolution of a DNS record in the process of dereferencing the URL for a web page. With such a URL, the resource being located is the web page. It is not the DNS record used to look up the IP address of the web server.

So in that sense, when a DID document is used to locate (and describe how to interact with) another resource on the Web, the DID document itself is not the resource being located. It is like the DNS record.

However, there are also contexts in which you do want to treat a DID document as a locate-able Web resource. For example, if you want to add a fragment to a DID to reference a public key object inside the DID document as a secondary resource. In that case the DID document is the primary resource.

What Markus and I realized is that any reference that needs to treat the DID document as a primary resource needs to add something to the DID—turning it into a DID URL. But if you had only a DID with nothing else appended, then the fact that the DID alone can be resolved to a DID document does not make that DID document the resource being identified. Rather the DID document is like the DNS record.

Thankfully, this is also consistent with the first statement in the intro paragraph, i.e., that "A DID always identifies the DID subject". If the DID subject is Alice (or Best Buy, or a scooter, or anything else that does not exist on the network), then that DID is clearly a URI that cannot function as a URL because the resource it identifies is not locate-able on the Web.

This also thankfully lets us avoid the HTTP Range 14 issue with DIDs, because the DID by itself always identifies the DID subject and never by itself identifies some other resource describing the DID subject.

[peacekeeper]

Just for reference, a more in-depth discussion of this is here.

[msporny]

Hmm, these rules:

did                = "did:" method-name ":" method-specific-id
method-specific-id = *idchar *( ":" *idchar )

Mean that this is a valid DID:

did:v1:

I don't think it should be. We should probably change it to this:

method-specific-id = 1*idchar *( ":" *idchar )

[peacekeeper]

@msporny I think I agree with you, however the possibility of having an empty method-specific-id has been explicitly discussed. This would make it possible to have a DID Document for the method itself. See #189 (review) and #187 (comment).

[msporny]

For DID Documents for the method itself, I think people want "did:v1" not "did:v1:" (note the extra colon at the end). The current ABNF states that "did:v1" is not valid, right? That's the point I'm trying to make. In other words, if people want did:method, then we should have ABNF for that (or modify the existing ABNF to support that use case.

[talltree]

@msporny Permit me to disagree. I see no issue with requiring the valid DID that identifies a DID method to end in a colon. To me, it's actually more intuitive that way. For example, if I want to refer to the DID scheme by itself, I would write "the did: scheme". If I want to talk about the Veres One DID scheme, I would write "the did:v1: scheme".

[peacekeeper]

Created issue #198 to keep track of this.

[msporny]

Suggest not using colon and semantically it's used as a separator elsewhere. I suggest we just do the whole kebab-case thing and do "foo-" instead.

I won't block this PR going in over that, but if we don't change it, I'll probably raise an issue for later on this item.

[peacekeeper]

Created issue #199 to keep track of this.

[msporny]

oof, this feels like a bad thing to do. If we're going to allow this, there is no reason to prefix it with the method name, don't prefix at all.

[peacekeeper]

Created issue #200 to keep track of this and also your other comment below about hierarchical method namespaces.

[msporny]

I don't understand the benefit of this. What is the use case? Why are we saying anything about this?

[peacekeeper]

Merging per decision in 2019-05-09 DID Spec and DID Resolution Spec meeting.