Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Complete top-to-bottom review of testability of normative statements. #526

Merged
merged 5 commits into from
Jan 10, 2021
Merged

Complete top-to-bottom review of testability of normative statements. #526

Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0aa7c41
Remove ineffective/already tested/untestable MUST statements.
msporny Jan 3, 2021
27abae7
Remove ineffective/already tested/untestable SHOULD statements.
msporny Jan 3, 2021
3a9af61
Remove ineffective/already tested/untestable MAY statements.
msporny Jan 3, 2021
1cec627
Remove ineffective/already tested/untestable OPTIONAL statements.
msporny Jan 3, 2021
ce0f0e3
Fix grammar on CID tag 42 rule.
msporny Jan 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 64 additions & 76 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -943,15 +943,15 @@ <h2>DID Parameters</h2>
</table>

<p>
Implementers as well as <a>DID method</a> specification authors MAY use
Implementers as well as <a>DID method</a> specification authors might 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
DID parameters might 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>
Expand Down Expand Up @@ -1108,7 +1108,7 @@ <h2>Relative DID URLs</h2>

<p>
When resolving a relative DID URL reference, the algorithm specified in <a
data-cite="RFC3986#section-5">RFC3986 Section 5: Reference Resolution</a> MUST
data-cite="RFC3986#section-5">RFC3986 Section 5: Reference Resolution</a> MUST
be used. The <strong>base URI</strong> value is the <a>DID</a> that is
associated with the <a>DID subject</a>, see Section <a href="#did-subject"></a>.
The <strong>scheme</strong> is <code>did</code>. The <strong>authority</strong>
Expand Down Expand Up @@ -1290,12 +1290,12 @@ <h2>Extensibility</h2>
together.
</li>
<li>
Representations MAY define other extensibility mechanisms, including ones that do
not require the use of the DID Specification Registries. Such extension mechanisms SHOULD
support lossless conversion into any other conformant representation. Extension
mechanisms for a representation SHOULD define a mapping of all properties and
representation syntax into the <a href="#data-model">data model</a> and its type
system.
Representations MAY define other extensibility mechanisms, including ones that
do not require the use of the DID Specification Registries. Such extension
mechanisms SHOULD support lossless conversion into any other conformant
representation. Extension mechanisms for a representation SHOULD define a
mapping of all properties and representation syntax into the <a
href="#data-model">data model</a> and its type system.
</li>
</ol>
<p class="note">
Expand Down Expand Up @@ -1600,7 +1600,7 @@ <h2>Verification Methods</h2>

<p>
In the case where a verification method is a public key, the value of the
<code><a>id</a></code> property MAY be structured as a
<code><a>id</a></code> property might be structured as a
<a href="https://en.wikipedia.org/wiki/Compound_key">compound key</a>. This is
especially useful for integrating with existing key management systems and key
formats such as JWK [[RFC7517]]. It is RECOMMENDED that JWK <code>kid</code>
Expand Down Expand Up @@ -1809,7 +1809,7 @@ <h3>Verification method types</h3>


<p>
The <a>DID document</a> MUST NOT express revoked keys using a <a>verification
The <a>DID document</a> does not express revoked keys using a <a>verification
relationship</a>.
</p>
<p>
Expand Down Expand Up @@ -1847,9 +1847,9 @@ <h2>Verification Relationships</h2>
</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 method</a> is 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
<a>verification relationship</a> cannot be used for that <a>verification
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
Comment on lines +1850 to 1854
Copy link
Member

Choose a reason for hiding this comment

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

Just noting that I tried to remove this normative language in an earlier PR based on a comment by @kdenhartog, and @msporny objected on the basis that it is testable. Given this is a conflict between present manu and past manu, I'm going to suggest manu can make the call :)

Copy link
Member Author

Choose a reason for hiding this comment

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

*lol* ... Dammit, past manu... 'causing trouble.

Past manu was wrong, @rhiaro and @kdenhartog are right.

