From c9a6ecd40e6c70848b625dc1445c307764a40732 Mon Sep 17 00:00:00 2001
From: Markus Sabadello <markus@danubetech.com>
Date: Thu, 17 Sep 2020 12:14:38 +0200
Subject: [PATCH 01/89] Make alsoKnownAs a subsection of DID Subject.
---
index.html | 40 ++++++++++++++++++++++------------------
1 file changed, 22 insertions(+), 18 deletions(-)
diff --git a/index.html b/index.html
index 8fe21ac8..3b8d1d96 100644
--- a/index.html
+++ b/index.html
@@ -1220,7 +1220,7 @@ <h1>Core Properties</h1>
<code><a>id</a></code>: defined in <a href="#did-subject"></a>
</li>
<li>
-<code><a>alsoKnownAs</a></code>: defined in <a href="#did-subject"></a>
+<code><a>alsoKnownAs</a></code>: defined in <a href="#alsoknownas"></a>
</li>
<li>
<code><a>controller</a></code>: defined in <a href="#control"></a>
@@ -1293,32 +1293,35 @@ <h2>DID Subject</h2>
party going forward.
</p>
- <p>
+ <section>
+ <h3>alsoKnownAs</h3>
+
+ <p>
A <a>DID subject</a> can have multiple identifiers for different purposes, or
at different times. The assertion that two or more <a>DIDs</a> (or other types
of <a>URI</a>) identify the same <a>DID subject</a> can be made using the
<code><a>alsoKnownAs</a></code> property.
- </p>
+ </p>
- <p>
+ <p>
<a>DID documents</a> MAY include the <code><a>alsoKnownAs</a></code> property.
- </p>
+ </p>
- <dl>
- <dt><dfn>alsoKnownAs</dfn></dt>
- <dd>
+ <dl>
+ <dt><dfn>alsoKnownAs</dfn></dt>
+ <dd>
The value of <code>alsoKnownAs</code> MUST be a
<a data-cite="INFRA#lists">list</a> where each item in the list is a
<a>URI</a> conforming to [[RFC3986]].
- </dd>
- <dd>
+ </dd>
+ <dd>
This relationship is a statement that the subject of this identifier is
also identified by one or more other identifiers.
- </dd>
- </dl>
+ </dd>
+ </dl>
- <div class="note" title="Equivalence and alsoKnownAs">
- <p>
+ <div class="note" title="Equivalence and alsoKnownAs">
+ <p>
Applications might choose to consider two identifiers related by
<code><a>alsoKnownAs</a></code> to be equivalent <em>if</em> the
<code><a>alsoKnownAs</a></code> relationship is reciprocated in the reverse
@@ -1327,15 +1330,16 @@ <h2>DID Subject</h2>
<code><a>alsoKnownAs</a></code> assertion does not prove that this assertion
is true. Therefore it is strongly advised that a requesting party obtain
independent verification of an <code>alsoKnownAs</code> assertion.
- </p>
- <p>
+ </p>
+ <p>
Given that the <a>DID subject</a> might use different identifiers for different
purposes, an expectation of strong equivalence between the two identifiers, or
merging the graphs of the two corresponding <a>DID documents</a>, is not
necessarily appropriate, <em>even with</em> a reciprocal relationship.
- </p>
- </div>
+ </p>
+ </div>
+ </section>
</section>
<section>
From 21bd17b0f58aa9104bf9d5b1de60d5f2a1530745 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Mon, 21 Sep 2020 12:10:21 +0100
Subject: [PATCH 02/89] respec: replace WG info with 'group' property and fix
internal refs
---
index.html | 46 ++++++++++++++++++++++------------------------
1 file changed, 22 insertions(+), 24 deletions(-)
diff --git a/index.html b/index.html
index 3b8d1d96..246f1d5d 100644
--- a/index.html
+++ b/index.html
@@ -22,10 +22,8 @@
</script>
<script class="remove" type="text/javascript">
var respecConfig = {
- wgPublicList: "public-did-wg",
- wgPatentURI: "https://www.w3.org/2004/01/pp-impl/117488/status",
- wg: "Decentralized Identifier Working Group",
- wgURI: "https://www.w3.org/2019/did-wg/",
+ wgPublicList: "public-did-wg",
+ group: "did",
// specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "WD",
@@ -1288,8 +1286,8 @@ <h2>DID Subject</h2>
However, the fully resolved <a>DID document</a> always contains a valid
<code><a>id</a></code> property. The value of <code><a>id</a></code> in the
resolved <a>DID document</a> MUST match the <a>DID</a> that was
-resolved, or be populated with the equivalent canonical <a>DID</a>
-specified by the <a>DID method</a>, which SHOULD be used by the resolving
+resolved, or be populated with the equivalent canonical <a>DID</a>
+specified by the <a>DID method</a>, which SHOULD be used by the resolving
party going forward.
</p>
@@ -1465,7 +1463,7 @@ <h2>Verification Methods</h2>
values are set to the public key fingerprint [[RFC7638]]. It is RECOMMENDED
that verification methods that use JWKs to represent their public keys utilize
the value of <code>kid</code> as their fragment identifier. See the first key
-in <a href="#example-17-various-public-keys">example of various public keys</a>
+in <a href="#example-13-various-public-keys"></a>
for an example of a public key with a compound key identifier.
</p>
@@ -2555,11 +2553,11 @@ <h3>
provided, the <a>URIs</a> MUST be interpreted as an ordered set. It is
RECOMMENDED that dereferencing each <a>URI</a> results in a document containing
machine-readable information about the context. To enable interoperability
-with other representations, <a>URLs</a> registered in the
-DID Specification Registries [[DID-SPEC-REGISTRIES]] referring to
-JSON-LD Contexts SHOULD be associated with a cryptographic hash of
+with other representations, URLs registered in the
+DID Specification Registries [[DID-SPEC-REGISTRIES]] referring to
+JSON-LD Contexts SHOULD be associated with a cryptographic hash of
the content of the JSON-LD Context. This ensures that the interpretation of the
-information by JSON-LD consumers will be the same as interpretations
+information by JSON-LD consumers will be the same as interpretations
over other representations by other consumers that rely on the
DID Specification Registries [[DID-SPEC-REGISTRIES]].
</dd>
@@ -2984,7 +2982,7 @@ <h2>Method Schemes</h2>
The meaning of colons in the <code>method-specific-id</code> is entirely
method-specific. Colons might be used by <a>DID methods</a> for establishing
hierarchically partitioned namespaces, for identifying specific instances or
-parts of the <a>verifiable data registry</a>, or for other purposes.
+parts of the <a>verifiable data registry</a>, or for other purposes.
Implementers are advised to avoid assuming any meanings or
behaviors associated with a colon that are generically applicable to all
<a>DID methods</a>.
@@ -3488,7 +3486,7 @@ <h2>
relating to the results of the <a>DID URL Dereferencing</a> process. This
structure is REQUIRED and in the case of an error in the dereferencing process,
this MUST NOT be empty.
-Properties defined by this specification are in
+Properties defined by this specification are in
<a href="#did-url-dereferencing-metadata-properties"></a>.
If the dereferencing is not successful, this structure MUST contain an
<code>error</code> property describing the error.
@@ -3511,7 +3509,7 @@ <h2>
<dd>
If the dereferencing is successful, this MUST be a <a href="metadata-structure">
metadata structure</a>, but the structure MAY be empty. This structure contains
-metadata about the <code>content-stream</code>.
+metadata about the <code>content-stream</code>.
If the <code>content-stream</code> is a <a>DID document</a>, this MUST be a
<code>did-document-metadata</code> structure as described in <a>DID
Resolution</a>.
@@ -3636,8 +3634,8 @@ <h2>
Each property value MUST be a <a data-cite="INFRA#string">string</a>,
<a data-cite="INFRA#maps">map</a>, <a data-cite="INFRA#lists">list</a>,
<a data-cite="INFRA#boolean">boolean</a>, or <a data-cite="INFRA#null">null</a>.
-The values within any complex data structures such as maps and lists
-MUST be one of these data types as well.
+The values within any complex data structures such as maps and lists
+MUST be one of these data types as well.
All metadata property definitions MUST define the value type, including any additional
formats or restrictions to that value (for example, a string formatted as a date or as a decimal integer).
It is RECOMMENDED that property definitions use strings for values where possible.
@@ -3647,7 +3645,7 @@ <h2>
All implementations of functions that use metadata structures as either input or output MUST
be able to fully represent all data types described here in a deterministic fashion. As inputs and
outputs using metadata structures are defined in terms of data types and not their serialization,
-the method for representation is internal to the implementation of the function and is out of
+the method for representation is internal to the implementation of the function and is out of
scope of this specification.
</p>
@@ -3682,7 +3680,7 @@ <h2>
{
"error": "not-found"
}
- </pre>
+ </pre>
<p>
This example corresponds to a metadata structure of the following format:
@@ -4224,7 +4222,7 @@ <h2>
</p>
<p class="note">
- These examples are for information purposes only,
+ These examples are for information purposes only,
it is considered a best practice to avoid using the same verification method for multiple purposes.
</p>
@@ -4361,7 +4359,7 @@ <h2>
]
}
</pre>
-
+
</section>
<section class="informative">
@@ -4370,13 +4368,13 @@ <h2>
</h2>
<p class="note">
- These examples are for information purposes only.
+ These examples are for information purposes only.
See <a href="https://www.w3.org/TR/vc-data-model/">
W3C Verifiable Credentials Data Model
</a> for additional examples.
</p>
- <pre class="example" title="Verifiable Credential linked to a verification method of type Ed25519VerificationKey2018">
+ <pre class="example" title="Verifiable Credential linked to a verification method of type Ed25519VerificationKey2018">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
@@ -4418,7 +4416,7 @@ <h2>
}
</pre>
- <pre class="example" title="Verifiable Credential linked to a verification method of type JsonWebKey2020">
+ <pre class="example" title="Verifiable Credential linked to a verification method of type JsonWebKey2020">
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
@@ -4489,7 +4487,7 @@ <h2>
Encrypting
</h2>
<p class="note">
- These examples are for information purposes only,
+ These examples are for information purposes only,
it is considered a best practice to avoid dislosing unnecessary information in JWE headers.
</p>
<pre class="example" title="JWE linked to a verification method via kid">
From 7f3c0bab2228730e4c24ae3fbb959eca78609ce2 Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Sun, 20 Sep 2020 09:55:52 -0500
Subject: [PATCH 03/89] chore: add JsonWebKey2020 to did core
---
index.html | 10 +++++++++-
1 file changed, 9 insertions(+), 1 deletion(-)
diff --git a/index.html b/index.html
index 246f1d5d..f4f300c2 100644
--- a/index.html
+++ b/index.html
@@ -1688,6 +1688,14 @@ <h3>Key types and formats</h3>
Bitcoin format [[BASE58]] using the <code>publicKeyBase58</code> property.
</td>
</tr>
+ <tr>
+ <td>
+JWK<br/>(<code>JsonWebKey2020</code>)
+ </td>
+ <td>
+Key types listed in <a href="https://www.iana.org/assignments/jose/jose.xhtml">JOSE</a>, represented using [[RFC7517]] using the <code>publicKeyJwk</code> property.
+ </td>
+ </tr>
</tbody>
</table>
@@ -1702,7 +1710,7 @@ <h3>Key types and formats</h3>
<span class="comment">...</span>
"verificationMethod": [{
"id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
- "type": "JwsVerificationKey2020",
+ "type": "JsonWebKey2020",
"controller": "did:example:123",
"publicKeyJwk": {
"crv": "Ed25519",
From fa2bd93bd2ee21ae8a9914cff5e7621cfa30c495 Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Tue, 22 Sep 2020 19:27:24 -0500
Subject: [PATCH 04/89] chore: address #356 - forbid multiple key formats in
the same verification method
---
index.html | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/index.html b/index.html
index f4f300c2..3a218b4f 100644
--- a/index.html
+++ b/index.html
@@ -1588,6 +1588,14 @@ <h3>Key types and formats</h3>
A public key can be used as a <a>verification method</a>.
</p>
+<p>
+A <a>verification method</a> MUST contain a single verification material property
+(for example <code>publicKeyJwk</code> or <code>publicKeyBase58</code>, not both).
+</p>
+
+
+
+
<p>
This specification strives to limit the number of formats for expressing public
key material in a <a>DID document</a> to the fewest possible, to increase the
From 55c97d6c37068784a2aa74ae236beca61f1c67d3 Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Tue, 22 Sep 2020 19:28:40 -0500
Subject: [PATCH 05/89] chore: remove whitespace
---
index.html | 3 ---
1 file changed, 3 deletions(-)
diff --git a/index.html b/index.html
index 3a218b4f..6738a602 100644
--- a/index.html
+++ b/index.html
@@ -1593,9 +1593,6 @@ <h3>Key types and formats</h3>
(for example <code>publicKeyJwk</code> or <code>publicKeyBase58</code>, not both).
</p>
-
-
-
<p>
This specification strives to limit the number of formats for expressing public
key material in a <a>DID document</a> to the fewest possible, to increase the
From 83eb1c576dde0401451f42071a17e6baa3eaf651 Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Wed, 23 Sep 2020 09:08:29 -0500
Subject: [PATCH 06/89] Update index.html
Co-authored-by: Manu Sporny <msporny@digitalbazaar.com>
---
index.html | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/index.html b/index.html
index 6738a602..39bdf8ad 100644
--- a/index.html
+++ b/index.html
@@ -1589,8 +1589,10 @@ <h3>Key types and formats</h3>
</p>
<p>
-A <a>verification method</a> MUST contain a single verification material property
-(for example <code>publicKeyJwk</code> or <code>publicKeyBase58</code>, not both).
+A <a>verification method</a> MUST NOT contain multiple verification material properties.
+For example, expressing key material in a <a>verification method</a> using both
+<code>publicKeyJwk</code> and <code>publicKeyBase58</code> at the same time
+is prohibited.
</p>
<p>
From e03c72817c5b87e6a74db24147f21ba3288ab15c Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Wed, 30 Sep 2020 08:37:01 -0500
Subject: [PATCH 07/89] chore: fix shortname
---
w3c.json | 16 ++++++++++------
1 file changed, 10 insertions(+), 6 deletions(-)
diff --git a/w3c.json b/w3c.json
index 0bdcfd97..89dc10f0 100644
--- a/w3c.json
+++ b/w3c.json
@@ -1,6 +1,10 @@
- {
- "group": [117488]
-, "contacts": ["iherman"]
-, "repo-type": "rec-track"
-, "shortName": "did-spec"
-}
+{
+ "group": [
+ 117488
+ ],
+ "contacts": [
+ "iherman"
+ ],
+ "repo-type": "rec-track",
+ "shortName": "did-core"
+}
\ No newline at end of file
From 49d8ae4cd2802dbd335e1c8b0021e786be99b6c5 Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Thu, 8 Oct 2020 08:19:51 -0500
Subject: [PATCH 08/89] Allow fragments to be applied to secondary resources.
* fix: allow fragments to be applied to secondary resources regardless of representation
Co-authored-by: Manu Sporny <msporny@digitalbazaar.com>
---
index.html | 35 ++++++++++++++++++++++++-----------
1 file changed, 24 insertions(+), 11 deletions(-)
diff --git a/index.html b/index.html
index 39bdf8ad..f7cfcde3 100644
--- a/index.html
+++ b/index.html
@@ -1028,15 +1028,15 @@ <h2>Query</h2>
<h2>Fragment</h2>
<p>
-A <a>DID fragment</a> is used as method-independent reference into the <a>DID
-document</a> to identify a component of the document (for example, a unique
-<a>public key description</a> or <a>service endpoint</a>). <a>DID fragment</a>
-syntax and semantics are identical to a generic URI fragment and MUST conform
-to <a data-cite="RFC3986#section-3.5">RFC 3986, section 3.5</a>. To
-dereference a <a>DID fragment</a>, the complete <a>DID URL</a> including the
+A <a>DID fragment</a> is used as method-independent reference into a <a>DID Document</a> or external resource.
+ </p>
+
+<p>
+<a>DID fragment</a> syntax and semantics are identical to a generic URI fragment
+and MUST conform to <a data-cite="RFC3986#section-3.5">RFC 3986, section 3.5</a>.
+To dereference a <a>DID fragment</a>, the complete <a>DID URL</a> including the
<a>DID fragment</a> MUST be used as input to the <a>DID URL dereferencing</a>
-function for the target component in the <a>DID document</a> object. For more
-information, see <a href="#did-url-dereferencing"></a>.
+function. For more information, see <a href="#did-url-dereferencing"></a>.
</p>
<p>
@@ -1044,9 +1044,7 @@ <h2>Fragment</h2>
that are more restrictive than the generic rules in this section.
</p>
- <pre class="example nohighlight">
-did:example:123456#public-key-1
- </pre>
+
<p>
In order to maximize interoperability, implementers are urged to ensure that
@@ -1056,6 +1054,21 @@ <h2>Fragment</h2>
be interpreted in the same way across representations.
</p>
+ <p>For example:</p>
+ <ul>
+ <li>A unique <a>verification method</a> in a <a>DID Document</a>
+ <pre class="example nohighlight">did:example:123#public-key-0</pre>
+ </li>
+
+ <li>A unique <a>service endpoint</a> in a <a>DID Document</a>
+ <pre class="example nohighlight">did:example:123#agent</pre>
+ </li>
+
+ <li>A resource external to a <a>DID Document</a>
+ <pre class="example nohighlight">did:example:123?service=agent&relativeRef=/credentials#degree</pre>
+ </li>
+ </ul>
+
<p>
Additional semantics for fragment identifiers, which are compatible with and
layered upon the semantics in this section, are described for JSON-LD
From 10c12c354f375f7126d2ee31bf2c4b981b5e94f9 Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Sun, 20 Sep 2020 10:40:06 -0500
Subject: [PATCH 09/89] chore: cleanup key representations
---
index.html | 37 ++++++++++++-------------------------
1 file changed, 12 insertions(+), 25 deletions(-)
diff --git a/index.html b/index.html
index f7cfcde3..28776cdb 100644
--- a/index.html
+++ b/index.html
@@ -1644,7 +1644,7 @@ <h3>Key types and formats</h3>
<table class="simple" id="public-key-support">
<caption>
This table defines the support for public key expression in a DID document.
-For each public key type, a maximum of two encoding formats are supported.
+For each public key type, a maximum of two encoding formats is supported.
</caption>
<thead>
<tr>
@@ -1663,9 +1663,8 @@ <h3>Key types and formats</h3>
RSA<br/>(<code>RsaVerificationKey2018</code>)
</td>
<td>
-RSA public key values MUST either be encoded as a JWK [[RFC7517]] or be
-encoded in Privacy Enhanced Mail (PEM) format using the
-<code>publicKeyPem</code> property.
+RSA public key values MUST be encoded as a JWK [[RFC7517]] using the
+<code>publicKeyJwk</code> property.
</td>
</tr>
<tr>
@@ -1673,38 +1672,31 @@ <h3>Key types and formats</h3>
ed25519<br/>(<code>Ed25519VerificationKey2018</code>)
</td>
<td>
-Ed25519 public key values MUST either be encoded as a JWK [[RFC7517]] or be
+Ed25519 public key values MUST either be encoded as a JWK [[RFC7517]]
+using the <code>publicKeyJwk</code> or be
encoded as the raw 32-byte public key value in Base58 Bitcoin format
[[BASE58]] using the <code>publicKeyBase58</code> property.
</td>
</tr>
<tr>
<td>
-secp256k1-koblitz<br/>(pending)
+secp256k1
</td>
<td>
-Secp256k1 Koblitz public key values MUST either be encoded as a JWK
-[[RFC7517]] or be encoded as the raw 33-byte public key value in Base58
+Secp256k1 Koblitz public key values MUST either be encoded as a JWK [[RFC7517]]
+using the <code>publicKeyJwk</code> or be
+encoded as the raw 33-byte public key value in Base58
Bitcoin format [[BASE58]] using the <code>publicKeyBase58</code> property.
</td>
</tr>
<tr>
<td>
-secp256r1<br/>(<code>SchnorrSecp256k1VerificationKey2019</code>)
- </td>
- <td>
-Secp256r1 public key values MUST either be encoded as a JWK [[RFC7517]] or be
-encoded as the raw 32-byte public key value encoded in Base58 Bitcoin format
-[[BASE58]] using the <code>publicKeyBase58</code> property.
- </td>
- </tr>
- <tr>
- <td>
Curve25519<br/>(<code>X25519KeyAgreementKey2019</code>)
</td>
<td>
-Curve25519 (also known as X25519) public key values MUST either be encoded as
-a JWK [[RFC7517]] or be encoded as the raw 32-byte public key value in Base58
+Curve25519 (also known as X25519) public key values MUST either be encoded
+as a JWK [[RFC7517]] using the <code>publicKeyJwk</code> or be
+encoded as the raw 32-byte public key value in Base58
Bitcoin format [[BASE58]] using the <code>publicKeyBase58</code> property.
</td>
</tr>
@@ -1743,11 +1735,6 @@ <h3>Key types and formats</h3>
"type": "Ed25519VerificationKey2018",
"controller": "did:example:pqrstuvwxyz0987654321",
"publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
- }, {
- "id": "did:example:123456789abcdefghi#keys-2",
- "type": "Secp256k1VerificationKey2018",
- "controller": "did:example:123456789abcdefghi",
- "publicKeyHex": "02b97c30de767f084ce3080168ee293053ba33b235d7116a3263d29f1450936b71"
}],
<span class="comment">...</span>
}
From 058c48d29ab12bd65ccfc6538114258af37b3e96 Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Sun, 20 Sep 2020 10:45:11 -0500
Subject: [PATCH 10/89] chore: remove redundantt word
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index 28776cdb..aaeea96f 100644
--- a/index.html
+++ b/index.html
@@ -1683,7 +1683,7 @@ <h3>Key types and formats</h3>
secp256k1
</td>
<td>
-Secp256k1 Koblitz public key values MUST either be encoded as a JWK [[RFC7517]]
+Secp256k1 public key values MUST either be encoded as a JWK [[RFC7517]]
using the <code>publicKeyJwk</code> or be
encoded as the raw 33-byte public key value in Base58
Bitcoin format [[BASE58]] using the <code>publicKeyBase58</code> property.
From adf41c8f3e5d597e279f4806f86ca8e8f55c5354 Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Fri, 9 Oct 2020 12:19:01 -0500
Subject: [PATCH 11/89] chore: add issue linking to #423
---
index.html | 7 +++++++
1 file changed, 7 insertions(+)
diff --git a/index.html b/index.html
index aaeea96f..ea508477 100644
--- a/index.html
+++ b/index.html
@@ -1641,6 +1641,13 @@ <h3>Key types and formats</h3>
expressed and encoded.
</p>
+<p class="issue" data-number="423">
+The Working Group is still debating how best to communicate support for
+specific verification method types.
+</p>
+
+ https://github.com/w3c/did-core/issues/
+
<table class="simple" id="public-key-support">
<caption>
This table defines the support for public key expression in a DID document.
From fc88a586c63d4c0308148f9fc07f06d5805ae254 Mon Sep 17 00:00:00 2001
From: Orie Steele <orie@transmute.industries>
Date: Mon, 12 Oct 2020 09:12:47 -0500
Subject: [PATCH 12/89] Add JSON-LD Producer / Consumer details.
* chore: use infra to define context value types
* chore: add issue regarding working group activity
* chore: remove @base in example
Co-authored-by: Tobias Looker <tplooker@gmail.com>
Co-authored-by: Manu Sporny <msporny@digitalbazaar.com>
---
index.html | 86 +++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 66 insertions(+), 20 deletions(-)
diff --git a/index.html b/index.html
index ea508477..3639d858 100644
--- a/index.html
+++ b/index.html
@@ -2399,6 +2399,7 @@ <h3>Production</h3>
reserved for JSON-LD producers.
</p>
+
</section>
<section>
@@ -2524,34 +2525,73 @@ <h3>
</h3>
<p>
-The <a>DID document</a> is serialized following the rules in the JSON processor,
-with one addition: <a>DID documents</a> MUST include the <code>@context</code>
-property.
+The <a>DID document</a> MUST be serialized as a JSON document,
+with one additional requirement: <br/>
+The <a>DID document</a> MUST include the <code>@context</code> property.
</p>
<dl>
<dt>@context</dt>
<dd>
-The value of the <code>@context</code> property MUST be one or more <a>URIs</a>,
-where the value of the first <a>URI</a> is
-<code>https://www.w3.org/ns/did/v1</code>. All members of the
+
+<p>
+The <a href="https://www.w3.org/TR/json-ld11/#the-context">JSON-LD specification </a>
+defines values that are valid for this property.
+</p>
+
+<p>
+The value of <code>@context</code> MUST be exactly one of these values.
+</p>
+
+<ul>
+ <li>
+ The <a href="https://infra.spec.whatwg.org/#strings">INFRA string</a>
+ <code>https://www.w3.org/ns/did/v1</code>.
+ <pre class="example">
+ {
+ "@context": "https://www.w3.org/ns/did/v1",
+ ...
+ }
+ </pre>
+ </li>
+ <li>
+ An <a href="https://infra.spec.whatwg.org/#lists">INFRA list</a>,
+ with first item the <a href="https://infra.spec.whatwg.org/#strings">INFRA string</a>
+ <code>https://www.w3.org/ns/did/v1</code>, and subsequent items of type
+ <a href="https://infra.spec.whatwg.org/#strings">INFRA string</a> or
+ <a href="https://infra.spec.whatwg.org/#maps">INFRA map</a>.
+ <pre class="example">
+ {
+ "@context": [
+ "https://www.w3.org/ns/did/v1",
+ "https://example.com/blockchain-identity/v1"
+ ],
+ ...
+ }
+ </pre>
+ <p class="issue" data-number="432">The working group is still discussing restrictions on <code>@base</code>, beyond what JSON-LD allows.</p>
+ </li>
+</ul>
+
+
+All members of the
<code>@context</code> property SHOULD exist in the DID specification
registries in order to achieve interoperability across different
-representations. If a member does not exist in the DID specification
-registries, then the DID Document will not be interoperable across
+representations.
+
+If a member does not exist in the DID specification
+registries, then the DID Document might not be interoperable across
representations.
+
+<p>
+ Producers SHOULD NOT produce DID Documents that
+ contain properties not defined via the <code>@context</code>.
+ Properties that are not defined via the <code>@context</code> MAY be dropped by Consumers.
+</p>
+
</dd>
</dl>
- <p class="issue" data-number="202">
-This specification defines globally interoperable documents, and the requirement
-that the context value be in the verifiable data registry means that different JSON-LD
-processors can consume the document without having to dereference anything in
-the context field. However, a pair of producers and consumers can have local
-extension agreements. This needs to be clarified in a section on extensibility
-and linked here when available.
- </p>
-
</section>
<section>
@@ -2569,9 +2609,10 @@ <h3>
<dl>
<dt>@context</dt>
<dd>
-The value of the <code>@context</code> property MUST be one or more <a>URIs</a>,
-where the value of the first <a>URI</a> is
-<code>https://www.w3.org/ns/did/v1</code>. If more than one <a>URI</a> is
+The value of the <code>@context</code> property MUST conform
+to the <a href="#production-0">JSON-LD Production Rules</a>.
+
+If more than one <a>URI</a> is
provided, the <a>URIs</a> MUST be interpreted as an ordered set. It is
RECOMMENDED that dereferencing each <a>URI</a> results in a document containing
machine-readable information about the context. To enable interoperability
@@ -2595,6 +2636,11 @@ <h3>
that decision.
</p>
+ <p>
+ Consumers SHOULD drop all properties from a DID Documents that
+ are not defined via the <code>@context</code>.
+ </p>
+
</section>
</section>
From 9ebb3bde862b29d8daba630a76a75a9ed469d7dd Mon Sep 17 00:00:00 2001
From: Markus Sabadello <markus@danubetech.com>
Date: Sat, 3 Oct 2020 01:50:16 +0200
Subject: [PATCH 13/89] Rename resolveStream to resolveRepresentation
---
index.html | 20 ++++++++++----------
1 file changed, 10 insertions(+), 10 deletions(-)
diff --git a/index.html b/index.html
index 3639d858..6fd3ea21 100644
--- a/index.html
+++ b/index.html
@@ -3281,7 +3281,7 @@ <h2>
</code></p>
<p><code>
-resolveStream ( did, did-resolution-input-metadata ) <br>
+resolveRepresentation ( did, did-resolution-input-metadata ) <br>
-> ( did-resolution-metadata, did-document-stream, did-document-metadata )
</code></p>
@@ -3302,7 +3302,7 @@ <h2>
</dt>
<dd>
A <a href="#metadata-structure">metadata structure</a> consisting of input
-options to the <code>resolve</code> and <code>resolveStream</code> functions in addition to the <code>did</code>
+options to the <code>resolve</code> and <code>resolveRepresentation</code> functions in addition to the <code>did</code>
itself.
Properties defined by this specification are in <a href="#did-resolution-input-metadata-properties"></a>.
This input is REQUIRED, but the structure MAY be empty.
@@ -3321,10 +3321,10 @@ <h2>
A <a href="#metadata-structure">metadata structure</a> consisting of values
relating to the results of the <a>DID resolution</a> process. This structure is
REQUIRED and MUST NOT be empty. This metadata typically changes between
-invocations of the <code>resolve</code> and <code>resolveStream</code> functions as it represents data about the
+invocations of the <code>resolve</code> and <code>resolveRepresentation</code> functions as it represents data about the
resolution process itself.
Properties defined by this specification are in <a href="#did-resolution-metadata-properties"></a>.
-If the resolution is successful, and if the <code>resolveStream</code> function was called, this structure MUST contain a <code>content-type</code> property containing the mime-type of the <code>did-document-stream</code> in this result.
+If the resolution is successful, and if the <code>resolveRepresentation</code> function was called, this structure MUST contain a <code>content-type</code> property containing the mime-type of the <code>did-document-stream</code> in this result.
If the resolution is not successful, this structure MUST contain an <code>error</code> property describing the error.
</dd>
<dt>
@@ -3338,9 +3338,9 @@ <h2>
did-document-stream
</dt>
<dd>
-If the resolution is successful, and if the <code>resolveStream</code> function was called, this MUST be a byte stream of the resolved
+If the resolution is successful, and if the <code>resolveRepresentation</code> function was called, this MUST be a byte stream of the resolved
<a>DID document</a> in one of the conformant <a href="#representations">representations</a>. The byte
-stream MAY then be parsed by the caller of the <code>resolveStream</code> function
+stream MAY then be parsed by the caller of the <code>resolveRepresentation</code> function
into a <a>DID document</a> abstract data model, which can in turn be validated
and processed. If the resolution is unsuccessful, this value MUST be an empty
stream.
@@ -3364,7 +3364,7 @@ <h2>
<p>
<a>DID resolver</a> implementations MUST NOT alter the signature of these
functions in any way. <a>DID resolver</a> implementations MAY map the
-<code>resolve</code> and <code>resolveStream</code> functions to a method-specific internal function to perform
+<code>resolve</code> and <code>resolveRepresentation</code> functions to a method-specific internal function to perform
the actual <a>DID resolution</a> process. <a>DID resolver</a> implementations
MAY implement and expose additional
functions with different signatures in addition to the <code>resolve</code>
@@ -3388,7 +3388,7 @@ <h3>
<dd>
The MIME type of the caller's preferred <a href="#representations">representation</a> of the <a>DID document</a>. The <a>DID resolver</a> implementation
SHOULD use this value to determine the representation contained in the returned <code>did-document-stream</code> if such
-a representation is supported and available. This property is OPTIONAL. It is only used if the <code>resolveStream</code>
+a representation is supported and available. This property is OPTIONAL. It is only used if the <code>resolveRepresentation</code>
function is called and MUST be ignored if the <code>resolve</code> function is called.
</dd>
</dl>
@@ -3410,10 +3410,10 @@ <h3>
</dt>
<dd>
The MIME type of the returned <code>did-document-stream</code>.
-This property is REQUIRED if resolution is successful and if the <code>resolveStream</code> function was called.
+This property is REQUIRED if resolution is successful and if the <code>resolveRepresentation</code> function was called.
It MUST NOT be present if the <code>resolve</code> function was called.
The value of this property MUST be the MIME type of one of the conformant <a href="#representations">representations</a>.
-The caller of the <code>resolveStream</code> function MUST use this value when determining how to
+The caller of the <code>resolveRepresentation</code> function MUST use this value when determining how to
parse and process the <code>did-document-stream</code> returned by this function into a
<a>DID document</a> abstract data model.
</dd>
From c764c67667d09dadf31dbaf6a1e34d39653ce96a Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sat, 3 Oct 2020 20:05:02 +0100
Subject: [PATCH 14/89] editorial: Remove duplicate subsection; fix line
lengths
---
index.html | 70 ++++++++++++++++++++++++------------------------------
1 file changed, 31 insertions(+), 39 deletions(-)
diff --git a/index.html b/index.html
index 6fd3ea21..c8a535b7 100644
--- a/index.html
+++ b/index.html
@@ -3625,8 +3625,9 @@ <h3>
</h3>
<p>
-The possible properties within this structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
-This specification defines the following common properties.
+The possible properties within this structure and their possible values are
+defined by [[DID-SPEC-REGISTRIES]]. This specification defines the following
+common properties.
</p>
<dl>
@@ -3644,15 +3645,16 @@ <h3>
The error code from the dereferencing process.
This property is REQUIRED when there is an error in the dereferencing process.
The value of this property is a single keyword string.
-The possible property values of this field are defined by [[DID-SPEC-REGISTRIES]].
-This specification defines the following error values:
+The possible property values of this field are defined by
+[[DID-SPEC-REGISTRIES]]. This specification defines the following error
+values:
<dl>
<dt>
invalid-did-url
</dt>
<dd>
-The <a>DID URL</a> supplied to the <a>DID URL Dereferencing</a> function does not
-conform to valid syntax. (See <a href="#did-url-syntax"></a>.)
+The <a>DID URL</a> supplied to the <a>DID URL Dereferencing</a> function does
+not conform to valid syntax. (See <a href="#did-url-syntax"></a>.)
</dd>
<dt>
unauthorized
@@ -3674,19 +3676,6 @@ <h3>
</section>
- <section>
- <h3>
-DID URL Dereferencing Metadata Properties
- </h3>
-
- <p>
-The possible properties within this structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
-This specification defines the following common properties.
- </p>
-
- </section>
-
-
</section>
<section>
@@ -3697,29 +3686,32 @@ <h2>
<p>
Input and output metadata is often involved during the <a>DID Resolution</a>,
<a>DID URL Dereferencing</a>, and other DID-related processes. The structure
-used to communicate this metadata MUST be a <a data-cite="INFRA#maps">map</a> of
-properties. Each property name MUST be a <a data-cite="INFRA#string">string</a>.
-Each property value MUST be a <a data-cite="INFRA#string">string</a>,
-<a data-cite="INFRA#maps">map</a>, <a data-cite="INFRA#lists">list</a>,
-<a data-cite="INFRA#boolean">boolean</a>, or <a data-cite="INFRA#null">null</a>.
-The values within any complex data structures such as maps and lists
-MUST be one of these data types as well.
-All metadata property definitions MUST define the value type, including any additional
-formats or restrictions to that value (for example, a string formatted as a date or as a decimal integer).
-It is RECOMMENDED that property definitions use strings for values where possible.
+used to communicate this metadata MUST be a <a data-cite="INFRA#maps">map</a>
+of properties. Each property name MUST be a <a
+data-cite="INFRA#string">string</a>. Each property value MUST be a <a
+data-cite="INFRA#string">string</a>, <a data-cite="INFRA#maps">map</a>, <a
+data-cite="INFRA#lists">list</a>, <a data-cite="INFRA#boolean">boolean</a>, or
+<a data-cite="INFRA#null">null</a>. The values within any complex data
+structures such as maps and lists MUST be one of these data types as well.
+All metadata property definitions MUST define the value type, including any
+additional formats or restrictions to that value (for example, a string
+formatted as a date or as a decimal integer). It is RECOMMENDED that property
+definitions use strings for values where possible.
</p>
<p>
-All implementations of functions that use metadata structures as either input or output MUST
-be able to fully represent all data types described here in a deterministic fashion. As inputs and
-outputs using metadata structures are defined in terms of data types and not their serialization,
-the method for representation is internal to the implementation of the function and is out of
+All implementations of functions that use metadata structures as either input
+or output MUST be able to fully represent all data types described here in a
+deterministic fashion. As inputs and outputs using metadata structures are
+defined in terms of data types and not their serialization, the method for
+representation is internal to the implementation of the function and is out of
scope of this specification.
</p>
<p>
-The following example demonstrates a JSON-encoded metadata structure that might be
-used as <a href="#did-resolution-input-metadata-properties">DID resolution input metadata</a></a>.
+The following example demonstrates a JSON-encoded metadata structure that
+might be used as <a href="#did-resolution-input-metadata-properties">DID
+resolution input metadata</a></a>.
</p>
<pre class="example" title="JSON-encoded DID resolution input metadata example">
@@ -3740,8 +3732,8 @@ <h2>
<p>
The next example demonstrates a JSON-encoded metadata structure that might be
-used as <a href="#did-resolution-metadata-properties">DID resolution metadata</a> if a
-DID was not found.
+used as <a href="#did-resolution-metadata-properties">DID resolution
+metadata</a> if a DID was not found.
</p>
<pre class="example" title="JSON-encoded DID resolution metadata example">
@@ -3762,8 +3754,8 @@ <h2>
<p>
The next example demonstrates a JSON-encoded metadata structure that might be
-used as <a href="#did-document-metadata-properties">DID document metadata</a> to
-describe timestamps associated with the DID document.
+used as <a href="#did-document-metadata-properties">DID document metadata</a>
+to describe timestamps associated with the DID document.
</p>
<pre class="example" title="JSON-encoded DID document metadata example">
From 3962f54dd52b201458442cbc0df52e0ef2b62b61 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 22 Sep 2020 20:09:00 +0100
Subject: [PATCH 15/89] Abstract: improve accuracy, towards #401
---
index.html | 16 +++++++---------
1 file changed, 7 insertions(+), 9 deletions(-)
diff --git a/index.html b/index.html
index c8a535b7..b309da82 100644
--- a/index.html
+++ b/index.html
@@ -183,15 +183,13 @@
the design enables the controller of a <a>DID</a> to prove control over it
without requiring permission from any other party.
-<a>DID</a>s are URLs that associate
-a <a>DID subject</a> with a <a>DID document</a> allowing trustable interactions
-associated with that subject. Each <a>DID document</a> can express cryptographic
-material, verification methods, or <a>service endpoints</a>, which provide a set
-of mechanisms enabling a <a>DID controller</a> to prove control of the
-<a>DID</a>. <a>Service endpoints</a> enable trusted interactions associated with
-the <a>DID subject</a>. A <a>DID document</a> might contain semantics about the
-subject that it identifies. A <a>DID document</a> might contain the <a>DID
-subject</a> itself (e.g. a data model).
+<a>DID</a>s are URIs that associate a <a>DID subject</a> with a <a>DID
+document</a> allowing trustable interactions associated with that subject.
+Each <a>DID document</a> can express cryptographic material, verification
+methods, or <a>service endpoints</a>, which provide a set of mechanisms
+enabling a <a>DID controller</a> to prove control of the <a>DID</a>.
+<a>Service endpoints</a> enable trusted interactions associated with the
+<a>DID subject</a>.
</p>
<p>
This document specifies a common data model, a URL format, and a set of
From d7724e67cbdea8bab31ba5b15d9ecc12970bfc61 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 22 Sep 2020 21:11:53 +0100
Subject: [PATCH 16/89] Intro: editorial suggestions from #401
---
index.html | 38 +++++++++++++++++++-------------------
1 file changed, 19 insertions(+), 19 deletions(-)
diff --git a/index.html b/index.html
index b309da82..db9d10ae 100644
--- a/index.html
+++ b/index.html
@@ -285,18 +285,18 @@ <h1>
authority to guarantee the continued existence of the identifier.
</p>
<p>
-This specification does not require any particular technology or cryptography to
-underpin the generation, persistence, resolution or interpretation of DIDs.
-Rather, it defines: a) the generic syntax for all DIDs, and b) the generic
-requirements for performing the four basic CRUD operations (create, read,
-update, deactivate) on the metadata associated with a DID (called the DID
-document).
+This specification does not presuppose any particular technology or
+cryptography to underpin the generation, persistence, resolution or
+interpretation of DIDs. Rather, it defines: a) the generic syntax for all
+DIDs, and b) the generic requirements for performing the four basic CRUD
+operations (create, read, update, deactivate) on the metadata associated with
+a DID (called the DID document).
</p>
<p>
This enables implementers to design specific types of DIDs to work with the
-computing infrastructure they trust (e.g., blockchain, distributed ledger,
-decentralized file system, distributed database, peer-to-peer network). The
-specification for a specific type of DID is called a DID method. Implementers of
+computing infrastructure they trust (e.g., distributed ledger, decentralized
+file system, distributed database, peer-to-peer network). The specification
+for a specific type of DID is called a DID method. Implementers of
applications or systems using DIDs can choose to support the DID methods most
appropriate for their particular use cases.
</p>
@@ -386,8 +386,7 @@ <h2>
<p>
<a>Decentralized Identifiers</a> are a component of larger systems, such as
the Verifiable Credentials ecosystem [[VC-DATA-MODEL]], which drove the design
-goals for this specification. This section summarizes the primary design goals
-for this specification.
+goals for this specification. These design goals are summarized here.
</p>
<table class="simple">
@@ -566,7 +565,7 @@ <h2>
typically asserted by the control of a set of cryptographic keys used by
software acting on behalf of the controller, though it may also be asserted via
other mechanisms. Note that a DID may have more than one controller, and the
-controller(s) may include the <a>DID subject</a>.
+<a>DID subject</a> can be the DID controller.
</dd>
<dt>
@@ -588,12 +587,13 @@ <h2>
<dd>
<a>DID documents</a> contain metadata associated with a <a>DID</a>. They
typically express verification methods (such as public keys) and <a>services</a>
-relevant to interactions with the DID subject. A DID document is serialized
-according to a particular syntax (see <a href="#core-representations"></a>). The
-<a>DID</a> itself is the value of the `id` property. The generic properties
-supported in a DID document are specified in <a href="#core-properties"></a>.
-The properties present in a DID document may be updated according to the
-applicable operations outlined in <a href="#methods"></a>.
+relevant to interactions with the DID subject. A DID document is represents an
+abstract data model, and can be serialized according to a particular syntax
+(see <a href="#core-representations"></a>). The generic properties supported
+in a DID document are specified in <a href="#core-properties"></a>.
+The <a>DID</a> itself is the value of the `id` property. The properties
+present in a DID document may be updated according to the applicable
+operations outlined in <a href="#methods"></a>.
</dd>
<dt>
@@ -612,7 +612,7 @@ <h2>
<a>URI</a> specification ([[RFC3986]]) and a specific <a>URI</a> scheme
([[IANA-URI-SCHEMES]] (such as the http: and https: schemes specified in
[[RFC7230]]). It is also similar to the relationship between the IETF generic
-URN specification ([[RFC8141]]) and a specific URN namespace definition, (such
+URN specification ([[RFC8141]]) and a specific URN namespace definition (such
as the <a>UUID</a> URN namespace defined in [[RFC4122]]). The difference is that
a DID method specification, as well as defining a specific DID scheme, also
specifies the methods creating, resolving, updating, and deactivating
From b9dd1692cee40f985d2effe8d0d0829157ece059 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 22 Sep 2020 21:27:12 +0100
Subject: [PATCH 17/89] Terms: editorial suggestions from #401
---
terms.html | 15 +++++++++------
1 file changed, 9 insertions(+), 6 deletions(-)
diff --git a/terms.html b/terms.html
index 676374e2..de2fcb2c 100644
--- a/terms.html
+++ b/terms.html
@@ -61,9 +61,11 @@
<dt><dfn>decentralized public key infrastructure</dfn> (DPKI)</dt>
<dd>
- <a href="https://en.wikipedia.org/wiki/Public_key_infrastructure">Public key infrastructure</a>
- that does not rely on traditional <a href="https://en.wikipedia.org/wiki/Certificate_authority">certificate authorities</a> because it uses <a>decentralized identifiers</a> and
-<a>DID documents</a>) to discover and verify <a>public key descriptions</a>.
+<a href="https://en.wikipedia.org/wiki/Public_key_infrastructure">Public key
+infrastructure</a> that does not rely on traditional
+<a href="https://en.wikipedia.org/wiki/Certificate_authority">certificate
+authorities</a> because it uses <a>decentralized identifiers</a> and
+<a>DID documents</a> to discover and verify <a>public key descriptions</a>.
</dd>
<dt><dfn data-lt="did controllers|did controller(s)">DID controller</dfn></dt>
@@ -180,8 +182,9 @@
<dd>
A <a>DID</a> plus any additional syntactic component that conforms to the
definition in <a href="#did-url-syntax"></a>. This includes an optional <a>DID
-path</a>, optional <a>DID query</a> (and its leading <code>?</code> character),
-and optional <a>DID fragment</a> (and its leading <code>#</code> character).
+path</a> (and its leading <code>/</code> character), optional <a>DID query</a>
+(and its leading <code>?</code> character), and optional <a>DID fragment</a>
+(and its leading <code>#</code> character).
</dd>
<dt><dfn>DID URL dereferencing</dfn></dt>
@@ -192,7 +195,7 @@
resource may be a <a>DID document</a> plus additional metadata, or it may be a
secondary resource contained within the <a>DID document</a>, or it may be a
resource entirely external to the <a>DID document</a>. If the function begins
-with a <a>DID URL</a>, it use the <a>DID resolution</a> function to fetch a
+with a <a>DID URL</a>, it uses the <a>DID resolution</a> function to fetch a
<a>DID document</a> indicated by the <a>DID</a> contained within the
<a>DID URL</a>. The dereferencing function then can perform additional
processing on the <a>DID document</a> to return the dereferenced resource
From f102581561cadaff6e793343cc1337571551c686 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 22 Sep 2020 21:52:58 +0100
Subject: [PATCH 18/89] DID params: reshuffle, change some slightly out of
place text to a note, for #401
---
index.html | 107 +++++++++++++++++++++++++++--------------------------
1 file changed, 54 insertions(+), 53 deletions(-)
diff --git a/index.html b/index.html
index db9d10ae..c2cea37b 100644
--- a/index.html
+++ b/index.html
@@ -835,7 +835,9 @@ <h2>DID Parameters</h2>
<p>
The <a>DID URL</a> syntax supports a simple format for parameters
-based on the <code>query</code> component (See <a href="#query"></a>).
+based on the <code>query</code> component (See <a href="#query"></a>). Adding
+a DID parameter to a <a>DID URL</a> means that the parameter becomes part of
+the identifier for a <a>resource</a>.
</p>
<p>
Some DID parameter names (for example, for service selection) are
@@ -868,7 +870,8 @@ <h2>DID Parameters</h2>
<td>
A resource hash of the <a>DID document</a> to add integrity protection, as
specified in [[?HASHLINK]]. The associated value MUST be an
-<a data-lt="ascii string">ASCII string</a>. <i>This parameter is non-normative.</i>
+<a data-lt="ascii string">ASCII string</a>. <i>This parameter is
+non-normative.</i>
</td>
</tr>
<tr>
@@ -876,8 +879,8 @@ <h2>DID Parameters</h2>
<code><a>service</a></code>
</td>
<td>
-Identifies a service from the <a>DID document</a> by service ID. The associated
-value MUST be an <a data-lt="ascii string">ASCII string</a>.
+Identifies a service from the <a>DID document</a> by service ID. The
+associated value MUST be an <a data-lt="ascii string">ASCII string</a>.
</td>
</tr>
<tr>
@@ -886,9 +889,9 @@ <h2>DID Parameters</h2>
</td>
<td>
Identifies a specific version of a <a>DID document</a> to be resolved (the
-version ID could be sequential, or a <a>UUID</a>, or method-specific). Note that
-this parameter might not be supported by all <a>DID methods</a>. The associated
-value MUST be an <a data-lt="ascii string">ASCII string</a>.
+version ID could be sequential, or a <a>UUID</a>, or method-specific). Note
+that this parameter might not be supported by all <a>DID methods</a>. The
+associated value MUST be an <a data-lt="ascii string">ASCII string</a>.
</td>
</tr>
@@ -897,14 +900,14 @@ <h2>DID Parameters</h2>
<code>version-time</code>
</td>
<td>
-Identifies a certain version timestamp of a <a>DID document</a> to be resolved.
-That is, the <a>DID document</a> that was valid for a <a>DID</a> at a certain
-time. Note that this parameter might not be supported by all <a>DID methods</a>.
-The associated value MUST be an <a data-lt="ascii string">ASCII string</a>
-which is a valid XML datetime value, as defined in section 3.3.7 of
+Identifies a certain version timestamp of a <a>DID document</a> to be
+resolved. That is, the <a>DID document</a> that was valid for a <a>DID</a> at
+a certain time. Note that this parameter might not be supported by all <a>DID
+methods</a>. The associated value MUST be an <a data-lt="ascii string">ASCII
+string</a> which is a valid XML datetime value, as defined in section 3.3.7 of
<a href="https://www.w3.org/TR/xmlschema11-2/">W3C XML Schema Definition
-Language (XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]]. This datetime value
-MUST be normalized to UTC 00:00, as indicated by the trailing "Z".
+Language (XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]]. This datetime
+value MUST be normalized to UTC 00:00, as indicated by the trailing "Z".
</td>
</tr>
@@ -915,29 +918,16 @@ <h2>DID Parameters</h2>
<td>
A relative URI reference according to <a
data-cite="RFC3986#section-4.2">RFC3986 Section 4.2</a>
-that identifies a resource at a <a>service endpoint</a>, which is selected from
-a <a>DID document</a> by using the <code>service</code> parameter. The
-associated value MUST be an <a data-lt="ascii string">ASCII string</a> and MUST
-use percent-encoding for certain characters as specified in <a
+that identifies a resource at a <a>service endpoint</a>, which is selected
+from a <a>DID document</a> by using the <code>service</code> parameter. The
+associated value MUST be an <a data-lt="ascii string">ASCII string</a> and
+MUST use percent-encoding for certain characters as specified in <a
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>.
</td>
</tr>
</tbody>
</table>
- <p>
-Implementers as well as <a>DID method</a> specification authors MAY use additional
-DID parameters that are not listed here.
-For maximum interoperability, it is RECOMMENDED that DID parameters use the official
-W3C DID Specification Registries mechanism [[DID-SPEC-REGISTRIES]], to avoid collision
-with other uses of the same DID parameter with different semantics.
- </p>
-
- <p>
-Additional considerations for processing these parameters are discussed in
-[[?DID-RESOLUTION]].
- </p>
-
<p>
Two example <a>DID URLs</a> using the <code><a>service</a></code> and
<code>version-time</code> DID parameters are shown below.
@@ -952,33 +942,44 @@ <h2>DID Parameters</h2>
</pre>
<p>
-Adding a DID parameter to a <a>DID URL</a> means that the parameter becomes part
-of an identifier for a <a>resource</a> (the <a>DID document</a> or other).
-Alternatively, the <a>DID resolution</a> and the <a>DID URL dereferencing</a>
-functions can also be influenced by passing input metadata to a <a>DID
-resolver</a> that are not part of the DID URL. (See <a
-href="#did-resolution-input-metadata-properties"></a>). Such input
-metadata could for example control caching
-or the desired encoding of a resolution result. This is comparable to HTTP,
-where certain parameters could either be included in an HTTP URL, or
-alternatively passed as HTTP headers during the dereferencing process. The
-important distinction is that DID parameters that are part of the <a>DID URL</a>
-should be used to specify <i>what <a>resource</a> is being identified</i>,
-whereas input metadata that is not part of the <a>DID URL</a>
-should be use to control <i>how that <a>resource</a> is resolved or
-dereferenced</i>.
+Implementers as well as <a>DID method</a> specification authors MAY use
+additional DID parameters that are not listed here. For maximum
+interoperability, it is RECOMMENDED that DID parameters use the official W3C
+DID Specification Registries mechanism [[DID-SPEC-REGISTRIES]], to avoid
+collision with other uses of the same DID parameter with different semantics.
</p>
<p>
DID parameters MAY be used if there is a clear use case where the parameter
-needs to be part of a URI that can be used as a link, or as a <a>resource</a> in
-RDF / JSON-LD documents.
+needs to be part of a URI that can be used as a link, or as a <a>resource</a>
+in RDF / JSON-LD documents.
</p>
<p>
-DID parameters SHOULD NOT be used if the same functionality can be expressed by
-passing input metadata to a <a>DID resolver</a>, and if there is no need to construct a
-URI for use as a link, or as a <a>resource</a> in RDF / JSON-LD documents.
+DID parameters SHOULD NOT be used if the same functionality can be expressed
+by passing input metadata to a <a>DID resolver</a> (see <a
+href="#did-resolution-input-metadata-properties"></a>), and if there is no need
+to construct a URI for use as a link, or as a <a>resource</a> in RDF / JSON-LD
+documents.
+ </p>
+
+ <p>
+Additional considerations for processing these parameters are discussed in
+[[?DID-RESOLUTION]].
+ </p>
+
+ <p class="note" title="DID parameters and DID resolution">
+The <a>DID resolution</a> and the <a>DID URL dereferencing</a> functions can
+be influenced by passing input metadata to a <a>DID resolver</a> that are
+not part of the DID URL. (See <a
+href="#did-resolution-input-metadata-properties"></a>). This is comparable to
+HTTP, where certain parameters could either be included in an HTTP URL, or
+alternatively passed as HTTP headers during the dereferencing process. The
+important distinction is that DID parameters that are part of the <a>DID
+URL</a> should be used to specify <em>what <a>resource</a> is being
+identified</em>, whereas input metadata that is not part of the <a>DID URL</a>
+should be use to control <em>how that <a>resource</a> is resolved or
+dereferenced</em>.
</p>
</section>
@@ -987,8 +988,8 @@ <h2>DID Parameters</h2>
<h2>Path</h2>
<p>
-A <a>DID path</a> is identical to a generic URI path and MUST conform to the <a
-data-cite="!rfc3986#section-3.3"><code>path-abempty</code></a> ABNF rule in
+A <a>DID path</a> is identical to a generic URI path and MUST conform to the
+<a data-cite="!rfc3986#section-3.3"><code>path-abempty</code></a> ABNF rule in
[[!RFC3986]].
</p>
From acf788c3b122ecd94c5a471b94ef8eca4ca76a82 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 22 Sep 2020 21:58:04 +0100
Subject: [PATCH 19/89] Verification methods: fix typo
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index c2cea37b..2ba631d5 100644
--- a/index.html
+++ b/index.html
@@ -1525,7 +1525,7 @@ <h2>Verification Methods</h2>
As well as the <code><a>verificationMethod</a></code> property, verification
methods can be embedded in or referenced from properties associated with
various <a>verification relationships</a> (see
-<a href="#verification-relationships"></a>. Referencing verification methods
+<a href="#verification-relationships"></a>). Referencing verification methods
allows them to be used with more than one <a>verification relationship</a>.
</p>
From 54664a34dd4a5191ec4191d719948e3580f09da9 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 22 Sep 2020 22:13:35 +0100
Subject: [PATCH 20/89] Issues: remove closed (for #403)
---
index.html | 46 ----------------------------------------------
1 file changed, 46 deletions(-)
diff --git a/index.html b/index.html
index 2ba631d5..8618e4e9 100644
--- a/index.html
+++ b/index.html
@@ -4586,77 +4586,31 @@ <h1>Current Issues</h1>
result in changes to this specification.
</p>
- <div class="issue" data-number="5">Where will the DID contexts(s) live?</div>
- <div class="issue" data-number="8">Leverage RFC7518 to specify cryptographic algorithms</div>
- <div class="issue" data-number="9">Replace RsaSignature2017 by a standard JWA signature</div>
- <div class="issue" data-number="10">Explain RsaSignature2018</div>
- <div class="issue" data-number="14">Standardize the key revocation list </div>
- <div class="issue" data-number="23">publicKeyJwk, publicKeyHex, publicKeyBase64, publicKeyBase58 missing from context.</div>
<div class="issue" data-number="33">Cheap DIDs and the option to migrate DIDs between ledgers using standard DID Deprecation Registries</div>
- <div class="issue" data-number="36">Details on the use of method-specific DID parameters</div>
- <div class="issue" data-number="55">Add support for ethereumAddress public key type in @context</div>
- <div class="issue" data-number="57">Clarification of other verification methods in authentication section missing</div>
<div class="issue" data-number="58">Registry handling</div>
- <div class="issue" data-number="65">Does DID Document metadata belong in the Document?</div>
<div class="issue" data-number="72">Privacy Considerations - Specifically call out GDPR</div>
- <div class="issue" data-number="75">tracking revocation of public keys</div>
- <div class="issue" data-number="85">Syntactially differentiate data about the DID versus application data</div>
- <div class="issue" data-number="92">Add CBOR a valid type of DID document syntax similar to JSON and on par with JSON-LD</div>
<div class="issue" data-number="94">Create DID explainer</div>
- <div class="issue" data-number="95">Document Structure</div>
<div class="issue" data-number="104">Horizontal Review: Internationalization self test</div>
<div class="issue" data-number="105">Horizontal Review: Accessibility self test</div>
<div class="issue" data-number="118">Specification needs to be compliant with WCAG 2.0</div>
<div class="issue" data-number="119">Horizontal Review: offer review opportunity to TAG</div>
<div class="issue" data-number="122">When is a DID subject not a DID controller (if ever)?</div>
- <div class="issue" data-number="137">Should the DID parameters be normative in the spec?</div>
<div class="issue" data-number="151">Include discussion of eIDAS levels-of-assurance</div>
- <div class="issue" data-number="154">Decoupling DID Core spec from LD-Proof / LDS specs</div>
<div class="issue" data-number="163">Uses of terms defined in the specification should be links to their definitions</div>
- <div class="issue" data-number="165">What are entityship and start-of-authority (SOA) problems?</div>
- <div class="issue" data-number="169">Replace registries administered community groups with registries established by this specification</div>
<div class="issue" data-number="170">Public key "id" and "type" members duplicate JWK "kid" and "kty" members</div>
- <div class="issue" data-number="171">Add public key examples using JWKs</div>
<div class="issue" data-number="174">Underspecified semantics of "updated" property</div>
- <div class="issue" data-number="176">Unsubstantiated statement about protecting against attacks when compromised</div>
- <div class="issue" data-number="178">Underspecified statement on combining timestamps with signatures</div>
- <div class="issue" data-number="185">Supported ciphers in a DID document</div>
- <div class="issue" data-number="190">What is being discussed in issue 4 (clarification of TERMX via use-cases, spec pointers, and PR)</div>
- <div class="issue" data-number="195">Unclear which verification methods are authorized for did document operations </div>
- <div class="issue" data-number="198">Add sections on DID Resolution</div>
<div class="issue" data-number="199">Clarification on what DIDs might identify</div>
- <div class="issue" data-number="202">JSON-LD Contexts in Registry</div>
<div class="issue" data-number="203">Define DID Document Metadata</div>
- <div class="issue" data-number="204">Define terminology for properties and values</div>
<div class="issue" data-number="205">How to treat unknown properties</div>
- <div class="issue" data-number="207">Add section on extensibility and conformance</div>
<div class="issue" data-number="208">IETF did+ld+json media type registration</div>
- <div class="issue" data-number="236">publicKeyHex format unused by spec currently</div>
<div class="issue" data-number="240">Should did-core restrict the use of JWK?</div>
- <div class="issue" data-number="248">Need term for relying party</div>
<div class="issue" data-number="249">How to mitigate the single source of failure wrt/ "Trust into the Universal Resolver"?</div>
<div class="issue" data-number="253">Added DID resolution and dereferencing contracts.</div>
- <div class="issue" data-number="258">List of early implementations conforming to spec?</div>
- <div class="issue" data-number="259">DIDs and JOSE: publicKey.id and publicKey.publicKeyJwk.kid</div>
- <div class="issue" data-number="260">Clear explanation on how can A DID have more than one controller</div>
<div class="issue" data-number="261">Definition of the term "client" in regard to SSI principles</div>
- <div class="issue" data-number="266">Should DID support self-signed certificates?</div>
<div class="issue" data-number="267">Put key points up front</div>
- <div class="issue" data-number="268">What degree should proof purposes be defined for specific application layer usages?</div>
- <div class="issue" data-number="269">transfer of controllership and it's intersection with the subject of an identifier</div>
- <div class="issue" data-number="270">did parameter equivilance</div>
- <div class="issue" data-number="272">Remove all unspecified properties/functionality from the spec</div>
- <div class="issue" data-number="273">invert mapping between proof purposes and verification methods?</div>
- <div class="issue" data-number="274">Ambiguity around necessity of populated top-level DID Document 'id' property</div>
- <div class="issue" data-number="280">Remove uses of publicKeyHex </div>
- <div class="issue" data-number="281">Specifications needed for supported key representations publicKeyJwk, publcKeyPem, and publicKeyBase58</div>
<div class="issue" data-number="282">Added CBOR section </div>
- <div class="issue" data-number="283">Verification method block should be a first citizen like public keys</div>
- <div class="issue" data-number="289">Should DID Methods expose Proof Purposes for DID Operations?</div>
<div class="issue" data-number="291">PING Horizontal Review</div>
<div class="issue" data-number="292">Horizontal Review Tracking</div>
- <div class="issue" data-number="293">Remove `proof`</div>
- <div class="issue" data-number="294">Create a seperate top level block for defining proof purposes</div>
<div class="issue" data-number="295">Define simple type-less resolution function</div>
<div class="issue" data-number="296">Define resolution function with data types</div>
<div class="issue" data-number="297">Define resolution function with data types and property values</div>
From d40f815321cbdf7dabf2b43885e6c7181242943c Mon Sep 17 00:00:00 2001
From: Amy Guy <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 09:41:50 +0000
Subject: [PATCH 21/89] Clarify multiple DID controllers
Co-authored-by: Brent Zundel <brent.zundel@gmail.com>
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index 8618e4e9..3a24876e 100644
--- a/index.html
+++ b/index.html
@@ -565,7 +565,7 @@ <h2>
typically asserted by the control of a set of cryptographic keys used by
software acting on behalf of the controller, though it may also be asserted via
other mechanisms. Note that a DID may have more than one controller, and the
-<a>DID subject</a> can be the DID controller.
+<a>DID subject</a> can be the DID controller, or one of them.
</dd>
<dt>
From 8be853a2b3e451a2bc84edadf59bbc136f00e2c3 Mon Sep 17 00:00:00 2001
From: Amy Guy <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 09:42:31 +0000
Subject: [PATCH 22/89] Grammar fix
Co-authored-by: Brent Zundel <brent.zundel@gmail.com>
---
terms.html | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/terms.html b/terms.html
index de2fcb2c..5d54825e 100644
--- a/terms.html
+++ b/terms.html
@@ -182,9 +182,9 @@
<dd>
A <a>DID</a> plus any additional syntactic component that conforms to the
definition in <a href="#did-url-syntax"></a>. This includes an optional <a>DID
-path</a> (and its leading <code>/</code> character), optional <a>DID query</a>
-(and its leading <code>?</code> character), and optional <a>DID fragment</a>
-(and its leading <code>#</code> character).
+path</a> (with its leading <code>/</code> character), optional <a>DID query</a>
+(with its leading <code>?</code> character), and optional <a>DID fragment</a>
+(with its leading <code>#</code> character).
</dd>
<dt><dfn>DID URL dereferencing</dfn></dt>
From b414bccd2a57b6290101cfbccbe73c4fa469ae53 Mon Sep 17 00:00:00 2001
From: Amy Guy <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 09:43:15 +0000
Subject: [PATCH 23/89] Add back sentence about DID subject as information
resource
Co-authored-by: Brent Zundel <brent.zundel@gmail.com>
---
index.html | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/index.html b/index.html
index 3a24876e..c1bc8e29 100644
--- a/index.html
+++ b/index.html
@@ -189,7 +189,8 @@
methods, or <a>service endpoints</a>, which provide a set of mechanisms
enabling a <a>DID controller</a> to prove control of the <a>DID</a>.
<a>Service endpoints</a> enable trusted interactions associated with the
-<a>DID subject</a>.
+<a>DID subject</a>. A <a>DID document</a> might contain the <a>DID subject</a>
+itself, if the <a>DID subject</a> is an information resource such as a data model.
</p>
<p>
This document specifies a common data model, a URL format, and a set of
From b2346aac4dcafc39451ca511ba76c6c04ee8e72e Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sat, 3 Oct 2020 16:20:41 +0100
Subject: [PATCH 24/89] conformance: remove redundant/untestable normative
language, towards #384
---
index.html | 13 ++++++-------
1 file changed, 6 insertions(+), 7 deletions(-)
diff --git a/index.html b/index.html
index c1bc8e29..b27389b1 100644
--- a/index.html
+++ b/index.html
@@ -675,19 +675,18 @@ <h2>
</p>
<p>
-A <dfn>conforming DID</dfn> is any concrete expression of the rules specified in
-Section <a href="#identifier"></a> and MUST comply with relevant normative
+A <dfn>conforming DID</dfn> is any concrete expression of the rules specified
+in Section <a href="#identifier"></a> and complies with relevant normative
statements in that section.
</p>
<p>
A <dfn>conforming DID document</dfn> is any concrete expression of the data
-model described in this specification and MUST comply with the relevant
+model described in this specification and complies with with the relevant
normative statements in Sections <a href="#data-model"></a> and <a
-href="#core-properties"></a>. A serialization format for the conforming document
-MUST be deterministic, bi-directional, and lossless as described in Section <a
-href="#core-representations"></a>. The <a>conforming DID document</a> MAY be
-transmitted or stored in any such serialization format.
+href="#core-properties"></a>. A serialization format for the conforming
+document is deterministic, bi-directional, and lossless as described in
+Section <a href="#core-representations"></a>.
</p>
<p>
From 6026da8ed82b06a300e1670a3aa60b636334a7d4 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 18 Oct 2020 17:00:23 +0100
Subject: [PATCH 25/89] conformance: Fix grammar, thanks @brentzundel
---
index.html | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/index.html b/index.html
index b27389b1..90a6faaf 100644
--- a/index.html
+++ b/index.html
@@ -676,13 +676,13 @@ <h2>
<p>
A <dfn>conforming DID</dfn> is any concrete expression of the rules specified
-in Section <a href="#identifier"></a> and complies with relevant normative
+in Section <a href="#identifier"></a> which complies with relevant normative
statements in that section.
</p>
<p>
A <dfn>conforming DID document</dfn> is any concrete expression of the data
-model described in this specification and complies with with the relevant
+model described in this specification which complies with the relevant
normative statements in Sections <a href="#data-model"></a> and <a
href="#core-properties"></a>. A serialization format for the conforming
document is deterministic, bi-directional, and lossless as described in
From adef25ca0f4ebab3583ff8ead0151e3a096e0144 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sat, 3 Oct 2020 21:10:44 +0100
Subject: [PATCH 26/89] keys: remove normative language around 'assume' (#384)
---
index.html | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/index.html b/index.html
index 90a6faaf..f7acef59 100644
--- a/index.html
+++ b/index.html
@@ -1747,16 +1747,16 @@ <h3>Key types and formats</h3>
</pre>
<p>
-If a public key does not exist in the <a>DID document</a>, it MUST be assumed
-the key was revoked or is invalid. The <a>DID document</a> MUST NOT express
-revoked keys using a <a>verification relationship</a>. Each <a>DID method</a>
-specification is expected to detail how revocation is performed and tracked.
+If a public key does not exist in the <a>DID document</a>, the key was revoked
+or is invalid. The <a>DID document</a> MUST NOT express revoked keys using a
+<a>verification relationship</a>. Each <a>DID method</a> specification is
+expected to detail how revocation is performed and tracked.
</p>
<p class="note">
Caching and expiration of the keys in a <a>DID document</a> is entirely the
-responsibility of <a>DID resolvers</a> and requesting parties. For more information,
-see Section <a href="#resolution"></a>.
+responsibility of <a>DID resolvers</a> and requesting parties. For more
+information, see Section <a href="#resolution"></a>.
</p>
</section>
From 430e3a9748bcec6c41963e168144da959a28e953 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sat, 3 Oct 2020 21:12:27 +0100
Subject: [PATCH 27/89] verification methods: Fix wording (#384)
---
index.html | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/index.html b/index.html
index f7acef59..db9958bc 100644
--- a/index.html
+++ b/index.html
@@ -1776,9 +1776,8 @@ <h2>Verification Relationships</h2>
[[DID-SPEC-REGISTRIES]].
</p>
<p>
-The information in a <a>DID document</a> MUST be explicit about the
-<a>verification relationship</a> between the <a>DID subject</a> and the
-<a>verification method</a>.
+The <a>verification relationship</a> between the <a>DID subject</a> and the
+<a>verification method</a> MUST be explicit in the <a>DID document</a>.
<a>Verification methods</a> that are not associated with a particular
<a>verification relationship</a> MUST NOT be used for that <a>verification
relationship</a>. See the sections below for more detailed examples of a
From 27f5de7702dfa223aff4f8c7279ebd335a92de75 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sat, 3 Oct 2020 21:22:23 +0100
Subject: [PATCH 28/89] verification methods: Remove untestable normative
language
Noted by @kdenhartog that statements about consuming software is
out of scope (and untestable).
---
index.html | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/index.html b/index.html
index db9958bc..44a63c6c 100644
--- a/index.html
+++ b/index.html
@@ -1778,10 +1778,12 @@ <h2>Verification Relationships</h2>
<p>
The <a>verification relationship</a> between the <a>DID subject</a> and the
<a>verification method</a> MUST be explicit in the <a>DID document</a>.
-<a>Verification methods</a> that are not associated with a particular
-<a>verification relationship</a> MUST NOT be used for that <a>verification
-relationship</a>. See the sections below for more detailed examples of a
-<a>verification relationship</a>.
+Applications are expected to respect explicit <a>verification relationships</a>
+and therefore to <em>not</em> use a <a>verification method</a> for a
+particular <a>verification relationship</a> <em>unless</em> the
+<a>verification method</a> is explicitly associated with the <a>verification
+relationship</a> in question. See the sections below for more detailed
+examples of a <a>verification relationship</a>.
</p>
<section>
From feea9dbf8a5c2ed2b55ea58b9b0bd832dcf0ab3d Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sat, 3 Oct 2020 21:30:42 +0100
Subject: [PATCH 29/89] service: 'unordered set' should be an INFRA ordered set
(#384)
---
index.html | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/index.html b/index.html
index 44a63c6c..dcb87758 100644
--- a/index.html
+++ b/index.html
@@ -2189,11 +2189,11 @@ <h2>Service Endpoints</h2>
<dd>
<p>
If a <a>DID document</a> includes a <code>service</code> property, the value
-of the property SHOULD be an unordered set of <a>service endpoint</a>s, where
-each service endpoint is described by a set of properties. Each <a>service
-endpoint</a> MUST have <code><a>id</a></code>, <code>type</code>, and
-<code><a>serviceEndpoint</a></code> properties, and MAY include additional
-properties.
+of the property SHOULD be an <a data-cite="INFRA#ordered-set">ordered set</a>
+of <a>service endpoint</a>s, where each service endpoint is described by a set
+of properties. Each <a>service endpoint</a> MUST have <code><a>id</a></code>,
+<code>type</code>, and <code><a>serviceEndpoint</a></code> properties, and MAY
+include additional properties.
</p>
<p>
The value of the <code><a>id</a></code> property MUST be a <a>URI</a>.
From 4e6b97c57ff6e147bdcd6cb534f7c8ef9fd909ae Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 18 Oct 2020 16:54:25 +0100
Subject: [PATCH 30/89] Revert "verification methods: Remove untestable
normative language"
This reverts commit f3cbd50b69dd6d7f8c0aa262ae00019f9c9aec95. This
language is testable by attempting to use a verification method
that does not appear in the DID document.
---
index.html | 10 ++++------
1 file changed, 4 insertions(+), 6 deletions(-)
diff --git a/index.html b/index.html
index dcb87758..cc513a31 100644
--- a/index.html
+++ b/index.html
@@ -1778,12 +1778,10 @@ <h2>Verification Relationships</h2>
<p>
The <a>verification relationship</a> between the <a>DID subject</a> and the
<a>verification method</a> MUST be explicit in the <a>DID document</a>.
-Applications are expected to respect explicit <a>verification relationships</a>
-and therefore to <em>not</em> use a <a>verification method</a> for a
-particular <a>verification relationship</a> <em>unless</em> the
-<a>verification method</a> is explicitly associated with the <a>verification
-relationship</a> in question. See the sections below for more detailed
-examples of a <a>verification relationship</a>.
+<a>Verification methods</a> that are not associated with a particular
+<a>verification relationship</a> MUST NOT be used for that <a>verification
+relationship</a>. See the sections below for more detailed examples of a
+<a>verification relationship</a>.
</p>
<section>
From 9d4e4e0fc995f26a1f38ada9845e372786477eeb Mon Sep 17 00:00:00 2001
From: Sangwon Hong <qpakzk@gmail.com>
Date: Sun, 11 Oct 2020 21:57:58 +0900
Subject: [PATCH 31/89] Fix a minor parenthesis typo.
Signed-off-by: Sangwon Hong <qpakzk@gmail.com>
From 98dbfc51a93843202ed19a3f140d1f2657754c15 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Mon, 12 Oct 2020 11:05:38 +0100
Subject: [PATCH 32/89] representations: remove redundant normative language
(normative reqs are more explicit in subsequent sentences) towards #384
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index cc513a31..9591c25a 100644
--- a/index.html
+++ b/index.html
@@ -2275,7 +2275,7 @@ <h2>Service Endpoints</h2>
<h1>Core Representations</h1>
<p>
-All concrete representations of a <a>DID document</a> MUST be serialized using a
+All concrete representations of a <a>DID document</a> are serialized using a
deterministic mapping that is able to be unambiguously parsed into the data
model defined in this specification. All serialization methods MUST define rules
for the bidirectional translation of a <a>DID document</a> both into and out of
From 1de3ff005216960b049478b16c93022cae9bf2f3 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Mon, 12 Oct 2020 11:08:25 +0100
Subject: [PATCH 33/89] representations: remove duplicate inverse normative
language and rearrange for clarity; #384
---
index.html | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/index.html b/index.html
index 9591c25a..81a1bec0 100644
--- a/index.html
+++ b/index.html
@@ -2279,12 +2279,12 @@ <h1>Core Representations</h1>
deterministic mapping that is able to be unambiguously parsed into the data
model defined in this specification. All serialization methods MUST define rules
for the bidirectional translation of a <a>DID document</a> both into and out of
-the representation in question. As a consequence, translation between any two
-representations MUST be done by parsing the source format into a <a>DID
-document</a> model (described in Sections <a href="#data-model"></a> and <a
-href="#core-properties"></a>) and then serializing the <a>DID document</a> model
-into the target representation. An implementation MUST NOT convert between
-representations without first parsing to a <a>DID document</a> model.
+the representation in question. An implementation MUST NOT convert between
+representations without first parsing to a <a>DID document</a> model
+(described in Sections <a href="#data-model"></a> and <a
+href="#core-properties"></a>); translation between any two representations is
+done by parsing the source format into a <a>DID document</a> model and then
+serializing the <a>DID document</a> model into the target representation.
</p>
<p>
From 635d6af524133b3cdf27bd4a3eae35b592d9143d Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Mon, 12 Oct 2020 11:56:05 +0100
Subject: [PATCH 34/89] representations: Consolidate duplicative inverse
normative statements about content type, #384
---
index.html | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/index.html b/index.html
index 81a1bec0..eebf8b82 100644
--- a/index.html
+++ b/index.html
@@ -2295,10 +2295,10 @@ <h1>Core Representations</h1>
<p>
Producers MUST indicate which representation of a document has been used via a
-media type in the document's metadata. Consumers MUST determine which
-representation a document is in via the <code>content-type</code> DID resolver
-metadata field. (See <a href="#did-resolution"></a>). Consumers MUST NOT
-determine the representation of a document through its content alone.
+media type in the document's metadata. Consumers MUST determine the
+representation of a <a>DID document</a> via the <code>content-type</code> DID
+resolver metadata field (see <a href="#did-resolution"></a>), <em>not</em>
+through the content of the <a>DID document</a> alone.
</p>
<p class="issue" data-number="203">
From a8b6e9b3b71c8257d753b7a2774c10f27a8d4c5f Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 13 Oct 2020 14:37:31 +0100
Subject: [PATCH 35/89] resolution: Normative statements and spacing fixup.
Removes redundant/untestable intro normative language. Also
makes references to the Registries consistent with the rest
of the spec by saying "SHOULD be registered in" rather than "are
defined in". (#384)
---
index.html | 185 +++++++++++++++++++++++++++++------------------------
1 file changed, 103 insertions(+), 82 deletions(-)
diff --git a/index.html b/index.html
index eebf8b82..1203c9a7 100644
--- a/index.html
+++ b/index.html
@@ -3284,7 +3284,7 @@ <h2>
</code></p>
<p>
-The input variables of these functions MUST be as follows:
+The input variables of these functions are as follows:
</p>
<dl>
@@ -3292,23 +3292,23 @@ <h2>
did
</dt>
<dd>
-A conformant <a>DID</a> as a single string. This is the <a>DID</a> to resolve.
-This input is REQUIRED.
+This is the <a>DID</a> to resolve. This input is REQUIRED and the value MUST
+be a conformant <a>DID</a>.
</dd>
<dt>
did-resolution-input-metadata
</dt>
<dd>
A <a href="#metadata-structure">metadata structure</a> consisting of input
-options to the <code>resolve</code> and <code>resolveRepresentation</code> functions in addition to the <code>did</code>
-itself.
-Properties defined by this specification are in <a href="#did-resolution-input-metadata-properties"></a>.
+options to the <code>resolve</code> and <code>resolveRepresentation</code>
+functions in addition to the <code>did</code> itself. Properties defined by
+this specification are in <a href="#did-resolution-input-metadata-properties"></a>.
This input is REQUIRED, but the structure MAY be empty.
</dd>
</dl>
<p>
-The output variables of these functions MUST be as follows:
+The output variables of these functions are as follows:
</p>
<dl>
@@ -3316,31 +3316,44 @@ <h2>
did-resolution-metadata
</dt>
<dd>
+ <p>
A <a href="#metadata-structure">metadata structure</a> consisting of values
-relating to the results of the <a>DID resolution</a> process. This structure is
-REQUIRED and MUST NOT be empty. This metadata typically changes between
-invocations of the <code>resolve</code> and <code>resolveRepresentation</code> functions as it represents data about the
-resolution process itself.
-Properties defined by this specification are in <a href="#did-resolution-metadata-properties"></a>.
-If the resolution is successful, and if the <code>resolveRepresentation</code> function was called, this structure MUST contain a <code>content-type</code> property containing the mime-type of the <code>did-document-stream</code> in this result.
-If the resolution is not successful, this structure MUST contain an <code>error</code> property describing the error.
+relating to the results of the <a>DID resolution</a> process. This structure
+is REQUIRED and MUST NOT be empty.
+ </p>
+ <p>
+This metadata typically changes between invocations of the
+<code>resolve</code> and <code>resolveRepresentation</code> functions as it
+represents data about the resolution process itself. Properties defined by
+this specification are in <a href="#did-resolution-metadata-properties"></a>.
+ </p>
+ <p>
+If the resolution is successful, and if the <code>resolveRepresentation</code>
+function was called, this structure MUST contain a <code>content-type</code>
+property containing the mime-type of the <code>did-document-stream</code> in
+this result. If the resolution is not successful, this structure MUST contain
+an <code>error</code> property describing the error.
+ </p>
</dd>
<dt>
did-document
</dt>
<dd>
-If the resolution is successful, and if the <code>resolve</code> function was called, this MUST be a <a>DID document</a> conforming to the abstract data model.
-If the resolution is unsuccessful, this value MUST be empty.
+If the resolution is successful, and if the <code>resolve</code> function was
+called, this MUST be a <a>DID document</a> conforming to the abstract data
+model. If the resolution is unsuccessful, this value MUST be empty.
</dd>
<dt>
did-document-stream
</dt>
<dd>
-If the resolution is successful, and if the <code>resolveRepresentation</code> function was called, this MUST be a byte stream of the resolved
-<a>DID document</a> in one of the conformant <a href="#representations">representations</a>. The byte
-stream MAY then be parsed by the caller of the <code>resolveRepresentation</code> function
-into a <a>DID document</a> abstract data model, which can in turn be validated
-and processed. If the resolution is unsuccessful, this value MUST be an empty
+If the resolution is successful, and if the <code>resolveRepresentation</code>
+function was called, this MUST be a byte stream of the resolved <a>DID
+document</a> in one of the conformant
+<a href="#representations">representations</a>. The byte stream MAY then be
+parsed by the caller of the <code>resolveRepresentation</code> function into a
+<a>DID document</a> abstract data model, which can in turn be validated and
+processed. If the resolution is unsuccessful, this value MUST be an empty
stream.
</dd>
<dt>
@@ -3349,24 +3362,25 @@ <h2>
<dd>
If the resolution is successful, this MUST be a <a
href="#metadata-structure">metadata structure</a>. This structure contains
-metadata about the <a>DID document</a> contained in the <code>did-document</code> or
-<code>did-document-stream</code>. This metadata typically does not change
-between invocations of the <code>resolve</code> function unless the <a>DID
-document</a> changes, as it represents data about the <a>DID document</a>. If
-the resolution is unsuccessful, this output MUST be an empty <a
-href="#metadata-structure">metadata structure</a>.
-Properties defined by this specification are in <a href="#did-document-metadata-properties"></a>.
+metadata about the <a>DID document</a> contained in the
+<code>did-document</code> or <code>did-document-stream</code>. This metadata
+typically does not change between invocations of the <code>resolve</code>
+function unless the <a>DID document</a> changes, as it represents data about
+the <a>DID document</a>. If the resolution is unsuccessful, this output MUST
+be an empty <a href="#metadata-structure">metadata structure</a>. Properties
+defined by this specification are in <a
+href="#did-document-metadata-properties"></a>.
</dd>
</dl>
<p>
<a>DID resolver</a> implementations MUST NOT alter the signature of these
functions in any way. <a>DID resolver</a> implementations MAY map the
-<code>resolve</code> and <code>resolveRepresentation</code> functions to a method-specific internal function to perform
-the actual <a>DID resolution</a> process. <a>DID resolver</a> implementations
-MAY implement and expose additional
-functions with different signatures in addition to the <code>resolve</code>
-function specified here.
+<code>resolve</code> and <code>resolveRepresentation</code> functions to a
+method-specific internal function to perform the actual <a>DID resolution</a>
+process. <a>DID resolver</a> implementations MAY implement and expose
+additional functions with different signatures in addition to the
+<code>resolve</code> function specified here.
</p>
<section>
@@ -3375,8 +3389,9 @@ <h3>
</h3>
<p>
-The possible properties within this structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
-This specification defines the following common properties.
+The possible properties within this structure and their possible values are
+defined by [[DID-SPEC-REGISTRIES]]. This specification defines the following
+common properties.
</p>
<dl>
@@ -3384,10 +3399,13 @@ <h3>
accept
</dt>
<dd>
-The MIME type of the caller's preferred <a href="#representations">representation</a> of the <a>DID document</a>. The <a>DID resolver</a> implementation
-SHOULD use this value to determine the representation contained in the returned <code>did-document-stream</code> if such
-a representation is supported and available. This property is OPTIONAL. It is only used if the <code>resolveRepresentation</code>
-function is called and MUST be ignored if the <code>resolve</code> function is called.
+The MIME type of the caller's preferred <a
+href="#representations">representation</a> of the <a>DID document</a>. The
+<a>DID resolver</a> implementation SHOULD use this value to determine the
+representation contained in the returned <code>did-document-stream</code> if
+such a representation is supported and available. This property is OPTIONAL.
+It is only used if the <code>resolveRepresentation</code> function is called
+and MUST be ignored if the <code>resolve</code> function is called.
</dd>
</dl>
</section>
@@ -3398,8 +3416,9 @@ <h3>
</h3>
<p>
-The possible properties within this structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
-This specification defines the following common properties.
+The possible properties within this structure and their possible values are
+defined by [[DID-SPEC-REGISTRIES]]. This specification defines the following
+common properties.
</p>
<dl>
@@ -3407,37 +3426,39 @@ <h3>
content-type
</dt>
<dd>
-The MIME type of the returned <code>did-document-stream</code>.
-This property is REQUIRED if resolution is successful and if the <code>resolveRepresentation</code> function was called.
-It MUST NOT be present if the <code>resolve</code> function was called.
-The value of this property MUST be the MIME type of one of the conformant <a href="#representations">representations</a>.
-The caller of the <code>resolveRepresentation</code> function MUST use this value when determining how to
-parse and process the <code>did-document-stream</code> returned by this function into a
-<a>DID document</a> abstract data model.
+The MIME type of the returned <code>did-document-stream</code>. This property
+is REQUIRED if resolution is successful and if the
+<code>resolveRepresentation</code> function was called. This property MUST NOT
+be present if the <code>resolve</code> function was called. The value of this
+property MUST be the MIME type of one of the conformant <a
+href="#representations">representations</a>. The caller of the
+<code>resolveRepresentation</code> function MUST use this value when
+determining how to parse and process the <code>did-document-stream</code>
+returned by this function into a <a>DID document</a> abstract data model.
</dd>
<dt>
error
</dt>
<dd>
-The error code from the resolution process.
-This property is REQUIRED when there is an error in the resolution process.
-The value of this property is a single keyword string.
-The possible property values of this field are defined by [[DID-SPEC-REGISTRIES]].
+The error code from the resolution process. This property is REQUIRED when
+there is an error in the resolution process. The value of this property MUST
+be a single keyword string. The possible property values of this field SHOULD
+be registered in the DID Specification Registries [[DID-SPEC-REGISTRIES]].
This specification defines the following error values:
<dl>
<dt>
invalid-did
</dt>
<dd>
-The <a>DID</a> supplied to the <a>DID resolution</a> function does not
-conform to valid syntax. (See <a href="#did-syntax"></a>.)
+The <a>DID</a> supplied to the <a>DID resolution</a> function does not conform
+to valid syntax. (See <a href="#did-syntax"></a>.)
</dd>
<dt>
unauthorized
</dt>
<dd>
-The caller is not authorized to resolve this <a>DID</a> with
-this <a>DID resolver</a>.
+The caller is not authorized to resolve this <a>DID</a> with this <a>DID
+resolver</a>.
</dd>
<dt>
not-found
@@ -3458,7 +3479,8 @@ <h3>
</h3>
<p>
-The possible properties within this structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
+The possible properties within this structure and their possible values SHOULD
+be registered in the DID Specification Registries [[DID-SPEC-REGISTRIES]].
This specification defines the following common properties.
</p>
@@ -3470,11 +3492,11 @@ <h3>
DID document metadata SHOULD include a <code>created</code> property
to indicate the timestamp of the <a href="#create">Create operation</a>.
This property MAY not be supported by a given <a>DID method</a>.
-The value of
-the property MUST be a valid XML datetime value, as defined in section 3.3.7 of
-<a href="https://www.w3.org/TR/xmlschema11-2/">W3C XML Schema Definition
-Language (XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]]. This datetime value
-MUST be normalized to UTC 00:00, as indicated by the trailing "Z".
+The value of the property MUST be a valid XML datetime value, as defined in
+section 3.3.7 of <a href="https://www.w3.org/TR/xmlschema11-2/">W3C XML Schema
+Definition Language (XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]]. This
+datetime value MUST be normalized to UTC 00:00, as indicated by the trailing
+"Z".
</dd>
<dt>
updated
@@ -3483,9 +3505,8 @@ <h3>
DID document metadata SHOULD include an <code>updated</code> property
to indicate the timestamp of the last <a href="#update">Update operation</a>.
This property MAY not be supported by a given <a>DID method</a>.
-The value of
-the property MUST follow the same formatting rules as the <code>created</code>
-property.
+The value of the property MUST follow the same formatting rules as the
+<code>created</code> property.
</dd>
</dl>
@@ -3524,8 +3545,7 @@ <h2>
</dt>
<dd>
A conformant <a>DID URL</a> as a single string. This is the <a>DID URL</a> to
-dereference.
-This input is REQUIRED.
+dereference. This input is REQUIRED.
</dd>
<dt>
did-url-dereferencing-input-metadata
@@ -3533,9 +3553,9 @@ <h2>
<dd>
A <a href="metadata-structure">metadata structure</a> consisting of input
options to the <code>dereference</code> function in addition to the <code>did-url</code>
-itself.
-Properties defined by this specification are in <a href="#did-url-dereferencing-input-metadata-properties"></a>.
-This input is REQUIRED, but the structure MAY be empty.
+itself. Properties defined by this specification are in <a
+href="#did-url-dereferencing-input-metadata-properties"></a>. This input is
+REQUIRED, but the structure MAY be empty.
</dd>
</dl>
@@ -3580,7 +3600,8 @@ <h2>
<code>did-document-metadata</code> structure as described in <a>DID
Resolution</a>.
-If the dereferencing is unsuccessful, this output MUST be an empty <a href="metadata-structure">metadata structure</a>.
+If the dereferencing is unsuccessful, this output MUST be an empty <a
+href="metadata-structure">metadata structure</a>.
</dd>
</dl>
@@ -3600,8 +3621,9 @@ <h3>
</h3>
<p>
-The possible properties within this structure and their possible values are defined by [[DID-SPEC-REGISTRIES]].
-This specification defines the following common properties.
+The possible properties within this structure and their possible values SHOULD
+be registered in the [[DID-SPEC-REGISTRIES]]. This specification defines the
+following common properties.
</p>
<dl>
@@ -3609,8 +3631,8 @@ <h3>
accept
</dt>
<dd>
-The MIME type the caller prefers for <code>content-stream</code>. The <a>DID URL
-Dereferencing</a> implementation SHOULD use this value to determine the
+The MIME type the caller prefers for <code>content-stream</code>. The <a>DID
+URL Dereferencing</a> implementation SHOULD use this value to determine the
representation contained in the returned value if such a representation is
supported and available. This property is OPTIONAL.
</dd>
@@ -3640,12 +3662,11 @@ <h3>
error
</dt>
<dd>
-The error code from the dereferencing process.
-This property is REQUIRED when there is an error in the dereferencing process.
-The value of this property is a single keyword string.
-The possible property values of this field are defined by
-[[DID-SPEC-REGISTRIES]]. This specification defines the following error
-values:
+The error code from the dereferencing process. This property is REQUIRED when
+there is an error in the dereferencing process. The value of this property is
+a single keyword string. The possible property values of this field SHOULD be
+registered in the DID Specification Registries [DID-SPEC-REGISTRIES]]. This
+specification defines the following error values:
<dl>
<dt>
invalid-did-url
@@ -3694,7 +3715,7 @@ <h2>
All metadata property definitions MUST define the value type, including any
additional formats or restrictions to that value (for example, a string
formatted as a date or as a decimal integer). It is RECOMMENDED that property
-definitions use strings for values where possible.
+definitions use strings for values.
</p>
<p>
From ddc3f97f510111fefa9f81633585f5b34cbed82c Mon Sep 17 00:00:00 2001
From: Amy Guy <amy@rhiaro.co.uk>
Date: Sun, 18 Oct 2020 16:51:06 +0100
Subject: [PATCH 36/89] Clarify DID format requirements
Co-authored-by: Brent Zundel <brent.zundel@gmail.com>
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index 1203c9a7..5ac8ffc8 100644
--- a/index.html
+++ b/index.html
@@ -3293,7 +3293,7 @@ <h2>
</dt>
<dd>
This is the <a>DID</a> to resolve. This input is REQUIRED and the value MUST
-be a conformant <a>DID</a>.
+be a conformant <a>DID</a> expressed as a single string.
</dd>
<dt>
did-resolution-input-metadata
From 7065647b62b82265ab4483c8fd5f92158c44a6ed Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 13 Oct 2020 14:53:06 +0100
Subject: [PATCH 37/89] methods/security: Move normative statement about
signatures from Security Considerations to Methods (#384) and fix spacing
---
index.html | 41 +++++++++++++++++++++++------------------
1 file changed, 23 insertions(+), 18 deletions(-)
diff --git a/index.html b/index.html
index 5ac8ffc8..1b7a7508 100644
--- a/index.html
+++ b/index.html
@@ -3166,13 +3166,13 @@ <h2>
Potential denial of service attacks MUST be identified as well.
</p>
<p>
-This section MUST discuss, per Section 5 of [[RFC3552]], residual risks (such as
-the risks from compromise in a related protocol, incorrect implementation, or
-cipher) after threat mitigation was deployed.
+This section MUST discuss, per Section 5 of [[RFC3552]], residual risks (such
+as the risks from compromise in a related protocol, incorrect implementation,
+or cipher) after threat mitigation was deployed.
</p>
<p>
-This section MUST provide integrity protection and update authentication for all
-operations required by Section <a href="#method-operations"></a>.
+This section MUST provide integrity protection and update authentication for
+all operations required by Section <a href="#method-operations"></a>.
</p>
<p>
If the technology involves authentication, particularly user-host
@@ -3181,12 +3181,12 @@ <h2>
</p>
<p>
<a>DID methods</a> MUST discuss the policy mechanism by which <a>DIDs</a> are
-proven to be uniquely assigned. A <a>DID</a> fits the functional definition of a
-URN, as defined in [[RFC8141]]. That is, a <a>DID</a> is a persistent identifier
-that is assigned once to a resource and never reassigned to a different
-resource. This is particularly important in a security context because a
-<a>DID</a> might be used to identify a specific party subject to a specific set
-of authorization rights.
+proven to be uniquely assigned. A <a>DID</a> fits the functional definition of
+a URN, as defined in [[RFC8141]]. That is, a <a>DID</a> is a persistent
+identifier that is assigned once to a resource and never reassigned to a
+different resource. This is particularly important in a security context
+because a <a>DID</a> might be used to identify a specific party subject to a
+specific set of authorization rights.
</p>
<p>
Method-specific endpoint authentication MUST be discussed. Where <a>DID
@@ -3210,6 +3210,10 @@ <h2>
SHOULD be clearly labeled.
</p>
<p>
+<a>DID method</a> specifications SHOULD explain and specify the implementation
+of signatures on <a>DID documents</a>, if applicable.
+ </p>
+ <p>
Where <a>DID methods</a> make use of peer-to-peer computing resources, such as
with all known <a>DLTs</a>, the expected burdens of those resources SHOULD be
discussed in relation to denial of service.
@@ -3846,8 +3850,8 @@ <h3>
</h3>
<p>
-Signatures and <a>verifiable timestamps</a> allow <a>DID documents</a> to be cryptographically
-verifiable.
+Signatures and <a>verifiable timestamps</a> allow <a>DID documents</a> to be
+cryptographically verifiable.
</p>
<p>
@@ -3867,8 +3871,8 @@ <h3>
</ul>
<p>
-Proving control of a <a>DID</a>, that is, the binding between the <a>DID</a> and
-the <a>DID document</a> that describes it, requires a two step process:
+Proving control of a <a>DID</a>, that is, the binding between the <a>DID</a>
+and the <a>DID document</a> that describes it, requires a two step process:
</p>
<ol start="1">
@@ -3878,8 +3882,8 @@ <h3>
</li>
<li>
-Verifying that the <code><a>id</a></code> property of the resulting <a>DID document</a>
-matches the <a>DID</a> that was resolved.
+Verifying that the <code><a>id</a></code> property of the resulting <a>DID
+document</a> matches the <a>DID</a> that was resolved.
</li>
</ol>
@@ -3890,7 +3894,8 @@ <h3>
<p>
Signatures on <a>DID documents</a> are optional. <a>DID method</a>
-specifications SHOULD explain and specify their implementation if applicable.
+specifications are expected to explain and specify their implementation if
+applicable.
</p>
</section>
From 54128a7583ac32dff45024ca6ed252b9715bfd48 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 13 Oct 2020 13:56:44 +0100
Subject: [PATCH 38/89] normative statements: Removes duplicate normative
language (#384)
Removes duplicate normative statements in introductory text in
favour of more precise statements in the paragraphs which follow
in the JSON and JSON-LD representation sections.
Also fixes some spacing and formatting.
---
index.html | 158 +++++++++++++++++++++++++++--------------------------
1 file changed, 81 insertions(+), 77 deletions(-)
diff --git a/index.html b/index.html
index 1b7a7508..4505aca3 100644
--- a/index.html
+++ b/index.html
@@ -1029,10 +1029,10 @@ <h2>Fragment</h2>
<p>
A <a>DID fragment</a> is used as method-independent reference into a <a>DID Document</a> or external resource.
</p>
-
+
<p>
-<a>DID fragment</a> syntax and semantics are identical to a generic URI fragment
-and MUST conform to <a data-cite="RFC3986#section-3.5">RFC 3986, section 3.5</a>.
+<a>DID fragment</a> syntax and semantics are identical to a generic URI fragment
+and MUST conform to <a data-cite="RFC3986#section-3.5">RFC 3986, section 3.5</a>.
To dereference a <a>DID fragment</a>, the complete <a>DID URL</a> including the
<a>DID fragment</a> MUST be used as input to the <a>DID URL dereferencing</a>
function. For more information, see <a href="#did-url-dereferencing"></a>.
@@ -1043,7 +1043,7 @@ <h2>Fragment</h2>
that are more restrictive than the generic rules in this section.
</p>
-
+
<p>
In order to maximize interoperability, implementers are urged to ensure that
@@ -1601,9 +1601,9 @@ <h3>Key types and formats</h3>
</p>
<p>
-A <a>verification method</a> MUST NOT contain multiple verification material properties.
-For example, expressing key material in a <a>verification method</a> using both
-<code>publicKeyJwk</code> and <code>publicKeyBase58</code> at the same time
+A <a>verification method</a> MUST NOT contain multiple verification material properties.
+For example, expressing key material in a <a>verification method</a> using both
+<code>publicKeyJwk</code> and <code>publicKeyBase58</code> at the same time
is prohibited.
</p>
@@ -1641,7 +1641,7 @@ <h3>Key types and formats</h3>
</p>
<p class="issue" data-number="423">
-The Working Group is still debating how best to communicate support for
+The Working Group is still debating how best to communicate support for
specific verification method types.
</p>
@@ -1678,7 +1678,7 @@ <h3>Key types and formats</h3>
ed25519<br/>(<code>Ed25519VerificationKey2018</code>)
</td>
<td>
-Ed25519 public key values MUST either be encoded as a JWK [[RFC7517]]
+Ed25519 public key values MUST either be encoded as a JWK [[RFC7517]]
using the <code>publicKeyJwk</code> or be
encoded as the raw 32-byte public key value in Base58 Bitcoin format
[[BASE58]] using the <code>publicKeyBase58</code> property.
@@ -1689,7 +1689,7 @@ <h3>Key types and formats</h3>
secp256k1
</td>
<td>
-Secp256k1 public key values MUST either be encoded as a JWK [[RFC7517]]
+Secp256k1 public key values MUST either be encoded as a JWK [[RFC7517]]
using the <code>publicKeyJwk</code> or be
encoded as the raw 33-byte public key value in Base58
Bitcoin format [[BASE58]] using the <code>publicKeyBase58</code> property.
@@ -1700,8 +1700,8 @@ <h3>Key types and formats</h3>
Curve25519<br/>(<code>X25519KeyAgreementKey2019</code>)
</td>
<td>
-Curve25519 (also known as X25519) public key values MUST either be encoded
-as a JWK [[RFC7517]] using the <code>publicKeyJwk</code> or be
+Curve25519 (also known as X25519) public key values MUST either be encoded
+as a JWK [[RFC7517]] using the <code>publicKeyJwk</code> or be
encoded as the raw 32-byte public key value in Base58
Bitcoin format [[BASE58]] using the <code>publicKeyBase58</code> property.
</td>
@@ -2327,9 +2327,9 @@ <h2>
</h2>
<p>
-When producing and consuming DID documents that are in plain JSON (as indicated
-by a <code>content-type</code> of <code>application/did+json</code> in the
-resolver metadata), the following rules MUST be followed.
+This section sets out the requirements for producing and consuming <a>DID
+documents</a> that are in plain JSON (as indicated by a <code>content-type</code>
+of <code>application/did+json</code> in the resolver metadata).
</p>
<section>
@@ -2340,7 +2340,7 @@ <h3>Production</h3>
object</a> conforming to [[!RFC8259]]. All top-level properties of the <a>DID
document</a> MUST be represented by using the property name as the name of the
member of the JSON object. The values of properties of the data model described
-in Section <a href="#data-model"></a>, including all extensions, MUST be encoded
+in Section <a href="#data-model"></a>, including all extensions, are encoded
in JSON [[RFC8259]] by mapping property values to JSON types as follows:
</p>
@@ -2493,16 +2493,16 @@ <h2>
</p>
<p>
-When producing and consuming DID documents that are in JSON-LD (as indicated by
-a <code>content-type</code> of <code>application/did+ld+json</code> in the
-resolver metadata), the following rules MUST be followed.
+This section sets out the requirements for producing and consuming <a>DID
+documents</a> that are in plain JSON (as indicated by a <code>content-type</code>
+of <code>application/did+ld+json</code> in the resolver metadata).
</p>
<ul>
<li>
The <code>@id</code> and <code>@type</code> keywords are aliased to
-<code><a>id</a></code> and <code>type</code> respectively, enabling developers to use
-this specification as idiomatic JSON.
+<code><a>id</a></code> and <code>type</code> respectively, enabling developers
+to use this specification as idiomatic JSON.
</li>
<li>
Even though JSON-LD allows any IRI as node identifiers, <a>DID documents</a>
@@ -2523,69 +2523,73 @@ <h3>
</h3>
<p>
-The <a>DID document</a> MUST be serialized as a JSON document,
-with one additional requirement: <br/>
-The <a>DID document</a> MUST include the <code>@context</code> property.
+The <a>DID document</a> MUST be serialized as a JSON document, with one
+additional requirement: The <a>DID document</a> MUST include the
+<code>@context</code> property.
</p>
<dl>
<dt>@context</dt>
<dd>
-<p>
-The <a href="https://www.w3.org/TR/json-ld11/#the-context">JSON-LD specification </a>
-defines values that are valid for this property.
-</p>
+ <p>
+The <a href="https://www.w3.org/TR/json-ld11/#the-context">JSON-LD
+specification</a> defines values that are valid for this property.
+ </p>
-<p>
+ <p>
The value of <code>@context</code> MUST be exactly one of these values.
-</p>
-
-<ul>
- <li>
- The <a href="https://infra.spec.whatwg.org/#strings">INFRA string</a>
- <code>https://www.w3.org/ns/did/v1</code>.
- <pre class="example">
- {
- "@context": "https://www.w3.org/ns/did/v1",
- ...
- }
- </pre>
- </li>
- <li>
- An <a href="https://infra.spec.whatwg.org/#lists">INFRA list</a>,
- with first item the <a href="https://infra.spec.whatwg.org/#strings">INFRA string</a>
- <code>https://www.w3.org/ns/did/v1</code>, and subsequent items of type
- <a href="https://infra.spec.whatwg.org/#strings">INFRA string</a> or
- <a href="https://infra.spec.whatwg.org/#maps">INFRA map</a>.
- <pre class="example">
- {
- "@context": [
- "https://www.w3.org/ns/did/v1",
- "https://example.com/blockchain-identity/v1"
- ],
- ...
- }
- </pre>
- <p class="issue" data-number="432">The working group is still discussing restrictions on <code>@base</code>, beyond what JSON-LD allows.</p>
- </li>
-</ul>
+ </p>
+ <ul>
+ <li>
+The <a href="https://infra.spec.whatwg.org/#strings">INFRA string</a>
+<code>https://www.w3.org/ns/did/v1</code>.
+ <pre class="example">
+{
+ "@context": "https://www.w3.org/ns/did/v1",
+ ...
+}
+ </pre>
+ </li>
+ <li>
+An <a href="https://infra.spec.whatwg.org/#lists">INFRA list</a>,
+with first item the <a href="https://infra.spec.whatwg.org/#strings">INFRA
+string</a> <code>https://www.w3.org/ns/did/v1</code>, and subsequent items of
+type <a href="https://infra.spec.whatwg.org/#strings">INFRA string</a> or
+<a href="https://infra.spec.whatwg.org/#maps">INFRA map</a>.
+ <pre class="example">
+{
+ "@context": [
+ "https://www.w3.org/ns/did/v1",
+ "https://example.com/blockchain-identity/v1"
+ ],
+ ...
+}
+ </pre>
+ <p class="issue" data-number="432">
+The working group is still discussing restrictions on <code>@base</code>,
+beyond what JSON-LD allows.
+ </p>
+ </li>
+ </ul>
-All members of the
-<code>@context</code> property SHOULD exist in the DID specification
-registries in order to achieve interoperability across different
-representations.
+ <p>
+All members of the <code>@context</code> property SHOULD exist in the DID
+specification registries [[DID-SPEC-REGISTRIES]] in order to achieve
+interoperability across different representations.
+ </p>
-If a member does not exist in the DID specification
-registries, then the DID Document might not be interoperable across
-representations.
+ <p>
+If a member does not exist in the DID specification registries, then the
+<a>DID document</a> might not be interoperable across representations.
+ </p>
-<p>
- Producers SHOULD NOT produce DID Documents that
- contain properties not defined via the <code>@context</code>.
- Properties that are not defined via the <code>@context</code> MAY be dropped by Consumers.
-</p>
+ <p>
+Producers SHOULD NOT produce <a>DID documents</a> that contain properties not
+defined via the <code>@context</code>. Properties that are not defined via the
+<code>@context</code> MAY be dropped by Consumers.
+ </p>
</dd>
</dl>
@@ -2607,8 +2611,8 @@ <h3>
<dl>
<dt>@context</dt>
<dd>
-The value of the <code>@context</code> property MUST conform
-to the <a href="#production-0">JSON-LD Production Rules</a>.
+The value of the <code>@context</code> property MUST conform
+to the <a href="#production-0">JSON-LD Production Rules</a>.
If more than one <a>URI</a> is
provided, the <a>URIs</a> MUST be interpreted as an ordered set. It is
@@ -2635,10 +2639,10 @@ <h3>
</p>
<p>
- Consumers SHOULD drop all properties from a DID Documents that
- are not defined via the <code>@context</code>.
+ Consumers SHOULD drop all properties from a DID Documents that
+ are not defined via the <code>@context</code>.
</p>
-
+
</section>
</section>
From ac32aca370472ab1c10c8244292d76205a68a2fd Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 13 Oct 2020 14:10:19 +0100
Subject: [PATCH 39/89] json-ld representation: Move normative language about
@context URIs.
Normative requirements about dereferencing and and hashing contents
of @context URIs are requirements on a producer rather than a
consumer, so these statements have been moved accordingly. (#384)
Also removes normative language around conforming to JSON-LD
production rules as this is not a requirement on the consumer, but
advisory.
---
index.html | 45 ++++++++++++++++++++-------------------------
1 file changed, 20 insertions(+), 25 deletions(-)
diff --git a/index.html b/index.html
index 4505aca3..8720fd91 100644
--- a/index.html
+++ b/index.html
@@ -2577,22 +2577,25 @@ <h3>
<p>
All members of the <code>@context</code> property SHOULD exist in the DID
specification registries [[DID-SPEC-REGISTRIES]] in order to achieve
-interoperability across different representations.
+interoperability across different representations. If a member does not exist
+in the DID specification registries, then the <a>DID document</a> might not be
+interoperable across representations.
</p>
<p>
-If a member does not exist in the DID specification registries, then the
-<a>DID document</a> might not be interoperable across representations.
+It is RECOMMENDED that dereferencing each <a>URI</a> value of the
+<code>@context</code> property results in a document containing
+machine-readable information about the context. These URIs SHOULD be
+associated with a cryptographic hash of the content of the JSON-LD Context as
+part of registration in the DID Specification Registries [[DID-SPEC-REGISTRIES]].
</p>
-
- <p>
+ </dd>
+ </dl>
+ <p>
Producers SHOULD NOT produce <a>DID documents</a> that contain properties not
defined via the <code>@context</code>. Properties that are not defined via the
<code>@context</code> MAY be dropped by Consumers.
- </p>
-
- </dd>
- </dl>
+ </p>
</section>
@@ -2611,20 +2614,12 @@ <h3>
<dl>
<dt>@context</dt>
<dd>
-The value of the <code>@context</code> property MUST conform
-to the <a href="#production-0">JSON-LD Production Rules</a>.
-
-If more than one <a>URI</a> is
-provided, the <a>URIs</a> MUST be interpreted as an ordered set. It is
-RECOMMENDED that dereferencing each <a>URI</a> results in a document containing
-machine-readable information about the context. To enable interoperability
-with other representations, URLs registered in the
-DID Specification Registries [[DID-SPEC-REGISTRIES]] referring to
-JSON-LD Contexts SHOULD be associated with a cryptographic hash of
-the content of the JSON-LD Context. This ensures that the interpretation of the
-information by JSON-LD consumers will be the same as interpretations
-over other representations by other consumers that rely on the
-DID Specification Registries [[DID-SPEC-REGISTRIES]].
+ <p>
+The value of the <code>@context</code> property conforms to the
+<a href="#production-0">JSON-LD Production Rules</a>. If more than one
+<a>URI</a> is provided, the <a>URIs</a> MUST be interpreted as an
+<a data-cite="INFRA#ordered-set">ordered set</a>.
+ </p>
</dd>
</dl>
@@ -2639,8 +2634,8 @@ <h3>
</p>
<p>
- Consumers SHOULD drop all properties from a DID Documents that
- are not defined via the <code>@context</code>.
+Consumers SHOULD drop all properties from a DID Documents that are not defined
+via the <code>@context</code>.
</p>
</section>
From 717f38ab465be6827c7f9306559c13663abf5ff0 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 13 Oct 2020 14:43:55 +0100
Subject: [PATCH 40/89] Fix typo
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index 8720fd91..e33a8a90 100644
--- a/index.html
+++ b/index.html
@@ -2494,7 +2494,7 @@ <h2>
<p>
This section sets out the requirements for producing and consuming <a>DID
-documents</a> that are in plain JSON (as indicated by a <code>content-type</code>
+documents</a> that are in JSON-LD (as indicated by a <code>content-type</code>
of <code>application/did+ld+json</code> in the resolver metadata).
</p>
From 2a3ca5dc9045e71ea82c9b654201e241b99aefc9 Mon Sep 17 00:00:00 2001
From: Amy Guy <amy@rhiaro.co.uk>
Date: Sun, 18 Oct 2020 19:21:17 +0100
Subject: [PATCH 41/89] editorial: Add internal ref
Co-authored-by: Brent Zundel <brent.zundel@gmail.com>
---
index.html | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/index.html b/index.html
index e33a8a90..dc28f9da 100644
--- a/index.html
+++ b/index.html
@@ -2634,8 +2634,8 @@ <h3>
</p>
<p>
-Consumers SHOULD drop all properties from a DID Documents that are not defined
-via the <code>@context</code>.
+Consumers SHOULD drop all properties from a <a>DID document</a> that are not
+defined via the <code>@context</code>.
</p>
</section>
From 8a69098cb516a9b915b22d849bc6da35732bd4b8 Mon Sep 17 00:00:00 2001
From: gjgd <7913565+gjgd@users.noreply.github.com>
Date: Tue, 27 Oct 2020 13:31:49 +0100
Subject: [PATCH 42/89] Remove proof property from example.
---
index.html | 6 ------
1 file changed, 6 deletions(-)
diff --git a/index.html b/index.html
index dc28f9da..75b6b9e1 100644
--- a/index.html
+++ b/index.html
@@ -2881,12 +2881,6 @@ <h4>DagCBOR</h4>
],
"created": "2018-12-01T03:00:00Z",
"id": "did:example:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew",
- "proof": {
- "created": "2020-05-01T03:00:02Z",
- "creator": "did:example:12D3KooWMHdrzcwpjbdrZs5GGqERAvcgqX3b5dpuPtPa9ot69yew; example:key=id=bafyreicubtx5wqo3nosc4cazrkctfhwd6rewezgpwoe4swirls4ebdhs2i",
- "signatureValue": "o9r6LxgoGN8FoaeeUA6EdDcv12GvDzFEmCgjWzvpur2YSQyA8W2r0SSWUK+nH5tMqzaFLun6wwZ1Eot37amGDg==",
- "type": "ed25519Signature2018"
- },
"verificationMethod": [
{
"curve": "ed25519",
From 04f500587e7aaf75b4e053c4ca6ffdf5e020dc4d Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sat, 3 Oct 2020 16:51:20 +0100
Subject: [PATCH 43/89] syntax: Move normative statements about method
requirements to Method Schemes section (#384)
---
index.html | 21 +++++++++++----------
1 file changed, 11 insertions(+), 10 deletions(-)
diff --git a/index.html b/index.html
index 75b6b9e1..7f1412b7 100644
--- a/index.html
+++ b/index.html
@@ -770,12 +770,8 @@ <h3>DID Syntax</h3>
</pre>
<p>
-A <a>DID method</a> specification MUST further restrict the generic <a>DID</a>
-syntax by defining its own <code>method-name</code> and its own
-<code>method-specific-id</code> syntax. Case sensitivity and normalization of
-the value of the <code>method-specific-id</code> rule MUST be defined by the
-governing <a>DID method</a> specification. For more information, see Section
-<a href="#methods"></a>.
+For requirements on <a>DID methods</a> relating to the <a>DID</a> syntax, see
+Section <a href="#method-schemes"></a>.
</p>
<div class="note" title="Persistence">
@@ -3005,10 +3001,10 @@ <h2>Method Schemes</h2>
maintained in the DID Methods Registry, which is part of [[?DID-SPEC-REGISTRIES]].
</p>
<p>
- Authors of new <a>DID method</a> specifications are encouraged to add their
- method names to the DID Method Registry so that other implementors
- and members of the community have a place to see an overview of existing
- <a>DID methods</a>.
+Authors of new <a>DID method</a> specifications are encouraged to add their
+method names to the DID Method Registry so that other implementors
+and members of the community have a place to see an overview of existing
+<a>DID methods</a>.
</p>
</div>
@@ -3017,6 +3013,11 @@ <h2>Method Schemes</h2>
<code>method-specific-id</code> component of a <a>DID</a>.
</p>
<p>
+Case sensitivity and normalization of the value of the
+<code>method-specific-id</code> rule MUST be defined by the <a>DID method</a>
+specification.
+ </p>
+ <p>
The <code>method-specific-id</code> value MUST be able to be generated without
the use of a centralized registry service.
</p>
From 9d24bc040b8ecff7f0fd4b127484453435f1a986 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sat, 3 Oct 2020 17:12:13 +0100
Subject: [PATCH 44/89] params: Refactor parameters table to make normative
language more precise (#384)
---
index.html | 55 ++++++++++++++++++++++++++----------------------------
1 file changed, 26 insertions(+), 29 deletions(-)
diff --git a/index.html b/index.html
index 7f1412b7..22688ad3 100644
--- a/index.html
+++ b/index.html
@@ -836,14 +836,10 @@ <h2>DID Parameters</h2>
the identifier for a <a>resource</a>.
</p>
<p>
-Some DID parameter names (for example, for service selection) are
-completely independent of any specific <a>DID method</a> and MUST always
-function the same way for all <a>DIDs</a>. Other DID parameter names (for
-example, for versioning) MAY be supported by certain <a>DID methods</a>, but
-MUST operate uniformly across those <a>DID methods</a> that do support them.
- </p>
- <p>
-The following table defines a set of DID parameter names.
+Some DID parameters are supported by all <a>DID methods</a> and others need
+not be. Where optional parameters are supported, they are expected to operate
+uniformly across the <a>DID methods</a> that do support them. Requirements
+which enable this are detailed in the following table.
</p>
<table class="simple">
@@ -865,9 +861,9 @@ <h2>DID Parameters</h2>
</td>
<td>
A resource hash of the <a>DID document</a> to add integrity protection, as
-specified in [[?HASHLINK]]. The associated value MUST be an
-<a data-lt="ascii string">ASCII string</a>. <i>This parameter is
-non-normative.</i>
+specified in [[?HASHLINK]]. Support for this parameter is OPTIONAL. If
+present, the associated value MUST be an <a data-lt="ascii string">ASCII
+string</a>.
</td>
</tr>
<tr>
@@ -875,8 +871,9 @@ <h2>DID Parameters</h2>
<code><a>service</a></code>
</td>
<td>
-Identifies a service from the <a>DID document</a> by service ID. The
-associated value MUST be an <a data-lt="ascii string">ASCII string</a>.
+Identifies a service from the <a>DID document</a> by service ID. Support for
+this parameter is REQUIRED. The associated value MUST be an <a data-lt="ascii
+string">ASCII string</a>.
</td>
</tr>
<tr>
@@ -885,9 +882,9 @@ <h2>DID Parameters</h2>
</td>
<td>
Identifies a specific version of a <a>DID document</a> to be resolved (the
-version ID could be sequential, or a <a>UUID</a>, or method-specific). Note
-that this parameter might not be supported by all <a>DID methods</a>. The
-associated value MUST be an <a data-lt="ascii string">ASCII string</a>.
+version ID could be sequential, or a <a>UUID</a>, or method-specific). Support
+for this parameter is OPTIONAL. If present, the associated value MUST be an <a
+data-lt="ascii string">ASCII string</a>.
</td>
</tr>
@@ -896,14 +893,14 @@ <h2>DID Parameters</h2>
<code>version-time</code>
</td>
<td>
-Identifies a certain version timestamp of a <a>DID document</a> to be
-resolved. That is, the <a>DID document</a> that was valid for a <a>DID</a> at
-a certain time. Note that this parameter might not be supported by all <a>DID
-methods</a>. The associated value MUST be an <a data-lt="ascii string">ASCII
-string</a> which is a valid XML datetime value, as defined in section 3.3.7 of
-<a href="https://www.w3.org/TR/xmlschema11-2/">W3C XML Schema Definition
-Language (XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]]. This datetime
-value MUST be normalized to UTC 00:00, as indicated by the trailing "Z".
+Identifies a certain version timestamp of a <a>DID document</a> to be resolved.
+That is, the <a>DID document</a> that was valid for a <a>DID</a> at a certain
+time. Support for this parameter is OPTIONAL. If present, the associated value
+MUST be an <a data-lt="ascii string">ASCII string</a> which is a valid XML
+datetime value, as defined in section 3.3.7 of <a
+href="https://www.w3.org/TR/xmlschema11-2/">W3C XML Schema Definition Language
+(XSD) 1.1 Part 2: Datatypes</a> [[XMLSCHEMA11-2]]. This datetime value MUST be
+normalized to UTC 00:00, as indicated by the trailing "Z".
</td>
</tr>
@@ -914,11 +911,11 @@ <h2>DID Parameters</h2>
<td>
A relative URI reference according to <a
data-cite="RFC3986#section-4.2">RFC3986 Section 4.2</a>
-that identifies a resource at a <a>service endpoint</a>, which is selected
-from a <a>DID document</a> by using the <code>service</code> parameter. The
-associated value MUST be an <a data-lt="ascii string">ASCII string</a> and
-MUST use percent-encoding for certain characters as specified in <a
-data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>.
+that identifies a resource at a <a>service endpoint</a>, which is selected from
+a <a>DID document</a> by using the <code>service</code> parameter. Support for
+this parameter is REQUIRED. The associated value MUST be an <a data-lt="ascii
+string">ASCII string</a> and MUST use percent-encoding for certain characters
+as specified in <a data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>.
</td>
</tr>
</tbody>
From bcbbe4c5b1d7ca3217b8267304fea2c10da85932 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sat, 3 Oct 2020 19:46:20 +0100
Subject: [PATCH 45/89] fragment: Move URL dereferencing bit to appropriate
section (#384)
---
index.html | 98 ++++++++++++++++++++++++++++--------------------------
1 file changed, 50 insertions(+), 48 deletions(-)
diff --git a/index.html b/index.html
index 22688ad3..47f7920e 100644
--- a/index.html
+++ b/index.html
@@ -921,6 +921,19 @@ <h2>DID Parameters</h2>
</tbody>
</table>
+ <p>
+Implementers as well as <a>DID method</a> specification authors MAY use
+additional DID parameters that are not listed here. For maximum
+interoperability, it is RECOMMENDED that DID parameters use the official W3C
+DID Specification Registries mechanism [[DID-SPEC-REGISTRIES]], to avoid
+collision with other uses of the same DID parameter with different semantics.
+ </p>
+
+ <p>
+Additional considerations for processing these parameters are discussed in
+[[?DID-RESOLUTION]].
+ </p>
+
<p>
Two example <a>DID URLs</a> using the <code><a>service</a></code> and
<code>version-time</code> DID parameters are shown below.
@@ -935,11 +948,21 @@ <h2>DID Parameters</h2>
</pre>
<p>
-Implementers as well as <a>DID method</a> specification authors MAY use
-additional DID parameters that are not listed here. For maximum
-interoperability, it is RECOMMENDED that DID parameters use the official W3C
-DID Specification Registries mechanism [[DID-SPEC-REGISTRIES]], to avoid
-collision with other uses of the same DID parameter with different semantics.
+Adding a DID parameter to a <a>DID URL</a> means that the parameter becomes
+part of an identifier for a <a>resource</a> (the <a>DID document</a> or other).
+Alternatively, the <a>DID resolution</a> and the <a>DID URL dereferencing</a>
+functions can also be influenced by passing input metadata to a <a>DID
+resolver</a> that are not part of the DID URL. (See <a
+href="#did-resolution-input-metadata-properties"></a>). Such input
+metadata could for example control caching
+or the desired encoding of a resolution result. This is comparable to HTTP,
+where certain parameters could either be included in an HTTP URL, or
+alternatively passed as HTTP headers during the dereferencing process. The
+important distinction is that DID parameters that are part of the <a>DID URL</a>
+should be used to specify <i>what <a>resource</a> is being identified</i>,
+whereas input metadata that is not part of the <a>DID URL</a>
+should be use to control <i>how that <a>resource</a> is resolved or
+dereferenced</i>.
</p>
<p>
@@ -949,30 +972,8 @@ <h2>DID Parameters</h2>
</p>
<p>
-DID parameters SHOULD NOT be used if the same functionality can be expressed
-by passing input metadata to a <a>DID resolver</a> (see <a
-href="#did-resolution-input-metadata-properties"></a>), and if there is no need
-to construct a URI for use as a link, or as a <a>resource</a> in RDF / JSON-LD
-documents.
- </p>
-
- <p>
-Additional considerations for processing these parameters are discussed in
-[[?DID-RESOLUTION]].
- </p>
-
- <p class="note" title="DID parameters and DID resolution">
-The <a>DID resolution</a> and the <a>DID URL dereferencing</a> functions can
-be influenced by passing input metadata to a <a>DID resolver</a> that are
-not part of the DID URL. (See <a
-href="#did-resolution-input-metadata-properties"></a>). This is comparable to
-HTTP, where certain parameters could either be included in an HTTP URL, or
-alternatively passed as HTTP headers during the dereferencing process. The
-important distinction is that DID parameters that are part of the <a>DID
-URL</a> should be used to specify <em>what <a>resource</a> is being
-identified</em>, whereas input metadata that is not part of the <a>DID URL</a>
-should be use to control <em>how that <a>resource</a> is resolved or
-dereferenced</em>.
+It is expected that DID parameters will <em>not</em> be used if the same
+functionality can be expressed by passing input metadata to a DID resolver.
</p>
</section>
@@ -1020,15 +1021,18 @@ <h2>Query</h2>
<h2>Fragment</h2>
<p>
-A <a>DID fragment</a> is used as method-independent reference into a <a>DID Document</a> or external resource.
+A <a>DID fragment</a> is used as method-independent reference into a <a>DID
+document</a> or external resource.
</p>
-<p>
-<a>DID fragment</a> syntax and semantics are identical to a generic URI fragment
-and MUST conform to <a data-cite="RFC3986#section-3.5">RFC 3986, section 3.5</a>.
-To dereference a <a>DID fragment</a>, the complete <a>DID URL</a> including the
-<a>DID fragment</a> MUST be used as input to the <a>DID URL dereferencing</a>
-function. For more information, see <a href="#did-url-dereferencing"></a>.
+ <p>
+<a>DID fragment</a> syntax and semantics are identical to a generic URI
+fragment and MUST conform to <a data-cite="RFC3986#section-3.5">RFC 3986,
+section 3.5</a>.
+ </p>
+ <p>
+For information about how to dereference a <a>DID fragment</a>, see
+<a href="#did-url-dereferencing"></a>.
</p>
<p>
@@ -1036,8 +1040,6 @@ <h2>Fragment</h2>
that are more restrictive than the generic rules in this section.
</p>
-
-
<p>
In order to maximize interoperability, implementers are urged to ensure that
<a>DID fragments</a> are interpreted in the same way across representations (as
@@ -3517,12 +3519,11 @@ <h2>
The DID URL dereferencing function dereferences a <a>DID URL</a> into
a resource with contents depending on the <a>DID URL</a>'s components,
including the <a>DID method</a>, method-specific identifier, path, query,
-and fragment. This process depends on <a>DID resolution</a>
-of the <a>DID</a> contained in the <a>DID URL</a>.
-The details of how this
-process is accomplished are outside the scope of this specification, but all
-conformant implementations MUST implement a function which has the
-following abstract form:
+and fragment. This process depends on <a>DID resolution</a> of the <a>DID</a>
+contained in the <a>DID URL</a>.
+The details of how this process is accomplished are outside the scope of this
+specification, but all conformant implementations MUST implement a function
+which has the following abstract form:
</p>
<p><code>
@@ -3540,16 +3541,17 @@ <h2>
</dt>
<dd>
A conformant <a>DID URL</a> as a single string. This is the <a>DID URL</a> to
-dereference. This input is REQUIRED.
+dereference. To dereference a <a>DID fragment</a>, the complete <a>DID URL</a>
+including the <a>DID fragment</a> MUST be used. This input is REQUIRED.
</dd>
<dt>
did-url-dereferencing-input-metadata
</dt>
<dd>
A <a href="metadata-structure">metadata structure</a> consisting of input
-options to the <code>dereference</code> function in addition to the <code>did-url</code>
-itself. Properties defined by this specification are in <a
-href="#did-url-dereferencing-input-metadata-properties"></a>. This input is
+options to the <code>dereference</code> function in addition to the
+<code>did-url</code> itself. Properties defined by this specification are in
+<a href="#did-url-dereferencing-input-metadata-properties"></a>. This input is
REQUIRED, but the structure MAY be empty.
</dd>
</dl>
From b0f38ec897ed02eea1a4420bf12f2c64db311703 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 18 Oct 2020 19:03:58 +0100
Subject: [PATCH 46/89] parameters: Restore language about parameters being
independant of DID methods (thanks @peacekeeper)
---
index.html | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/index.html b/index.html
index 47f7920e..dae539d3 100644
--- a/index.html
+++ b/index.html
@@ -836,10 +836,12 @@ <h2>DID Parameters</h2>
the identifier for a <a>resource</a>.
</p>
<p>
-Some DID parameters are supported by all <a>DID methods</a> and others need
-not be. Where optional parameters are supported, they are expected to operate
-uniformly across the <a>DID methods</a> that do support them. Requirements
-which enable this are detailed in the following table.
+Some DID parameters are completely independent of of any specific <a>DID
+method</a>, and function the same way for all <a>DIDs</a>. Other DID
+parameters are not necessarily supported by all <a>DID methods</a>. Where
+optional parameters are supported, they are expected to operate uniformly
+across the <a>DID methods</a> that do support them. Requirements which enable
+this are detailed in the following table.
</p>
<table class="simple">
From 3c836fe8cdb36f9acbf8f5da399d13204701b5fe Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 18 Oct 2020 19:05:45 +0100
Subject: [PATCH 47/89] parameters: Explicitly note that hl is non-normative,
thanks @iherman
---
index.html | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/index.html b/index.html
index dae539d3..8902e091 100644
--- a/index.html
+++ b/index.html
@@ -863,9 +863,9 @@ <h2>DID Parameters</h2>
</td>
<td>
A resource hash of the <a>DID document</a> to add integrity protection, as
-specified in [[?HASHLINK]]. Support for this parameter is OPTIONAL. If
-present, the associated value MUST be an <a data-lt="ascii string">ASCII
-string</a>.
+specified in [[?HASHLINK]]. This parameter is non-normative. Support for this
+parameter is OPTIONAL. If present, the associated value MUST be an
+<a data-lt="ascii string">ASCII string</a>.
</td>
</tr>
<tr>
From b47ebe268c584a394a0b4c7b6f7094c3c8b68015 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 18 Oct 2020 19:10:28 +0100
Subject: [PATCH 48/89] parameters: Reorder table so required params are first,
optional are next, and the non-normative one is last.
---
index.html | 28 +++++++++++++---------------
1 file changed, 13 insertions(+), 15 deletions(-)
diff --git a/index.html b/index.html
index 8902e091..041d10a5 100644
--- a/index.html
+++ b/index.html
@@ -859,13 +859,16 @@ <h2>DID Parameters</h2>
<tbody>
<tr>
<td>
-<code>hl</code>
+<code>relative-ref</code>
</td>
<td>
-A resource hash of the <a>DID document</a> to add integrity protection, as
-specified in [[?HASHLINK]]. This parameter is non-normative. Support for this
-parameter is OPTIONAL. If present, the associated value MUST be an
-<a data-lt="ascii string">ASCII string</a>.
+A relative URI reference according to <a
+data-cite="RFC3986#section-4.2">RFC3986 Section 4.2</a>
+that identifies a resource at a <a>service endpoint</a>, which is selected from
+a <a>DID document</a> by using the <code>service</code> parameter. Support for
+this parameter is REQUIRED. The associated value MUST be an <a data-lt="ascii
+string">ASCII string</a> and MUST use percent-encoding for certain characters
+as specified in <a data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>.
</td>
</tr>
<tr>
@@ -889,7 +892,6 @@ <h2>DID Parameters</h2>
data-lt="ascii string">ASCII string</a>.
</td>
</tr>
-
<tr>
<td>
<code>version-time</code>
@@ -905,19 +907,15 @@ <h2>DID Parameters</h2>
normalized to UTC 00:00, as indicated by the trailing "Z".
</td>
</tr>
-
<tr>
<td>
-<code>relative-ref</code>
+<code>hl</code>
</td>
<td>
-A relative URI reference according to <a
-data-cite="RFC3986#section-4.2">RFC3986 Section 4.2</a>
-that identifies a resource at a <a>service endpoint</a>, which is selected from
-a <a>DID document</a> by using the <code>service</code> parameter. Support for
-this parameter is REQUIRED. The associated value MUST be an <a data-lt="ascii
-string">ASCII string</a> and MUST use percent-encoding for certain characters
-as specified in <a data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>.
+A resource hash of the <a>DID document</a> to add integrity protection, as
+specified in [[?HASHLINK]]. This parameter is non-normative. Support for this
+parameter is OPTIONAL. If present, the associated value MUST be an
+<a data-lt="ascii string">ASCII string</a>.
</td>
</tr>
</tbody>
From 5dd10b5a3654f7be046ddb810ea35733a494ab59 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Mon, 26 Oct 2020 15:13:29 +0000
Subject: [PATCH 49/89] parameters: rearrange section to make more sense
---
index.html | 48 ++++++++++++++++++++++--------------------------
1 file changed, 22 insertions(+), 26 deletions(-)
diff --git a/index.html b/index.html
index 041d10a5..5216bf4b 100644
--- a/index.html
+++ b/index.html
@@ -929,6 +929,17 @@ <h2>DID Parameters</h2>
collision with other uses of the same DID parameter with different semantics.
</p>
+ <p>
+DID parameters MAY be used if there is a clear use case where the parameter
+needs to be part of a URI that can be used as a link, or as a <a>resource</a>
+in RDF / JSON-LD documents.
+ </p>
+
+ <p>
+It is expected that DID parameters will <em>not</em> be used if the same
+functionality can be expressed by passing input metadata to a DID resolver.
+ </p>
+
<p>
Additional considerations for processing these parameters are discussed in
[[?DID-RESOLUTION]].
@@ -947,33 +958,18 @@ <h2>DID Parameters</h2>
did:foo:21tDAKCERh95uGgKbJNHYp?version-time=2002-10-10T17:00:00Z
</pre>
- <p>
-Adding a DID parameter to a <a>DID URL</a> means that the parameter becomes
-part of an identifier for a <a>resource</a> (the <a>DID document</a> or other).
-Alternatively, the <a>DID resolution</a> and the <a>DID URL dereferencing</a>
-functions can also be influenced by passing input metadata to a <a>DID
-resolver</a> that are not part of the DID URL. (See <a
-href="#did-resolution-input-metadata-properties"></a>). Such input
-metadata could for example control caching
-or the desired encoding of a resolution result. This is comparable to HTTP,
-where certain parameters could either be included in an HTTP URL, or
+ <p class="note" title="DID parameters and DID resolution">
+The <a>DID resolution</a> and the <a>DID URL dereferencing</a> functions can
+be influenced by passing input metadata to a <a>DID resolver</a> that are
+not part of the DID URL. (See <a
+href="#did-resolution-input-metadata-properties"></a>). This is comparable to
+HTTP, where certain parameters could either be included in an HTTP URL, or
alternatively passed as HTTP headers during the dereferencing process. The
-important distinction is that DID parameters that are part of the <a>DID URL</a>
-should be used to specify <i>what <a>resource</a> is being identified</i>,
-whereas input metadata that is not part of the <a>DID URL</a>
-should be use to control <i>how that <a>resource</a> is resolved or
-dereferenced</i>.
- </p>
-
- <p>
-DID parameters MAY be used if there is a clear use case where the parameter
-needs to be part of a URI that can be used as a link, or as a <a>resource</a>
-in RDF / JSON-LD documents.
- </p>
-
- <p>
-It is expected that DID parameters will <em>not</em> be used if the same
-functionality can be expressed by passing input metadata to a DID resolver.
+important distinction is that DID parameters that are part of the <a>DID
+URL</a> should be used to specify <em>what <a>resource</a> is being
+identified</em>, whereas input metadata that is not part of the <a>DID URL</a>
+should be use to control <em>how that <a>resource</a> is resolved or
+dereferenced</em>.
</p>
</section>
From 87ababfe8bdf4055b48a2026d87c1b2bf7874f65 Mon Sep 17 00:00:00 2001
From: Markus Sabadello <markus@danubetech.com>
Date: Mon, 19 Oct 2020 13:21:01 +0200
Subject: [PATCH 50/89] Remove "unauthorized" and add "deactivated" error code.
Addresses https://github.com/w3c/did-core/issues/402.
Signed-off-by: Markus Sabadello <markus@danubetech.com>
---
index.html | 26 +++++++++++++-------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/index.html b/index.html
index 5216bf4b..fda943c8 100644
--- a/index.html
+++ b/index.html
@@ -3447,18 +3447,18 @@ <h3>
to valid syntax. (See <a href="#did-syntax"></a>.)
</dd>
<dt>
-unauthorized
+not-found
</dt>
<dd>
-The caller is not authorized to resolve this <a>DID</a> with this <a>DID
-resolver</a>.
+The <a>DID resolver</a> was unable to find the <a>DID document</a>
+resulting from this resolution request.
</dd>
<dt>
-not-found
+deactivated
</dt>
<dd>
-The <a>DID resolver</a> was unable to return the <a>DID document</a>
-resulting from this resolution request.
+The <a>DID</a> supplied to the <a>DID resolution</a> function has been
+deactivated. (See <a href="#deactivate"></a>.)
</dd>
</dl>
</dd>
@@ -3669,19 +3669,19 @@ <h3>
not conform to valid syntax. (See <a href="#did-url-syntax"></a>.)
</dd>
<dt>
-unauthorized
+not-found
</dt>
<dd>
-The caller is not authorized to dereference the given <a>DID URL</a> with the
-given <a>DID URL dereferencer</a>.
+The <a>DID URL dereferencer</a> was unable to find the
+<code>content-stream</code> resulting from this dereferencing request.
</dd>
<dt>
-not-found
+deactivated
</dt>
<dd>
-The <a>DID URL dereferencer</a> was unable to return the
-<code>content-stream</code> resulting from this dereferencing request.
- </dd>
+The <a>DID</a> in the <a>DID URL</a> supplied to the <a>DID URL
+dereferencing</a> function has been deactivated. (See
+<a href="#deactivate"></a>.)
</dl>
</dd>
</dl>
From 84e08e48d55e154a8c32d01276621fdcce694b01 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 12:38:27 +0000
Subject: [PATCH 51/89] editorial: fix stray link to issues
---
index.html | 2 --
1 file changed, 2 deletions(-)
diff --git a/index.html b/index.html
index fda943c8..58e64712 100644
--- a/index.html
+++ b/index.html
@@ -1636,8 +1636,6 @@ <h3>Key types and formats</h3>
specific verification method types.
</p>
- https://github.com/w3c/did-core/issues/
-
<table class="simple" id="public-key-support">
<caption>
This table defines the support for public key expression in a DID document.
From 58225f14c334c97e54e71c4a2b457db7509b5806 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 13:20:10 +0000
Subject: [PATCH 52/89] editorial: Clarify importance of ordering of property
values, for #411
---
index.html | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/index.html b/index.html
index 58e64712..3a376c29 100644
--- a/index.html
+++ b/index.html
@@ -1253,6 +1253,16 @@ <h1>Core Properties</h1>
</li>
</ul>
+ <p class="note" title="Ordering of values">
+As a result of the data model being defined using terminology from [[INFRA]],
+property values which can contain more than one item, such as
+<a data-cite="INFRA#lists">lists</a> and <a
+data-cite="INFRA#ordered-set">sets</a>, are explicitly ordered. For the
+purposes of this specification, unless otherwise stated, ordering is not
+important and implementations are not expected to produce or consume
+deterministically ordered values.
+ </p>
+
<section>
<h2>DID Subject</h2>
From 09b4d6eb6a06bce8e3409c49f9a9a46c7b53be4f Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 10:04:31 +0000
Subject: [PATCH 53/89] editorial: update JSON-LD reference, for #403
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index 3a376c29..27d1d43d 100644
--- a/index.html
+++ b/index.html
@@ -2487,7 +2487,7 @@ <h2>
</h2>
<p>
-[[!JSON-LD]] is a JSON-based format used to serialize
+[[!JSON-LD11]] is a JSON-based format used to serialize
<a href="http://www.w3.org/TR/ld-glossary/#linked-data">Linked Data</a>.
</p>
From 8a02a41fdaad19be0d44d72bb96028d74512b0a6 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 11:31:28 +0000
Subject: [PATCH 54/89] resolution: link for conforming DID doc, #403
---
index.html | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/index.html b/index.html
index 27d1d43d..943a39c9 100644
--- a/index.html
+++ b/index.html
@@ -3341,8 +3341,8 @@ <h2>
</dt>
<dd>
If the resolution is successful, and if the <code>resolve</code> function was
-called, this MUST be a <a>DID document</a> conforming to the abstract data
-model. If the resolution is unsuccessful, this value MUST be empty.
+called, this MUST be a <a>conforming DID document</a>. If the resolution is
+unsuccessful, this value MUST be empty.
</dd>
<dt>
did-document-stream
From 12873fd1dcba7b06d32f6eaa443d35aaffabaf14 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 11:36:24 +0000
Subject: [PATCH 55/89] security: Remove unnecessary phrase, #403
---
index.html | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/index.html b/index.html
index 943a39c9..028dfcb3 100644
--- a/index.html
+++ b/index.html
@@ -4080,9 +4080,9 @@ <h2>
</p>
<p>
-Solutions to this problem (and there are many) should be defined in separate
-specifications that reference this specification. It is strongly recommended
-that such specifications carefully consider the:
+Solutions to this problem should be defined in separate specifications that
+reference this specification. It is strongly recommended that such
+specifications carefully consider the:
</p>
<ul>
From a06028e7764c67935d3f6844327a7ae06d5edc06 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 11:47:51 +0000
Subject: [PATCH 56/89] privacy: Add reference to Privacy by Design and clarify
source of quote, #403
---
common.js | 9 +++++++++
index.html | 19 ++++++++++---------
2 files changed, 19 insertions(+), 9 deletions(-)
diff --git a/common.js b/common.js
index dffd56cc..a2a7e4f5 100644
--- a/common.js
+++ b/common.js
@@ -159,6 +159,15 @@ var ccg = {
],
status: "Draft Community Group Report",
publisher: "Credentials Community Group"
+ },
+ "PRIVACY-BY-DESIGN": {
+ title: "Privacy by Design",
+ href: "https://iapp.org/media/pdf/resource_center/pbd_implement_7found_principles.pdf",
+ authors: [
+ "Ann Cavoukian"
+ ],
+ date: "2011",
+ publisher: "Information and Privacy Commissioner"
}
}
};
diff --git a/index.html b/index.html
index 028dfcb3..dd4e70ad 100644
--- a/index.html
+++ b/index.html
@@ -4182,15 +4182,16 @@ <h1>
<p>
It is critically important to apply the principles of Privacy by Design
-to all aspects of the <a>decentralized identifier</a> architecture, because
-<a>DIDs</a> and <a>DID documents</a> are, by design, administered directly by
-the <a>DID controller(s)</a>. There is no registrar, hosting company, or other
-intermediate service provider to recommend or apply additional privacy
-safeguards. The authors of this specification have applied all seven Privacy by
-Design principles throughout its development. For example, privacy in this
-specification is preventative not remedial, and privacy is an embedded default.
-Furthermore, the <a>decentralized identifier</a> architecture by itself embodies
-principle #7, "Respect for user privacy — keep it user-centric."
+[[PRIVACY-BY-DESIGN]] to all aspects of the <a>decentralized identifier</a>
+architecture, because <a>DIDs</a> and <a>DID documents</a> are, by design,
+administered directly by the <a>DID controller(s)</a>. There is no registrar,
+hosting company, or other intermediate service provider to recommend or apply
+additional privacy safeguards. The authors of this specification have applied
+all seven Privacy by Design principles throughout its development. For example,
+privacy in this specification is preventative not remedial, and privacy is an
+embedded default. Furthermore, the <a>decentralized identifier</a>
+architecture by itself embodies Privacy by Design principle #7: "Respect for
+user privacy — keep it user-centric."
</p>
<p>
From 953bfe6d49f08e9368b8823dafe9b20b124c0c10 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 11:59:01 +0000
Subject: [PATCH 57/89] references: fix versions, internal refs and normative
status, #403
---
common.js | 4 ++--
index.html | 17 +++++++----------
2 files changed, 9 insertions(+), 12 deletions(-)
diff --git a/common.js b/common.js
index a2a7e4f5..db31fb4e 100644
--- a/common.js
+++ b/common.js
@@ -43,7 +43,7 @@ var ccg = {
},
"DID-USE-CASES": {
title: "Decentralized Identifier Use Cases",
- href: "https://w3c.github.io/did-use-cases/",
+ href: "https://www.w3.org/TR/did-use-cases/",
authors: [
"Joe Andrieu",
"Kim Hamilton Duffy",
@@ -113,7 +113,7 @@ var ccg = {
"HASHLINK": {
title: "Cryptographic Hyperlinks",
date: "December 2018",
- href: "https://tools.ietf.org/html/draft-sporny-hashlink-02",
+ href: "https://tools.ietf.org/html/draft-sporny-hashlink-05",
authors: [
"Manu Sporny"
],
diff --git a/index.html b/index.html
index dd4e70ad..e5c3b041 100644
--- a/index.html
+++ b/index.html
@@ -1629,7 +1629,7 @@ <h3>Key types and formats</h3>
<p class="issue">
The Working Group is still debating whether the base encoding format used will
-be Base58 (Bitcoin) [[BASE58]], base64url [[RFC7515]], or base16 (hex)
+be Base58 (Bitcoin) [[?BASE58]], base64url [[RFC7515]], or base16 (hex)
[[RFC4648]]. The entries in the table below currently assume PEM and Base58
(Bitcoin), but might change to base64url and/or base16 (hex) after the group
achieves consensus on this particular issue.
@@ -1680,7 +1680,7 @@ <h3>Key types and formats</h3>
Ed25519 public key values MUST either be encoded as a JWK [[RFC7517]]
using the <code>publicKeyJwk</code> or be
encoded as the raw 32-byte public key value in Base58 Bitcoin format
-[[BASE58]] using the <code>publicKeyBase58</code> property.
+[[?BASE58]] using the <code>publicKeyBase58</code> property.
</td>
</tr>
<tr>
@@ -1691,7 +1691,7 @@ <h3>Key types and formats</h3>
Secp256k1 public key values MUST either be encoded as a JWK [[RFC7517]]
using the <code>publicKeyJwk</code> or be
encoded as the raw 33-byte public key value in Base58
-Bitcoin format [[BASE58]] using the <code>publicKeyBase58</code> property.
+Bitcoin format [[?BASE58]] using the <code>publicKeyBase58</code> property.
</td>
</tr>
<tr>
@@ -1702,7 +1702,7 @@ <h3>Key types and formats</h3>
Curve25519 (also known as X25519) public key values MUST either be encoded
as a JWK [[RFC7517]] using the <code>publicKeyJwk</code> or be
encoded as the raw 32-byte public key value in Base58
-Bitcoin format [[BASE58]] using the <code>publicKeyBase58</code> property.
+Bitcoin format [[?BASE58]] using the <code>publicKeyBase58</code> property.
</td>
</tr>
<tr>
@@ -4712,8 +4712,7 @@ <h2>application/did+json</h2>
<p>
Fragment identifiers used with
<a href="#application-did-json">application/did+json</a> are treated
-according to the rules defined in
-<a data-cite="DID-CORE#fragment">DID Core v1.0, Fragment</a> [[DID-CORE]].
+according to the rules defined in <a href="#fragment"></a>.
</p>
</section>
@@ -4838,8 +4837,7 @@ <h2>application/did+cbor</h2>
<p>
Fragment identifiers used with
<a href="#application-did-json">application/did+cbor</a> are treated
-according to the rules defined in
-<a data-cite="DID-CORE#fragment">DID Core v1.0, Fragment</a> [[DID-CORE]].
+according to the rules defined in <a href="#fragment"></a>.
</p>
</section>
@@ -4899,8 +4897,7 @@ <h2>application/did+dag+cbor</h2>
<p>
Fragment identifiers used with
<a href="#application-did-json">application/did+cbor</a> are treated
-according to the rules defined in
-<a data-cite="DID-CORE#fragment">DID Core v1.0, Fragment</a> [[DID-CORE]].
+according to the rules defined in <a href="#fragment"></a>.
</p>
</section>
From f2faaebc25c2bf06259590fa59a56c62f8efb6df Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Sun, 25 Oct 2020 11:59:47 +0000
Subject: [PATCH 58/89] iana: fix typos in cbor links
---
index.html | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/index.html b/index.html
index e5c3b041..ec945b57 100644
--- a/index.html
+++ b/index.html
@@ -4836,7 +4836,7 @@ <h2>application/did+cbor</h2>
<p>
Fragment identifiers used with
-<a href="#application-did-json">application/did+cbor</a> are treated
+<a href="#application-did-cbor">application/did+cbor</a> are treated
according to the rules defined in <a href="#fragment"></a>.
</p>
</section>
@@ -4896,7 +4896,7 @@ <h2>application/did+dag+cbor</h2>
<p>
Fragment identifiers used with
-<a href="#application-did-json">application/did+cbor</a> are treated
+<a href="#application-did-dag-cbor">application/did+dag+cbor</a> are treated
according to the rules defined in <a href="#fragment"></a>.
</p>
</section>
From d1a398f58058475fb7ca321840d0850877f7179d Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Mon, 26 Oct 2020 12:49:38 +0000
Subject: [PATCH 59/89] privacy: Add privacy concerns about 'type' (and
similar) property.
Per WG resolution at https://www.w3.org/2019/did-wg/Meetings/Minutes/2020-10-06-did#resolution1
---
index.html | 28 ++++++++++++++++++++++++++++
1 file changed, 28 insertions(+)
diff --git a/index.html b/index.html
index ec945b57..8e3ffb96 100644
--- a/index.html
+++ b/index.html
@@ -4269,6 +4269,34 @@ <h2>
</p>
</section>
+ <section>
+ <h2>
+Assigning a type to the DID subject
+ </h2>
+ <p>
+It is dangerous to add properties to the <a>DID document</a> that can be used
+to indicate, explicitly or through inference, what <em>type</em> or nature of
+thing the <a>DID subject</a> is, particularly if the <a>DID subject</a> is a
+person.
+ </p>
+ <p>
+Not only do such properties potentially result in personally identifiable
+information (see
+<a href="#keep-personally-identifiable-information-pii-private"></a>) or
+correlatable data (see <a href="#did-correlation-risks-and-pseudonymous-dids">
+</a> and <a href="#did-document-correlation-risks"></a>) being present in the
+<a>DID document</a>, but they can be used for grouping particular <a>DIDs</a>
+in such a way that they are included in or excluded from certain operations or
+functionalities.
+ </p>
+ <p>
+To minimize these risks, all properties in a <a>DID document</a> should be
+for expressing cryptographic material or verification methods related to
+using the <a>DID</a>.
+ </p>
+
+ </section>
+
<section>
<h2>
Herd Privacy
From 772aabe1e93f4413e33e513cc3d59a782b1712d2 Mon Sep 17 00:00:00 2001
From: Amy Guy <amy@rhiaro.co.uk>
Date: Mon, 2 Nov 2020 12:06:33 +0000
Subject: [PATCH 60/89] Extend 'type' privacy concerns
Co-authored-by: Brent Zundel <brent.zundel@gmail.com>
---
index.html | 13 ++++++++++---
1 file changed, 10 insertions(+), 3 deletions(-)
diff --git a/index.html b/index.html
index 8e3ffb96..dbb757e6 100644
--- a/index.html
+++ b/index.html
@@ -4290,9 +4290,16 @@ <h2>
functionalities.
</p>
<p>
-To minimize these risks, all properties in a <a>DID document</a> should be
-for expressing cryptographic material or verification methods related to
-using the <a>DID</a>.
+Including <em>type</em> information in a <a>DID Document</a> can
+result in personal privacy harms even for <a>DID Subjects</a> that are
+non-person entities, such as IoT devices. The aggregation of such
+information around a <a>DID Controller</a> could serve as a form of
+digital fingerprint and this is best avoided.
+ </p>
+ <p>
+To minimize these risks, all properties in a <a>DID document</a> ought to be
+for expressing cryptographic material, endpoints, or verification methods related
+to using the <a>DID</a>.
</p>
</section>
From 3ba71dfaf3cfcd1a7e0f429753287dac250cc951 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 27 Oct 2020 12:13:01 +0000
Subject: [PATCH 61/89] editorial: Remove closed issues, #403
---
index.html | 33 ---------------------------------
1 file changed, 33 deletions(-)
diff --git a/index.html b/index.html
index dbb757e6..9efdc4a7 100644
--- a/index.html
+++ b/index.html
@@ -2300,12 +2300,6 @@ <h1>Core Representations</h1>
through the content of the <a>DID document</a> alone.
</p>
- <p class="issue" data-number="203">
-This requirement depends on the return of DID document metadata that still needs
-to be defined by this specification. Once defined, that should be linked from
-here.
- </p>
-
<p>
The production and consumption rules in this section apply to all
implementations seeking to be fully compatible with independent implementations
@@ -2315,11 +2309,6 @@ <h1>Core Representations</h1>
for more information.
</p>
- <p class="issue" data-number="207">
-A link to a section on extensibility and conformance as it applies to data
-representations should be added here once that section has been written.
- </p>
-
<section>
<h2>
JSON
@@ -2374,11 +2363,6 @@ <h3>Production</h3>
</li>
</ul>
- <p class="issue" data-number="204">
-An "empty" value is not specified by this document. It seems to imply a null
-value, but this is unclear.
- </p>
-
<p>
Implementers producing JSON are advised to ensure that their algorithms are
aligned with the <a data-cite="INFRA#json">JSON serialization rules</a> in
@@ -2404,14 +2388,6 @@ <h3>
Consumption
</h3>
- <p class="issue" data-number="204">
-In this section and we use the term "property name" to refer to the string that
-represents the property itself, but this specification still needs to define a
-concrete term for such aspects of a property of a DID document. We also need a
-concrete term for "the document itself" as opposed to "the collection or
-properties of the document".
- </p>
-
<p>
The top-level element MUST be a JSON object. Any other data type at the top
level is an error and MUST be rejected. The top-level JSON object represents
@@ -2457,11 +2433,6 @@ <h3>
consumption rules</a> in the [[INFRA]] specification.
</p>
- <p class="issue" data-number="204">
-An "empty" value is not specified by this document. It seems to imply a null
-value, but this is unclear.
- </p>
-
<p>
The value of the <code>@context</code> object member MUST be ignored as this is
reserved for JSON-LD consumers.
@@ -4647,24 +4618,20 @@ <h1>Current Issues</h1>
<div class="issue" data-number="33">Cheap DIDs and the option to migrate DIDs between ledgers using standard DID Deprecation Registries</div>
<div class="issue" data-number="58">Registry handling</div>
<div class="issue" data-number="72">Privacy Considerations - Specifically call out GDPR</div>
- <div class="issue" data-number="94">Create DID explainer</div>
<div class="issue" data-number="104">Horizontal Review: Internationalization self test</div>
<div class="issue" data-number="105">Horizontal Review: Accessibility self test</div>
<div class="issue" data-number="118">Specification needs to be compliant with WCAG 2.0</div>
<div class="issue" data-number="119">Horizontal Review: offer review opportunity to TAG</div>
- <div class="issue" data-number="122">When is a DID subject not a DID controller (if ever)?</div>
<div class="issue" data-number="151">Include discussion of eIDAS levels-of-assurance</div>
<div class="issue" data-number="163">Uses of terms defined in the specification should be links to their definitions</div>
<div class="issue" data-number="170">Public key "id" and "type" members duplicate JWK "kid" and "kty" members</div>
<div class="issue" data-number="174">Underspecified semantics of "updated" property</div>
<div class="issue" data-number="199">Clarification on what DIDs might identify</div>
- <div class="issue" data-number="203">Define DID Document Metadata</div>
<div class="issue" data-number="205">How to treat unknown properties</div>
<div class="issue" data-number="208">IETF did+ld+json media type registration</div>
<div class="issue" data-number="240">Should did-core restrict the use of JWK?</div>
<div class="issue" data-number="249">How to mitigate the single source of failure wrt/ "Trust into the Universal Resolver"?</div>
<div class="issue" data-number="253">Added DID resolution and dereferencing contracts.</div>
- <div class="issue" data-number="261">Definition of the term "client" in regard to SSI principles</div>
<div class="issue" data-number="267">Put key points up front</div>
<div class="issue" data-number="282">Added CBOR section </div>
<div class="issue" data-number="291">PING Horizontal Review</div>
From 69eeffb202bf2e614df5e7aa6f5cc88775fbfc78 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 27 Oct 2020 12:39:38 +0000
Subject: [PATCH 62/89] methods: Remove requirement about name length
We already have registered methods that violate this requirement;
and methods should be free to make their own choices about this.
For https://github.com/w3c/did-core/issues/403
---
index.html | 4 ----
1 file changed, 4 deletions(-)
diff --git a/index.html b/index.html
index 9efdc4a7..181ced12 100644
--- a/index.html
+++ b/index.html
@@ -2962,10 +2962,6 @@ <h2>Method Schemes</h2>
publication.
</p>
- <p>
-The method name SHOULD be five characters or less.
- </p>
-
<div class="note" title="Unique DID method names">
<p>
Because there is no central authority for allocating or approving <a>DID
From f5ba78ce96c64378ba4a0e78389a8c9646701073 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 27 Oct 2020 12:46:23 +0000
Subject: [PATCH 63/89] methods: Remove req for few method-specific-id formats
This should be up to the DID method, doesn't make sense to
constrain it as it is internal to DID method (no affect on
interop); and "as possible" is not testable. See #384"
---
index.html | 4 +---
1 file changed, 1 insertion(+), 3 deletions(-)
diff --git a/index.html b/index.html
index 181ced12..71ab699f 100644
--- a/index.html
+++ b/index.html
@@ -2998,9 +2998,7 @@ <h2>Method Schemes</h2>
<p>
If needed, a method-specific <a>DID scheme</a> MAY define multiple
-<code>method-specific-id</code> formats. It is RECOMMENDED that a
-method-specific <a>DID scheme</a> define as few <code>method-specific-id</code>
-formats as possible.
+<code>method-specific-id</code> formats.
</p>
<p>
From 394513dde10f0ad53887ced52b3bacc2be208e5b Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 27 Oct 2020 19:11:12 +0000
Subject: [PATCH 64/89] references: DID Spec Registries needs to be
informative, not rec-track, #403
---
index.html | 30 +++++++++++++++---------------
1 file changed, 15 insertions(+), 15 deletions(-)
diff --git a/index.html b/index.html
index 71ab699f..5b22721e 100644
--- a/index.html
+++ b/index.html
@@ -925,7 +925,7 @@ <h2>DID Parameters</h2>
Implementers as well as <a>DID method</a> specification authors MAY use
additional DID parameters that are not listed here. For maximum
interoperability, it is RECOMMENDED that DID parameters use the official W3C
-DID Specification Registries mechanism [[DID-SPEC-REGISTRIES]], to avoid
+DID Specification Registries mechanism [[?DID-SPEC-REGISTRIES]], to avoid
collision with other uses of the same DID parameter with different semantics.
</p>
@@ -1178,7 +1178,7 @@ <h2>Extensibility</h2>
<ol>
<li>
For maximum interoperability, it is RECOMMENDED that extensions use the official
-W3C DID Specification Registries mechanism [[DID-SPEC-REGISTRIES]]. The use of
+W3C DID Specification Registries mechanism [[?DID-SPEC-REGISTRIES]]. The use of
this mechanism for new properties or other extensions is the only specified method
that ensures that two different representations will be able to work together.
</li>
@@ -1191,7 +1191,7 @@ <h2>Extensibility</h2>
<p class="note">
It is always possible for two specific implementations to agree out-of-band to
use a mutually understood extension or representation that is not recorded in
-the DID Core Registries [[DID-SPEC-REGISTRIES]]; interoperability between such
+the DID Core Registries [[?DID-SPEC-REGISTRIES]]; interoperability between such
implementations and the larger ecosystem will be less reliable.
</p>
</section>
@@ -1438,7 +1438,7 @@ <h2>Verification Methods</h2>
In order to maximize interoperability, support for public keys as verification
methods is restricted: see <a href="#key-types-and-formats"></a>. For other
types of verification method, the verification method SHOULD be registered in
-the [[DID-SPEC-REGISTRIES]].
+the [[?DID-SPEC-REGISTRIES]].
</p>
<p>
@@ -1484,7 +1484,7 @@ <h2>Verification Methods</h2>
The value of the <code>type</code> property MUST be exactly one verification
method type. In order to maximize global interoperability, the
<a>verification method</a> type SHOULD be registered in the
-[[DID-SPEC-REGISTRIES]].
+[[?DID-SPEC-REGISTRIES]].
</p>
<p>
The value of the <code>controller</code> property MUST be a <a
@@ -1623,7 +1623,7 @@ <h3>Key types and formats</h3>
MUST NOT use any other key format than those listed in the
<a href="#public-key-support">Public Key Support table</a>. For public key
types that are not listed here, the type value and corresponding format
-property SHOULD be registered in [[DID-SPEC-REGISTRIES]], as with any other
+property SHOULD be registered in [[?DID-SPEC-REGISTRIES]], as with any other
verification method.
</p>
@@ -1772,7 +1772,7 @@ <h2>Verification Relationships</h2>
A <a>DID document</a> MAY include a property expressing a specific
<a>verification relationship</a>. In order to maximize global
interoperability, the property SHOULD be registered in
-[[DID-SPEC-REGISTRIES]].
+[[?DID-SPEC-REGISTRIES]].
</p>
<p>
The <a>verification relationship</a> between the <a>DID subject</a> and the
@@ -2546,7 +2546,7 @@ <h3>
<p>
All members of the <code>@context</code> property SHOULD exist in the DID
-specification registries [[DID-SPEC-REGISTRIES]] in order to achieve
+specification registries [[?DID-SPEC-REGISTRIES]] in order to achieve
interoperability across different representations. If a member does not exist
in the DID specification registries, then the <a>DID document</a> might not be
interoperable across representations.
@@ -2557,7 +2557,7 @@ <h3>
<code>@context</code> property results in a document containing
machine-readable information about the context. These URIs SHOULD be
associated with a cryptographic hash of the content of the JSON-LD Context as
-part of registration in the DID Specification Registries [[DID-SPEC-REGISTRIES]].
+part of registration in the DID Specification Registries [[?DID-SPEC-REGISTRIES]].
</p>
</dd>
</dl>
@@ -3356,7 +3356,7 @@ <h3>
<p>
The possible properties within this structure and their possible values are
-defined by [[DID-SPEC-REGISTRIES]]. This specification defines the following
+defined by [[?DID-SPEC-REGISTRIES]]. This specification defines the following
common properties.
</p>
@@ -3383,7 +3383,7 @@ <h3>
<p>
The possible properties within this structure and their possible values are
-defined by [[DID-SPEC-REGISTRIES]]. This specification defines the following
+defined by [[?DID-SPEC-REGISTRIES]]. This specification defines the following
common properties.
</p>
@@ -3409,7 +3409,7 @@ <h3>
The error code from the resolution process. This property is REQUIRED when
there is an error in the resolution process. The value of this property MUST
be a single keyword string. The possible property values of this field SHOULD
-be registered in the DID Specification Registries [[DID-SPEC-REGISTRIES]].
+be registered in the DID Specification Registries [[?DID-SPEC-REGISTRIES]].
This specification defines the following error values:
<dl>
<dt>
@@ -3446,7 +3446,7 @@ <h3>
<p>
The possible properties within this structure and their possible values SHOULD
-be registered in the DID Specification Registries [[DID-SPEC-REGISTRIES]].
+be registered in the DID Specification Registries [[?DID-SPEC-REGISTRIES]].
This specification defines the following common properties.
</p>
@@ -3588,7 +3588,7 @@ <h3>
<p>
The possible properties within this structure and their possible values SHOULD
-be registered in the [[DID-SPEC-REGISTRIES]]. This specification defines the
+be registered in the [[?DID-SPEC-REGISTRIES]]. This specification defines the
following common properties.
</p>
@@ -3612,7 +3612,7 @@ <h3>
<p>
The possible properties within this structure and their possible values are
-defined by [[DID-SPEC-REGISTRIES]]. This specification defines the following
+defined by [[?DID-SPEC-REGISTRIES]]. This specification defines the following
common properties.
</p>
From 3151f339d49d6093ff7ca27d408a39e9d092d9de Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 27 Oct 2020 19:48:57 +0000
Subject: [PATCH 65/89] editorial: Clarify that id is only for DID subject when
at top level of DID doc; #401
---
index.html | 20 +++++++++++++++-----
1 file changed, 15 insertions(+), 5 deletions(-)
diff --git a/index.html b/index.html
index 5b22721e..f14ccfd9 100644
--- a/index.html
+++ b/index.html
@@ -1267,14 +1267,15 @@ <h1>Core Properties</h1>
<h2>DID Subject</h2>
<p>
-The <a>DID subject</a> is denoted with the <code><a>id</a></code> property. The
-<a>DID subject</a> is the entity that the <a>DID document</a> is about. That is,
-it is the entity identified by the <a>DID</a> and described by the
-<a>DID document</a>.
+The <a>DID subject</a> is denoted with the <code><a>id</a></code> property at
+the top level of a <a>DID document</a>. The <a>DID subject</a> is the entity
+that the <a>DID document</a> is about. That is, it is the entity identified by
+the <a>DID</a> and described by the <a>DID document</a>.
</p>
<p>
-<a>DID documents</a> MUST include the <code><a>id</a></code> property.
+<a>DID documents</a> MUST include the <code><a>id</a></code> property at the
+top level.
</p>
<dl>
@@ -1304,6 +1305,15 @@ <h2>DID Subject</h2>
party going forward.
</p>
+ <p class="note" title="Nested objects with the id property">
+A <a>DID document</a> can contain objects which have their own unique
+identifier; see, for example, <a href="#verification-methods"></a>. Such other
+objects also use the <code>id</code> property to denote the identifier of
+the object in question. The <code>id</code> property only denotes the
+<a>DID</a> of the <a>DID subject</a> when it is present at the <em>top
+level</em> of a <a>DID document</a>.
+ </p>
+
<section>
<h3>alsoKnownAs</h3>
From 43bbcdaf88ff3f72c608132b1a332ed62a0edbf9 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 27 Oct 2020 21:54:34 +0000
Subject: [PATCH 66/89] verification relationships: Condense sections, reduce
reptition, improve readability
---
index.html | 370 +++++++++++++++++++----------------------------------
1 file changed, 133 insertions(+), 237 deletions(-)
diff --git a/index.html b/index.html
index f14ccfd9..9cfaa4f7 100644
--- a/index.html
+++ b/index.html
@@ -1779,34 +1779,45 @@ <h2>Verification Relationships</h2>
<a>DID subject</a> and a <a>verification method</a>.
</p>
<p>
-A <a>DID document</a> MAY include a property expressing a specific
-<a>verification relationship</a>. In order to maximize global
-interoperability, the property SHOULD be registered in
-[[?DID-SPEC-REGISTRIES]].
+Different <a>verification relationships</a> enable the associated
+<a>verification methods</a> to be used for different purposes. It is up to a
+<em>verifier</em> to ascertain the validity of a verification attempt by
+checking that the <a>verification method</a> used is contained in the
+appropriate <a>verification relationship</a> property of the <a>DID
+Document</a>.
</p>
<p>
The <a>verification relationship</a> between the <a>DID subject</a> and the
<a>verification method</a> MUST be explicit in the <a>DID document</a>.
<a>Verification methods</a> that are not associated with a particular
<a>verification relationship</a> MUST NOT be used for that <a>verification
-relationship</a>. See the sections below for more detailed examples of a
-<a>verification relationship</a>.
+relationship</a>. For example, a <a>verification method</a> in the value of
+the <code><a>authentication</a></code> property cannot be used to engage in
+key agreement protocols with the <a>DID subject</a>—the value of the
+<code><a>keyAgreement</a></code> property needs to be used for that.
+ </p>
+ <p>
+This specification defines several <a>verification relationships</a> below. A
+<a>DID document</a> MAY include any of these, or other properties, to express
+a specific <a>verification relationship</a>. In order to maximize global
+interoperability, any such properties used SHOULD be registered in
+[[DID-SPEC-REGISTRIES]].
</p>
- <section>
- <h3>authentication</h3>
+ <dl>
+ <dt><dfn>authentication</dfn></dt>
+ <dd>
+The <code>authentication</code> property is OPTIONAL.
+ </dd>
+ <dd>
+If present, the associated value MUST be an <a
+data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
+methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
+ </dd>
+ </dl>
+ <div class="note" title="Uses of authentication">
<p>
-Authentication is a <a>verification relationship</a> which an entity can use
-to prove it is the <a>DID subject</a> or acting on behalf of the
-<a>DID Subject</a> as a <a>DID Controller</a>. The <em>verifier</em> of an
-authentication attempt can check if the authenticating party is presenting a
-valid proof of authentication, that is, that they are who they say they are.
-Note that a successful authentication on its own might or might not confer
-authority; that is up to the verifying application.
- </p>
-
- <p class="note" title="Uses of authentication">
If authentication is established, it is up to the <a>DID method</a> or other
application to decide what to do with that information. A particular <a>DID
method</a> could decide that authenticating as a <a>DID controller</a> is
@@ -1818,27 +1829,8 @@ <h3>authentication</h3>
model, but <a>DID methods</a> and applications are expected to define this
themselves.
</p>
-
- <p>
-A <a>DID document</a> MAY include an <code><a>authentication</a></code> property.
-The <code><a>authentication</a></code> property is a relationship between the <a>DID
-subject</a> and a set of verification methods (such as, but not limited to,
-public keys). It means that the <a>DID subject</a> has authorized some set of
-<a>verification methods</a> (per the value of the <code><a>authentication</a></code>
-property) for the purpose of authentication.
- </p>
-
- <dl>
- <dt><dfn>authentication</dfn></dt>
- <dd>
-The associated value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a>
-of one or more <a>verification methods</a>. Each <a>verification method</a> MAY
-be embedded or referenced.
- </dd>
- </dl>
-
<p>
-This statement is useful to any <em>authentication verifier</em> that needs
+This is useful to any <em>authentication verifier</em> that needs
to check to see if an entity that is attempting to <a>authenticate</a> is, in
fact, presenting a valid proof of authentication. When a <em>verifier</em>
receives some data (in some protocol-specific format) that contains a proof
@@ -1848,23 +1840,18 @@ <h3>authentication</h3>
public key) listed under <code><a>authentication</a></code> in the
<a>DID Document</a>.
</p>
-
- <p>
-The <a>verification method</a> indicated by the <code><a>authentication</a></code>
-property of a <a>DID document</a> can only be used to <a>authenticate</a> the
-<a>DID subject</a>. To <a>authenticate</a> the <a>DID controller</a> (in cases
-where the <a>DID controller</a> is not <em>also</em> the <a>DID subject</a>)
-the entity associated with the value of <code>controller</code> (see
-Section <a href="#control"></a>) needs to <a>authenticate</a> itself with its
-<em>own</em> <a>DID document</a> and attached <code><a>authentication</a></code>
-<a>verification relationship</a>.
- </p>
-
<p>
-Example:
+Note that the <a>verification method</a> indicated by the
+<code><a>authentication</a></code> property of a <a>DID document</a> can only
+be used to <a>authenticate</a> the <a>DID subject</a>. To <a>authenticate</a>
+a different <a>DID controller</a> the entity associated with the value of
+<code>controller</code> (see Section <a href="#control"></a>) needs to
+<a>authenticate</a> with its <em>own</em> <a>DID document</a> and attached
+<code><a>authentication</a></code> <a>verification relationship</a>.
</p>
+ </div>
- <pre class="example nohighlight" title="Authentication property
+ <pre class="example nohighlight" title="Authentication property
containing three verification methods">
{
"@context": "https://www.w3.org/ns/did/v1",
@@ -1887,118 +1874,73 @@ <h3>authentication</h3>
],
<span class="comment">...</span>
}
- </pre>
- </section>
+ </pre>
- <section>
- <h3>assertionMethod</h3>
- <p>
-The <code><a>assertionMethod</a></code> property is used to express a
-<a>verification relationship</a> which indicates that a <a>verification
-method</a> can be used to verify a proof that a statement was
-asserted on behalf of the <a>DID subject</a>. A <em>verifier</em>
-of such a proof can ensure that a <a>verification method</a> used
-with the proof was authorized to be used with proofs for that purpose
-by checking that the <a>verification method</a> is contained in the
-<code><a>assertionMethod</a></code> of the <a>DID Document</a>.
- </p>
+ <dl>
+ <dt><dfn>assertionMethod</dfn></dt>
+ <dd>
+The <code>assertionMethod</code> property is OPTIONAL.
+ </dd>
+ <dd>
+If present, the associated value MUST be an <a
+data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
+methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
+ </dd>
+ </dl>
- <p class="note" title="Uses of assertionMethod">
-If <code><a>assertionMethod</a></code> is established, it is up to the
-verifier to validate that the <a>verification method</a> used for providing
-proof of an assertion is valid and is associated with the
-<code><a>assertionMethod</a></code> <a>verification relationship</a>. An
-example of when this property is useful is during the processing of a
+ <p class="note" title="Uses of assertionMethod">
+An example of when this property is useful is during the processing of a
verifiable credential by a verifier. During validation, a verifier checks to
see if a verifiable credential has been signed by the <a>DID Subject</a> by
checking that the <a>verification method</a> used to assert the proof is
associated with the <code><a>assertionMethod</a></code> property in the
corresponding <a>DID Document</a>.
- </p>
-
- <p>
-A <a>DID document</a> MAY include an <code><a>assertionMethod</a></code> property.
- </p>
-
- <dl>
- <dt><dfn>assertionMethod</dfn></dt>
- <dd>
-The associated value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a>
-of one or more <a>verification methods</a>. Each <a>verification method</a> MAY
-be embedded or referenced.
- </dd>
- </dl>
-
- <p>
-Example:
- </p>
+ </p>
- <pre class="example nohighlight" title="Assertion method property
- containing two verification methods">
+ <pre class="example nohighlight" title="Assertion method property
+ containing two verification methods">
{
- "@context": "https://www.w3.org/ns/did/v1",
- "id": "did:example:123456789abcdefghi",
- <span class="comment">...</span>
- "assertionMethod": [
- <span class="comment">// this method can be used to assert statements as did:...fghi</span>
- "did:example:123456789abcdefghi#keys-1",
- <span class="comment">// this method is *only* authorized for assertion of statements, it may not</span>
- <span class="comment">// be used for any other verification relationship, so its full description is</span>
- <span class="comment">// embedded here rather than using only a reference</span>
- {
- "id": "did:example:123456789abcdefghi#keys-2",
- "type": "Ed25519VerificationKey2018",
- "controller": "did:example:123456789abcdefghi",
- "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
- }
- ],
- <span class="comment">...</span>
+"@context": "https://www.w3.org/ns/did/v1",
+"id": "did:example:123456789abcdefghi",
+<span class="comment">...</span>
+"assertionMethod": [
+ <span class="comment">// this method can be used to assert statements as did:...fghi</span>
+ "did:example:123456789abcdefghi#keys-1",
+ <span class="comment">// this method is *only* authorized for assertion of statements, it may not</span>
+ <span class="comment">// be used for any other verification relationship, so its full description is</span>
+ <span class="comment">// embedded here rather than using only a reference</span>
+ {
+ "id": "did:example:123456789abcdefghi#keys-2",
+ "type": "Ed25519VerificationKey2018",
+ "controller": "did:example:123456789abcdefghi",
+ "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
+ }
+],
+<span class="comment">...</span>
}
- </pre>
- </section>
-
- <section>
- <h3>keyAgreement</h3>
- <p>
-The <code><a>keyAgreement</a></code> property is used to express a <a>verification
-relationship</a> which an entity can use to engage in key agreement protocols
-on behalf of the <a>DID subject</a>. The <em>counterparties</em> in a key
-agreement protocol can use the <code><a>keyAgreement</a></code> <a>verification
-relationship</a> to check whether a party performing a key agreement protocol
-on behalf of the <a>DID subject</a> is authorized by checking if the
-<a>verification method</a> used during the key agreement protocol is
-associated with the <code><a>keyAgreement</a></code> property contained in the <a>DID
-Document</a>.
- </p>
-
- <p>
-A <a>DID document</a> MAY include an <code><a>keyAgreement</a></code> property.
- </p>
-
- <dl>
- <dt><dfn>keyAgreement</dfn></dt>
- <dd>
-The associated value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a>
-of one or more <a>verification methods</a>. Each <a>verification method</a> MAY
-be embedded or referenced.
- </dd>
- </dl>
+ </pre>
- <p class="note" title="Uses of keyAgreement">
-It is up to a verifier to validate that the <a>verification method</a>
-used during a key agreement exchange is valid and is associated with the
-<code><a>keyAgreement</a></code> property. An example of when this property is useful
-is during the establishment of a TLS session on behalf of the <a>DID
-Subject</a>. In this case, the counterparty checks that the <a>verification
-method</a> used during the protocol handshake is associated with the
-<code><a>keyAgreement</a></code> property in the <a>DID Document</a>.
- </p>
+ <dl>
+ <dt><dfn>keyAgreement</dfn></dt>
+ <dd>
+The <code>keyAgreement</code> property is OPTIONAL.
+ </dd>
+ <dd>
+If present, the associated value MUST be an <a
+data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
+methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
+ </dd>
+ </dl>
- <p>
-Example:
- </p>
+ <p class="note" title="Uses of keyAgreement">
+An example of when this property is useful is during the establishment of a
+TLS session on behalf of the <a>DID Subject</a>. In this case, the
+counterparty checks that the <a>verification method</a> used during the
+protocol handshake is associated with the <code><a>keyAgreement</a></code>
+property in the <a>DID Document</a>.
+ </p>
- <pre class="example nohighlight" title="Key agreement property
+ <pre class="example nohighlight" title="Key agreement property
containing two verification methods">
{
"@context": "https://www.w3.org/ns/did/v1",
@@ -2020,53 +1962,30 @@ <h3>keyAgreement</h3>
<span class="comment">...</span>
}
- </pre>
- </section>
-
- <section>
- <h3>capabilityInvocation</h3>
- <p>
-The <code><a>capabilityInvocation</a></code> property is used to express a
-<a>verification relationship</a> which an entity can use to invoke
-capabilities as the <a>DID subject</a> or on behalf of the <a>DID subject</a>.
-A capability is an expression of an action that the <a>DID subject</a> is
-authorized to take. The <em>verifier</em> of a capability invocation attempt
-can check the validity of a capability by checking if the <a>verification
-method</a> used with the proof is contained in the
-<code><a>capabilityInvocation</a></code> property of the <a>DID Document</a>.
- </p>
-
- <p>
-A <a>DID document</a> MAY include an <code><a>capabilityInvocation</a></code>
-property.
- </p>
+ </pre>
- <dl>
- <dt><dfn>capabilityInvocation</dfn></dt>
- <dd>
-The associated value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a>
-of one or more <a>verification methods</a>. Each <a>verification method</a> MAY
-be embedded or referenced.
- </dd>
- </dl>
+ <dl>
+ <dt><dfn>capabilityInvocation</dfn></dt>
+ <dd>
+The <code>capabilityInvocation</code> property is OPTIONAL.
+ </dd>
+ <dd>
+If present, the associated value MUST be an <a
+data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
+methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
+ </dd>
+ </dl>
- <p class="note" title="Uses of capabilityInvocation">
-It is the responsibility of a verifier to ensure that the
-<a>verification method</a> used when presenting a capability is invoked and is
-associated with the <code><a>capabilityInvocation</a></code> property. An example of
-when this property is useful is when a <a>DID subject</a> chooses to invoke
-their capability to start a vehicle through the combined usage of a
-<a>verification method</a> and the <code>StartCar</code> capability. In this
-example, the vehicle would be the <em>verifier</em> and would need to verify
-that the <a>verification method</a> exists in the
+ <p class="note" title="Uses of capabilityInvocation">
+An example of when this property is useful is when a <a>DID subject</a>
+chooses to invoke their capability to start a vehicle through the combined
+usage of a <a>verification method</a> and the <code>StartCar</code>
+capability. In this example, the vehicle would be the <em>verifier</em> and
+would need to verify that the <a>verification method</a> exists in the
<code><a>capabilityInvocation</a></code> property.
- </p>
-
- <p>
-Example:
- </p>
+ </p>
- <pre class="example nohighlight" title="Capability invocation property
+ <pre class="example nohighlight" title="Capability invocation property
containing two verification methods">
{
"@context": "https://www.w3.org/ns/did/v1", "id":
@@ -2088,50 +2007,28 @@ <h3>capabilityInvocation</h3>
<span class="comment">...</span>
}
- </pre>
- </section>
-
- <section>
- <h3>capabilityDelegation</h3>
- <p>
-The <code><a>capabilityDelegation</a></code> property is used to express a
-<a>verification relationship</a> which an entity can use to grant capabilities
-as the <a>DID subject</a> or on behalf of the <a>DID subject</a> to other
-<em>capability invokers</em>. The <em>verifier</em> of a
-<code><a>capabilityDelegation</a></code> attempt can check the validity of a
-capability to grant invocation of a capability by checking if the
-<a>verification method</a> used with the proof is contained in the
-<code><a>capabilityDelegation</a></code> section of the <a>DID Document</a>.
- </p>
-
- <p>
-A <a>DID document</a> MAY include an <code><a>capabilityDelegation</a></code>
-property.
- </p>
-
- <dl>
- <dt><dfn>capabilityDelegation</dfn></dt>
- <dd>
-The associated value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a>
-of one or more <a>verification methods</a>. Each <a>verification method</a> MAY
-be embedded or referenced.
- </dd>
- </dl>
+ </pre>
- <p class="note" title="Uses of capabilityDelegation">
-It is up to a verifier to validate that the <a>verification method</a> used
-when presenting a capability is valid and is associated with the
-<code><a>capabilityDelegation</a></code> property. An example of when this
-property is useful is when a <a>DID Subject</a> chooses to grant their
-capability to start a vehicle through the combined usage of a <a>verification
-method</a> and the <code>StartCar</code> capability to a capability invoker.
- </p>
+ <dl>
+ <dt><dfn>capabilityDelegation</dfn></dt>
+ <dd>
+The <code>capabilityDelegation</code> property is OPTIONAL.
+ </dd>
+ <dd>
+If present, the associated value MUST be an <a
+data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
+methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
+ </dd>
+ </dl>
- <p>
-Example:
- </p>
+ <p class="note" title="Uses of capabilityDelegation">
+An example of when this property is useful is when a <a>DID Subject</a>
+chooses to grant their capability to start a vehicle through the combined
+usage of a <a>verification method</a> and the <code>StartCar</code> capability
+to a capability invoker.
+ </p>
- <pre class="example nohighlight" title="Capability Delegation property
+ <pre class="example nohighlight" title="Capability Delegation property
containing two verification methods">
{
"@context": "https://www.w3.org/ns/did/v1", "id":
@@ -2153,8 +2050,7 @@ <h3>capabilityDelegation</h3>
<span class="comment">...</span>
}
- </pre>
- </section>
+ </pre>
</section>
<section>
From 7bec1858d147157cc89c5e5efabb7ce53f3fd223 Mon Sep 17 00:00:00 2001
From: Amy Guy <amy@rhiaro.co.uk>
Date: Mon, 2 Nov 2020 12:07:18 +0000
Subject: [PATCH 67/89] Fix grammar
Co-authored-by: Brent Zundel <brent.zundel@gmail.com>
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index 9cfaa4f7..9ecffee7 100644
--- a/index.html
+++ b/index.html
@@ -1844,7 +1844,7 @@ <h2>Verification Relationships</h2>
Note that the <a>verification method</a> indicated by the
<code><a>authentication</a></code> property of a <a>DID document</a> can only
be used to <a>authenticate</a> the <a>DID subject</a>. To <a>authenticate</a>
-a different <a>DID controller</a> the entity associated with the value of
+a different <a>DID controller</a>, the entity associated with the value of
<code>controller</code> (see Section <a href="#control"></a>) needs to
<a>authenticate</a> with its <em>own</em> <a>DID document</a> and attached
<code><a>authentication</a></code> <a>verification relationship</a>.
From 65302fbd9abcce0b3842537f2dce3671d9f2914d Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 12:18:13 -0500
Subject: [PATCH 68/89] Fix ReSpec configuration.
---
index.html | 47 ++++++++++++++++++++++-------------------------
1 file changed, 22 insertions(+), 25 deletions(-)
diff --git a/index.html b/index.html
index 9ecffee7..721b6a25 100644
--- a/index.html
+++ b/index.html
@@ -11,39 +11,39 @@
offline.
-->
- <script class='remove'
- src='https://www.w3.org/Tools/respec/respec-w3c'>
- </script><!--script src='./respec-w3c-common.js' class='remove'></script-->
-
- <script src="https://unpkg.com/reqlist/lib/reqlist.js" class="remove"></script>
- <link href="https://unpkg.com/reqlist/lib/reqlist.css" class="removeOnSave" rel="stylesheet" type="text/css" />
-
- <script class='remove' src="./common.js">
- </script>
+ <script class="remove"
+ src="https://www.w3.org/Tools/respec/respec-w3c"></script>
+ <script class="remove"
+ src="https://unpkg.com/reqlist/lib/reqlist.js"></script>
+ <link class="removeOnSave" rel="stylesheet" type="text/css"
+ href="https://unpkg.com/reqlist/lib/reqlist.css" />
+
+ <script class='remove' src="./common.js"></script>
<script class="remove" type="text/javascript">
var respecConfig = {
- wgPublicList: "public-did-wg",
+ // the W3C WG and public mailing list
group: "did",
-
- // specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
- specStatus: "WD",
+ wgPublicList: "public-did-wg",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "did-core",
+ // specification status (e.g., WD, LCWD, NOTE, etc.). If in doubt use ED.
+ specStatus: "WD",
+ // Editor's Draft URL
edDraftURI: "https://w3c.github.io/did-core/",
- // subtitle
+ // subtitle for the spec
subtitle: "Core architecture, data model, and representations",
// if you wish the publication date to be other than today, set this
//publishDate: "2019-11-07",
- // if there is a previously published draft, uncomment this and set its
+ // previously published draft, uncomment this and set its
// YYYY-MM-DD date and its maturity status
- previousPublishDate: "2020-07-31",
- previousMaturity: "WD",
+ //previousPublishDate: "2020-07-31",
+ //previousMaturity: "WD",
// automatically allow term pluralization
pluralize: true,
@@ -52,8 +52,8 @@
localBiblio: ccg.localBiblio,
xref: "web-platform",
github: {
- repoURL: "https://github.com/w3c/did-core/",
- branch: "master"
+ repoURL: "https://github.com/w3c/did-core/",
+ branch: "master"
},
includePermalinks: false,
@@ -67,8 +67,7 @@
// ],
- // editors, add as many as you like
- // only "name" is required
+ // list of specification editors
editors: [{
name: "Drummond Reed",
url: "https://www.linkedin.com/in/drummondreed/",
@@ -92,9 +91,7 @@
}
],
- // authors, add as many as you like.
- // This is optional, uncomment if you have authors as well as editors.
- // only "name" is required. Same format as editors.
+ // list of specification authors
authors: [{
name: "Drummond Reed",
url: "https://www.linkedin.com/in/drummondreed/",
@@ -111,7 +108,7 @@
},
{
name: "Dave Longley",
- url: "",
+ url: "https://github.com/dlongley",
company: "Digital Bazaar",
companyURL: "https://digitalbazaar.com/",
w3cid: 48025
From 1e7bef857dc919273ccb519849822beeddb25419 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 12:22:59 -0500
Subject: [PATCH 69/89] Fix paragraph boundaries in Abstract.
---
index.html | 33 ++++++++++++++++-----------------
1 file changed, 16 insertions(+), 17 deletions(-)
diff --git a/index.html b/index.html
index 721b6a25..dd51e23a 100644
--- a/index.html
+++ b/index.html
@@ -66,7 +66,6 @@
// add_reqlist_button
// ],
-
// list of specification editors
editors: [{
name: "Drummond Reed",
@@ -171,23 +170,23 @@
<a>Decentralized identifiers</a> (DIDs) are a new type of identifier that
enables verifiable, decentralized digital identity. A <a>DID</a> identifies any
subject (e.g., a person, organization, thing, data model, abstract entity, etc.)
-that the controller of the <a>DID</a> decides that it identifies.
-
-In contrast to typical, federated identifiers, DIDs have been designed
-so that they may be decoupled from centralized registries, identity providers,
-and certificate authorities. Specifically, while other parties might be used
-to help enable the discovery of information related to a <a>DID</a>,
-the design enables the controller of a <a>DID</a> to prove control over it
-without requiring permission from any other party.
-
-<a>DID</a>s are URIs that associate a <a>DID subject</a> with a <a>DID
-document</a> allowing trustable interactions associated with that subject.
+that the controller of the <a>DID</a> decides that it identifies. In contrast to
+typical, federated identifiers, DIDs have been designed so that they may be
+decoupled from centralized registries, identity providers, and certificate
+authorities. Specifically, while other parties might be used to help enable the
+discovery of information related to a <a>DID</a>, the design enables the
+controller of a <a>DID</a> to prove control over it without requiring permission
+from any other party. <a>DID</a>s are URIs that associate a <a>DID subject</a>
+with a <a>DID document</a> allowing trustable interactions associated with that
+subject.
+ </p>
+ <p>
Each <a>DID document</a> can express cryptographic material, verification
-methods, or <a>service endpoints</a>, which provide a set of mechanisms
-enabling a <a>DID controller</a> to prove control of the <a>DID</a>.
-<a>Service endpoints</a> enable trusted interactions associated with the
-<a>DID subject</a>. A <a>DID document</a> might contain the <a>DID subject</a>
-itself, if the <a>DID subject</a> is an information resource such as a data model.
+methods, or <a>service endpoints</a>, which provide a set of mechanisms enabling
+a <a>DID controller</a> to prove control of the <a>DID</a>. <a>Service
+endpoints</a> enable trusted interactions associated with the <a>DID
+subject</a>. A <a>DID document</a> might contain the <a>DID subject</a> itself,
+if the <a>DID subject</a> is an information resource such as a data model.
</p>
<p>
This document specifies a common data model, a URL format, and a set of
From d2b367b52cc86d19e354ff2a2d9ac3c86a4a72f7 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 12:31:35 -0500
Subject: [PATCH 70/89] Add subsection for Authentication.
---
index.html | 50 +++++++++++++++++++++++++++++---------------------
1 file changed, 29 insertions(+), 21 deletions(-)
diff --git a/index.html b/index.html
index dd51e23a..ff5cc1b6 100644
--- a/index.html
+++ b/index.html
@@ -1800,20 +1800,27 @@ <h2>Verification Relationships</h2>
[[DID-SPEC-REGISTRIES]].
</p>
- <dl>
- <dt><dfn>authentication</dfn></dt>
- <dd>
-The <code>authentication</code> property is OPTIONAL.
- </dd>
- <dd>
-If present, the associated value MUST be an <a
-data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
-methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
- </dd>
- </dl>
+ <section>
+ <h2>Authentication</h2>
- <div class="note" title="Uses of authentication">
<p>
+The `authentication` <a>verification relationship</a> is used to specify how the
+<a>DID subject</a> is expected to be authenticated, such as for the purposes of
+logging into a website.
+ </p>
+
+ <dl>
+ <dt><dfn>authentication</dfn></dt>
+ <dd>
+The <code>authentication</code> property is OPTIONAL. If present, the associated
+value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a> of one or more
+<a>verification methods</a>. Each <a>verification method</a> MAY be embedded or
+referenced.
+ </dd>
+ </dl>
+
+ <div class="note" title="Uses of authentication">
+ <p>
If authentication is established, it is up to the <a>DID method</a> or other
application to decide what to do with that information. A particular <a>DID
method</a> could decide that authenticating as a <a>DID controller</a> is
@@ -1824,8 +1831,8 @@ <h2>Verification Relationships</h2>
<em>after</em> the authentication check is out of scope for the DID data
model, but <a>DID methods</a> and applications are expected to define this
themselves.
- </p>
- <p>
+ </p>
+ <p>
This is useful to any <em>authentication verifier</em> that needs
to check to see if an entity that is attempting to <a>authenticate</a> is, in
fact, presenting a valid proof of authentication. When a <em>verifier</em>
@@ -1835,8 +1842,8 @@ <h2>Verification Relationships</h2>
ensure that the proof can be verified using a <a>verification method</a> (e.g.,
public key) listed under <code><a>authentication</a></code> in the
<a>DID Document</a>.
- </p>
- <p>
+ </p>
+ <p>
Note that the <a>verification method</a> indicated by the
<code><a>authentication</a></code> property of a <a>DID document</a> can only
be used to <a>authenticate</a> the <a>DID subject</a>. To <a>authenticate</a>
@@ -1844,11 +1851,11 @@ <h2>Verification Relationships</h2>
<code>controller</code> (see Section <a href="#control"></a>) needs to
<a>authenticate</a> with its <em>own</em> <a>DID document</a> and attached
<code><a>authentication</a></code> <a>verification relationship</a>.
- </p>
- </div>
+ </p>
+ </div>
- <pre class="example nohighlight" title="Authentication property
- containing three verification methods">
+ <pre class="example nohighlight" title="Authentication property
+ containing three verification methods">
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:example:123456789abcdefghi",
@@ -1870,7 +1877,8 @@ <h2>Verification Relationships</h2>
],
<span class="comment">...</span>
}
- </pre>
+ </pre>
+ </section>
<dl>
<dt><dfn>assertionMethod</dfn></dt>
From e228df1acb393b2bca3f14cb954596c8726a6ffc Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 12:58:29 -0500
Subject: [PATCH 71/89] Add subsection for Assertion Method.
---
index.html | 40 ++++++++++++++++++++++++----------------
1 file changed, 24 insertions(+), 16 deletions(-)
diff --git a/index.html b/index.html
index ff5cc1b6..e2057353 100644
--- a/index.html
+++ b/index.html
@@ -1880,29 +1880,36 @@ <h2>Authentication</h2>
</pre>
</section>
- <dl>
- <dt><dfn>assertionMethod</dfn></dt>
- <dd>
-The <code>assertionMethod</code> property is OPTIONAL.
- </dd>
- <dd>
-If present, the associated value MUST be an <a
-data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
-methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
- </dd>
- </dl>
+ <section>
+ <h2>Assertion Method</h2>
+
+ <p>
+The `assertionMethod` <a>verification relationship</a> is used to specify how
+the <a>DID subject</a> is expected to express claims, such as for the purposes
+of issuing a Verifiable Credential [[?VC-DATA-MODEL]].
+ </p>
- <p class="note" title="Uses of assertionMethod">
+ <dl>
+ <dt><dfn>assertionMethod</dfn></dt>
+ <dd>
+The <code>assertionMethod</code> property is OPTIONAL. If present, the
+associated value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a> of
+one or more <a>verification methods</a>. Each <a>verification method</a> MAY be
+embedded or referenced.
+ </dd>
+ </dl>
+
+ <p>
An example of when this property is useful is during the processing of a
verifiable credential by a verifier. During validation, a verifier checks to
see if a verifiable credential has been signed by the <a>DID Subject</a> by
checking that the <a>verification method</a> used to assert the proof is
associated with the <code><a>assertionMethod</a></code> property in the
corresponding <a>DID Document</a>.
- </p>
+ </p>
- <pre class="example nohighlight" title="Assertion method property
- containing two verification methods">
+ <pre class="example nohighlight" title="Assertion method property
+ containing two verification methods">
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:example:123456789abcdefghi",
@@ -1922,7 +1929,8 @@ <h2>Authentication</h2>
],
<span class="comment">...</span>
}
- </pre>
+ </pre>
+ </section>
<dl>
<dt><dfn>keyAgreement</dfn></dt>
From 2d7973e4b87b89d8250516d72073fe12855754ab Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 13:07:46 -0500
Subject: [PATCH 72/89] Add subsection for Key Agreement.
---
index.html | 50 ++++++++++++++++++++++++++++----------------------
1 file changed, 28 insertions(+), 22 deletions(-)
diff --git a/index.html b/index.html
index e2057353..cb9d235a 100644
--- a/index.html
+++ b/index.html
@@ -1932,28 +1932,34 @@ <h2>Assertion Method</h2>
</pre>
</section>
- <dl>
- <dt><dfn>keyAgreement</dfn></dt>
- <dd>
-The <code>keyAgreement</code> property is OPTIONAL.
- </dd>
- <dd>
-If present, the associated value MUST be an <a
-data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
-methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
- </dd>
- </dl>
+ <section>
+ <h2>Key Agreement</h2>
- <p class="note" title="Uses of keyAgreement">
-An example of when this property is useful is during the establishment of a
-TLS session on behalf of the <a>DID Subject</a>. In this case, the
-counterparty checks that the <a>verification method</a> used during the
-protocol handshake is associated with the <code><a>keyAgreement</a></code>
-property in the <a>DID Document</a>.
- </p>
+ <p>
+The `keyAgreement` <a>verification relationship</a> is used to specify how
+to encrypt information to the <a>DID subject</a>, such as for the purposes
+of establishing a secure communication channel with the recipient.
+ </p>
- <pre class="example nohighlight" title="Key agreement property
- containing two verification methods">
+ <dl>
+ <dt><dfn>keyAgreement</dfn></dt>
+ <dd>
+The <code>keyAgreement</code> property is OPTIONAL. If present, the associated
+value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a> of one or more
+<a>verification methods</a>. Each <a>verification method</a> MAY be embedded or
+referenced.
+ </dd>
+ </dl>
+
+ <p>
+An example of when this property is useful is when encrypting a message
+intended for the <a>DID Subject</a>. In this case, the counterparty uses the
+public cryptographic key information in the <a>verification method</a>
+to wrap a decryption key for the recipient.
+ </p>
+
+ <pre class="example nohighlight" title="Key agreement property
+ containing two verification methods">
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:example:123456789abcdefghi",
@@ -1973,8 +1979,8 @@ <h2>Assertion Method</h2>
],
<span class="comment">...</span>
}
-
- </pre>
+ </pre>
+ </section>
<dl>
<dt><dfn>capabilityInvocation</dfn></dt>
From 4a660663b783f7c07830c8eea9867b1e9bb90f00 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 13:14:26 -0500
Subject: [PATCH 73/89] Add Capability Invocation section.
---
index.html | 41 ++++++++++++++++++++++++-----------------
1 file changed, 24 insertions(+), 17 deletions(-)
diff --git a/index.html b/index.html
index cb9d235a..de62ea7c 100644
--- a/index.html
+++ b/index.html
@@ -1982,29 +1982,36 @@ <h2>Key Agreement</h2>
</pre>
</section>
- <dl>
- <dt><dfn>capabilityInvocation</dfn></dt>
- <dd>
-The <code>capabilityInvocation</code> property is OPTIONAL.
- </dd>
- <dd>
-If present, the associated value MUST be an <a
-data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
-methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
- </dd>
- </dl>
+ <section>
+ <h2>Capability Invocation</h2>
+
+ <p>
+The `capabilityInvocation` <a>verification relationship</a> is used to specify
+a mechanism that might be used by the <a>DID subject</a> to invoke a
+cryptographic capability, such as the authorization to access an HTTP API.
+ </p>
+
+ <dl>
+ <dt><dfn>capabilityInvocation</dfn></dt>
+ <dd>
+The <code>capabilityInvocation</code> property is OPTIONAL. If present, the
+associated value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a> of
+one or more <a>verification methods</a>. Each <a>verification method</a> MAY be
+embedded or referenced.
+ </dd>
+ </dl>
- <p class="note" title="Uses of capabilityInvocation">
+ <p>
An example of when this property is useful is when a <a>DID subject</a>
chooses to invoke their capability to start a vehicle through the combined
usage of a <a>verification method</a> and the <code>StartCar</code>
capability. In this example, the vehicle would be the <em>verifier</em> and
would need to verify that the <a>verification method</a> exists in the
<code><a>capabilityInvocation</a></code> property.
- </p>
+ </p>
- <pre class="example nohighlight" title="Capability invocation property
- containing two verification methods">
+ <pre class="example nohighlight" title="Capability invocation property
+ containing two verification methods">
{
"@context": "https://www.w3.org/ns/did/v1", "id":
"did:example:123456789abcdefghi",
@@ -2024,8 +2031,8 @@ <h2>Key Agreement</h2>
],
<span class="comment">...</span>
}
-
- </pre>
+ </pre>
+ </section>
<dl>
<dt><dfn>capabilityDelegation</dfn></dt>
From 2b27dd2675d79e754cb4c7753ec65f49607318ef Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 13:14:46 -0500
Subject: [PATCH 74/89] Remove "Method" from "Assertion Method" title.
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index de62ea7c..d770d615 100644
--- a/index.html
+++ b/index.html
@@ -1881,7 +1881,7 @@ <h2>Authentication</h2>
</section>
<section>
- <h2>Assertion Method</h2>
+ <h2>Assertion</h2>
<p>
The `assertionMethod` <a>verification relationship</a> is used to specify how
From 1c42c4b06b32193a8bd9d96293099ec88ca4be06 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 13:20:38 -0500
Subject: [PATCH 75/89] Add section on Capability Delegation.
---
index.html | 44 ++++++++++++++++++++++++++------------------
1 file changed, 26 insertions(+), 18 deletions(-)
diff --git a/index.html b/index.html
index d770d615..099b7658 100644
--- a/index.html
+++ b/index.html
@@ -2034,27 +2034,35 @@ <h2>Capability Invocation</h2>
</pre>
</section>
- <dl>
- <dt><dfn>capabilityDelegation</dfn></dt>
- <dd>
-The <code>capabilityDelegation</code> property is OPTIONAL.
- </dd>
- <dd>
-If present, the associated value MUST be an <a
-data-cite="INFRA#ordered-set">ordered set</a> of one or more <a>verification
-methods</a>. Each <a>verification method</a> MAY be embedded or referenced.
- </dd>
- </dl>
+ <section>
+ <h2>Capability Delegation</h2>
- <p class="note" title="Uses of capabilityDelegation">
+ <p>
+The `capabilityDelegation` <a>verification relationship</a> is used to specify
+a mechanism that might be used by the <a>DID subject</a> to delegate
+a cryptographic capability to another party, such as delegating the
+authority to access a specific HTTP API to a subordinate.
+ </p>
+
+ <dl>
+ <dt><dfn>capabilityDelegation</dfn></dt>
+ <dd>
+The <code>capabilityDelegation</code> property is OPTIONAL. If present, the
+associated value MUST be an <a data-cite="INFRA#ordered-set">ordered set</a> of
+one or more <a>verification methods</a>. Each <a>verification method</a> MAY be
+embedded or referenced.
+ </dd>
+ </dl>
+
+ <p>
An example of when this property is useful is when a <a>DID Subject</a>
chooses to grant their capability to start a vehicle through the combined
usage of a <a>verification method</a> and the <code>StartCar</code> capability
-to a capability invoker.
- </p>
+to a party other than themselves.
+ </p>
- <pre class="example nohighlight" title="Capability Delegation property
- containing two verification methods">
+ <pre class="example nohighlight" title="Capability Delegation property
+ containing two verification methods">
{
"@context": "https://www.w3.org/ns/did/v1", "id":
"did:example:123456789abcdefghi",
@@ -2074,8 +2082,8 @@ <h2>Capability Invocation</h2>
],
<span class="comment">...</span>
}
-
- </pre>
+ </pre>
+ </section>
</section>
<section>
From 41362c8c136d9697061d4b2c043ec62f36666639 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 13:31:02 -0500
Subject: [PATCH 76/89] Fix broken references.
---
index.html | 16 +++++++++-------
1 file changed, 9 insertions(+), 7 deletions(-)
diff --git a/index.html b/index.html
index 099b7658..2887f429 100644
--- a/index.html
+++ b/index.html
@@ -11,6 +11,8 @@
offline.
-->
+ <script class="remove"
+ src="https://unpkg.com/browse/jquery/dist/jquery.min.js"></script>
<script class="remove"
src="https://www.w3.org/Tools/respec/respec-w3c"></script>
<script class="remove"
@@ -42,8 +44,8 @@
// previously published draft, uncomment this and set its
// YYYY-MM-DD date and its maturity status
- //previousPublishDate: "2020-07-31",
- //previousMaturity: "WD",
+ previousPublishDate: "2020-11-08",
+ previousMaturity: "WD",
// automatically allow term pluralization
pluralize: true,
@@ -1231,16 +1233,16 @@ <h1>Core Properties</h1>
<code><a>authentication</a></code>: defined in <a href="#authentication"></a>.
</li>
<li>
-<code><a>assertionMethod</a></code>: defined in <a href="#assertionmethod"></a>.
+<code><a>assertionMethod</a></code>: defined in <a href="#assertion"></a>.
</li>
<li>
-<code><a>keyAgreement</a></code>: defined in <a href="#keyagreement"></a>.
+<code><a>keyAgreement</a></code>: defined in <a href="#key-agreement"></a>.
</li>
<li>
-<code><a>capabilityDelegation</a></code>: defined in <a href="#capabilitydelegation"></a>.
+<code><a>capabilityDelegation</a></code>: defined in <a href="#capability-delegation"></a>.
</li>
<li>
-<code><a>capabilityInvocation</a></code>: defined in <a href="#capabilityinvocation"></a>.
+<code><a>capabilityInvocation</a></code>: defined in <a href="#capability-invocation"></a>.
</li>
<li>
<code><a>service</a></code>: defined in <a href="#service-endpoints"></a>.
@@ -1482,7 +1484,7 @@ <h2>Verification Methods</h2>
values are set to the public key fingerprint [[RFC7638]]. It is RECOMMENDED
that verification methods that use JWKs to represent their public keys utilize
the value of <code>kid</code> as their fragment identifier. See the first key
-in <a href="#example-13-various-public-keys"></a>
+in <a href="#example-15-various-public-keys"></a>
for an example of a public key with a compound key identifier.
</p>
From b426d4855ea8dda876ef2b918ef34ed2170e9fba Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 15:12:14 -0500
Subject: [PATCH 77/89] Remove ReSpec error due to use of old respec code.
---
common.js | 52 +++++++++++++++++++++++++++++++---------------------
1 file changed, 31 insertions(+), 21 deletions(-)
diff --git a/common.js b/common.js
index db31fb4e..fcace788 100644
--- a/common.js
+++ b/common.js
@@ -4,7 +4,6 @@
/* ... who stole it from Manu Sporny of the JSON-LD 1.0 Working Group */
/* ... who stole it from Shane McCarron, that beautiful, beautiful man. */
/* exported restrictReferences */
-
var ccg = {
// Add as the respecConfig localBiblio variable
// Extend or override global respec references
@@ -181,34 +180,20 @@ var ccg = {
const termNames = [] ;
const termsReferencedByTerms = [] ;
-function restrictReferences(utils, content) {
+function restrictReferences(utils, content, filename) {
const base = document.createElement("div");
base.innerHTML = content;
- // New new logic:
- //
- // 1. build a list of all term-internal references
- // 2. When ready to process, for each reference INTO the terms,
- // remove any terms they reference from the termNames array too.
- const noPreserve = base.querySelectorAll("dfn:not(.preserve)");
- for (const item of noPreserve) {
- const $t = $(item);
- const titles = $t.getDfnTitles();
- const n = $t.makeID("dfn", titles[0]);
- if (n) {
- termNames[n] = $t.parent();
- }
- }
-
- const $container = $(".termlist", base) ;
- const containerID = $container.makeID("", "terms") ;
return (base.innerHTML);
}
require(["core/pubsubhub"], (respecEvents) => {
"use strict";
- respecEvents.sub('end', (message) => {
+ console.log("RESPEC EVENTS", respecEvents);
+
+ respecEvents.sub('end-all', (message) => {
+ console.log("END EVENT", message);
// remove data-cite on where the citation is to ourselves.
const selfDfns = document.querySelectorAll("dfn[data-cite^='" + respecConfig.shortName.toUpperCase() + "#']");
for (const dfn of selfDfns) {
@@ -229,8 +214,32 @@ require(["core/pubsubhub"], (respecEvents) => {
// class 'termlist', and if the target of that reference is
// also within a 'dl' element of class 'termlist', then
// consider it an internal reference and ignore it.
- respecEvents.sub('end', (message) => {
+ respecEvents.sub('end-all', (message) => {
+ console.log("message", message);
if (message === 'core/link-to-dfn') {
+ // 1. build a list of all term-internal references
+ // 2. When ready to process, for each reference INTO the terms,
+ // remove any terms they reference from the termNames array too.
+ const noPreserve =
+ document.querySelectorAll("#terminology dfn:not(.preserve)");
+
+ for (const item of noPreserve) {
+ const $t = $(item);
+ const titles = getDfnTitles(item);
+ console.log('titles', titles);
+ /*
+ const $t = $(item);
+ const titles = $t.getDfnTitles();
+ const n = $t.makeID("dfn", titles[0]);
+ if (n) {
+ termNames[n] = $t.parent();
+ }
+ */
+ }
+
+ //const $container = $(".termlist", base) ;
+ //const containerID = $container.makeID("", "terms") ;
+
// all definitions are linked; find any internal references
const internalTerms = document.querySelectorAll(".termlist a.internalDFN");
for (const item of internalTerms) {
@@ -282,6 +291,7 @@ require(["core/pubsubhub"], (respecEvents) => {
// delete any terms that were not referenced.
for (const term in termNames) {
+ //console.log("DELETE TERM?", term);
const $p = $("#"+term);
// Remove term definitions inside a dt, where data-cite does not start with shortname
if ($p === undefined) { continue; }
From d54d51ebb299f3cfeeb9b95f0078c90181d48cf8 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 16:31:59 -0500
Subject: [PATCH 78/89] Rework Data Model section.
Add different classes of properties, all datatypes, move
representation authoring rules to later in document.
---
index.html | 196 +++++++++++++++++++++++++++++++++++++++++------------
terms.html | 4 +-
2 files changed, 155 insertions(+), 45 deletions(-)
diff --git a/index.html b/index.html
index 2887f429..15578551 100644
--- a/index.html
+++ b/index.html
@@ -588,7 +588,7 @@ <h2>
typically express verification methods (such as public keys) and <a>services</a>
relevant to interactions with the DID subject. A DID document is represents an
abstract data model, and can be serialized according to a particular syntax
-(see <a href="#core-representations"></a>). The generic properties supported
+(see <a href="#representations"></a>). The generic properties supported
in a DID document are specified in <a href="#core-properties"></a>.
The <a>DID</a> itself is the value of the `id` property. The properties
present in a DID document may be updated according to the applicable
@@ -684,7 +684,7 @@ <h2>
normative statements in Sections <a href="#data-model"></a> and <a
href="#core-properties"></a>. A serialization format for the conforming
document is deterministic, bi-directional, and lossless as described in
-Section <a href="#core-representations"></a>.
+Section <a href="#representations"></a>.
</p>
<p>
@@ -1037,7 +1037,7 @@ <h2>Fragment</h2>
<p>
In order to maximize interoperability, implementers are urged to ensure that
<a>DID fragments</a> are interpreted in the same way across representations (as
-described in <a href="#core-representations"></a>). For example, while
+described in <a href="#representations"></a>). For example, while
JSON Pointer [[?RFC6901]] can be used in a <a>DID fragment</a>, it will not
be interpreted in the same way across representations.
</p>
@@ -1127,47 +1127,127 @@ <h2>Relative DID URLs</h2>
<section>
<h1>Data Model</h1>
<p>
-This specification defines an abstract data model for <a>DID documents</a>,
-independent of any specific representation. This section provides a
-high-level description of the data model, a set of requirements for
-representations, and a set of requirements for extensibility.
+This specification defines an abstract data model for <a>DID documents</a> that
+is capable of being serialized into multiple concrete representations. This
+section provides a high-level description of the data model, how different types
+of properties are expressed in the data model, and instructions for extending
+the data model.
</p>
- <section>
- <h2>Definition</h2>
- <p>
+ <p>
A <a>DID document</a> consists of a <a data-cite="INFRA#maps">map</a> of <a
-data-cite="INFRA#map-entry">properties</a>, which are name-value pairs (ie. a
-property name, and a property value). The definitions of each of these
-properties are specified in section <a href="#core-properties"></a>. Specific
-representations are defined in section <a href="#core-representations"></a>.
- </p>
- </section>
- <section>
- <h2>Representations</h2>
- <p>
-Following are the requirements for representations.
- </p>
- <ol>
- <li>
-A representation MUST define an unambiguous encoding and decoding of all
-property names and their associated values as defined in this specification.
-This means anything you can represent in the <a>DID document</a> data model
-can be represented in any compliant representation.
- </li>
- <li>
-The representation MUST be associated with an IANA-registered MIME type.
- </li>
- <li>
-The representation MUST define fragment processing rules for its MIME type that
-are conformant with the fragment processing rules defined in section
-<a href="#fragment"></a> of this specification.
- </li>
- </ol>
- <p>
-The core representations are specified in section
-<a href="#core-representations"></a>.
- </p>
- </section>
+data-cite="INFRA#map-entry">properties</a>, where each property consists of
+a property name/property value pair. The data model contains at least two
+different classes of properties. The first class of properties are called
+core properties, and are specified in section <a href="#core-properties"></a>.
+The second class of properties are called representation properties, and
+are specified in section <a href="#representations"></a>.
+ </p>
+ <p>
+All property names in the data model are <a
+data-cite="INFRA#strings">strings</a>. All property values are expressed
+using one of the data types in the table below.
+ </p>
+
+ <table class="simple" id="public-key-support">
+ <thead>
+ <tr>
+ <th>
+Data Type
+ </th>
+ <th>
+Considerations
+ </th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td>
+<a data-cite="INFRA#maps">ordered map</a>
+ </td>
+ <td>
+A finite ordered sequence of key/value pairs, with no key appearing twice as
+specified in [[INFRA]].
+ </td>
+ </tr>
+ <tr>
+ <td>
+<a data-cite="INFRA#list">list</a>
+ </td>
+ <td>
+A finite ordered sequence of items as specified in [[INFRA]].
+ </td>
+ </tr>
+ <tr>
+ <td>
+<a data-cite="INFRA#ordered-set">ordered set</a>
+ </td>
+ <td>
+A <a data-cite="INFRA#list">list</a> that does not contain the same item twice
+as specified in [[INFRA]].
+ </td>
+ </tr>
+ <tr>
+ <td>
+<dfn>datetime</dfn>
+ </td>
+ <td>
+A date and time value that is capable of losslessly expressing all values
+expressible by a `dateTime` as specified in
+[<a data-cite="XMLSCHEMA11-2#dateTime">XMLSCHEMA11-2</a>].
+ </td>
+ </tr>
+ <tr>
+ <td>
+<a data-cite="INFRA#string">string</a>
+ </td>
+ <td>
+A sequence of code units often used to represent human readable language
+as specified in [[INFRA]].
+ </td>
+ </tr>
+ <tr>
+ <td>
+<dfn>decimal</dfn>
+ </td>
+ <td>
+A value that represents a subset of the real numbers, which can be
+represented by decimal numerals as specified in
+[<a data-cite="XMLSCHEMA11-2#decimal">XMLSCHEMA11-2</a>]. To maximize
+interoperability, implementers are urged to only express values capable of
+being represented by 53 bits in binary notation.
+ </td>
+ </tr>
+ <tr>
+ <td>
+<dfn>double</dfn>
+ </td>
+ <td>
+A value that is often used to approximate arbitrary real numbers as specified
+in [<a data-cite="XMLSCHEMA11-2#double">XMLSCHEMA11-2</a>]. To maximize
+interoperability, implementers are urged to only express values capable of
+being represented by 64 bits in binary notation.
+ </td>
+ </tr>
+ <tr>
+ <td>
+<a data-cite="INFRA#boolean">boolean</a>
+ </td>
+ <td>
+A value that is either true or false as defined in [[INFRA]].
+ </td>
+ </tr>
+ <tr>
+ <td>
+<a data-cite="INFRA#null">null</a>
+ </td>
+ <td>
+A value that is used to indicate the lack of a value as defined in [[INFRA]].
+ </td>
+ </tr>
+ </tbody>
+ </table>
+
<section>
<h2>Extensibility</h2>
<p>
@@ -2212,7 +2292,7 @@ <h2>Service Endpoints</h2>
</section>
<section class="normative">
- <h1>Core Representations</h1>
+ <h1>Representations</h1>
<p>
All concrete representations of a <a>DID document</a> are serialized using a
@@ -2250,6 +2330,36 @@ <h1>Core Representations</h1>
for more information.
</p>
+ <section>
+ <h2>Creating Representations</h2>
+ <p>
+The <a href="#data-model">data model</a> provided in this specification
+supports being serialized into a variety of existing representations. Some
+applications might require the creation of a new representation. All new
+representations require the following:
+ </p>
+ <ol>
+ <li>
+A representation MUST define an unambiguous encoding and decoding of all
+property names and their associated values as defined in this specification.
+This means anything you can represent in the <a>DID document</a> data model
+can be represented in any compliant representation.
+ </li>
+ <li>
+The representation MUST be associated with an IANA-registered MIME type.
+ </li>
+ <li>
+The representation MUST define fragment processing rules for its MIME type that
+are conformant with the fragment processing rules defined in section
+<a href="#fragment"></a> of this specification.
+ </li>
+ </ol>
+ <p>
+In order to maximize interoperability, representation specification authors
+SHOULD register their representation in the [[?DID-SPEC-REGISTRIES]].
+ </p>
+ </section>
+
<section>
<h2>
JSON
diff --git a/terms.html b/terms.html
index 5d54825e..2c532530 100644
--- a/terms.html
+++ b/terms.html
@@ -100,7 +100,7 @@
<a href="https://en.wikipedia.org/wiki/Attribute_(computing)">attributes</a> or
<a href="https://en.wikipedia.org/wiki/Claims-based_identity">claims</a>
describing the <a>DID subject</a>. A DID document may have one or more different
-<a>representations</a> as defined in <a href="#core-representations"></a> or in
+<a>representations</a> as defined in <a href="#representations"></a> or in
the W3C DID Specification Registries [[DID-SPEC-REGISTRIES]].
</dd>
@@ -252,7 +252,7 @@
readily communicated via the protocol, and that consists of a set of
representation metadata and a potentially unbounded stream of representation
data." A <a>DID document</a> is a representation of information
-describing a <a>DID subject</a>. The <a href="#core-representations"></a>
+describing a <a>DID subject</a>. The <a href="#representations"></a>
section of the <a href="https://w3.org/TR/did-core">DID Core specification</a>
defines several representation formats for a <a>DID document</a>.
</dd>
From 7062a41f11dafe0454ed7d22dfcb95abf59d3b54 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 19:36:02 -0500
Subject: [PATCH 79/89] Replace decimal with integer. Specify IEEE 754-2008 for
double.
---
index.html | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/index.html b/index.html
index 15578551..7e438160 100644
--- a/index.html
+++ b/index.html
@@ -1208,11 +1208,10 @@ <h1>Data Model</h1>
</tr>
<tr>
<td>
-<dfn>decimal</dfn>
+<dfn>integer</dfn>
</td>
<td>
-A value that represents a subset of the real numbers, which can be
-represented by decimal numerals as specified in
+A real number without a fractional component as specified in
[<a data-cite="XMLSCHEMA11-2#decimal">XMLSCHEMA11-2</a>]. To maximize
interoperability, implementers are urged to only express values capable of
being represented by 53 bits in binary notation.
@@ -1225,8 +1224,9 @@ <h1>Data Model</h1>
<td>
A value that is often used to approximate arbitrary real numbers as specified
in [<a data-cite="XMLSCHEMA11-2#double">XMLSCHEMA11-2</a>]. To maximize
-interoperability, implementers are urged to only express values capable of
-being represented by 64 bits in binary notation.
+interoperability, implementers are urged to only express doubles capable of
+being represented as IEEE double-precision 64-bit floating point values
+[[IEEE 754-2008]].
</td>
</tr>
<tr>
From 4002505543012e8de5c4999903476080a5f6a1a9 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 19:39:06 -0500
Subject: [PATCH 80/89] Fix IEEE 754-2008 reference.
---
index.html | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/index.html b/index.html
index 7e438160..e8f0c545 100644
--- a/index.html
+++ b/index.html
@@ -1225,8 +1225,7 @@ <h1>Data Model</h1>
A value that is often used to approximate arbitrary real numbers as specified
in [<a data-cite="XMLSCHEMA11-2#double">XMLSCHEMA11-2</a>]. To maximize
interoperability, implementers are urged to only express doubles capable of
-being represented as IEEE double-precision 64-bit floating point values
-[[IEEE 754-2008]].
+being represented as IEEE double-precision 64-bit floating point values.
</td>
</tr>
<tr>
From 9916e14ec3e3888a6484c7480c29d06f18ed15ef Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Sun, 8 Nov 2020 19:44:42 -0500
Subject: [PATCH 81/89] Fix number warning in data types.
---
index.html | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/index.html b/index.html
index e8f0c545..d62e2ab9 100644
--- a/index.html
+++ b/index.html
@@ -1213,8 +1213,8 @@ <h1>Data Model</h1>
<td>
A real number without a fractional component as specified in
[<a data-cite="XMLSCHEMA11-2#decimal">XMLSCHEMA11-2</a>]. To maximize
-interoperability, implementers are urged to only express values capable of
-being represented by 53 bits in binary notation.
+interoperability, implementers are urged to heed the advice regarding
+integers in <a data-cite="rfc7159#section-6">RFC7159, Section 6: Numbers</a>.
</td>
</tr>
<tr>
@@ -1224,8 +1224,8 @@ <h1>Data Model</h1>
<td>
A value that is often used to approximate arbitrary real numbers as specified
in [<a data-cite="XMLSCHEMA11-2#double">XMLSCHEMA11-2</a>]. To maximize
-interoperability, implementers are urged to only express doubles capable of
-being represented as IEEE double-precision 64-bit floating point values.
+interoperability, implementers are urged to heed the advice regarding
+doubles in <a data-cite="rfc7159#section-6">RFC7159, Section 6: Numbers</a>.
</td>
</tr>
<tr>
From 59a7cd09cd0fd482ae03e84549100a853350f762 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Wed, 11 Nov 2020 16:14:30 -0500
Subject: [PATCH 82/89] Apply suggestions to Data Model from @brentzundel code
review.
Co-authored-by: Brent Zundel <brent.zundel@gmail.com>
---
index.html | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/index.html b/index.html
index d62e2ab9..3d850a4c 100644
--- a/index.html
+++ b/index.html
@@ -2334,15 +2334,15 @@ <h2>Creating Representations</h2>
<p>
The <a href="#data-model">data model</a> provided in this specification
supports being serialized into a variety of existing representations. Some
-applications might require the creation of a new representation. All new
+applications might require the creation of a new representation. All
representations require the following:
</p>
<ol>
<li>
-A representation MUST define an unambiguous encoding and decoding of all
+A representation MUST define an unambiguous encoding and decoding for all
property names and their associated values as defined in this specification.
-This means anything you can represent in the <a>DID document</a> data model
-can be represented in any compliant representation.
+This enables anything that can be represented in the <a>DID document</a> data
+model to also be represented in a compliant representation.
</li>
<li>
The representation MUST be associated with an IANA-registered MIME type.
From b8e0ff4eadc346d7259d99b74f02d6209a286a16 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Tue, 17 Nov 2020 09:22:29 -0500
Subject: [PATCH 83/89] Rename "Creating Representations" to "Representation
Requirements".
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index 3d850a4c..c04f80bd 100644
--- a/index.html
+++ b/index.html
@@ -2330,7 +2330,7 @@ <h1>Representations</h1>
</p>
<section>
- <h2>Creating Representations</h2>
+ <h2>Representation Requirements</h2>
<p>
The <a href="#data-model">data model</a> provided in this specification
supports being serialized into a variety of existing representations. Some
From 919ad01ef84cefb0a8dc1e466e045b58da58ffb1 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Tue, 17 Nov 2020 09:24:02 -0500
Subject: [PATCH 84/89] Ensure representations associated with one MIME type.
Co-authored-by: Justin Richer <justin@bspk.io>
---
index.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/index.html b/index.html
index c04f80bd..f116ceb9 100644
--- a/index.html
+++ b/index.html
@@ -2345,7 +2345,7 @@ <h2>Representation Requirements</h2>
model to also be represented in a compliant representation.
</li>
<li>
-The representation MUST be associated with an IANA-registered MIME type.
+The representation MUST be uniquely associated with an IANA-registered MIME type.
</li>
<li>
The representation MUST define fragment processing rules for its MIME type that
From ca8d10e7e6d56fb72123b2d3804aec79f613fd66 Mon Sep 17 00:00:00 2001
From: Manu Sporny <msporny@digitalbazaar.com>
Date: Tue, 17 Nov 2020 11:49:37 -0500
Subject: [PATCH 85/89] Make language around data type requirements more
specific.
Co-authored-by: Justin Richer <justin@bspk.io>
---
index.html | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/index.html b/index.html
index f116ceb9..d1a12a73 100644
--- a/index.html
+++ b/index.html
@@ -2340,7 +2340,8 @@ <h2>Representation Requirements</h2>
<ol>
<li>
A representation MUST define an unambiguous encoding and decoding for all
-property names and their associated values as defined in this specification.
+property names and all data model <a href="#data-model">data types</a>
+as defined in this specification.
This enables anything that can be represented in the <a>DID document</a> data
model to also be represented in a compliant representation.
</li>
From 53cce5970275839b78d8960b247d1194e099119e Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Tue, 27 Oct 2020 20:10:34 +0000
Subject: [PATCH 86/89] terms: add 'immutable' to DLT definition, #401
---
terms.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/terms.html b/terms.html
index 2c532530..f44e0be5 100644
--- a/terms.html
+++ b/terms.html
@@ -216,7 +216,7 @@
A <a href="https://en.wikipedia.org/wiki/Distributed_database">distributed database</a>
in which the various nodes use a
<a href="https://en.wikipedia.org/wiki/Consensus_(computer_science)">consensus protocol</a>
-to maintain a shared ledger in which each transaction is cryptographically
+to maintain an immutable shared ledger in which each transaction is cryptographically
signed and chained to the previous transaction.
</dd>
From faecb1e97ecdca933d460b3ead29f62a9a3bae7b Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Wed, 11 Nov 2020 09:11:36 +0000
Subject: [PATCH 87/89] terms: Update DLT definition, from @jandrieu
---
terms.html | 12 +++++++-----
1 file changed, 7 insertions(+), 5 deletions(-)
diff --git a/terms.html b/terms.html
index f44e0be5..4a874459 100644
--- a/terms.html
+++ b/terms.html
@@ -213,11 +213,13 @@
<dt><dfn data-lt="distributed ledger technology|DLT">distributed ledger</dfn> (DLT)</dt>
<dd>
-A <a href="https://en.wikipedia.org/wiki/Distributed_database">distributed database</a>
-in which the various nodes use a
-<a href="https://en.wikipedia.org/wiki/Consensus_(computer_science)">consensus protocol</a>
-to maintain an immutable shared ledger in which each transaction is cryptographically
-signed and chained to the previous transaction.
+A non-centralized system for recording events. These systems establish
+sufficient confidence for participating users to rely upon the data recorded
+by others to make operational decisions. They typically use distributed
+databases where different nodes use a consensus protocol to confirm the
+ordering of cryptographically signed transactions. The linking of digitally
+signed transactions over time often makes the history of the ledger
+effectively immutable.
</dd>
<dt><dfn data-lt="proofPurpose">proof purpose</dfn></dt>
From 26ad2ebcc487b2893bf464e4e465c83286a387d9 Mon Sep 17 00:00:00 2001
From: Amy Guy <amy@rhiaro.co.uk>
Date: Wed, 11 Nov 2020 14:18:48 +0000
Subject: [PATCH 88/89] Fix language
Co-authored-by: Manu Sporny <msporny@digitalbazaar.com>
---
terms.html | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/terms.html b/terms.html
index 4a874459..f947784e 100644
--- a/terms.html
+++ b/terms.html
@@ -214,7 +214,7 @@
<dd>
A non-centralized system for recording events. These systems establish
-sufficient confidence for participating users to rely upon the data recorded
+sufficient confidence for participants to rely upon the data recorded
by others to make operational decisions. They typically use distributed
databases where different nodes use a consensus protocol to confirm the
ordering of cryptographically signed transactions. The linking of digitally
From 002b9f0f6e3022321254366c31dfd9171a645889 Mon Sep 17 00:00:00 2001
From: rhiaro <amy@rhiaro.co.uk>
Date: Mon, 16 Nov 2020 13:08:34 +0000
Subject: [PATCH 89/89] feature at risk: note for did+ld+json media type, for
#208
---
index.html | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/index.html b/index.html
index d1a12a73..bcdbcbfa 100644
--- a/index.html
+++ b/index.html
@@ -2519,6 +2519,13 @@ <h2>
of <code>application/did+ld+json</code> in the resolver metadata).
</p>
+ <p class="issue atrisk" data-number="208">
+Use of the media type <code>application/did+ld+json</code> is pending
+clarification over registration of media types with multiple suffixes. The
+alternative will be to use <code>application/did+jsonld</code> if multiple
+suffixes cannot be registered by the time the rest of DID Core is ready for PR.
+ </p>
+
<ul>
<li>
The <code>@id</code> and <code>@type</code> keywords are aliased to
@@ -4765,6 +4772,14 @@ <h2>application/did+json</h2>
<section>
<h2>application/did+ld+json</h2>
+
+ <p class="issue atrisk" data-number="208">
+Use of the media type <code>application/did+ld+json</code> is pending
+clarification over registration of media types with multiple suffixes. The
+alternative will be to use <code>application/did+jsonld</code> if multiple
+suffixes cannot be registered by the time the rest of DID Core is ready for PR.
+ </p>
+
<dl>
<dt>Type name:</dt>
<dd>application</dd>