-
Notifications
You must be signed in to change notification settings - Fork 45
Refactor ABNF rules for DIDs and DID References. #168
Changes from all commits
a3f19e4
a7299a1
f637960
dcded0a
22b492c
3d840d5
d9c39c7
75012c3
b288d0c
d09b5b0
15c4246
66b632e
24c7fb7
89a234c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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" | ||
}] | ||
|
@@ -702,80 +703,103 @@ <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>. | ||
</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 <a>Service Endpoint</a> resources, queries, and fragments. | ||
</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 / "." / "-" / "_" | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The following are not defined: There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. So, that's intentional. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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? :) There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should this be |
||
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 | ||
</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 in Section | ||
<a href="#did-reference"></a>) is | ||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should this be There was a problem hiding this comment. Choose a reason for hiding this commentThe 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]]). | ||
The DID Reference service query and service fragment | ||
(the <code>service-query</code> and <code>service-fragment</code> rules | ||
in Section <a href="#did-reference"></a>) parts are | ||
identical to their URI counterparts and MUST conform to the ABNF of the query | ||
and fragment rules in [[RFC3986]]. | ||
</p> | ||
</section> | ||
|
||
|
@@ -800,8 +824,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> | ||
|
@@ -813,7 +837,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> | ||
|
@@ -822,7 +846,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. | ||
|
@@ -1402,31 +1426,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", | ||
|
@@ -1435,7 +1459,7 @@ <h2> | |
"currency": "USD" | ||
} | ||
}, { | ||
"id": "did:example:123456789abcdefghi;authpush", | ||
"id": "did:example:123456789abcdefghi#authpush", | ||
"type": "DidAuthPushModeVersion1", | ||
"serviceEndpoint": "http://auth.example.com/did:example:123456789abcdefg" | ||
}] | ||
|
@@ -1699,7 +1723,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>] | ||
|
@@ -1770,7 +1794,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. | ||
|
@@ -1794,18 +1818,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> | ||
|
||
|
@@ -2621,22 +2646,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": { | ||
|
@@ -2645,9 +2676,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/" | ||
}] | ||
|
There was a problem hiding this comment.
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?