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

Cleanup terms around "DID scheme" #185

Closed
wants to merge 1 commit into from
Closed

Cleanup terms around "DID scheme" #185

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
40 changes: 20 additions & 20 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -333,12 +333,12 @@ <h2>
</h2>

<p>
The first purpose of this specification is to define the generic
DID scheme and a generic set of operations on DID documents that can be
The first purpose of this specification is to define the DID URI
scheme and a generic set of operations on DID documents that can be
implemented for any distributed ledger or network capable of
supporting DIDs. The second purpose of this specification is to
define the conformance requirements for a DID method
specification—a separate specification that defines a specific DID
specification—a separate specification that defines a DID method
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggestions: Change all references to "DID method scheme" to just "DID method". Using "scheme" in both places may confuse folks. While it is true that a "DID method" is a scheme, most readers will miss the nuance and most likely use "DID URI scheme" and "DID method scheme" interchangeably.

Copy link
Member Author

@rhiaro rhiaro Mar 31, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

That works in some places, but I'm not sure about the section 'DID Method Schemes' (L1919) and generally how we differentiate between when the spec is talking about the method-specific character string in the DID, and the DID method itself. Or maybe we don't need to?

Eg. "A DID method specification MUST define exactly one DID method scheme identified by exactly one method name"

Copy link
Contributor

@msporny msporny Mar 31, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

Would replacing that with something like: "A DID method specification MUST define further restrictions to the method and specific-idstring parameters defined in the DID URI scheme"?

The goal would be to effectively state: "There is one DID URI scheme, that's in this specification." The "DID URI scheme" may be further restricted by DID method specifications."

... or does that not address the text you're concerned about?

Copy link
Contributor

Choose a reason for hiding this comment

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

So while I think that generally works, I still think we need to define and use a term for what the previous spec called a "DID method scheme", i.e., the syntax (ABNF) defined by a DID method that restricts the generic DID scheme.

How about we just call it a "DID method syntax"?

Also, I want to be able to continue to use the term "generic DID syntax" for this portion of this spec so that we can mirror the same language from RFC 3986. Read these two paragraphs:

1.1.1.  Generic Syntax

   Each URI begins with a scheme name, as defined in Section 3.1, that
   refers to a specification for assigning identifiers within that
   scheme.  As such, the URI syntax is a federated and extensible naming
   system wherein each scheme's specification may further restrict the
   syntax and semantics of identifiers using that scheme.
   ...
   A parser of the generic URI syntax can parse any URI reference into
   its major components.  Once the scheme is determined, further
   scheme-specific parsing can be performed on the components.  In other
   words, the URI generic syntax is a superset of the syntax of all URI
   schemes.

So I would really like to use the same language to talk about the relationship of DIDs and DID methods, i.e., to be able to say:

The DID generic syntax is a superset of the syntax of all DID method syntaxes.

I'm drafting the proposed new text for the Decentralized Identifiers section of the spec (in this Google doc) to use this language. See what you think.

scheme and specific set of DID document operations for a specific
distributed ledger or network.
</p>
Expand Down Expand Up @@ -733,11 +733,11 @@ <h1>

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

<p>
The generic <a>DID scheme</a> is a URI scheme conformant with
The <a>DID URI 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
Expand Down Expand Up @@ -771,14 +771,14 @@ <h2>
</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
A <a>DID path</a> (the did-path rule in Section <a href="#did-uri-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>.
</p>

<p>
A specific DID scheme MAY specify ABNF rules for DID paths that are
A DID method scheme MAY specify ABNF rules for DID paths that are
more restrictive than the generic rules in this section.
</p>
</section>
Expand All @@ -789,8 +789,8 @@ <h2>
</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
A <a>DID fragment</a> (the did-fragment rule in Section
<a href="#did-uri-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
reference into the DID Document to identify a component of a DID Document
Expand All @@ -800,7 +800,7 @@ <h2>
</p>

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

Expand Down Expand Up @@ -836,8 +836,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.
specific-idstring rule in Section <a href="#did-uri-scheme"></a>
MUST be defined by the governing DID method specification.
</li>
</ol>
</section>
Expand Down Expand Up @@ -1920,16 +1920,16 @@ <h2>
</h2>

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

<p>
Since DIDs are intended for decentralized identity infrastructure, it is NOT
RECOMMENDED to establish a definitive software registry of unique DID method names.
Rather, the uniqueness of DID method names should be established via
human consensus, i.e., a specific DID scheme MUST use a method name
human consensus, i.e., a DID method scheme MUST use a method name
that is unique among all DID method names known to the specification
authors at the time of publication. To facilitate this, we maintain a document
listing known DID method names and their associated specifications (see Appendix
Expand All @@ -1944,19 +1944,19 @@ <h2>
</p>

<p>
The DID method specification for the specific DID scheme MUST specify
The DID method specification 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
the DID rule in Section <a href="#did-uri-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 DID method specification MAY define multiple specific
specific-idstring formats. It is RECOMMENDED that a DID method
specification define as few specific-idstring formats as possible.
</p>
</section>

Expand Down
10 changes: 5 additions & 5 deletions terms.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
not require a centralized registration authority because it is
registered with <a>distributed ledger</a> technology or other form of
decentralized network. The generic format of a DID is defined in this
specification. A specific <a>DID scheme</a> is defined in a
specification. A DID method scheme is defined in a
<a>DID method</a> specification.
</dd>

Expand Down Expand Up @@ -92,7 +92,7 @@
<dt><dfn data-lt="">DID Method</dfn></dt>

<dd>
A definition of how a specific DID scheme can be implemented
A definition of how a DID method scheme can be implemented
on a specific distributed ledger or network, including the precise
method(s) by which DIDs are resolved and deactivated and DID Documents
are written and updated.
Expand All @@ -119,12 +119,12 @@



<dt><dfn data-lt="">DID Scheme</dfn></dt>
<dt><dfn data-lt="">DID URI Scheme</dfn></dt>

<dd>
The formal syntax of a <a>Decentralized Identifier</a>. The generic DID
The formal syntax of a <a>Decentralized Identifier</a>. The DID URI
scheme is defined in this specification. Separate DID method specifications
define a specific <a>DID scheme</a> that works with that specific DID method.
define DID method schemes that works with that specific DID method.
</dd>


Expand Down