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

Refactor ABNF rules for DIDs and DID References. #168

Closed
wants to merge 14 commits into from
Closed

Refactor ABNF rules for DIDs and DID References. #168

Changes from 10 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
a3f19e4
Refactor ABNF rules for DIDs and DID References.
dmitrizagidulin Feb 12, 2019
a7299a1
Switch order of DID Fragments and DID Reference Service Path sections.
dmitrizagidulin Feb 12, 2019
f637960
Separate did-fragment-reference and did-service-reference in the ABNF…
dmitrizagidulin Feb 12, 2019
dcded0a
Add paragraph about service query and fragment rules.
dmitrizagidulin Feb 12, 2019
22b492c
Adjust references to method-specific-idstring.
dmitrizagidulin Feb 12, 2019
3d840d5
Replace relevant usages of <pre> with <code>.
dmitrizagidulin Feb 12, 2019
d9c39c7
Minor formatting fix.
dmitrizagidulin Feb 12, 2019
75012c3
Adjust ALPHA and DIGIT references.
dmitrizagidulin Feb 12, 2019
b288d0c
Update service ids in examples.
dmitrizagidulin Feb 12, 2019
d09b5b0
Do not use relative urls for service IDs.
dmitrizagidulin Feb 13, 2019
15c4246
Update index.html (add comma)
davidlehn Feb 14, 2019
66b632e
Update index.html (oxford comma and link)
davidlehn Feb 14, 2019
24c7fb7
Update index.html (capitalization, links)
davidlehn Feb 14, 2019
89a234c
Update index.html (did reference service mentions)
davidlehn Feb 16, 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
167 changes: 98 additions & 69 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -534,6 +534,7 @@ <h2>
"publicKeyPem": "-----BEGIN PUBLIC KEY...END PUBLIC KEY-----\r\n"
}],
"service": [{
"id": "did:example:123456789abcdefghi#service123",
"type": "ExampleService",
"serviceEndpoint": "https://example.com/endpoint/8377464"
}]
Expand Down Expand Up @@ -702,80 +703,100 @@ <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]]. It consists of a DID method name, followed by a method-specific
identifier. The term DID refers only to the identifier conforming to
the did rule in the ABNF below.

Additionally, a DID can be used as a component in a DID Reference, described in
the <a href="#did-reference">DID Reference section</a> below.
</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 <code>ALPHA</code> and <code>DIGIT</code>.
Copy link
Contributor

Choose a reason for hiding this comment

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

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

</p>
dmitrizagidulin marked this conversation as resolved.
Show resolved Hide resolved

<pre class="nohighlight">
did-reference = did [ "/" did-path ] [ "#" did-fragment ]
did = "did:" method ":" specific-idstring
did = "did:" method ":" method-specific-idstring
method = 1*methodchar
methodchar = %x61-7A / DIGIT
specific-idstring = idstring *( ":" idstring )
method-specific-idstring = idstring *( ":" idstring )
idstring = 1*idchar
idchar = ALPHA / DIGIT / "." / "-"
</pre>
<p>
See Sections <a href="#paths"></a> and <a href="#fragments"></a> for the ABNF rules defining DID paths and
fragments.
</p>
</section>

<section>
<h2>
Paths
DID Reference
</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 path SHOULD be used to address resources available via a DID
service endpoint. See Section <a href="#service-endpoints"></a>.
DID References are used for two main purposes: to refer to sections
inside a DID Document (via <a href="#did-fragments">DID Fragments</a>), and as a
portable way to refer to Service Endpoint resources, queries and fragments.
dmitrizagidulin marked this conversation as resolved.
Show resolved Hide resolved
</p>

<p>
A specific DID scheme MAY specify ABNF rules for DID paths that are
more restrictive than the generic rules in this section.
</p>
</section>
<pre class="nohighlight">
did-reference = did (did-fragment-reference / did-service-reference)
did-fragment-reference = "#" did-fragment
did-service-reference = ";" service-id [ "/" service-path ] [ "?" service-query ] [ "#" service-fragment ]
service-id = ALPHA / DIGIT / "." / "-" / "_"
Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Author

Choose a reason for hiding this comment

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

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).

Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Author

Choose a reason for hiding this comment

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

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

</pre>

<section>
<h2>
Fragments
</h2>
<section>
<h3>
DID Fragments
</h3>

