Did-core: 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? | https://github.com/w3c/did-core/pull/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? | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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. | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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.") | https://github.com/w3c/did-core/pull/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" | https://github.com/w3c/did-core/pull/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 | | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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. | https://github.com/w3c/did-core/pull/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. | https://github.com/w3c/did-core/pull/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. | https://github.com/w3c/did-core/pull/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)." | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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. | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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? | https://github.com/w3c/did-core/pull/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" | https://github.com/w3c/did-core/pull/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 | https://github.com/w3c/did-core/pull/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 ?

[rhiaro]

are we required to test RECOMMENDED ?

Yes, RECOMMENDED is the same as SHOULD

[OR13]

Then I RECOMMEND removing this recommendation :)

[msporny]

Yes, RECOMMENDED is the same as SHOULD

It depends on the WG... my experience is that many don't test SHOULD statements. Or they say, "We'll start with the MUST statements in the spec and then test the SHOULD statements if we have time"... and then 99% of all WGs run out of time testing the MUST statements and never get around to writing tests for SHOULD, even after the WG wraps up.

Sometimes, when you test SHOULD statements, certain members argue that they have a very good reason for not doing the SHOULD thing and so lobby to remove the test from the test suite (and are usually successful in doing so).

[msporny]

It is RECOMMENDED that a method-specific DID scheme define as few method-specific-id formats as possible.

I agree that this doesn't create any sort of objective requirement and isn't human testable as a result. Attempting to enforce it will just result in arguments between the evaluator and the implementer. Evaluator: "You defined 15 method-specific-ids in your DID Spec, it doesn't conform."... Implementer: "But that's the minimum possible, we need all of those method-specific-ids!"

[rhiaro]

I agree that this doesn't create any sort of objective requirement and isn't human testable as a result. Attempting to enforce it will just result in arguments between the evaluator and the implementer. Evaluator: "You defined 15 method-specific-ids in your DID Spec, it doesn't conform."... Implementer: "But that's the minimum possible, we need all of those method-specific-ids!"

To rectify this we can either change to

"It is advisable that a method-specific DID scheme define as few method-specifc-id formats as possible"

or something (human) testable along the lines of requiring each method-specific-id format to be explained and justified in the DID method spec. There's no bar to judge whether it's _good_ justification, but that some attempt being made seems worth enforcing? (And I expect is something DID method specs would actually want to do anyway? If not, it generally encourages clearer documentation, which would result in a better DID method spec.)

[rhiaro]

I will re-generate a list of normative statements when PRs #454 and #455 are merged

[rhiaro]

Okie dokie, here are the normative statements as of 2020-11-24T19:35:00+00:00 (note, still some outstanding PRs so you may spot things in here you thought we'd agreed to change - you're probably right - but helpful to scan the list and see if anything jumps out as totally wrong please!)

1.4 Conformance

A conforming producer is any algorithm realized as software and/or hardware and conforms to this specification if it generates conforming DIDs or conforming DID Documents. A conforming producer MUST NOT produce non-conforming DIDs or DID documents.

A conforming consumer is any algorithm realized as software and/or hardware and conforms to this specification if it consumes conforming DIDs or conforming DID documents. 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.

The DID method name MUST be an ASCII lowercase string.

3.2.1 DID Parameters

A relative URI reference according to RFC3986 Section 4.2 that identifies a resource at a service endpoint, which is selected from a DID document by using the service parameter. Support for this parameter is REQUIRED. The associated value MUST be an ASCII string and MUST use percent-encoding for certain characters as specified in RFC3986 Section 2.1.

Identifies a service from the DID document by service ID. Support for this parameter is REQUIRED. The associated value MUST be an ASCII string.

Identifies a specific version of a DID document to be resolved (the version ID could be sequential, or a UUID, or method-specific). Support for this parameter is OPTIONAL. If present, the associated value MUST be an ASCII string.