The normative-ness of the statement is being removed because it is a test intended for a conformance class of software that we don't define in DID Core. In other words, it has very little to do with production and consumption conformance classes and instead has more to do with software that implements authentication/authorization protocols.

Present manu is displeased that past manu failed to realize that. :P

key agreement protocols with the <a>DID subject</a>&mdash;the value of the
Expand Down Expand Up @@ -2189,7 +2189,7 @@ <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 <a data-cite="INFRA#ordered-set">ordered set</a>
of the property MUST be an <a data-cite="INFRA#ordered-set">ordered set</a>
Copy link
Member

Choose a reason for hiding this comment

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

was this originally a SHOULD because the value could potentially be an ordered set of just URI strings (which dereference to the rest of the data)? Worth checking if this change affects any implementations?

Copy link
Member Author

Choose a reason for hiding this comment

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

I'm not sure we ever had that use case... I may be wrong, but as far as I can remember... service was always supposed to be an array of objects (because you have to give the service an id, type, and a serviceEndpoint)... I don't know of any DID Method that doesn't follow that pattern.

of <a>service endpoints</a>, 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
Expand Down Expand Up @@ -2982,12 +2982,6 @@ <h3>Production</h3>
</li>
</ul>

<p>
The property name `@context` MAY be present in the CBOR representation of a DID
Document and if present SHOULD be ignored as this property is reserved for
JSON-LD processing.
</p>

<p>
All properties of the DID document represented in CBOR MUST be included in the
root map (major type 5). Properties MAY define additional data sub structures
Expand Down Expand Up @@ -3226,7 +3220,7 @@ <h4>DagCBOR</h4>
To produce a deterministic canonical CBOR representation of a DID document and
faciliate maximal lossless compatiblity with other core representations via the
<a href="#data-model">data model</a> the following constraints of a CBOR
representation of a DID Document MUST be followed:
representation are as follows:
</p>

<ul>
Expand Down Expand Up @@ -3265,12 +3259,12 @@ <h4>DagCBOR</h4>

<p>
When producing and consuming DID Documents representing in DagCBOR the following
rules MUST be followed:
rules are followed:
</p>

<ul>
<li>
Use no CBOR tags other than the CID tag (42)
CBOR tags other than the CID tag (42) MUST NOT be utilized.
msporny marked this conversation as resolved.
Show resolved Hide resolved
</li>
</ul>

Expand Down Expand Up @@ -3406,7 +3400,7 @@ <h2>Method Operations</h2>
</p>
<p>
Determining the authority of a party to carry out the operations is
method-specific. For example, a <a>DID method</a> MAY:
method-specific. For example, a <a>DID method</a> might:
</p>
<ul>
<li>
Expand Down Expand Up @@ -3608,7 +3602,7 @@ <h1>
<p>
All conformant <a>DID resolvers</a> MUST implement the <a>DID resolution</a>
functions for at least one <a>DID method</a> and MUST be able to return a <a>DID
document</a> in at least one conformant representation.
document</a> in at least one conformant representation.
</p>

<section>
Expand All @@ -3620,7 +3614,7 @@ <h2>
document</a> by using the "Read" operation of the applicable <a>DID method</a>.
(See <a href="#read-verify"></a>.) The details of how this process is
accomplished are outside the scope of this specification, but all conformant
implementations MUST implement two functions which have the following abstract
implementations implement two functions which have the following abstract
forms:
</p>