<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
[[RFC3986]]. A DID fragment MUST be used only as a method-independent
pointer into the DID Document to identify a unique key description or
other DID Document component. To resolve this pointer, the complete
DID reference including the DID fragment MUST be used as the value of
the id key for the target JSON object.
</p>
<p>
A generic <a>DID fragment</a> (the <code>did-fragment</code> rule in Section
<a href="#did-reference"></a>) is identical to a URI
fragment and MUST conform to the ABNF of the fragment ABNF rule in
[[RFC3986]]. A DID fragment MUST be used only as a method-independent
pointer into the DID Document to identify a unique key description or
other DID Document component. To resolve this pointer, the complete
DID reference including the DID fragment MUST be used as the value of
the id key for the target JSON object.
</p>

<p>
A specific DID scheme MAY specify ABNF rules for DID fragments that
Copy link
Contributor

Choose a reason for hiding this comment

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

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

are more restrictive than the generic rules in this section.
</p>

<p>
It is desirable that we enable tree-based processing of DIDs that include
DID fragments (which resolve directly within the DID document) to locate
metadata contained directly in the DID document or the service resource
given by the target URL without needing to rely on graph-based processing.
</p>
<p>
Implementations SHOULD NOT prevent the use of JSON pointers ([[RFC6901]]).
</p>
</section>

<section>
<h3>
DID Reference Service Paths, Queries and Fragments
dmitrizagidulin marked this conversation as resolved.
Show resolved Hide resolved
</h3>

<p>
A specific DID scheme MAY specify ABNF rules for DID fragments that
are more restrictive than the generic rules in this section.
A DID Reference Service path (the <code>service-path</code> rule above) is
dmitrizagidulin marked this conversation as resolved.
Show resolved Hide resolved
identical to a URI path and MUST conform to the ABNF of the path-rootless ABNF
rule in [[RFC3986]]. The path is used to address resources available via a DID
service endpoint. See Section <a href="#service-endpoints"></a>.
</p>

<p>
It is desirable that we enable tree-based processing of DIDs that include
DID fragments (which resolve directly within the DID document) to locate
metadata contained directly in the DID document or the service resource
given by the target URL without needing to rely on graph-based processing.
A specific DID scheme MAY specify ABNF rules for DID Reference service paths
Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Author

Choose a reason for hiding this comment

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

Probably, yeah

that are more restrictive than the generic rules in this section.
</p>

<p>
Implementations SHOULD NOT prevent the use of JSON pointers ([[RFC6901]]).
A DID Reference Service <code>query</code> and <code>fragment</code> parts are
dmitrizagidulin marked this conversation as resolved.
Show resolved Hide resolved
identical to their URI counterparts and MUST conform to the ABNF of the query
and fragment rules in [[RFC3986]].
</p>
</section>

Expand All @@ -800,8 +821,8 @@ <h2>

<li>
Case sensitivity and normalization of the value of the
specific-idstring rule in Section <a href="#the-generic-did-scheme">
</a> MUST be defined by the governing DID method specification.
<code>method-specific-idstring</code> rule in Section
<a href="#the-generic-did-scheme"></a> MUST be defined by the governing DID method specification.
</li>
</ol>
</section>
Expand All @@ -813,7 +834,7 @@ <h2>

<p>
A DID MUST be persistent and immutable, i.e., bound to an entity once
and never changed (forever).
and never changed (forever).
</p>

