Skip to content
This repository has been archived by the owner on Oct 29, 2019. It is now read-only.

Update ABNF to use matrix parameters #187

Closed
wants to merge 12 commits into from
Closed

Update ABNF to use matrix parameters #187

Changes from 4 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
acb52c9
Update ABNF to support matrix parameters.
peacekeeper Apr 19, 2019
559b6e9
Fix indentation.
peacekeeper Apr 19, 2019
fed3903
Update sections on Path and Fragment to match new ABNF.
peacekeeper Apr 19, 2019
c7d83ac
Add section on Query, similar to Path and Fragment.
peacekeeper Apr 19, 2019
976d630
Edits suggested by @rhiaro.
peacekeeper Apr 23, 2019
18c70f6
Update term definitions related to "DID URL".
peacekeeper Apr 23, 2019
4364b2a
Fix local reference to #generic-did-syntax.
peacekeeper Apr 23, 2019
4bf3edc
Fix external references.
peacekeeper Apr 23, 2019
20e044d
Additional edit suggested by @rhiaro regarding non-normative note.
peacekeeper Apr 23, 2019
1a25913
Fix external reference "HASHLINK".
peacekeeper Apr 25, 2019
fb0d851
Replace ABNF rule "specific-idstring" -> "method-specific-id" everywh…
peacekeeper Apr 25, 2019
9ec0477
Clarify that not all generic DID parameters must be supported by all …
peacekeeper Apr 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
269 changes: 245 additions & 24 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -733,46 +733,250 @@ <h1>

<section>
<h2>
The Generic DID Scheme
Generic DID Syntax
</h2>

<p>
The generic <a>DID scheme</a> is a URI scheme conformant with
[[RFC3986]]. It consists of a DID followed by an optional path and/or
fragment. The term DID refers only to the identifier conforming to
the did rule in the ABNF below; when used alone, it does not include
a path or fragment. A DID that may optionally include a path and/or
fragment is called a DID reference.
[[RFC3986]]. The DID scheme specializes only the scheme and
authority components of a DID URI—the path-abempty, query,
and fragment components are identical to the ABNF rules defined
in [[RFC3986]]. Note that the term “DID” refers only to the URI
peacekeeper marked this conversation as resolved.
Show resolved Hide resolved
conforming to the did rule in the ABNF below. A DID always identifies
the DID subject. The term “DID URL”, defined by the did-url rule,
refers to a URL that begins with a DID followed by one or more
additional components. A DID URL always identifies the resource to
be located.
</p>

<p>
Following is the ABNF definition using the syntax in [[RFC5234]]
(which defines ALPHA as upper or lowercase A-Z).
The following is the ABNF definition using the syntax in [[RFC5234]]
which defines ALPHA and DIGIT. All other rule names not defined in
this ABNF are defined in [[RFC3986]].
</p>

<pre class="nohighlight">
did-reference = did [ "/" did-path ] [ "#" did-fragment ]
did = "did:" method ":" specific-idstring
method = 1*methodchar
methodchar = %x61-7A / DIGIT
specific-idstring = idstring *( ":" idstring )
idstring = 1*idchar
idchar = ALPHA / DIGIT / "." / "-"
did = "did:" method-name ":" method-specific-id
method-name = 1*method-char
method-char = %x61-7A / DIGIT
method-specific-id = *idchar *( ":" *idchar )
idchar = ALPHA / DIGIT / "." / "-" / "_"
did-url = did *( ";" param ) path-abempty [ "?" query ]
[ "#" fragment ]
param = param-name [ "=" param-value ]
param-name = 1*param-char
param-value = *param-char
param-char = ALPHA / DIGIT / "." / "-" / "_" / ":" /
pct-encoded
</pre>
</section>

<section>
<h2>
Method-Specific Syntax
</h2>

<p>
A DID method specification MUST further restrict the generic DID
syntax by defining its own <code>method-name</code> and its own
<code>method-specific-id</code> syntax. See Section <a href="#did-methods"></a>.
</p>
</section>

