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

Show file tree
Hide file tree
Changes from all 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
19 changes: 19 additions & 0 deletions common.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,25 @@ var ccg = {
],
status: "CG-DRAFT",
publisher: "Digital Verification Community Group"
},
"HASHLINK": {
title: "Cryptographic Hyperlinks",
date: "December 2018",
href: "https://tools.ietf.org/html/draft-sporny-hashlink-02",
authors: [
"Manu Sporny"
],
status: "Internet-Draft",
publisher: "IETF"
},
"MATRIX-URIS": {
title: "Matrix URIs - Ideas about Web Architecture",
date: "December 1996",
href: "https://www.w3.org/DesignIssues/MatrixURIs.html",
authors: [
"Tim Berners-Lee"
],
status: "Personal View"
}
}
};
Expand Down
307 changes: 273 additions & 34 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -733,46 +733,268 @@ <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 <code>path-abempty</code>,
<code>query</code>, and <code>fragment</code> components are
identical to the ABNF rules defined
in [[RFC3986]].
</p>

<p class="note">
The term <a>DID</a> refers only to the URI
conforming to the <code>did</code> rule in the ABNF below. A
DID always identifies the DID subject. The term <a>DID URL</a>,
defined by the <code>did-url</code> 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>
See Sections <a href="#paths"></a> and <a href="#fragments"></a> for the ABNF rules defining DID paths and
fragments.
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>
Paths
Generic 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
DID URL syntax supports a simple, generalized format for parameters based on the
matrix parameter syntax ([[MATRIX-URIS]]).
The ABNF above does not specify any parameter names (the <code>param-name</code>
rule).
</p>
<p>
Some generic DID parameter names (e.g. for service selection) are completely
independent of any specific DID method and MUST always function the same way
for all DIDs.
Others (e.g. for versioning) MAY be supported by
certain DID methods, but MUST operate uniformly across those DID methods that
do support them.
</p>
<p>
Parameter names that are completely method-specific are covered in
<a href="#method-specific-did-parameter-names"></a>.
</p>
<p>
The following table defines a set of generic DID parameter names:
</p>

<table class="simple">
<thead>
<tr>
<th>Generic DID 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>
The exact processing rules for these parameters are specified in the DID
Resolution specification.
</p>

<p class="note">
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>
Method-Specific DID Parameter Names
</h2>

<p>
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>
A method-specific parameter name defined by one DID method MAY
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>
Both DID method namespaces and method-specific parameter
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,17 +1007,34 @@ <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
DID reference including the DID fragment MUST be used as the value of
DID URL including the DID fragment MUST be used as the value of
the key for the target component in the DID Document object.
</p>

Expand Down Expand Up @@ -836,7 +1075,7 @@ <h2>

<li>
Case sensitivity and normalization of the value of the
specific-idstring rule in Section <a href="#the-generic-did-scheme">
<code>method-specific-id</code> rule in Section <a href="#generic-did-syntax">
</a> MUST be defined by the governing DID method specification.
</li>
</ol>
Expand Down Expand Up @@ -1921,8 +2160,8 @@ <h2>

<p>
A DID method specification MUST define exactly one specific DID
scheme identified by exactly one method name (the method rule in
Section <a href="#the-generic-did-scheme"></a>).
scheme identified by exactly one method name (the <code>method-name</code> rule in
Section <a href="#generic-did-syntax"></a>).
</p>

<p>
Expand All @@ -1945,18 +2184,18 @@ <h2>

<p>
The DID method specification for the specific DID scheme MUST specify
how to generate the specific-idstring component of a DID. The
specific-idstring value MUST be able to be generated without the use
of a centralized registry service. The specific-idstring value SHOULD
how to generate the <code>method-specific-id</code> component of a DID. The
<code>method-specific-id</code> value MUST be able to be generated without the use
of a centralized registry service. The <code>method-specific-id</code> value SHOULD
be globally unique by itself. The fully qualified DID as defined by
the DID rule in Section <a href="#the-generic-did-scheme"></a> MUST
the DID rule in Section <a href="#generic-did-syntax"></a> MUST
be globally unique.
</p>

<p>
If needed, a specific DID scheme MAY define multiple specific
specific-idstring formats. It is RECOMMENDED that a specific DID
scheme define as few specific-idstring formats as possible.
<code>method-specific-id</code> formats. It is RECOMMENDED that a specific DID
scheme define as few <code>method-specific-id</code> formats as possible.
</p>
</section>

Expand Down
Loading