Expand Down Expand Up @@ -3701,7 +3695,7 @@ <h2>
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
<a href="#representations">representations</a>. The byte stream might then be
parsed by the caller of the <code>resolveRepresentation</code> function into a
<a href="#data-model">data model</a>, which can in turn be validated and
processed. If the resolution is unsuccessful, this value MUST be an empty
Expand All @@ -3725,11 +3719,11 @@ <h2>
</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
Conforming <a>DID resolver</a> implementations do not alter the signature of
these functions in any way. <a>DID resolver</a> implementations might 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
process. <a>DID resolver</a> implementations might implement and expose
additional functions with different signatures in addition to the
<code>resolve</code> function specified here.
</p>
Expand Down Expand Up @@ -3845,25 +3839,22 @@ <h3>DID Document Metadata Properties</h3>
<section>
<h4>created</h4>
<p>
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 <a data-cite="INFRA#string">string</a>
formatted as an
<a data-cite="XMLSCHEMA11-2#dateTime">XML Datetime</a> normalized to
UTC 00:00:00 and without sub-second decimal precision. For example:
DID document metadata SHOULD include a <code>created</code> property to indicate
the timestamp of the <a href="#create">Create operation</a>. The value of the
property MUST be a <a data-cite="INFRA#string">string</a> formatted as an <a
data-cite="XMLSCHEMA11-2#dateTime">XML Datetime</a> normalized to UTC 00:00:00
and without sub-second decimal precision. For example:
<code>2020-12-20T19:17:47Z</code>.
</p>
</section>

<section>
<h4>updated</h4>
<p>
DID document metadata SHOULD include an <code>updated</code> property
to indicate the timestamp of the last <a href="#update">Update operation</a>
for the document version which was resolved. 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.
DID document metadata SHOULD include an <code>updated</code> property to
indicate the timestamp of the last <a href="#update">Update operation</a> for
the document version which was resolved. The value of the property MUST follow
the same formatting rules as the <code>created</code> property.
</p>
</section>

Expand All @@ -3875,7 +3866,6 @@ <h4>
DID document metadata SHOULD include a <code>next-update</code> property if
the resolved document version is not the latest version of the document. It
indicates the timestamp of the next <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.
</p>
Expand All @@ -3886,11 +3876,10 @@ <h4>
version-id
</h4>
<p>
DID document metadata SHOULD include a <code>version-id</code> property
to indicate the version of the last <a href="#update">Update operation</a>
for the document version which was resolved. This property MAY not be
supported by a given <a>DID method</a>. The value of the property MUST be
an <a data-lt="ascii string">ASCII string</a>.
DID document metadata SHOULD include a <code>version-id</code> property to
indicate the version of the last <a href="#update">Update operation</a> for the
document version which was resolved. The value of the property MUST be an <a
data-lt="ascii string">ASCII string</a>.
</p>
</section>

Expand All @@ -3899,11 +3888,10 @@ <h4>
next-version-id
</h4>
<p>
DID document metadata SHOULD include a <code>next-version-id</code> property
if the resolved document version is not the latest version of the document.
It indicates the version of the next <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 be an <a data-lt="ascii string">ASCII string</a>.
DID document metadata SHOULD include a <code>next-version-id</code> property if
the resolved document version is not the latest version of the document. It
indicates the version of the next <a href="#update">Update operation</a>. The
value of the property MUST be an <a data-lt="ascii string">ASCII string</a>.
</p>
</section>