<section>
<h2>
Generic DID Parameter Names
</h2>

<p>
DID URL syntax supports a simple, generalized format for parameters based on the
matrix parameter syntax ([[MatrixURIs]]) originally proposed in 1996 by Tim
Berners-Lee and his collaborators.
peacekeeper marked this conversation as resolved.
Show resolved Hide resolved
The ABNF above does not specify any parameter names (the <code>param-name</code>
rule). The following table defines a set of generic DID parameter names for
parameters that MUST operate uniformly across all DID methods. (Method-specific
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If DID methods can't or won't implement some of the proposed parameters because of a preference for greater decentralization by limiting the heavy lifting done by resolvers, then there should be the option to not implement. Prefer wording that says if a DID method implements a parameter, that DID method parameter MUST operate uniformly.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 this reads like all parameters are required by all DID methods. Should be an IF-MUST. Suggest to change

The following table defines a set of generic DID parameter names for
parameters that MUST operate uniformly across all DID methods.

to

The following table defines a set of generic DID parameter names. DID
methods MAY implement any or all of the parameters, and those
implemented MUST operate uniformly across all DID methods.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since all DID methods must be able to resolve a DID to a DID Document, and the first four parameters (service, service-type, key, key-type) operate directly on the DID Document, I don't see how a DID method would NOT support them? Those parameters are completely generic.

I could however see that a particular implementation of a DID resolver may not support these parameters. E.g. a DID resolver may be able to resolve a DID to its DID Document, but it doesn't have the ability to select services or keys from the DID Document. I agree that probably we want to allow this too.

Does this make sense? Perhaps we mean the same thing anyway?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since all DID methods must be able to resolve a DID to a DID Document, and the first four parameters (service, service-type, key, key-type) operate directly on the DID Document

I agree. These params don't seem in jeopardy of not being supported by the resolver since these operate on the document returned and is of no consequence to the resolver.

I could however see that a particular implementation of a DID resolver may not support these parameters. E.g. a DID resolver may be able to resolve a DID to its DID Document, but it doesn't have the ability to select services or keys from the DID Document.

I agree, this shouldn't be of concern to the DID resolver

The parameters which you didn't mention, for example version-time would need to operate on a group of DIDs, and therefore be a function of the resolver. I'm I not understanding how parameters like version-time would work?

For parameters such as version-time, could these be IF the resolver implements they MUST operate in the same way?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, this shouldn't be of concern to the DID resolver

Depends on what we mean by "DID resolver". Is it just the component that returns the DID Document for a given DID, or does it perform the full dereferencing process for a DID URL. We haven't defined this very well yet. This will go into the separate DID Resolution spec.

I'm I not understanding how parameters like version-time would work?

It would return the DID Document for a given DID at a certain point in time (e.g. the one from 2 weeks ago, rather than the current DID Document). This will also be defined in more detail in the DID Resolution spec.

For parameters such as version-time, could these be IF the resolver implements they MUST operate in the same way?

Yes that's the idea.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Depends on what we mean by "DID resolver". Is it just the component that returns the DID Document for a given DID, or does it perform the full dereferencing process for a DID URL. We haven't defined this very well yet. This will go into the separate DID Resolution spec.

Great point. I've been thinking of the DID resolver as the mechanism that dereferences the DID URL. What happens client side should be a separate concern outside of the DID resolver perhaps? I do agree that this should be defined better.

Yes that's the idea.

Great, can we edit this PR so it reads that way?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If DID methods can't or won't implement some of the proposed parameters because of a preference for greater decentralization by limiting the heavy lifting done by resolvers, then there should be the option to not implement.

There should also be a away to perform a query against a DID method and DID resolver combination to determine which parameters are supported on a DID method by DID method basis.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rhiaro and @yancyribbens: Do you think 9ec0477 is a step in the right direction to clarify this?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should also be a away to perform a query against a DID method and DID resolver combination to determine which parameters are supported on a DID method by DID method basis.

@mwherman2000 As we have discussed in w3c/did-resolution#25, I agree this is a useful feature that can be supported by DID methods and DID resolvers, however I don't think this is in scope of the DID URL syntax. The proposed grammar always requires a method-specific-id as part of the DID URL, therefore there is no way to "perform a query against a DID method" itself using a DID URL.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually @mwherman2000, I'd like to correct myself. #189 (comment) just reminded me that in fact the method-specific-id can be blank, so with this currently proposed grammar, there could actually be an identifier for the method itself. Happy to explore that further...

parameter names are covered in the following section.)
peacekeeper marked this conversation as resolved.
Show resolved Hide resolved
</p>

