Refactor ABNF rules for DIDs and DID References.

[dmitrizagidulin]

This PR integrates and reflects the current consensus on the DID ABNF rules, as well as DID Reference and Service Endpoint ABNF rules.

Specifically:

• Separates the DID Reference ABNF from the DID ABNF
• Differentiates a DID fragment from a Service fragment
• Specifies ABNF rules for did query, did path
• Clarifies use cases for DID References (service endpoints resolution, key references, etc).
• Updates service endpoint id: properties in examples.

Replaces PR #106, addresses #85.

---

Preview | Diff

[dmitrizagidulin]

ABNF rules refactored. What remains (this should probably go in a separate PR? I'm not sure):

• Add an explanation for what DID Reference Service Paths are for
• Link to the corresponding section in the DID Resolution spec.

[mwherman2000]

How soon can this PR be accepted?

[davidlehn]

The following are not defined: did-fragment, service-path, service-query, service-fragment.

[dmitrizagidulin]

So, that's intentional. did-fragment, -path and -query are mentioned in the next paragraph (basically, the ABNF for them is the same as in the URI RFC).

[davidlehn]

Ah, I see. Unsure if that needs to be noted out or not. Leave it until someone else gets confused too.

[dmitrizagidulin]

Heh, yeah, I was wondering that same thing, but wasn't sure how to make it clearer. Does ABNF syntax have comments? :)

[davidlehn]

The ABNF RFC is linked a few lines up! Comments: https://tools.ietf.org/html/rfc5234#section-3.9

[davidlehn]

Should this be moved up a section and phrased so that it covers The Generic DID Scheme section and DID Reference section?

[davidlehn]

@dmitrizagidulin If the preview link is correct, there's a <section> tag issue somewhere. Everything is under section 4, vs the current version where that is not the case.

[davidlehn]

@dmitrizagidulin Does terms.html needs some updating too to match these changes? For instance, the metions and links about "DID Path" . (And while fixing that, maybe reword so the hard coded easy breakable "section x.y" text in that file isn't used)

[davidlehn]

There are more places where the def <a>term</a> style could be used. Unsure how far that sort of linking needs to go.

[davidlehn]

Should this be A specific <a>DID method</a> MAY...?

[davidlehn]

Should this be A specific <a>DID method</a> MAY?

[dmitrizagidulin]

Probably, yeah

[dhh1128]

I do not understand why we feel the need to use a different delimiter to distinguish service fragments from other types of fragments. Why can't we just use / for all fragments of any type, and require that their ID properties be unique within the DID Document?

[mwherman2000]

@dhh1128 I agree. At the did-url grammar level, we should focus on a minimum set of allowable syntax constructs - in support of the desired capabilities we want did-urls to have ...not try to encode all sorts of specific capabilities and functions into the grammar expressed using the ABNF notation.

Examples:

1. IMO a bad use of syntax: Reset the DID ABNF - removed "$" and "!" WebOfTrustInfo/rwot8-barcelona#164 (comment)
2. IMO a better use of syntax: did-url Use Cases: did-url Syntax Examples (and corresponding HTTP Binding Examples) w3c/did-resolution#32 (comment)

The latter, at a syntax (grammar) level, supports many levels of functional/capability innovation without having to change the grammar. It creates an "algebra" for working with a did and collections of dids, etc.

[peacekeeper]

@dmitrizagidulin do you think everything in this PR has been addressed by #189 (in fact, that one even cherry-picked a few commits from here)? Or would you say this PR here still has content that needs to be merged?

[kdenhartog]

I wanted to highlight the example of what I brought up on the DID call today about key-type matrix param being used as a method to specify a specific key-type within a grouping of key-types. For example, let's say in my DID-Doc I specify a grouping of RSAVerificationKey2016 RSAVerificationKey2017 and RSAVerificationKey2018 and call this grouping RSAVerificationSuite which is what the key-type would be listed in my DID Doc.

E.g. my DID Doc would be:

{
  "@context": ["https://w3id.org/did/v1", "https://w3id.org/security/v1"],
  "id": "did:example:123456789abcdefghi",
  ...
  "publicKey": [{
    "id": "did:example:123456789abcdefghi#keys-1",
    "type": "RsaVerificationSuite",
    "controller": "did:example:123456789abcdefghi",
    "publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
  }],
  ...
}

Then when referencing to the public key for verification, I could use did:example:123456789abcdefghi;key-type=RSAVerification2018#keys-1

To suggest that the same key can be used with multiple key types.

If you were to use this for service-type it would be something like a grouping of services where a common set of services sit behind a single endpoint. So for example, I may run an Agent which supports DIDComm v1 and DIDCommv2 and I would specify the serialization of the object by using:

did:example:123456789abcdefghi;key-type=DIDComm-JSON#agent

or

did:example:123456789abcdefghi;key-type=DIDComm-CBOR#agent

This is just an early example of where I think it may be used. I'm not sure if this indirection is useful, necessary, or neither. With that said, I want to take the time to agree with @dmitrizagidulin point raised that matrix params are not a method of optimizing resolver implementations. They should be used to identify a specific resource when the DID Doc contains metadata that describes a set.

[dmitrizagidulin]

This PR is superceded by PR #189, so, it's ok to close this one.