Identifies a certain version timestamp of a DID document to be resolved. That is, the DID document that was valid for a DID at a certain time. Support for this parameter is OPTIONAL. If present, the associated value MUST be an ASCII string which is 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]. This datetime value MUST be normalized to UTC 00:00, as indicated by the trailing "Z".

A resource hash of the DID document 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 ASCII string.

Implementers as well as DID method 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.

3.2.2 Path

A DID path is identical to a generic URI path and MUST conform to the path-abempty ABNF rule in [RFC3986].

3.2.3 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. If a DID query is present, it MUST be used as described in Section § 3.2.1 DID Parameters.

3.2.4 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 Relative DID URLs

When resolving a relative DID URL reference, the algorithm specified in RFC3986 Section 5: Reference Resolution MUST be used.

4.1 Extensibility

For maximum interoperability, it is RECOMMENDED that extensions use the official W3C DID Specification Registries mechanism [DID-SPEC-REGISTRIES].

Representations MAY define other extensibility mechanisms including methods for decentralized extensions. Such extension mechanisms MUST support lossless conversion into any other conformant representation.

5.1 DID Subject

DID documents MUST include the id property at the top level.

The value of id MUST be a string that conforms to the rules in Section § 3.1 DID Syntax.

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.1.1 alsoKnownAs

The value of alsoKnownAs MUST be a list where each item in the list is a URI conforming to [RFC3986].

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.

The corresponding DID document(s) SHOULD contain verification relationships that explicitly permit the use of certain verification methods for specific purposes.

When a controller property is present in a DID Document, its value expresses one or more DIDs. Any verification methods contained in the DID Documents for those DIDs SHOULD be accepted as authoritative, such that proofs that satisfy those verification methods are to be considered equivalent to proofs provided by the DID Subject.

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].

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. The properties MUST include the id, type, controller, and specific verification method properties, and MAY include additional properties.

The value of the id property for a verification method MUST be a URI. 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.

It is RECOMMENDED that JWK kid 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 kid as their fragment identifier.

The value of the type property MUST be exactly one verification method type. In order to maximize global interoperability, the verification method type SHOULD be registered in the [DID-SPEC-REGISTRIES].

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

A verification method MUST NOT contain multiple verification material properties.

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.

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.

RSA public key values MUST be encoded as a JWK [RFC7517] using the publicKeyJwk property.

Ed25519 public key values MUST either be encoded as a JWK [RFC7517] using the publicKeyJwk or be encoded as the raw 32-byte public key value in Base58 Bitcoin format [BASE58] using the publicKeyBase58 property.

Secp256k1 public key values MUST either be encoded as a JWK [RFC7517] using the publicKeyJwk or be encoded as the raw 33-byte public key value in Base58 Bitcoin format [BASE58] using the publicKeyBase58 property.

Curve25519 (also known as X25519) public key values MUST either be encoded as a JWK [RFC7517] using the publicKeyJwk or be encoded as the raw 32-byte public key value in Base58 Bitcoin format [BASE58] using the publicKeyBase58 property.

The DID document MUST NOT express revoked keys using a verification relationship.

5.4 Verification Relationships

The verification relationship between the DID subject and the verification method MUST be explicit in the DID document.

Verification methods that are not associated with a particular verification relationship MUST NOT be used for that verification relationship.

This specification defines several verification relationships below. A DID document MAY include any of these, or other properties, to express a specific verification relationship. In order to maximize global interoperability, any such properties used SHOULD be registered in [DID-SPEC-REGISTRIES].

5.4.1 Authentication

The authentication property is OPTIONAL. If present, the associated value MUST be an ordered set of one or more verification methods. Each verification method MAY be embedded or referenced.

5.4.2 Assertion

The assertionMethod property is OPTIONAL. If present, the associated value MUST be an ordered set of one or more verification methods. Each verification method MAY be embedded or referenced.

5.4.3 Key Agreement