<table class="simple">
<thead>
<tr>
<th>Parameter Name</th>
<th>Description</th>
</tr>
</thead>

<tbody>
<tr>
<td>
<code>service</code>
</td>
<td>
Selects a <code>service</code> JSON-LD object from the DID Document by id.
</td>
</tr>

<tr>
<td>
<code>service-type</code>
</td>
<td>
Selects all <code>service</code> JSON-LD objects from the DID Document by type.
</td>
</tr>

<tr>
<td>
<code>key</code>
</td>
<td>
Selects a <code>publicKey</code> JSON-LD object from the DID Document by id.
</td>
</tr>

<tr>
<td>
<code>key-type</code>
</td>
<td>
Selects all <code>publicKey</code> JSON-LD objects from the DID Document by type.
</td>
</tr>

<tr>
<td>
<code>version-id</code>
</td>
<td>
Specifies a specific version of a DID Document to be resolved (the version ID
could be sequential, or a UUID, or method-specific). Note: This parameter may
not be supported by all DID methods.
</td>
</tr>

<tr>
<td>
<code>version-time</code>
</td>
<td>
Specifies a certain version timestamp of a DID Document to be resolved (i.e.
the DID Document that was valid for a DID at a certain time). Note: This
parameter may not be supported by all DID methods.
</td>
</tr>

<tr>
<td>
<code>content-type</code>
</td>
<td>
Specifies a type of content object (other than a DID Document) to be returned
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe I missed something - what other kinds of content objects are in scope (and not implementation-specific) to be returned from the DID registry, other than a DID Document?

Copy link
Member Author

@peacekeeper peacekeeper Apr 23, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At RWoT#8 (I wasn't there), the idea of "content references" came up, which means that a DID URL could refer to some object in the registry other than a DID Document. For example, in the Sovrin/Indy universe, there is a use case to refer to schemas and credential definitions. At RWoT#8 the idea was to introduce additional syntax to accomplish this, but now we thought we can also just use matrix parameters to identify such additional objects. I'm not convinced that the concrete parameters that are currently here (content-type, content-id) are ideal. For example, perhaps path or query or fragment could be used instead of content-id or something like that. I would propose however that we don't let questions about individual matrix parameters stand in the way of merging the PR - we can always fine-tune the exact parameters later.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what other kinds of content objects are in scope..

+1. Referencing other objects seems out of scope unless there is a specific use case.

For example, in the Sovrin/Indy universe..

@peacekeeper This sounds like an implementation specific use case.. Any use cases that's specific to more than one implementation?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree the schema / credential definition example is specific to only the "sov" DID method, but the concept itself (having a mechanism to reference arbitrary content in the target system) could be generic. @ken-ebert and @talltree brought up this requirement of "content references".

from the target DID registry. Note: This parameter may not be supported by
all DID methods.
</td>
</tr>

<tr>
<td>
<code>content-id</code>
</td>
<td>
Specifies the method-specific identifier of a content object (other than a DID
Document) to be returned from the target DID registry. Note: This parameter
may not be supported by all DID methods.
</td>
</tr>

<tr>
<td>
<code>hl</code>
</td>
<td>
A resource hash of the resource identified by the DID URL to add integrity
protection, as specified in [[Hashlink]].
</td>
</tr>

</tbody>
</table>