<p>
Expand All @@ -822,7 +843,7 @@ <h2>
to multiple underlying distributed ledgers or networks over time,
thus maintaining its persistence independent of any particular ledger
or network. However registering the same identifier on multiple
ledgers or networks introduces extremely hard entityship and
ledgers or networks introduces extremely hard entityship and
<a href="https://en.wikipedia.org/wiki/List_of_DNS_record_types%23SOA">start-of-authority</a>
(SOA) problems. It also greatly increases implementation complexity
for developers.
Expand Down Expand Up @@ -1402,31 +1423,31 @@ <h2>
<pre class="example nohighlight" title="Various service endpoints">
{
"service": [{
"id": "did:example:123456789abcdefghi;openid",
"id": "did:example:123456789abcdefghi#openid",
"type": "OpenIdConnectVersion1.0Service",
"serviceEndpoint": "https://openid.example.com/"
}, {
"id": "did:example:123456789abcdefghi;vcr",
"id": "did:example:123456789abcdefghi#vcr",
"type": "CredentialRepositoryService",
"serviceEndpoint": "https://repository.example.com/service/8377464"
}, {
"id": "did:example:123456789abcdefghi;xdi",
"id": "did:example:123456789abcdefghi#xdi",
"type": "XdiService",
"serviceEndpoint": "https://xdi.example.com/8377464"
}, {
"id": "did:example:123456789abcdefghi;agent",
"id": "did:example:123456789abcdefghi#agent",
"type": "AgentService",
"serviceEndpoint": "https://agent.example.com/8377464"
}, {
"id": "did:example:123456789abcdefghi;hub",
"id": "did:example:123456789abcdefghi#hub",
"type": "HubService",
"serviceEndpoint": "https://hub.example.com/.identity/did:example:0123456789abcdef/"
}, {
"id": "did:example:123456789abcdefghi;messages",
"id": "did:example:123456789abcdefghi#messages",
"type": "MessagingService",
"serviceEndpoint": "https://example.com/messages/8377464"
}, {
"id": "did:example:123456789abcdefghi;inbox",
"id": "did:example:123456789abcdefghi#inbox",
"type": "SocialWebInboxService",
"serviceEndpoint": "https://social.example.com/83hfh37dj",
"description": "My public social inbox",
Expand All @@ -1435,7 +1456,7 @@ <h2>
"currency": "USD"
}
}, {
"id": "did:example:123456789abcdefghi;authpush",
"id": "did:example:123456789abcdefghi#authpush",
"type": "DidAuthPushModeVersion1",
"serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefg"
}]
Expand Down Expand Up @@ -1699,7 +1720,7 @@ <h2>
"authentication": [ ... ],
"service": [<span class="highlight">{
"@context": "did:example:contexts:987654321",
"id": "did:example:123456789abcdefghi;photos",
"id": "did:example:123456789abcdefghi#photos",
"type": "PhotoStreamService",
"serviceEndpoint": "https://example.org/photos/379283"
}</span>]
Expand Down Expand Up @@ -1770,7 +1791,7 @@ <h2>

<p>
A DID method specification MUST define exactly one specific DID
scheme identified by exactly one method name (the method rule in
scheme identified by exactly one method name (the <code>method</code> rule in
Section <a href="#the-generic-did-scheme"></a>). Since DIDs are
intended for decentralized identity infrastructure, it is NOT
RECOMMENDED to establish a registry of unique DID method names.
Expand All @@ -1794,18 +1815,19 @@ <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
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
be globally unique.
how to generate the <code>method-specific-idstring</code> component of a DID. The
<code>method-specific-idstring</code> value MUST be able to be generated without
the use of a centralized registry service. The
<code>method-specific-idstring</code> value SHOULD be globally unique by itself.
The DID as defined by the <code>did</code> rule in Section
<a href="#the-generic-did-scheme"></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.
If needed, a specific DID scheme MAY define multiple
<code>method-specific-idstring</code> formats. It is RECOMMENDED that a specific
DID scheme define as few <code>method-specific-idstring</code> formats as
possible.
</p>
</section>

Expand Down Expand Up @@ -2621,22 +2643,28 @@ <h1>
],

"service": [{
"id": "did:example:123456789abcdefghi#oidc",
"type": "OpenIdConnectVersion1.0Service",
"serviceEndpoint": "https://openid.example.com/"
}, {
"id": "did:example:123456789abcdefghi#vcStore",
"type": "CredentialRepositoryService",
"serviceEndpoint": "https://repository.example.com/service/8377464"
}, {
"id": "did:example:123456789abcdefghi#xdi",
"type": "XdiService",
"serviceEndpoint": "https://xdi.example.com/8377464"
}, {
"id": "did:example:123456789abcdefghi#hub",
"type": "HubService",
"serviceEndpoint": "https://hub.example.com/.identity/did:example:0123456789abcdef/"
}, {
"id": "did:example:123456789abcdefghi#messaging",
"type": "MessagingService",
"serviceEndpoint": "https://example.com/messages/8377464"
}, {
"type": "SocialWebInboxService",
"id": "did:example:123456789abcdefghi#inbox",
"serviceEndpoint": "https://social.example.com/83hfh37dj",
"description": "My public social inbox",
"spamCost": {
Expand All @@ -2645,9 +2673,10 @@ <h1>
}
}, {
"type": "DidAuthPushModeVersion1",
"id": "did:example:123456789abcdefghi#push",
"serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefghi"
}, {
"id": "did:example:123456789abcdefghi;bops",
"id": "did:example:123456789abcdefghi#bops",
"type": "BopsService",
"serviceEndpoint": "https://bops.example.com/enterprise/"
}]
Expand Down