The keyAgreement property is OPTIONAL. If present, the associated value MUST be an ordered set of one or more verification methods. Each verification method MAY be embedded or referenced.

5.4.4 Capability Invocation

The capabilityInvocation property is OPTIONAL. If present, the associated value MUST be an ordered set of one or more verification methods. Each verification method MAY be embedded or referenced.

5.4.5 Capability Delegation

The capabilityDelegation property is OPTIONAL. If present, the associated value MUST be an ordered set of one or more verification methods. Each verification method MAY be embedded or referenced.

5.5 Service Endpoints

If a DID document includes a service property, the value of the property SHOULD be an ordered set of service endpoints, where each service endpoint is described by a set of properties. Each service endpoint MUST have id, type, and serviceEndpoint properties, and MAY include additional properties.

The value of the id property MUST be a URI.

The value of service MUST NOT contain multiple entries with the same id. In this case, a DID document processor MUST produce an error.

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. Representations

All serialization methods MUST define rules for the bidirectional translation of a DID document both into and out of the representation in question.

An implementation MUST NOT convert between representations without first parsing to a DID document model (described in Sections § 4. Data Model and § 5. Core Properties); translation between any two representations is done by parsing the source format into a DID document model and then serializing the DID document model into the target representation.

Producers MUST indicate which representation of a document has been used via a media type in the document's metadata.

Consumers MUST determine the representation of a DID document via the content-type DID resolver metadata field (see § 8.1 DID Resolution ), not through the content of the DID document alone.

6.1 Representation Requirements

A representation MUST define an unambiguous encoding and decoding for all property names and all data model data types as defined in this specification.

The representation MUST be uniquely associated with an IANA-registered MIME type.

The representation MUST define fragment processing rules for its MIME type that are conformant with the fragment processing rules defined in section § 3.2.4 Fragment of this specification.

In order to maximize interoperability, representation specification authors SHOULD register their representation in the [DID-SPEC-REGISTRIES].

6.2 JSON

6.2.1 Production

A DID document MUST be a single JSON object conforming to [RFC8259].

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.

Numeric values representable as IEEE754 MUST be represented as a Number type.

Boolean values MUST be represented as a Boolean literal.

Sequence value MUST be represented as an Array type.

Unordered sets of values MUST be represented as an Array type.

Sets of properties MUST be represented as an Object type.

Empty values MUST be represented as a null literal.

Other values MUST be represented as a String type.

All properties of the DID document MUST be included in the root object. Properties MAY define additional data sub structures subject to the value representation rules in the list above.

The member name @context MUST NOT be used as this property is reserved for JSON-LD producers.

6.2.2 Consumption

The top-level element MUST be a JSON object.

Any other data type at the top level is an error and MUST be rejected.

Number types MUST interpreted as numeric values representable as IEEE754.

Boolean literals MUST be interpreted as a Boolean value.

An Array type MUST be interpreted as a Sequence or Unordered set, depending on the definition of the property for this value.

An Object type MUST be interpreted as a sets of properties.

A null literal MUST be interpreted as an Empty value.

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.

The value of the @context object member MUST be ignored as this is reserved for JSON-LD consumers.

Unknown object member names MUST be ignored as unknown properties.

6.3 JSON-LD

This means that the value of id that refers to the DID subject MUST be a valid DID and not any other kind of IRI.

6.3.1 Production

The DID document MUST be serialized as a JSON document, with one additional requirement: The DID document MUST include the @context property.

The value of @context MUST be exactly one of these values.

All members of the @context property SHOULD exist in the DID specification registries [DID-SPEC-REGISTRIES] in order to achieve interoperability across different representations.

It is RECOMMENDED that dereferencing each URI value of the @context 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].

Producers SHOULD NOT produce DID documents that contain properties not defined via the @context.

6.3.2 Consumption

The top-level element MUST be a JSON object.

Any other data type at the top level is an error and MUST be rejected.