<p>
See Sections <a href="#paths"></a> and <a href="#fragments"></a> for the ABNF rules defining DID paths and
fragments.
The exact processing rules for these parameters are specified in the DID
Resolution specification.
</p>

<p>
Note that there may be additional parameters or options that are not part
peacekeeper marked this conversation as resolved.
Show resolved Hide resolved
of the DID URL but instead passed to a DID resolver “out of band”, i.e.,
using a resolution protocol or some other mechanism. Such options could
for example control caching or the desired format of a resolution result.
This is similar to HTTP, where caching or result format are expressed as
HTTP headers rather than as part of an HTTP URL. The important distinction
is that DID parameters that are part of the DID URL specify what resource
is being identified, whereas DID resolver options that are not part of the
DID URL control how that resource is dereferenced.
</p>
</section>

<section>
<h2>
Paths
Method-Specific DID Parameter Names
</h2>

<p>
A generic <a>DID path</a> (the did-path rule in Section <a href="#the-generic-did-scheme"></a>) is identical to a URI path and MUST
conform to the ABNF of the path-rootless ABNF rule in [[RFC3986]]. A
A DID method specification MAY specify additional method-specific parameter
names. A method-specific parameter name MUST be prefixed by the method name
as defined by the <code>method-name</code> rule.
</p>

<p>
For example, if the method <code>did:foo:</code> defines the parameter bar,
the parameter name must be <code>foo:bar</code>. An example DID URL using
this method and this method-specific parameter would be:
</p>

<p>
<code>did:foo:21tDAKCERh95uGgKbJNHYp;foo:bar=high</code>
</p>

<p>
Note that a method-specific parameter name defined by one DID method MAY
peacekeeper marked this conversation as resolved.
Show resolved Hide resolved
be used by other DID methods. For example:
</p>

<p>
<code>did:example:21tDAKCERh95uGgKbJNHYp;foo:bar=low</code>
</p>

<p>
Method-specific parameter names MAY be combined with generic parameter
names in any order.
</p>

<p>
<code>did:example:21tDAKCERh95uGgKbJNHYp;service=agent;foo:bar=high</code>
</p>

<p>
Note that both DID method namespaces and method-specific parameter
peacekeeper marked this conversation as resolved.
Show resolved Hide resolved
namespaces may include colons, so they may be partitioned hierarchically
as defined by a DID method specification. Here is an example DID URL that
illustrates both:
</p>

<p>
<code>did:foo:baz:21tDAKCERh95uGgKbJNHYp;foo:baz:hex=b612</code>
</p>
</section>

<section>
<h2>
Path
</h2>

<p>
A generic <a>DID path</a> is identical to a URI path and MUST
conform to the the <code>path-abempty</code> ABNF rule in [[RFC3986]]. A
DID path SHOULD be used to address resources available via a DID
service endpoint. See Section <a href="#service-endpoints"></a>.
</p>
Expand All @@ -785,13 +989,30 @@ <h2>

<section>
<h2>
Fragments
Query
</h2>

<p>
A generic <a>DID query</a> is identical to a URI query and MUST
conform to the the <code>query</code> ABNF rule in [[RFC3986]]. A
DID query SHOULD be used to address resources available via a DID
service endpoint. See Section <a href="#service-endpoints"></a>.
</p>

<p>
A specific DID scheme MAY specify ABNF rules for DID queries that are
more restrictive than the generic rules in this section.
</p>
</section>

<section>
<h2>
Fragment
</h2>

<p>
A generic <a>DID fragment</a> (the did-fragment rule in Section
<a href="#the-generic-did-scheme"></a>) is identical to a URI
fragment and MUST conform to the ABNF of the fragment ABNF rule in
A generic <a>DID fragment</a> is identical to a URI
fragment and MUST conform to the the <code>fragment</code> ABNF rule in
[[RFC3986]]. A DID fragment MUST be used only as a method-independent
reference into the DID Document to identify a component of a DID Document
(e.g. a unique key description). To resolve this reference, the complete
Expand Down