Expand Down Expand Up @@ -3942,7 +3930,7 @@ <h4>equivalentId</h4>
<code>id</code> property value.
</dd>
<dd>
A resolving party MUST retain the values from the <code>id</code> and
A resolving party is expected to retain the values from the <code>id</code> and
<code><a>equivalentId</a></code> properties to ensure any subsequent
interactions with any of the values they contain are correctly handled as
logically equivalent (e.g. retain all variants in a database so an interaction
Expand Down Expand Up @@ -3999,13 +3987,13 @@ <h4>canonicalId</h4>
<code>id</code> property value.
</dd>
<dd>
A resolving party MUST use the <code><a>canonicalId</a></code> value as its
primary ID value for the DID subject and treat all other equivalent values as
secondary aliases. (e.g. update corresponding primary references in their
systems to reflect the new canonical ID directive). <span class="issue">The
testability of resolving parties is currently under debate and normative
statements related to resolving parties may be downgraded in the future from a
MUST to a SHOULD/MAY or similar language.</span>
A resolving party is expected to use the <code><a>canonicalId</a></code> value
as its primary ID value for the DID subject and treat all other equivalent
values as secondary aliases. (e.g. update corresponding primary references in
their systems to reflect the new canonical ID directive). <span
class="issue">The testability of resolving parties is currently under debate and
normative statements related to resolving parties may be downgraded in the
future from a MUST to a SHOULD/MAY or similar language.</span>
</dd>
</dl>

Expand Down Expand Up @@ -4035,7 +4023,7 @@ <h2>
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
specification, but all conformant implementations implement a function
Copy link
Contributor

Choose a reason for hiding this comment

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

Why would we not test this normative statement?

Copy link
Member Author

@msporny msporny Jan 5, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

How would we write a test to ensure that "a conformant implementation implements a function with the following abstract form". That is, how do we test to make sure an abstract function is defined... since by it's very nature, the function is abstract and has no testable realization?

which has the following abstract form:
</p>

Expand All @@ -4045,7 +4033,7 @@ <h2>
</code></p>

<p>
The input variables of this function MUST be as follows:
The input variables of this function are as follows:
Copy link
Contributor

Choose a reason for hiding this comment

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

Why would we not test this normative statement?

Copy link
Member Author

Choose a reason for hiding this comment

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

Eliminating this normative statement has no effect on the number of tests we write because each item in the list asserts a normative test as well and refers to a data structure for which there are already normative tests.

</p>

<dl>
Expand All @@ -4070,7 +4058,7 @@ <h2>
</dl>

<p>
The output variables of this function MUST be as follows:
The output variables of this function are as follows:
Copy link
Contributor

Choose a reason for hiding this comment

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

Why would we not test this normative statement?

Copy link
Member Author

Choose a reason for hiding this comment

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

Eliminating this normative statement has no effect on the number of tests we write because each item in the list asserts a normative test as well and refers to a data structure for which there are already normative tests.

</p>

<dl>
Expand All @@ -4093,7 +4081,7 @@ <h2>
<dd>
If the <code>dereferencing</code> function was called and successful, this MUST
contain a resource corresponding to the <a>DID URL</a>.
The <code>content-stream</code> MAY be a <a>DID document</a> in one of the
The <code>content-stream</code> SHOULD be a <a>DID document</a> in one of the
conformant <a href="#representations">representations</a> obtained through
the resolution process.

Expand All @@ -4116,13 +4104,13 @@ <h2>
</dl>

<p>
<a>DID URL Dereferencing</a> implementations MUST NOT alter the signature of
these functions in any way. <a>DID URL Dereferencing</a> implementations MAY
map the <code>dereference</code> function to a method-specific internal
function to perform the actual <a>DID URL Dereferencing</a> process. <a>DID
URL Dereferencing</a> implementations MAY implement and expose additional
functions with different signatures in addition to the <code>dereference</code>
function specified here.
Conforming <a>DID URL Dereferencing</a> implementations do not alter the
signature of these functions in any way. <a>DID URL Dereferencing</a>
implementations might map the <code>dereference</code> function to a
method-specific internal function to perform the actual <a>DID URL
Dereferencing</a> process. <a>DID URL Dereferencing</a> implementations might
implement and expose additional functions with different signatures in addition
to the <code>dereference</code> function specified here.
</p>

<section>
Expand All @@ -4142,7 +4130,7 @@ <h3>DID URL Dereferencing Input Metadata Properties</h3>
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.
supported and available.
</dd>
</dl>
</section>
Expand All @@ -4163,8 +4151,8 @@ <h3>
content-type
</dt>
<dd>
The MIME type of the returned <code>content-stream</code>.
This property is OPTIONAL if dereferencing is successful.
The MIME type of the returned <code>content-stream</code> SHOULD be expressed
using this property if dereferencing is successful.
</dd>
<dt>
error
Expand Down Expand Up @@ -4227,7 +4215,7 @@ <h2>

<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
or output are 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
Expand Down