If more than one URI is provided, the URIs MUST be interpreted as an ordered set.

Unknown object member names MUST be ignored as unknown properties.

Consumers SHOULD drop all properties from a DID document that are not defined via the @context.

6.4 CBOR

6.4.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:

Map keys MUST be strings.

Integer encoding MUST be as short as possible.

The expression of lengths in CBOR major types 2 through 5 MUST be as short as possible.

All floating point values MUST be encoded as 64-bits, even for integral values.

6.4.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:

The keys in every map must be sorted lowest value to highest. Sorting is performed on the bytes of the representation of the keys.

Indefinite-length items must be made into definite-length items.

6.4.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)

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).

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. (reworded to be non-normative in #470)

The DID method specification MUST specify how to generate the method-specific-id component of a DID.

Case sensitivity and normalization of the value of the method-specific-id rule MUST be defined by the DID method specification.

The method-specific-id value MUST be able to be generated without the use of a centralized registry service.

The method-specific-id value SHOULD be globally unique by itself. Any DID generated by the method MUST be globally unique.

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.

7.2.1 Create

The DID method specification MUST specify how a DID controller creates a DID and its associated DID document on the verifiable data registry, including all cryptographic operations necessary to establish proof of control.

7.2.2 Read/Verify

The DID method specification MUST specify how a DID resolver uses a DID to request a DID document from the verifiable data registry, including how the DID resolver can verify the authenticity of the response.

7.2.3 Update

The DID method specification MUST specify how a DID controller 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.

7.2.4 Deactivate

The DID method specification MUST specify how a DID controller 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.

7.3 Security Requirements

DID method specifications MUST include their own Security Considerations sections. This section MUST consider all the requirements mentioned in section 5 of [RFC3552] (page 27) for the DID operations defined in the specification.

At least the following forms of attack MUST be considered: eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle.

Potential denial of service attacks MUST be identified as well.

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 provide integrity protection and update authentication for all operations required by Section § 7.2 Method Operations.

If the technology involves authentication, particularly user-host authentication, the security of the authentication method MUST be clearly specified.

DID methods MUST discuss the policy mechanism by which DIDs are proven to be uniquely assigned.

Method-specific endpoint authentication MUST be discussed.

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.

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.

Data which is to be held secret (keying material, random seeds, and so on) SHOULD be clearly labeled.

DID method specifications SHOULD explain and specify the implementation of signatures on DID documents, if applicable.

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.

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.

7.4 Privacy Requirements

DID method specifications MUST include their own Privacy Considerations sections, if only to point to § 10. Privacy Considerations .

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.

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.

all conformant implementations MUST implement two functions which have the following abstract forms:

resolve ( did, did-resolution-input-metadata )
-> ( did-resolution-metadata, did-document, did-document-metadata )

8.1 DID Resolution

This is the DID to resolve. This input is REQUIRED and the value MUST be a conformant DID expressed as a single string.

A metadata structure consisting of input options to the resolve and resolveRepresentation functions in addition to the did itself. Properties defined by this specification are in § 8.1.1 DID Resolution Input Metadata Properties . This input is REQUIRED, but the structure MAY be empty.

A metadata structure consisting of values relating to the results of the DID resolution process. This structure is REQUIRED and MUST NOT be empty.

If the resolution is successful, and if the resolveRepresentation function was called, this structure MUST contain a content-type property containing the mime-type of the did-document-stream in this result.

If the resolution is not successful, this structure MUST contain an error property describing the error.

If the resolution is successful, and if the resolve function was called, this MUST be a conforming DID document.

If the resolution is unsuccessful, this value MUST be empty.

If the resolution is successful, and if the resolveRepresentation function was called, this MUST be a byte stream of the resolved DID document in one of the conformant representations.

If the resolution is unsuccessful, this value MUST be an empty stream.

If the resolution is successful, this MUST be a metadata structure.

If the resolution is unsuccessful, this output MUST be an empty metadata structure.

DID resolver implementations MUST NOT alter the signature of these functions in any way.

8.1.1 DID Resolution Input Metadata Properties

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. This property is OPTIONAL. It is only used if the resolveRepresentation function is called and MUST be ignored if the resolve function is called.

8.1.2 DID Resolution Metadata Properties

This property is REQUIRED if resolution is successful and if the resolveRepresentation function was called.

This property MUST NOT be present if the resolve function was called.

The value of this property MUST be the MIME type of one of the conformant representations.

The caller of the resolveRepresentation 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.

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].

