appendix text added #460
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4580,6 +4580,340 @@ <h1>Current Issues</h1> | |
|
|
||
| </section> | ||
|
|
||
| <section class="appendix"> | ||
| <h1>Frequently Asked Questions about DID Identification</h1> | ||
|
There was a problem hiding this comment. This PR is looking more and more like something that shouldn't go in the base specification, but rather an implementation guide or primer... Specs typically don't have FAQs in them. We can keep this here for now since we have nowhere else to put it. There was a problem hiding this comment. @msporny I was thinking the same thing and actually played with different names for this section. Happy to change the main heading and reword the subheads so they are not questions. |
||
| <section> | ||
| <h1>What types of resources can a DID identify?</h1> | ||
| <p> | ||
| Since a <a>DID</a> is a specific type of URI (Uniform Resource Identifier), | ||
| the answer to this question is provided by section 1.1 of the URI | ||
| specification [[!RFC3986]]: | ||
| </p> | ||
| <blockquote> | ||
| This specification does not limit the scope of what might be a resource; | ||
| rather, the term "resource" is used in a general sense for whatever might be | ||
| identified by a URI. Familiar examples include an electronic document, an | ||
| image, a source of information with a consistent purpose (e.g., "today's | ||
| weather report for Los Angeles"), a service (e.g., an HTTP-to-SMS gateway), | ||
| and a collection of other resources. A resource is not necessarily | ||
| accessible via the Internet; e.g., human beings, corporations, and bound | ||
| books in a library can also be resources. Likewise, abstract concepts can | ||
| be resources, such as the operators and operands of a mathematical equation, | ||
| the types of a relationship (e.g., "parent" or "employee"), or numeric | ||
| values (e.g., zero, one, and infinity). | ||
| </blockquote> | ||
| <p> | ||
| In other words, it does not matter whether a resource is “on” or “off” the | ||
| Internet—if it can be identified, it can be assigned a URI, and therefore it | ||
| can be assigned a <a>DID</a>. | ||
| </p> | ||
| </section> | ||
| <section> | ||
| <h1>How do you know what a DID identifies?</h1> | ||
| <p> | ||
| For any <a>DID</a>, the <a>DID controller</a> determines the <a>DID subject</a>. | ||
| It is not expected to be possible to determine the <a>DID subject</a> | ||
| from looking at the <a>DID</a> itself. The reason is that, in order to satisfy | ||
| several core properties of a <a>DID</a> as an identifier—especially | ||
| decentralization and cryptographic verifiability—<a>DIDs</a> are generally | ||
| only meaningful to machines, not humans. To illustrate, compare the following | ||
| two URIs: | ||
| </p> | ||
| <p> | ||
| <code>https://www.w3.org/2019/did-wg/WorkMode/getting-started</code> | ||
| </p> | ||
| <p> | ||
| <code>did:example:8uQhQMGzWxR8vw5P3UWH1j</code> | ||
| </p> | ||
| <p> | ||
| The first is the URL of the Getting Started page of the W3C DID Working | ||
| Group. This is a human-meaningful identifier (at least to someone who | ||
| understands the English language). In this sense, the reader can be said to | ||
| “know” what the URL identifies without having to dereference it (provided | ||
| the reader trusts the publisher of the URL). | ||
| </p> | ||
| <p> | ||
| The second URI—the example <a>DID</a>—is meaningless to humans no matter what | ||
| language you speak. What it identifies is anyone’s guess in the absence of | ||
| further information describing the <a>DID subject</a>. So further information | ||
| about the <a>DID subject</a> is only discoverable by resolving the <a>DID</a> | ||
| to the <a>DID document</a>, obtaining a verifiable credential about the | ||
| <a>DID</a>, or via some other description of the <a>DID</a>. | ||
| </p> | ||
| </section> | ||
| <section> | ||
| <h1>Does the DID identify the DID document?</h1> | ||
| <p> | ||
| No. To be very precise, the <a>DID</a> identifies the <a>DID subject</a> and | ||
| <em>resolves to</em> the <a>DID document</a> (by following the protocol | ||
| specified by the <a>DID method</a>). The <a>DID document</a> is not a | ||
| separate resource from the <a>DID subject</a> and does not have a URI | ||
| separate from the <a>DID</a>. Rather the <a>DID document</a> is an artifact | ||
| of <a>DID resolution</a> controlled by the <a>DID controller</a> for the | ||
| purpose of describing the <a>DID subject</a>. | ||
| </p> | ||
| <p> | ||
| This distinction is illustrated by the graph model shown below. | ||
| </p> | ||
| <figure id="did-and-did-document-graph"> | ||
| <img style="margin: auto; display: block; width: 75%;" | ||
| src="diagrams/figure-a.1-did-and-did-document-graph.png" alt=" | ||
| Diagram showing a graph model for how DID controllers assign DIDs to identify | ||
| DID subjects and resolve to DID documents that describe the DID subjects. | ||
|
Comment on lines
+4661
to
+4662
There was a problem hiding this comment. Imagine that you were blind and reading this. It's not clear what a "graph model" looks like. You could say something along the lines of:
There was a problem hiding this comment. I totally agree, @msporny. One question: do I need to do this full description for each of the figures in the appendix? And it may take quite a few words to describe the diagram—is that okay? There was a problem hiding this comment. Yes, we need to do this as a part of our accessibility requirements: #118 -- the description should go in a |
||
| " > | ||
| <figcaption> | ||
| A <a>DID</a> is an identifier assigned by a <a>DID controller</a> | ||
| to identify a <a>DID subject</a> and resolve to a | ||
| <a>DID document</a> that describes the <a>DID subject</a>. The | ||
| <a>DID document</a> is an artifact of <a>DID resolution</a> and | ||
| not a separate resource distinct from the <a>DID subject</a>. | ||
| </figcaption> | ||
| </figure> | ||
| </section> | ||
| <section> | ||
| <h1>What does the DID document say about the DID subject?</h1> | ||
| <p> | ||
| Each property in a <a>DID document</a> is a statement by the | ||
| <a>DID controller</a> that refers to: | ||
| </p> | ||
| <ul> | ||
| <li> | ||
| The string of characters defining identifiers for the <a>DID subject</a> | ||
| (e.g., the <code><a>id</a></code> and <code><a>alsoKnownAs</a></code> | ||
| properties) | ||
| </li> | ||
| <li> | ||
| How to interact with the <a>DID subject</a> (e.g., the | ||
| <code><a>verificationMethod</a></code> and <code><a>service</a></code> | ||
| properties). | ||
| </li> | ||
| <li> | ||
| How to to interpret the specific representation of the <a>DID document</a> | ||
msporny marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| (e.g., the <code>@context</code> property for a JSON-LD representation). | ||
| </li> | ||
| </ul> | ||
| <p> | ||
| There is only one required property in a <a>DID document</a>—the <code><a>id</a></code> | ||
| property—so that is the only statement guaranteed to be in a <a>DID document</a>. | ||
| That statement is illustrated by the solid red arrow in figure 2 asserting | ||
| that the <a>DID</a> identifies the <a>DID subject</a>. | ||
| </p> | ||
| </section> | ||
| <section> | ||
| <h1>How can you discover more information about the DID subject?</h1> | ||
| <p> | ||
| There are two basic options for discovery of more information about the | ||
| <a>DID subject</a>. The first option is to request more information from a | ||
| <a>service endpoint</a> if one or more are present in the <a>DID document</a>. | ||
| An example would be to query a <a>service endpoint</a> that supports | ||
| verifiable credentials for one or more claims (attributes) describing the | ||
| <a>DID subject</a>. | ||
| </p> | ||
| <p> | ||
| A second option is to use the <code><a>alsoKnownAs</a></code> property if it | ||
| is present in the <a>DID document</a>. The <a>DID controller</a> can use it | ||
| to provide a list of other URIs (including other <a>DIDs</a>) that identify | ||
| the same <a>DID subject</a>. Resolving or dereferencing these URIs might yield | ||
| other descriptions or representations of the <a>DID subject</a> as | ||
| illustrated in the figure below. | ||
| </p> | ||
| <figure id="alsoKnownAs-graph"> | ||
| <img style="margin: auto; display: block; width: 75%;" | ||
| src="diagrams/figure-a.2-also-known-as-graph.png" alt=" | ||
| Diagram showing a graph model that adds to figure 2 by showing an | ||
| alsoKnownAs property with an arc to another node representing a | ||
| different resource that dereferences to another description of the | ||
| DID subject. | ||
| " > | ||
| <figcaption> | ||
| A <a>DID document</a> can use the alsoKnownAs property to assert | ||
| another URI (including another <a>DID</a>) that identifies the | ||
| same <a>DID subject</a> | ||
| </figcaption> | ||
| </figure> | ||
| <p> | ||
| This mechanism is how DID identification can fulfill guidance from the W3C | ||
| in <a href="https://www.w3.org/TR/cooluris/">Cool URIs for the Semantic Web</a>: | ||
| </p> | ||
| <blockquote> | ||
| Given only a URI, machines and people should be able to retrieve a | ||
| description about the resource identified by the URI from the Web. Such | ||
| a look-up mechanism is important to establish shared understanding of | ||
| what a URI identifies. Machines should get RDF data and humans should | ||
| get a readable representation, such as HTML. | ||
| </blockquote> | ||
| <p> | ||
| Note that it is not required that a <a>DID document</a> use an | ||
| RDF-based representation; see <a href="#representations"></a>. | ||
| </p> | ||
| </section> | ||
| <section> | ||
| <h2>Can the DID document serve as a representation of the DID subject?</h2> | ||
| <p> | ||
| If the <a>DID subject</a> is a digital resource that can be retrieved | ||
| from the Internet, then yes, the <a>DID document</a> can serve as a | ||
| representation of the <a>DID subject</a>. For example, a data schema that | ||
| needs a persistent, cryptographically verifiable identifier could be | ||
| assigned a <a>DID</a>, and its <a>DID document</a> could be used as a | ||
| standard way to retrieve a representation of that schema. | ||
| </p> | ||
| <p> | ||
| Alternately, a <a>DID</a> can be used to identify a digital resource | ||
| that can be returned directly from a <a>verifiable data registry</a> if | ||
| that functionality is supported by the applicable <a>DID method</a>. | ||
| </p> | ||
| </section> | ||
| <section> | ||
| <h1>Can existing web resources also be assigned DIDs?</h1> | ||
| <p> | ||
| Yes, if the controller of a web page or any other web resource wants to | ||
|
There was a problem hiding this comment. This seems to be a better introduction of the usage of the "alsoKnownAs" property in my opinion. There was a problem hiding this comment. @kdenhartog Thanks - I agree. @rhiaro I'll leave it up to you if you want to reflect that in your text about the "alsoKnownAs" property. |
||
| assign it a persistent, cryptographically verifiable identifier, the | ||
| controller can give it a <a>DID</a>. For example, the author of a blog | ||
| hosted by a blog hosting company (under that hosting company’s own URL) | ||
| could create a <a>DID</a> for the blog. In the <a>DID document</a>, the | ||
| author can include an alsoKnownAs property pointing to the current URL of | ||
| the blog: | ||
| </p> | ||
| <code> | ||
| “alsoKnownAs”: [“https://myblog.blogging-host.example.com/home”] | ||
msporny marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| </code> | ||
| <p> | ||
| If the author subsequently moves the blog to a different hosting company | ||
| (or to the author’s own domain), the author can update the <a>DID document</a> | ||
| to point to the new URL for the blog: | ||
| </p> | ||
| <code> | ||
| “alsoKnownAs”: [“https://myblog.example.com/”] | ||
msporny marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| </code> | ||
| <p> | ||
| The <a>DID</a> effectively adds a layer of indirection for the blog URL. | ||
| This layer of indirection is under the control of the author instead of | ||
| under the control of an external administrative authority such as the blog | ||
| hosting company. This is how a <a>DID</a> can effectively function as an | ||
| enhanced <a href="https://tools.ietf.org/html/rfc8141">URN (Uniform Resource | ||
| Name)</a>—a persistent identifier for an information resource whose network | ||
| location might change over time. | ||
| </p> | ||
| </section> | ||
|
|
||
| <section> | ||
| <h1>What is the relationship between DID controllers and DID subjects?</h1> | ||
| <p> | ||
| To avoid confusion, the DID Working Group has found it helpful to classify | ||
msporny marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| <a>DID subject</a>s into two disjoint sets based on their relationship to | ||
| the <a>DID controller</a>. | ||
| </p> | ||
| <section> | ||
| <h2>Set #1: The DID subject <em>is</em> the DID controller</h2> | ||
| <p> | ||
| The first case, shown in figure 4, is the common scenario where the | ||
|
There was a problem hiding this comment. link to figure directly, numbering might change There was a problem hiding this comment. @rhiaro I totally agree but I'm not sure how to do that. Can I ask for your help with that after I've processed all these suggestions? |
||
| <a>DID subject</a> is also the <a>DID controller</a>. This is the case when | ||
| an individual or organization creates a <a>DID</a> to self-identify. | ||
| </p> | ||
| <figure id="controller-subject-equivalence"> | ||
| <img style="margin: auto; display: block; width: 75%;" | ||
| src="diagrams/figure-b.1-controller-and-subject-equivalence.png" alt=" | ||
| Diagram showing the same graph model as figure 2 except with an | ||
| equivalence arc from the DID subject to the DID controller. | ||
| " > | ||
| <figcaption> | ||
| The <a>DID subject</a> is the same entity as the <a>DID controller</a> | ||
|
There was a problem hiding this comment. This statement still feels a bit off to me. Curious if you're open to saying: "The DID Subject is the same entity as the DID Controller with the assistance of additional software" This nuance has become more apparent to me as we've looked at SSI from a legal perspective and so my thinking is that adding this will help to align legal minds and technical minds a bit more in their mental models. There was a problem hiding this comment. I am not sure I fully grasp the distinction. If the DID Controller, while identifying the same entity as the DID subject, has a different DID as a value, then I can see what you mean. But I would expect that if I create the DID document for my own DID (ie, identifying me) then the value of There was a problem hiding this comment. It feels odd to me to include mention of the "additional software" for the DID Controller. There was a problem hiding this comment.
I find that the analogy of a rake and a person not quite analogous to the situation at hand because the rake is incapable of performing actions on behalf of the person moving the rake. In other words, the rake has no agency whereas software performing digital signatures can. I'd suggest thinking about this example instead. If I had malware loaded onto my router and my router becomes a bot in a botnet and starts further spreading malware who is liable? Am I the owner of the router liable, or is the author of the malware liable, or is the manufacturer of the router liable? The difference comes when considering that the software is often not under the control of the Subject (e.g. they don't write, compile, and publish). Since they are not in control of the software there's the capability of the software behaving in an unexpected way to what the DID Subject expects and consents to. While from an identifier perspective it may appear logical to conjoin the two and say they're the same entity, from a protocol layer it doesn't always make sense. This is essentially the same idea as what OAuth 2.0 has done by separating the resource owner from the Client. They are not always logically equivalent and that distinction becomes important at layers above. Therefore, the DID Controller should be recogonized at least as a combination of the software and the person clicking buttons, not as a single entity. Or in OAuth terms the DID Controller is the combination of the client and the resource owner (although I'd probably be told off by others of assuming those two roles can be collapsed in any way). There was a problem hiding this comment. @brentzundel @iherman @talltree does my argument above sway you guys at all on this topic? There was a problem hiding this comment. I won't fight it going in if others want it, but it feels unnecessarily pedantic to me, especially in a non-normative part of the spec. There was a problem hiding this comment. @kdenhartog Sorry to take so long to reply to this thread but I have been waiting for to gather all the suggestions on the Appendix before processing them all (which I'm doing now). So, first off, yes, I understand the distinction you are making between the DID controller as an entity and the software used by the DID controller to effect control of the DID / DID document. However I don't think it makes it clearer to expand the definition of DID controller to include the software (I actually think that make the situation muddier). However it is a good idea is to clearly state that the DID controller exerts control via software, and from an architectural perspective (and even a legal perspective), that software needs to be taken into account. I will reflect that notion in my update to the Appendix text that I'm preparing right now. However I think your point about the separation between the DID controller as an entity (human, org, thing) and the software is important enough that you should do a PR to either add a separate subsection of Security Considerations to explain it — or see if it can be added to an existing subsection. |
||
| </figcaption> | ||
| </figure> | ||
| <p> | ||
|
There was a problem hiding this comment. I believe the 'Equivalence' (dotted) arc should be symmetric, ie, with an arrow head on both sides. Note that the There was a problem hiding this comment. @iherman Great point, I will fix the version of the diagram I have, and then coordinate the SVGs with you. |
||
| From a graph model perspective, even though the nodes identified as the | ||
| <a>DID controller</a> and <a>DID subject</a> in figure 4 are distinct, | ||
| there is a logical arc connecting them to express a semantic equivalence | ||
| relationship (in RDF/OWL, this is expressed using the <a href="https://www.w3.org/TR/owl-ref/#sameAs-def"><code>owl:sameAs</code> predicate)</a>. | ||
| </p> | ||
|
There was a problem hiding this comment. Purely editorial: I think all predicates like There was a problem hiding this comment. Agreed. I will fix. |
||
| </section> | ||
| <section> | ||
| <h2>Set #2: The DID subject is <em>not</em> the DID controller</h2> | ||
| <p> | ||
| The second case is when the <a>DID subject</a> is a separate entity from the | ||
| <a>DID controller</a>. This is the case when, for example, a parent creates | ||
| and maintains control of a <a>DID</a> for a child; a corporation creates and | ||
| maintains control of a <a>DID</a> for a subsidiary; or a manufacturer | ||
| creates and maintains control of a <a>DID</a> for a product, an IoT device, | ||
| or a digital file. | ||
| </p> | ||
| <p> | ||
| From a graph model perspective, the only difference from Set 1 that there is | ||
| no equivalence arc relationship between the <a>DID subject</a> and | ||
| <a>DID controller</a> nodes. | ||
| </p> | ||
| </section> | ||
| </section> | ||
|
|
||
| <section> | ||
| <h1>Can a DID document have multiple DID Controllers?</h1> | ||
| <p> | ||
| Yes. A <a>DID document</a> might have more than one <a>DID controller</a>. In | ||
| this situation there are two basic options available for how control can be | ||
| shared. | ||
| </p> | ||
| <section> | ||
| <h2>Option #1: Independent Control</h2> | ||
| <p> | ||
| In the first option, shown in the figure below, each of the <a>DID controllers</a> | ||
| might act on its own, i.e., each one has full power to update the | ||
| <a>DID document</a> independently. From a graph model perspective, in this | ||
| configuration: | ||
| </p> | ||
| <ul> | ||
| <li> | ||
| Each additional <a>DID controller</a> is another distinct graph node | ||
| (which might be identified by its own <a>DID</a>). | ||
| </li> | ||
| <li> | ||
| The same arcs (“controls” and “controller”) exist between each | ||
| <a>DID controller</a> and the <a>DID document</a>. | ||
| </li> | ||
| </ul> | ||
| <figure id="independent-did-controllers"> | ||
| <img style="margin: auto; display: block; width: 75%;" | ||
| src="diagrams/figure-c.1-independent-did-controllers.png" alt=" | ||
| Diagram showing three DID controllers each with an independent | ||
| control relationship with the DID document | ||
| " > | ||
| <figcaption> | ||
| Multiple independent <a>DID controllers</a> that can each act | ||
| independently | ||
| </figcaption> | ||
| </figure> | ||
| </section> | ||
| <section> | ||
| <h2>Option #2: Group Control</h2> | ||
| <p> | ||
| In the second option, the <a>DID controllers</a> are expected to act together in some | ||
| fashion, such as when using a cryptographic algorithm that requires multiple | ||
| digital signatures (“multi-sig”) or a threshold number of digital | ||
| signatures (“m-of-n”). From a functional standpoint, this option is similar | ||
| to a single <a>DID controller</a> because, although each of the | ||
|
There was a problem hiding this comment. Maybe it is worth, for laypersons, to have some sort of a reference or some example somewhere else in the document how a There was a problem hiding this comment. For multi-sig we could include multiple Link Data Security proofs as an array in a document showing the old state and the new state being signed by multiple keys from the old state. If we want to show a simple threshold option, we could talk about using a Shamir's secret sharing scheme, but from an example perspective there's not a great solution for this because this feature is actually managed at the key management layer. Another example that would be more complicated, but could show good examples would be to use a BLS Threshold signature. However, I don't know of anyone that's got running code to show that working properly and able to produce legitimate signatures with. If we just want some example signatures that don't actually verify I'm sure we could just encode a random string to the proper length and that would work, but we'd have no additional documentation about the LD security suite that would be associated with it because no one has actually created and properly documented that work. There was a problem hiding this comment. @iherman and @kdenhartog I agree with both of you that such examples would be helpful for the spec. However I don't think this appendix is the place for them vs. someplace in the main body of the spec. If one or more examples are added there, then we can add links to them from here. |
||
| <a>DID controllers</a> in the <a>DID controller</a> group has its own graph | ||
| node, the actual control collapses into a single logical graph node | ||
| representing the <a>DID controller</a> group as shown in this figure: | ||
| </p> | ||
| <figure id="group-did-controllers"> | ||
| <img style="margin: auto; display: block; width: 75%;" | ||
| src="diagrams/figure-c.2-group-did-controllers.png" alt=" | ||
| Diagram showing how three DID controllers act together as a single | ||
| DID controller group to control a DID document | ||
| " > | ||
| <figcaption> | ||
| Multiple <a>DID controllers</a> who are expected to act together as a | ||
| <a>DID controller</a> group | ||
| </figcaption> | ||
| </figure> | ||
| <p> | ||
| This configuration will often apply when the <a>DID subject</a> is an | ||
| organization, corporation, government agency, community, or other group | ||
| that is not controlled by a single individual. | ||
| </p> | ||
| </section> | ||
|
|
||
| </section> | ||
|
|
||
| <section class="appendix"> | ||
| <h1> | ||
| IANA Considerations | ||
|
|
@@ -4842,5 +5176,6 @@ <h2>application/did+dag+cbor</h2> | |
|
|
||
| </section> | ||
|
|
||
|
|
||
| </body> | ||
| </html> | ||
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.
A bunch of editorial remarks:
Please, use the respec trick of enclosing all subsections into its own
<section>resulting in:The latter feature is important for accessibility, and our document must be accessible.
I do not know if it is possible to get some clear definition of what the color coding of the diagrams are...
It would be great if all diagrams were done in SVG with a PNG fallback. I do not think these diagrams would work well on a mobile screen... To put my money where my mouth is, if you have difficulties with the recreation of the diagrams in SVG I can also do it, I have some diagram-creating tools that generate decent SVG.
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.
In fact, again editorially, it would be good to have all these as one single Appendix with sub-appendixes. Seen from the point of view of the overall document, they are pretty much related after all...
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.
+1 @iherman
@talltree I can do the section-wrangling to do what Ivan suggests if you like, either before or after any content changes are made (just, probably, not at the same time) - just let me know
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.
@iherman Agree on all your points. After accepting the numerous other suggestions, I will do a first pass on that refactoring. @rhiaro I may very well need your help in further formatting after I get through that refactor.