Add FAQ for DIDs.

Co-authored-by: Amy Guy <[email protected]> Co-authored-by: Dave Longley <[email protected]> Co-authored-by: Kyle Den Hartog <[email protected]> Co-authored-by: Joe Andrieu <[email protected]> Co-authored-by: Manu Sporny <[email protected]>
w3c · Feb 1, 2021 · 39877b1 · 39877b1
1 parent 261ce06
commit 39877b1
Show file tree

Hide file tree

Showing 6 changed files with 335 additions and 0 deletions.
diff --git a/diagrams/figure-a.1-did-and-did-document-graph.png b/diagrams/figure-a.1-did-and-did-document-graph.png
diff --git a/diagrams/figure-a.2-also-known-as-graph.png b/diagrams/figure-a.2-also-known-as-graph.png
diff --git a/diagrams/figure-b.1-controller-and-subject-equivalence.png b/diagrams/figure-b.1-controller-and-subject-equivalence.png
diff --git a/diagrams/figure-c.1-independent-did-controllers.png b/diagrams/figure-c.1-independent-did-controllers.png
diff --git a/diagrams/figure-c.2-group-did-controllers.png b/diagrams/figure-c.2-group-did-controllers.png
diff --git a/index.html b/index.html
@@ -5542,6 +5542,340 @@ <h1>Current Issues</h1>
 
   </section>
 
+  <section class="appendix">
+      <h1>Frequently Asked Questions about DID Identification</h1>
+    <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.
+          " >
+          <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 interpret the specific representation of the <a>DID document</a>
+        (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
+    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/home"]
+    </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/"]
+    </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, it is helpful to classify
+    <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
+    <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>
+          </figcaption>
+        </figure>
+    <p>
+    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>
+        </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
+    <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</h1>
 
@@ -5814,5 +6148,6 @@ <h2>application/did+dag+cbor</h2>
 
   </section>
 
+
 </body>
 </html>