Normative statements checklist: 7. Resolution

[Amy Guy]

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

7.1 DID Resolution

• did: This input is REQUIRED and the value MUST be a conformant DID as defined in § 3.1 DID Syntax.
• resolutionOptions: A metadata structure containing properties defined in § 7.1.1 DID Resolution Options. This input is REQUIRED, but the structure MAY be empty.
• didResolutionMetadata: This structure is REQUIRED, and in the case of an error in the resolution process, this MUST NOT be empty.
• ...If resolveRepresentation was called, this structure MUST contain a contentType property containing the Media Type of the representation found in the didDocumentStream.
• ...If the resolution is not successful, this structure MUST contain an error property describing the error.
• didDocument: If the resolution is successful, and if the resolve function was called, this MUST be a DID document abstract data model (a map) as described in § 4. Data Model that is capable of being transformed into a conforming DID Document (representation), using the production rules specified by the representation.
• ...The value of id in the resolved DID document MUST match the DID that was resolved.
• didDocumentStream: 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.
• didDocumentMetadata: If the resolution is successful, this MUST be a metadata structure. This structure contains metadata about the DID document contained in the didDocument property.
• ...If the resolution is unsuccessful, this output MUST be an empty metadata structure.

7.1.1 DID Resolution Options

• accept: The Media Type MUST be expressed as an ASCII string.
• ...The DID resolver implementation SHOULD use this value to determine the representation contained in the returned didDocumentStream if such a representation is supported and available.
• ...This property is OPTIONAL for the resolveRepresentation function
• ...and MUST NOT be used with the resolve function.

7.1.2 DID Resolution Metadata

• contentType: 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 an ASCII string that is the Media Type of the conformant representations.
• ...The caller of the resolveRepresentation function MUST use this value when determining how to parse and process the didDocumentStream returned by this function into the data model.
• error: This property is REQUIRED when there is an error in the resolution process.
• ...The value of this property MUST be a single keyword ASCII string.
• ...The possible property values of this field SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].

7.1.3 DID Document Metadata

• The possible properties within this structure and their possible values SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].
• created: DID document metadata SHOULD include a created property to indicate the timestamp of the Create operation.
• ...The value of the property MUST be a string formatted as an XML Datetime normalized to UTC 00:00:00 and without sub-second decimal precision.
• updated: DID document metadata SHOULD include an updated property to indicate the timestamp of the last Update operation for the document version which was resolved.
• ...The value of the property MUST follow the same formatting rules as the created property.
• deactivated: If a DID has been deactivated, DID document metadata MUST include this property with the boolean value true.
• ...If a DID has not been deactivated, this property is OPTIONAL, but if included, MUST have the boolean value false.
• nextUpdate: DID document metadata MAY include a nextUpdate property if the resolved document version is not the latest version of the document.
• ...The value of the property MUST follow the same formatting rules as the created property.
• versionId: DID document metadata SHOULD include a versionId property to indicate the version of the last Update operation for the document version which was resolved.
• ...The value of the property MUST be an ASCII string.
• nextVersionId: DID document metadata MAY include a nextVersionId property if the resolved document version is not the latest version of the document.
• ...The value of the property MUST be an ASCII string.
• equivalentId: The value of equivalentId MUST be a set where each item is a string that conforms to the rules in Section § 3.1 DID Syntax.
• ...Each equivalentId DID value MUST be produced by, and a form of, the same DID Method as the id property value.
• ...A conforming DID Method specification MUST guarantee that each equivalentId value is logically equivalent to the id property value.
• ...equivalentId is a much stronger form of equivalence than alsoKnownAs because the equivalence MUST be guaranteed by the governing DID method.
• canonicalId: The value of canonicalId MUST be a string that conforms to the rules in Section § 3.1 DID Syntax.
• ...A canonicalId value MUST be produced by, and a form of, the same DID Method as the id property value.
• ...A conforming DID Method specification MUST guarantee that the canonicalId value is logically equivalent to the id property value.

7.2 DID URL Dereferencing

• didUrl: To dereference a DID fragment, the complete DID URL including the DID fragment MUST be used.
• This input is REQUIRED.
• dereferencingOptions: This input is REQUIRED, but the structure MAY be empty.
• dereferencingMetadata: This structure is REQUIRED and in the case of an error in the dereferencing process, this MUST NOT be empty.
• ...If the dereferencing is not successful, this structure MUST contain an error property describing the error.
• contentStream: If the dereferencing function was called and successful, this MUST contain a resource corresponding to the DID URL.
• ...If the dereferencing is unsuccessful, this value MUST be empty.
• contentMetadata: If the dereferencing is successful, this MUST be a metadata structure, but the structure MAY be empty.
• ...If the contentStream is a DID document, this MUST be a didDocumentMetadata structure as described in DID Resolution.
• ...If the dereferencing is unsuccessful, this output MUST be an empty metadata structure.

7.2.1 DID URL Dereferencing Options

• The possible properties within this structure and their possible values SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].
• accept: The Media Type MUST be expressed as an ASCII string.
• ...The DID URL dereferencing implementation SHOULD use this value to determine the contentType of the representation contained in the returned value if such a representation is supported and available.
• ...The Media Type of the returned contentStream SHOULD be expressed using this property if dereferencing is successful.
• ...The Media Type value MUST be expressed as an ASCII string.

7.2.2 DID URL Dereferencing Metadata

• contentType: The Media Type of the returned contentStream SHOULD be expressed using this property if dereferencing is successful.
• ...The Media Type value MUST be expressed as an ASCII string.
• error: This property is REQUIRED when there is an error in the dereferencing process.
• ...The value of this property MUST be a single keyword expressed as an ASCII string.
• ...The possible property values of this field SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].

7.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, set, 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 registered in the DID Specification Registries [DID-SPEC-REGISTRIES] 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.
• The entire metadata structure MUST be serializable according to the JSON serialization rules in the [INFRA] specification.

[Markus Sabadello]

Related: #53

[Markus Sabadello]

Also assigning @shigeya , since I did section 7.1 (DID Resolution #29) and section 7.2 (DID URL Dereferencing #30), while he did section 7.3 (Metadata Structure #31).

[Shigeya Suzuki]

Since I don't have write permissio to this repository, I can't check tem, so... for 7.3 Metadata Structure, all but following two items are done:

All metadata property definitions registered in the DID Specification Registries [DID-SPEC-REGISTRIES] 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).

Following entry is RECOMMENDED so testing is not mandatory.

It is RECOMMENDED that property definitions use strings for values.

[Manu Sporny]

Since I don't have write permissio to this repository, I can't check tem,

I have checked the Metadata tests and did an additional audit. All checked items are implemented, non-checked items are human-only tests.

[Markus Sabadello]

Update: After merging #86, all statements in 7.1 and 7.2 should have tests, except MAY and SHOULD statements, as well as the following three MUST statements that we decided don't need tests:

• A conforming DID Method specification MUST guarantee that each equivalentId value is logically equivalent to the id property value.
• equivalentId is a much stronger form of equivalence than alsoKnownAs because the equivalence MUST be guaranteed by the governing DID method.
• A conforming DID Method specification MUST guarantee that the canonicalId value is logically equivalent to the id property value.

[Manu Sporny]

PR #86 has been merged. Marking as pending close.