Normative statements review

[rhiaro]

I used a respec extension to pull out all the normative statements from the spec. They are listed here, with a note about their testability (if empty, assume it's automatically testable afaik), and proposals for changes to some.

Changes are to remove redundancy (it's not good to have more than one normative statement for the same feature, especially in different sections of the spec, and especially if the wording is different such that it might introduce ambiguity); to move statements to more appropriate sections; or to remove normative language where it's not needed (eg. doesn't make sense in terms of something for concrete implementations to follow).

Changes are not to alter the intent of the wording spec in a normative way that would actually require implementation changes. If there is a normative statement that you disagree with the content or existence (rather than clarity, location or structure) of, please raise that in a new issue (and check for existing issues) rather than commenting here.

I will start a series of PRs for the proposed changes and keep track of them here too.

The main purpose of this is to help with the test suite development.

Something being "not automatically testable" is fine - just means the implementer asserts that it is true. "Not testable" at all, is a problem.

Please comment if there are any further changes you would like to see to normative statements, or if you disagree with any of my proposed changes, or if you notice I've missed one.

Section	Statement	Testability	Proposed change	PR
1.4 Conformance	A conforming DID is any concrete expression of the rules specified in Section § 3. Identifier and MUST comply with relevant normative statements in that section.	Not testable by itself; depends on certain other tests passing	Remove normative to be purely descriptive?	#426
1.4 Conformance	A conforming DID document is any concrete expression of the data model described in this specification and MUST comply with the relevant normative statements in Sections § 4. Data Model and § 5. Core Properties.	Not testable by itself; depends on certain other tests passing	Remove normative to be purely descriptive?	#426
1.4 Conformance	A serialization format for the conforming document MUST be deterministic, bi-directional, and lossless as described in Section § 6. Core Representations.		Remove as duplicate of same in section 6	#426
1.4 Conformance	A conforming producer MUST NOT produce non-conforming DIDs or DID documents.
1.4 Conformance	A conforming consumer MUST produce errors when consuming non-conforming DIDs or DID documents.
3.1 DID Syntax	The DID scheme name MUST be an ASCII lowercase string.
3.1 DID Syntax	The DID method name MUST be an ASCII lowercase string.
3.1 DID Syntax	A DID method specification MUST further restrict the generic DID syntax by defining its own method-name and its own method-specific-id syntax.	Not automatically testable	Move to DID Methods section	#427
3.1 DID Syntax	Case sensitivity and normalization of the value of the method-specific-id rule MUST be defined by the governing DID method specification.	Not automatically testable	Move to DID Methods section	#427
3.2.1 Generic DID URL Parameters	Some generic DID parameter names (for example, for service selection) are completely independent of any specific DID method and MUST always function the same way for all DIDs. Other DID parameter names (for example, for versioning) MAY be supported by certain DID methods, but MUST operate uniformly across those DID methods that do support them.		move normative statements that are vague like "some parameter names.. MUST" into specific param name dfns in table (in place of "Note that this parameter might not be supported by all DID methods"). "operate uniformly" is not automatically testable, but the specifics of the uniform operation - in the table - are, so suggest just removing this as a normative statement and relyling on the table for testable reqs.	#427
3.2.1 Generic DID URL Parameters	[hl] The associated value MUST be an ASCII string.
3.2.1 Generic DID URL Parameters	[service] The associated value MUST be an ASCII string.
3.2.1 Generic DID URL Parameters	[version-id] The associated value MUST be an ASCII string.
3.2.1 Generic DID URL Parameters	[version-time] The associated value MUST be an ASCII string.
3.2.1 Generic DID URL Parameters	[relative-ref] The associated value MUST be an ASCII string and MUST use percent-encoding for certain characters as specified in RFC3986 Section 2.1.
3.2.1 Generic DID URL Parameters	DID parameters SHOULD NOT be used if the same functionality can be expressed by passing input metadata to a DID resolver, and if there is no need to construct a URI for use as a link, or as a resource in RDF / JSON-LD documents.	Not testable	Change to non-normative guidence	#427
3.2.2 Method-Specific DID URL Parameters	A method-specific parameter name MUST be prefixed by the method name, as defined by the method-name rule.			no longer applicable, language removed
3.2.3 Path	A DID path is identical to a generic URI path and MUST conform to the path-abempty ABNF rule in [RFC3986].
3.2.4 Query	A DID query is derived from a generic URI query and MUST conform to the did-query ABNF rule in Section § 3.2 DID URL Syntax.
3.2.4 Query	If a DID query is present, it MUST be used as described in Sections § 3.2.1 Generic DID URL Parameters and § 3.2.2 Method-Specific DID URL Parameters.
3.2.5 Fragment	DID fragment syntax and semantics are identical to a generic URI fragment and MUST conform to RFC 3986, section 3.5.
3.2.5 Fragment	To dereference a DID fragment, the complete DID URL including the DID fragment MUST be used as input to the DID URL dereferencing function for the target component in the DID document object. For more information, see § 8.2 DID URL Dereferencing .		Maybe change this MUST to a pointer and have the normative statement only in the DID URL dereferencing section	#427
3.2.6 Relative DID URLs	When resolving a relative DID URL reference, the algorithm specified in RFC3986 Section 5: Reference Resolution MUST be used.
4.2 Representations	A representation MUST define an unambiguous encoding and decoding of all property names and their associated values as defined in this specification.	Not automatically testable
4.2 Representations	The representation MUST be associated with an IANA-registered MIME type.	Not automatically testable?
4.2 Representations	The representation MUST define fragment processing rules for its MIME type that are conformant with the fragment processing rules defined in section § 3.2.5 Fragment of this specification.	Not automatically testable
4.3 Extensibility	For maximum interoperability, it is RECOMMENDED that extensions use the official W3C DID Specification Registries mechanism [DID-SPEC-REGISTRIES].	Not automatically testable
4.3 Extensibility	Representations MAY define other extensibility mechanisms including methods for decentralized extensions. Such extension mechanisms MUST support lossless conversion into any other conformant representation.	Not automatically testable
5.1 DID Subject	DID documents MUST include the id property.
5.1 DID Subject	The value of id MUST be a string that conforms to the rules in Section § 3.1 DID Syntax.
5.1 DID Subject	The value of id in the resolved DID document MUST match the DID that was resolved, or be populated with the equivalent canonical DID specified by the DID method, which SHOULD be used by the resolving party going forward.
5.2 Control	The value of the controller property MUST be a string or an ordered set of strings that conform to the rules in Section § 3.1 DID Syntax.
5.2 Control	The corresponding DID document(s) SHOULD contain verification relationships that explicitly permit the use of certain verification methods for specific purposes.
5.3 Verification Methods	In order to maximize interoperability, support for public keys as verification methods is restricted: see § 5.3.1 Key types and formats. For other types of verification method, the verification method SHOULD be registered in the [DID-SPEC-REGISTRIES].	Not automatically testable, unless we have a machine readable lookup for Registries maybe?
5.3 Verification Methods	If a DID document includes a verificationMethod property, the value of the property MUST be an ordered set of verification methods, where each verification method is described by a map containing properties.
5.3 Verification Methods	The properties MUST include the id, type, controller, and specific verification method properties
5.3 Verification Methods	The value of the id property for a verification method MUST be a URI.
5.3 Verification Methods	When more than one verification method is present, the value of verificationMethod MUST NOT contain multiple entries with the same id.
5.3 Verification Methods	If the value of verificationMethod contains multiple entries with the same id, a DID document processor MUST produce an error.
5.3 Verification Methods	It is RECOMMENDED that JWK kid values are set to the public key fingerprint [RFC7638].
5.3 Verification Methods	It is RECOMMENDED that verification methods that use JWKs to represent their public keys utilize the value of kid as their fragment identifier.
5.3 Verification Methods	The value of the type property MUST be exactly one verification method type.
5.3 Verification Methods	In order to maximize global interoperability, the verification method type SHOULD be registered in the [DID-SPEC-REGISTRIES].	Not automatically testable, unless we have a machine readable lookup for Registries maybe?
5.3 Verification Methods	The value of the controller property MUST be a string that conforms to the rules in Section § 3.1 DID Syntax.
5.3.1 Key types and formats	When using any of the public key types described here, public key expression MUST NOT use any other key format than those listed in the Public Key Support table.
5.3.1 Key types and formats	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 verification method.	Not automatically testable
5.3.1 Key types and formats	RSA public key values MUST either be encoded as a JWK [RFC7517] or be encoded in Privacy Enhanced Mail (PEM) format using the publicKeyPem property.
5.3.1 Key types and formats	Ed25519 public key values MUST either be encoded as a JWK [RFC7517] or be encoded as the raw 32-byte public key value in Base58 Bitcoin format [BASE58] using the publicKeyBase58 property.
5.3.1 Key types and formats	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 Bitcoin format [BASE58] using the publicKeyBase58 property.
5.3.1 Key types and formats	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 publicKeyBase58 property.
5.3.1 Key types and formats	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 Bitcoin format [BASE58] using the publicKeyBase58 property.
5.3.1 Key types and formats	If a public key does not exist in the DID document, it MUST be assumed the key was revoked or is invalid.	Not testable	change the 'assumed' language to something non-normative as this is not testable and a bit weird (eg. "If a public key does not exist in the DID document, the key was revoked or is invalid.")	#429
5.3.1 Key types and formats	The DID document MUST NOT express revoked keys using a verification relationship.
5.4 Verification Relationships	A DID document MAY include a property expressing a specific verification relationship. In order to maximize global interoperability, the property SHOULD be registered in [DID-SPEC-REGISTRIES].	Not automatically testable
5.4 Verification Relationships	The information in a DID document MUST be explicit about the verification relationship between the DID subject and the verification method.		A bit odd wording.. propose "The verification relationship between the DID subject and the verification method MUST be explicit in the DID document"	#429
5.4 Verification Relationships	Verification methods that are not associated with a particular verification relationship MUST NOT be used for that verification relationship.	"Seems to be difficult to test because it pertains to software consuming the did document" - @kdenhartog		#429
5.4.1 authentication	The associated value MUST be an ordered set of one or more verification methods.
5.4.2 assertionMethod	The associated value MUST be an ordered set of one or more verification methods.
5.4.3 keyAgreement	The associated value MUST be an ordered set of one or more verification methods.
5.4.4 capabilityInvocation	The associated value MUST be an ordered set of one or more verification methods.
5.4.5 capabilityDelegation	The associated value MUST be an ordered set of one or more verification methods.
5.5 Service Endpoints	If a DID document includes a service property, the value of the property SHOULD be an unordered set of service endpoints, where each service endpoint is described by a set of properties.		"change to "SHOULD be an ordered set of service endpoints"" - @kdenhartog	#429
5.5 Service Endpoints	Each service endpoint MUST have id, type, and serviceEndpoint properties, and MAY include additional properties.
5.5 Service Endpoints	The value of the id property MUST be a URI.
5.5 Service Endpoints	The value of service MUST NOT contain multiple entries with the same id.
5.5 Service Endpoints	In this case, a DID document processor MUST produce an error.
5.5 Service Endpoints	The value of the serviceEndpoint property MUST be a valid URI conforming to [RFC3986] and normalized according to the rules in section 6 of [RFC3986] and to any normalization rules in its applicable URI scheme specification, OR a set of properties which describe the service endpoint further.
6. Core Representations	All concrete representations of a DID document MUST be serialized using a deterministic mapping that is able to be unambiguously parsed into the data model defined in this specification.	Not testable?	Given the next paragraph which breaks down what this actually entails, normative language is not needed in this particular sentence.	#434
6. Core Representations	All serialization methods MUST define rules for the bidirectional translation of a DID document both into and out of the representation in question.	Not automatically testable?
6. Core Representations	As a consequence, translation between any two representations MUST be done by parsing the source format into a DID document model (described in Sections § 4. Data Model and § 5. Core Properties) and then serializing the DID document model into the target representation.	Not automatically testable?
6. Core Representations	An implementation MUST NOT convert between representations without first parsing to a DID document model.	Not automatically testable?	Also a duplicate of previous, but inverse. Suggest removing one or the other.	#434
6. Core Representations	Producers MUST indicate which representation of a document has been used via a media type in the document's metadata.
6. Core Representations	Consumers MUST determine which representation a document is in via the content-type DID resolver metadata field. (See § 8.1 DID Resolution ).
6. Core Representations	Consumers MUST NOT determine the representation of a document through its content alone.		Duplicate but inverse of previous row; change this to clarifying non-normative.	#434
6.1 JSON	When producing and consuming DID documents that are in plain JSON (as indicated by a content-type of application/did+json in the resolver metadata), the following rules MUST be followed.	Not testable (by itself)	Each of the "rules" has its own MUST and this one is not testable by itself and is redundant, so propose rewording to something like "This section sets out the requirements for producing and consuming DID documents that are in plain JSON (as indicated by a content-type of application/did+json in the resolver metadata)."	#436
6.1.1 Production	A DID document MUST be a single JSON object conforming to [RFC8259].
6.1.1 Production	All top-level properties of the DID document MUST be represented by using the property name as the name of the member of the JSON object.
6.1.1 Production	The values of properties of the data model described in Section § 4. Data Model, including all extensions, MUST be encoded in JSON [RFC8259] by mapping property values to JSON types as follows:	Not testable (by itself)	Reword to non-normative intro, as concrete requirements are covered in subsequent text	#436
6.1.1 Production	Numeric values representable as IEEE754 MUST be represented as a Number type.
6.1.1 Production	Boolean values MUST be represented as a Boolean literal.
6.1.1 Production	Sequence value MUST be represented as an Array type.
6.1.1 Production	Unordered sets of values MUST be represented as an Array type.
6.1.1 Production	Sets of properties MUST be represented as an Object type.
6.1.1 Production	Empty values MUST be represented as a null literal.
6.1.1 Production	Other values MUST be represented as a String type.
6.1.1 Production	All properties of the DID document MUST be included in the root object.
6.1.1 Production	The member name @context MUST NOT be used as this property is reserved for JSON-LD producers.
6.1.2 Consumption	The top-level element MUST be a JSON object.
6.1.2 Consumption	Any other data type at the top level is an error and MUST be rejected.
6.1.2 Consumption	Number types MUST interpreted as numeric values representable as IEEE754.
6.1.2 Consumption	Boolean literals MUST be interpreted as a Boolean value.
6.1.2 Consumption	An Array type MUST be interpreted as a Sequence or Unordered set, depending on the definition of the property for this value.
6.1.2 Consumption	An Object type MUST be interpreted as a sets of properties.
6.1.2 Consumption	A null literal MUST be interpreted as an Empty value.
6.1.2 Consumption	String types MUST be interpreted as Strings, which may be further parsed depending on the definition of the property for this value into more specific data types such as URIs, date stamps, or other values.
6.1.2 Consumption	The value of the @context object member MUST be ignored as this is reserved for JSON-LD consumers.		Seems redundant based on the next statement - surely @context would just be another 'unknown' property in this case - no need to call it out in particular?	n/a
6.1.2 Consumption	Unknown object member names MUST be ignored as unknown properties.
6.2 JSON-LD	When producing and consuming DID documents that are in JSON-LD (as indicated by a content-type of application/did+ld+json in the resolver metadata), the following rules MUST be followed.	Not testable (by itself)	redundant MUST, propose changing to non-normative intro text	#436
6.2 JSON-LD	This means that the value of id MUST be a valid DID and not any other kind of IRI.
6.2.1 Production	The DID document is serialized following the rules in the JSON processor, with one addition: DID documents MUST inlude the @context property.
6.2.1 Production	The value of the @context property MUST be one or more URIs, where the value of the first URI is https://www.w3.or/ns/did/v1.
6.2.1 Production	All members of the @context property MUST exist be in the DID properties extension registry.	Not automatically testable	(fix the typo in this sentence)
6.2.2 Consumption	The top-level element MUST be a JSON object.
6.2.2 Consumption	Any other data type at the top level is an error and MUST be rejected.
6.2.2 Consumption	The value of the @context property MUST be one or more URIs, where the value of the first URI is https://www.w3.org/ns/did/v1.
6.2.2 Consumption	If more than one URI is provided, the URIs MUST be interpreted as an ordered set.
6.2.2 Consumption	It is RECOMMENDED that dereferencing each URI results in a document containing machine-readable information about the context.		This is not a requirement on the Consumer but rather the producer? Especially as we should actually be advising consumers not to fetch the remote context. Suggest moving to Production.	#436
6.2.2 Consumption	Unknown object member names MUST be ignored as unknown properties.
6.3.1 Production	When producing DID Documents that are represented as CBOR, in addition to the suggestions in section 3.9 of the CBOR [RFC7049] specification for deterministic mappings, the following constraints of the DID Document model MUST be followed:	Not testable (by itself)	Replace redundant MUST with non-normative intro text.Should the reference to RFC7049 be a MUST?
6.3.1 Production	Map keys MUST be strings.
6.3.1 Production	Integer encoding MUST be as short as possible.	Not testable	Define "as possible" or change to non-normative guidance
6.3.1 Production	The expression of lengths in CBOR major types 2 through 5 MUST be as short as possible.	Not testable	Define "as possible" or change to non-normative guidance
6.3.1 Production	All floating point values MUST be encoded as 64-bits, even for integral values.
6.3.2 Consumption	When consuming DID Documents that are represented as CBOR, in addition to the suggestions in section 3.9 of the CBOR [RFC7049] specification for deterministic mappings the following constraints of the DID Document model MUST be followed:	Not testable (by itself)	Replace redundant MUST with non-normative intro text. Should the reference to RFC7049 be a MUST?
6.3.2 Consumption	The keys in every map must be sorted lowest value to highest. Sorting is performed on the bytes of the representation of the keys.		actually not a proper normative statement but ought to be
6.3.2 Consumption	Indefinite-length items must be made into definite-length items.		actually not a proper normative statement but ought to be
6.3.3.1 DagCBOR	When producing and consuming DID Documents representing in DagCBOR the following rules MUST be followed: * Use no CBOR tags other than the CID tag (42)		rearrange so the MUST is in the rule rather than the preceding sentence.
7.1 Method Schemes	A DID method specification MUST define exactly one method-specific DID scheme, identified by exactly one method name (see the method-name rule in Section § 3.1 DID Syntax).	Not automatically testable
7.1 Method Schemes	The authors of a new DID method specification SHOULD use a method name that is unique among all DID method names known to them at the time of publication.	Not automatically testable
7.1 Method Schemes	The method name SHOULD be five characters or less.
7.1 Method Schemes	The DID method specification MUST specify how to generate the method-specific-id component of a DID.	Not automatically testable
7.1 Method Schemes	The method-specific-id value MUST be able to be generated without the use of a centralized registry service.	Not automatically testable
7.1 Method Schemes	The method-specific-id value SHOULD be globally unique by itself. Any DID generated by the method MUST be globally unique.	Not automatically testable
7.1 Method Schemes	The method-specific-id value SHOULD be globally unique by itself. Any DID generated by the method MUST be globally unique.	Not automatically testable
7.1 Method Schemes	If needed, a method-specific DID scheme MAY define multiple method-specific-id formats. It is RECOMMENDED that a method-specific DID scheme define as few method-specific-id formats as possible.	Not automatically testable	What is "as possible"? This isn't even human-testable really. Rephrase to say something like "each additional method-specific-id format MUST be justified in the Method spec"?
7.1 Method Schemes	The method-specific-id format MAY include colons. The use of colons MUST comply syntactically with the method-specific-id ABNF rule.
7.2 Method Operations	Each DID method MUST define how authorization is implemented, including any necessary cryptographic operations.	Not automatically testable
7.2.1 Create	The DID method specification MUST specify how a client creates a DID and its associated DID document on the verifiable data registry, including all cryptographic operations necessary to establish proof of control.	Not automatically testable
7.2.2 Read/Verify	The DID method specification MUST specify how a client uses a DID to request a DID document from the verifiable data registry, including how the client can verify the authenticity of the response.	Not automatically testable
7.2.3 Update	The DID method specification MUST specify how a client can update a DID document on the verifiable data registry, including all cryptographic operations necessary to establish proof of control, or state that updates are not possible.	Not automatically testable
7.2.4 Deactivate	The DID method specification MUST specify how a client can deactivate a DID on the verifiable data registry, including all cryptographic operations necessary to establish proof of deactivation, or state that deactivation is not possible.	Not automatically testable
7.3 Security Requirements	DID method specifications MUST include their own Security Considerations sections.	Not automatically testable
7.3 Security Requirements	This section MUST consider all the requirements mentioned in section 5 of [RFC3552] (page 27) for the DID operations defined in the specification.	Not automatically testable
7.3 Security Requirements	At least the following forms of attack MUST be considered: eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle.	Not automatically testable
7.3 Security Requirements	Potential denial of service attacks MUST be identified as well.	Not automatically testable
7.3 Security Requirements	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.	Not automatically testable
7.3 Security Requirements	This section MUST provide integrity protection and update authentication for all operations required by Section § 7.2 Method Operations.	Not automatically testable
7.3 Security Requirements	If the technology involves authentication, particularly user-host authentication, the security of the authentication method MUST be clearly specified.	Not automatically testable
7.3 Security Requirements	DID methods MUST discuss the policy mechanism by which DIDs are proven to be uniquely assigned.	Not automatically testable
7.3 Security Requirements	Method-specific endpoint authentication MUST be discussed.	Not automatically testable
7.3 Security Requirements	Where DID methods make use of DLTs with varying network topology, sometimes offered as light node or thin client implementations to reduce required computing resources, the security assumptions of the topology available to implementations of the DID method MUST be discussed.	Not automatically testable
7.3 Security Requirements	If the protocol incorporates cryptographic protection mechanisms, the DID method specification MUST clearly indicate which portions of the data are protected and what the protections are, and SHOULD give an indication to what sorts of attacks the cryptographic protection is susceptible.	Not automatically testable
7.3 Security Requirements	Data which is to be held secret (keying material, random seeds, and so on) SHOULD be clearly labeled.	Not automatically testable
7.3 Security Requirements	Where DID methods make use of peer-to-peer computing resources, such as with all known DLTs, the expected burdens of those resources SHOULD be discussed in relation to denial of service.	Not automatically testable
7.3 Security Requirements	DID methods that introduce new authentication service endpoint types (see Section § 5.5 Service Endpoints) SHOULD consider the security requirements of the supported authentication protocol.	Not automatically testable
7.4 Privacy Requirements	DID method specifications MUST include their own Privacy Considerations sections, if only to point to § 10. Privacy Considerations .	Not automatically testable
7.4 Privacy Requirements	The DID method specification's Privacy Considerations section MUST discuss any subsection of section 5 of [RFC6973] that could apply in a method-specific manner.	Not automatically testable
8. Resolution	All conformant DID resolvers MUST implement the DID resolution functions for at least one DID method and MUST be able to return a DID document in at least one conformant representation.
8.1 DID Resolution	[..] all conformant implementations MUST implement two functions which have the following abstract forms:
8.1 DID Resolution	The input variables of these functions MUST be as follows:	Not testable by itself	Remove redundant MUST	#437
8.1 DID Resolution	[did] A conformant DID as a single string. This is the DID to resolve. This input is REQUIRED.		Rephrase the MUST to encapsulate the fact that it needs to be a conformant DID	#437
8.1 DID Resolution	[did-resolution-input-metadata] This input is REQUIRED, but the structure MAY be empty.
8.1 DID Resolution	The output variables of these functions MUST be as follows:	Not testable by itself	Remove redundant MUST	#437
8.1 DID Resolution	[did-resolution-metadata] This structure is REQUIRED and MUST NOT be empty.
8.1 DID Resolution	[did-resolution-metadata] If the resolution is successful, and if the resolveStream function was called, this structure MUST contain a content-type property containing the mime-type of the did-document-stream in this result.
8.1 DID Resolution	[did-resolution-metadata] If the resolution is not successful, this structure MUST contain an error property describing the error.
8.1 DID Resolution	[did-document] If the resolution is successful, and if the resolve function was called, this MUST be a DID document conforming to the abstract data model.
8.1 DID Resolution	[did-document] If the resolution is unsuccessful, this value MUST be empty.
8.1 DID Resolution	[did-document-stream] If the resolution is successful, and if the resolveStream function was called, this MUST be a byte stream of the resolved DID document in one of the conformant representations.
8.1 DID Resolution	[did-document-stream] If the resolution is unsuccessful, this value MUST be an empty stream.
8.1 DID Resolution	[did-document-metadata] If the resolution is successful, this MUST be a metadata structure.
8.1 DID Resolution	[did-document-metadata] If the resolution is unsuccessful, this output MUST be an empty metadata structure.
8.1 DID Resolution	DID resolver implementations MUST NOT alter the signature of these functions in any way.
8.1.1 DID Resolution Input Metadata Properties	[accept] The DID resolver implementation SHOULD use this value to determine the representation contained in the returned did-document-stream if such a representation is supported and available.
8.1.1 DID Resolution Input Metadata Properties	[accept] This property is OPTIONAL.
8.1.1 DID Resolution Input Metadata Properties	[accept] It is only used if the resolveStream function is called and MUST be ignored if the resolve function is called.
8.1.2 DID Resolution Metadata Properties	[content-type] This property is REQUIRED if resolution is successful and if the resolveStream function was called.
8.1.2 DID Resolution Metadata Properties	[content-type] It MUST NOT be present if the resolve function was called.
8.1.2 DID Resolution Metadata Properties	[content-type] The value of this property MUST be the MIME type of one of the conformant representations.
8.1.2 DID Resolution Metadata Properties	[content-type] The caller of the resolveStream function MUST use this value when determining how to parse and process the did-document-stream returned by this function into a DID document abstract data model.
8.1.2 DID Resolution Metadata Properties	[error] 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 last two sentences are not normative statements, but should be?	#437
8.1.3 DID Document Metadata Properties	[created] DID document metadata SHOULD include a created property to indicate the timestamp of the Create operation.
8.1.3 DID Document Metadata Properties	[created] The value of the property MUST be a valid XML datetime value, as defined in section 3.3.7 of W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes [XMLSCHEMA11-2].
8.1.3 DID Document Metadata Properties	[created] This datetime value MUST be normalized to UTC 00:00, as indicated by the trailing "Z".
8.1.3 DID Document Metadata Properties	[updated] DID document metadata SHOULD include an updated property to indicate the timestamp of the last Update operation.
8.1.3 DID Document Metadata Properties	[updated] The value of the property MUST follow the same formatting rules as the created property.
8.3 Metadata Structure	The structure used to communicate this metadata MUST be a map of properties.
8.3 Metadata Structure	Each property name MUST be a string.
8.3 Metadata Structure	Each property value MUST be a string, map, list, boolean, or null.
8.3 Metadata Structure	The values within any complex data structures such as maps and lists MUST be one of these data types as well.
8.3 Metadata Structure	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).
8.3 Metadata Structure	It is RECOMMENDED that property definitions use strings for values where possible.		remove "where possible"	#437
8.3 Metadata Structure	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.
9.2.1 Proving Control of a DID and DID Document	Signatures on DID documents are optional. DID method specifications SHOULD explain and specify their implementation if applicable.		this needs to go in Methods? Security Considerations is non-normative	#438

[OR13]

On the special topic call, we discussed how we might start breaking these down into assertions, inputs, outputs, etc...

I think the next major action items are as follows:

Get the WG to comment on proceeding with these tests....

Merge https://github.com/OR13/did-core-tests
Into https://github.com/w3c/did-test-suite

Setup CI, add some more realistic scenarios.

[rhiaro]

4.2 Representations

In the spreadsheet, comment on 4.2 Representations statements was "Move this to a "Guidance for Authors of Representation Specifications" section." (I'm not sure by who - probably @kdenhartog? - and +1ed by @msporny). But if we move these out there's nothing left in that section any more. My take is that the normative language is fine, we just have to treat it like the DID methods normative language - this is a checklist for anyone vetting by hand an implementation of a new representation (though when/where this vetting happens I'm not sure - nothing in Registries for representations afaik). But if that doesn't make sense, I propose to leave it where it is but adjust to use non-normative language. Let me know.

[rhiaro]

5.3 Verification methods

Spreadsheet feedback from @kdenhartog:

Re: "If a DID document includes a verificationMethod property, the value of the property MUST be an ordered set of verification methods, where each verification method is described by a map containing properties."

This statement seems to imply that all verificationMethod property values must be "a map containing properties". This seems like it should read "a map containing properties or a did-url referencing a map containting properties".

The confusion might come from looking only at this statement and not the surrounding text though.

I agree with your reading that the value of verificationMethod must be a list of objects, and can't be a list of strings (URIs) or a list containing a mix of URIs and objects. Whether this is correct or not, I don't know. I think this isn't a 'refactoring' question but a substance question, and warrants a new issue.

Re: "When more than one verification method is present, the value of verificationMethod MUST NOT contain multiple entries with the same id."

"If the value of verificationMethod contains multiple entries with the same id, a DID document processor MUST produce an error."

[these] seem redundant. Could we condense them to one? My preference is for [the latter] which made [the former] clearer for me.

I actually think these are two distinct statements, the first aimed at publishers and the second aimed at consumers, though I agree they're getting at the same basic premise. If we only use the latter though, there's no normative statement to test whether a DID doc producer produces the error, only if a consumer catches it correctly.

[rhiaro]

PRs in for the rest of these, except the CBOR section which has completely changed and needs re-review.

Question for method schemes as yet unresolved:

If needed, a method-specific DID scheme MAY define multiple method-specific-id formats. It is RECOMMENDED that a method-specific DID scheme define as few method-specific-id formats as possible.

What is "as possible"? This isn't even human-testable really. Does rephrasing to say something like "each additional method-specific-id format MUST be justified in the Method spec" make sense? This can at least by eyeballed by a human reading the Method spec.

[OR13]

are we required to test RECOMMENDED ?

[brentzundel]

Addressing this issue requires tests to be written. Ideally we will have ample test coverage before CR.

[selfissued]

As stated in https://w3c.github.io/did-core/#conformance , "As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative." Therefore, there are many many normative statements in the spec that do not use RFC 2119 language. Our tests should therefore test important normative statements not using RFC 2119 language as well as those that do.

[rhiaro]

Our tests should therefore test important normative statements not using RFC 2119 language as well as those that do.

In order that such normative statements are easily detectable, I propose we switch them to use RFC2119 language. If anyone spots statements they believe to be normative which do not use RFC2119 language, please note them in this issue. (This will also help with notifying people who are writing tests, otherwise we can't guarantee we're going to get them all.)

[kdenhartog]

Should we also update the conformance portion of the specification to state only usage of RFC2119 language should be considered a normative statement as well?

[jricher]

Please see new IETF normative doc: https://tools.ietf.org/html/rfc8174

Specifically:

   In many IETF documents, several words, when they are in all capitals
   as shown below, are used to signify the requirements in the
   specification.  These capitalized words can bring significant clarity
   and consistency to documents because their meanings are well defined.
   This document defines how those words are interpreted in IETF
   documents when the words are in all capitals.

   o  These words can be used as defined here, but using them is not
      required.  Specifically, normative text does not require the use
      of these key words.  They are used for clarity and consistency
      when that is what's wanted, but a lot of normative text does not
      use them and is still normative.

   o  The words have the meanings specified herein only when they are in
      all capitals.

   o  When these words are not capitalized, they have their normal
      English meanings and are not affected by this document.

   Authors who follow these guidelines should incorporate this phrase
   near the beginning of their document:

      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
      "MAY", and "OPTIONAL" in this document are to be interpreted as
      described in BCP 14 [RFC2119] [RFC8174] when, and only when, they
      appear in all capitals, as shown here.

[msporny]

Please see new IETF normative doc: https://tools.ietf.org/html/rfc8174

Yes, and the DID Core specification has followed RFC8174 guidance (and uses the suggested text) for a while now, see second paragraph in the section on Conformance here:

https://w3c.github.io/did-core/#conformance

Unless I'm missing something, @rhiaro @kdenhartog @jricher -- I think we're good?

[kdenhartog]

Please see new IETF normative doc: https://tools.ietf.org/html/rfc8174

Yes, and the DID Core specification has followed RFC8174 guidance (and uses the suggested text) for a while now, see second paragraph in the section on Conformance here:

https://w3c.github.io/did-core/#conformance

Unless I'm missing something, @rhiaro @kdenhartog @jricher -- I think we're good?

That's good enough for me

[msporny]

PR #526 has been raised to deal with this issue. When that PR is merged, this issue will be closed.

[msporny]

PR #526 has been merged, closing.