Skip to content

Commit

Permalink
normative statements: Removes duplicate normative language (#384)
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@rhiaro
rhiaro committed Oct 13, 2020
1 parent c764c67 commit a2cc42f
Showing 1 changed file with 81 additions and 77 deletions.
158 changes: 81 additions & 77 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1030,10 +1030,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&nbsp;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&nbsp;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>.
Expand All @@ -1044,7 +1044,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
Expand Down Expand Up @@ -1602,9 +1602,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>

Expand Down Expand Up @@ -1642,7 +1642,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>

Expand Down Expand Up @@ -1679,7 +1679,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.
Expand All @@ -1690,7 +1690,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.
Expand All @@ -1701,8 +1701,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>
Expand Down Expand Up @@ -2329,9 +2329,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>
Expand All @@ -2342,7 +2342,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>

Expand Down Expand Up @@ -2495,16 +2495,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>
Expand All @@ -2525,69 +2525,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>
Expand All @@ -2609,8 +2613,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
Expand All @@ -2637,10 +2641,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>
Expand Down

0 comments on commit a2cc42f

Please sign in to comment.