8.1.3 DID Document Metadata Properties

The possible properties within this structure and their possible values SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].

DID document metadata SHOULD include a created property to indicate the timestamp of the Create operation. This property MAY not be supported by a given DID method. 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]. This datetime value MUST be normalized to UTC 00:00, as indicated by the trailing "Z".

DID document metadata SHOULD include an updated property to indicate the timestamp of the last Update operation. This property MAY not be supported by a given DID method. The value of the property MUST follow the same formatting rules as the created property.

8.2 DID URL Dereferencing

all conformant implementations MUST implement a function which has the following abstract form:

dereference ( did-url, did-url-dereferencing-input-metadata )
-> ( did-url-dereferencing-metadata, content-stream, content-metadata )

The input variables of this function MUST be as follows:

did-url To dereference a DID fragment, the complete DID URL including the DID fragment MUST be used. This input is REQUIRED.

did-url-dereferencing-input-metadata: This input is REQUIRED, but the structure MAY be empty.

The output variables of this function MUST be as follows:

did-url-dereferencing-metadata: 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 § 8.2.2 DID URL Dereferencing Metadata Properties . If the dereferencing is not successful, this structure MUST contain an error property describing the error.

content-stream: If the dereferencing function was called and successful, this MUST contain a resource corresponding to the DID URL. The content-stream MAY be a DID document in one of the conformant representations obtained through the resolution process. If the dereferencing is unsuccessful, this value MUST be empty.

content-metadata: If the dereferencing is successful, this MUST be a metadata structure, but the structure MAY be empty. This structure contains metadata about the content-stream. If the content-stream is a DID document, this MUST be a did-document-metadata structure as described in DID Resolution. If the dereferencing is unsuccessful, this output MUST be an empty metadata structure.

DID URL Dereferencing implementations MUST NOT alter the signature of these functions in any way.

8.2.1 DID URL Dereferencing Input Metadata Properties

The possible properties within this structure and their possible values SHOULD be registered in the [DID-SPEC-REGISTRIES].

The DID URL Dereferencing 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.

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]].

8.3 Metadata Structure

The structure used to communicate this metadata MUST be a map of properties.

Each property name MUST be a string.

Each property value MUST be a string, map, list, boolean, or null.

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.

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.

[msporny]

@OR13 would it be possible for you and the testers to go through this list and understand if what we are testing is appropriate?

This issue is not going to close until we transition into CR.

[OR13]

I would avoid sections 6,7,8 for now.... I am not sure how testable section 7 since its about requirements for another spec.

the earlier sections seem fairly safe to start tackling.

[kdenhartog]

Agree 1 through 5 are able to be implemented now from my read of them.

6 is going to be a bit tricky because knowing how another piece of software consumes a document seems a bit hard to test. Others might have suggestions about what to do for this.

7 is our set of manually tested statements for writing a DID Method and effectively act as what the DID Method Registries should be checking to have a DID Method registered. Might be worth us going through all the DID Methods and making sure that all of them actually meet the guidelines.

8 also seems fairly testable. Effectively what we do is pass the inputs in through the interface and return the result. The only thing that seems difficult to test in this regard would be the interface signature itself (at least in a language agnostic way), but the rest seems reasonable to me.

[OR13]

agree, 8 is testable.

[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.