Normative statements checklist: 6. Representations

[Amy Guy]

6.1 Production and Consumption

• A representation MUST define deterministic production and consumption rules for all data types specified in § 4. Data Model.
• A representation MUST be uniquely associated with an IANA-registered Media Type.
• A representation MUST define fragment processing rules for its Media Type that are conformant with the fragment processing rules defined in § Fragment.
• A representation SHOULD use the lexical representation of data model data types.
• In order to maximize interoperability, representation specification authors SHOULD register their representation in the DID Specification Registries [DID-SPEC-REGISTRIES].
• A conforming producer MUST take a DID document data model and a representation-specific entries map as input into the production process.
• A conforming producer MUST serialize all entries in the DID document data model, and the representation-specific entries map, that do not have explicit processing rules for the representation being produced using only the representation's data type processing rules and return the serialization after the production process completes.
• A conforming producer MUST return the Media Type string associated with the representation after the production process completes.
• A conforming producer MUST NOT produce non-conforming DIDs or DID documents.
• A conforming consumer MUST take a representation and Media Type string as input into the consumption process.
• A conforming consumer MUST determine the representation of a DID document using the Media Type input string.
• A conforming consumer MUST detect any representation-specific entry across all known representations and place the entry into a representation-specific entries map which is returned after the consumption process completes.
• A conforming consumer MUST add all non-representation-specific entries that do not have explicit processing rules for the representation being consumed to the DID document data model using only the representation's data type processing rules and return the DID document data model after the consumption process completes.
• A conforming consumer MUST produce errors when consuming non-conforming DIDs or DID documents.

6.2.1 [JSON] Production

• The DID document, DID document data structures, and representation-specific entries map MUST be serialized to the JSON representation according to the following production rules:
• map: A JSON Object, where each entry is serialized as a member of the JSON Object with the entry key as a JSON String member name and the entry value according to its type, as defined in this table.
• list: A JSON Array, where each element of the list is serialized, in order, as a value of the array according to its type, as defined in this table.
• set :A JSON Array, where each element of the set is added, in order, as a value of the array according to its type, as defined in this table.
• datetime: A JSON String serialized as an XML Datetime normalized to UTC 00:00:00 and without sub-second decimal precision.
• string: A JSON String.
• integer: A JSON Number without a decimal or fractional component.
• double: A JSON Number with a decimal and fractional component.
• boolean: A JSON Boolean.
• null: A JSON null literal.
• All entries of a DID document MUST be included in the root JSON Object.
• When serializing a DID document, a conforming producer MUST specify a media type of application/did+json to downstream applications such as described in § 7.1.2 DID Resolution Metadata.

6.2.2 [JSON] Consumption

• The DID document and DID document data structures JSON representation MUST be deserialized into the data model according to the following consumption rules:
• JSON Object: A map, where each member of the JSON Object is added as an entry to the map. Each entry key is set as the JSON Object member name. Each entry value is set by converting the JSON Object member value according to the JSON representation type as defined in this table. Since order is not specified by JSON Objects, no insertion order is guaranteed.
• JSON Array where the data model entry value is a list or unknown: A list, where each value of the JSON Array is added to the list in order, converted based on the JSON representation type of the array value, as defined in this table.
• JSON Array where the data model entry value is a set: A set, where each value of the JSON Array is added to the set in order, converted based on the JSON representation type of the array value, as defined in this table.
• JSON String where data model entry value is a datetime: A datetime.
• JSON String, where the data model entry value type is string or unknown: A string.
• JSON Number without a decimal or fractional component: An integer.
• JSON Number with a decimal and fractional component, or when entry value is a double regardless of inclusion of fractional component: A double.
• JSON Boolean: A boolean.
• JSON null literal: A null value.
• If media type information is available to a conforming consumer and the media type value is application/did+json, then the data structure being consumed is a DID document, and the root element MUST be a JSON Object where all members of the object are entries of the DID document.
• A conforming consumer for a JSON representation that is consuming a DID document with a root element that is not a JSON Object MUST report an error.

6.3.1 [JSON-LD] Production

• The DID document, DID document data structures, and representation-specific entries map MUST be serialized to the JSON-LD representation according to the JSON representation production rules as defined in § 6.2 JSON.
• In addition to using the JSON representation production rules, JSON-LD production MUST include the representation-specific @context entry.
• The serialized value of @context MUST be the JSON String https://www.w3.org/ns/did/v1, or a JSON Array where the first item is the JSON String https://www.w3.org/ns/did/v1 and the subsequent items are serialized according to the JSON representation production rules.
• all JSON-LD Contexts and their terms SHOULD be registered in the DID Specification Registries [DID-SPEC-REGISTRIES].
• A conforming producer that generates a JSON-LD representation SHOULD NOT produce a DID document that contains terms not defined via the @context as conforming consumers are expected to remove unknown terms.
• When serializing a JSON-LD representation of a DID document, a conforming producer MUST specify a media type of application/did+ld+json to downstream applications such as described in § 7.1.2 DID Resolution Metadata.

6.3.2 [JSON-LD] Consumption

• The DID document and any DID document data structures expressed by a JSON-LD representation MUST be deserialized into the data model according to the JSON representation consumption rules as defined in § 6.2 JSON.
• Conforming consumers that process a JSON-LD representation SHOULD drop all terms from a DID document that are not defined via the @context.

6.4.1 [CBOR] Production

• The DID document, DID document data structures, and representation-specific entries map MUST be serialized to the CBOR representation according to the following production rules:
• map :A CBOR map (major type 5), where each entry is represented as a member of the CBOR map. The entry key is expressed as a CBOR string (major type 3) as the key, and the entry value according to its type, as defined in this table.
• list: A CBOR array (major type 4), where each element of the list is added, in order, as a value of the array according to its type, as defined in this table.
• set: A CBOR array (major type 4), where each element of the list is added, in order, as a value of the array according to its type, as defined in this table.
• datetime: A CBOR string (major type 3) formatted as an XML Datetime normalized to UTC 00:00 and without sub-second decimal precision. For example: 2020-12-20T19:17:47Z.
• string: A CBOR string (major type 3).
• integer: A CBOR integer (major type 0 or 1), choosing the shortest byte representation.
• double: A CBOR floating-point number (major type 7). All floating point values MUST be encoded as 64-bits (additional type value 27), even for integral values.
• boolean: A CBOR simple value (major type 7, subtype 24) with a simple value of 21 (true) or 20 (false).
• null: A CBOR simple value (major type 7, subtype 24) with a simple value of 22 (null).
• Indefinite-length items are not allowed and MUST be made a CBOR definite length.
• All CBOR tags MUST be retained regardless of whether they are optional.
• All four Canonical CBOR rules listed in [RFC8949] MUST be applied to all relevant data types.
• All entries of a DID document MUST be included in the root CBOR map (major type 5).
• When serializing a DID document to its CBOR representation, a conforming producer MUST specify a media type of application/did+cbor to downstream applications such as described in § 7.1.2 DID Resolution Metadata.

6.4.2 [CBOR] Consumption

• The DID document and any DID document data structures expressed by the data model MUST be deserialized into the data model according to the following consumption rules:
• CBOR map (major type 5): A map, where each data item of the CBOR map is added as an entry to the map with the entry key being the data item name and the value converted based on the CBOR type and, if available, entry definition, as defined here; as no order can be enforced for general CBOR maps, no insertion order is guaranteed.
• CBOR array (major type 4), where the data model entry value is a list or unknown: A list, where each value of the CBOR array is added to the list in order, converted based on the CBOR type of the array value, as defined in this table.
• CBOR array (major type 4), where the data model entry value is a set: A set, where each value of the CBOR array is added to the set in order, converted based on the CBOR type of the array value as defined in this table.
• CBOR string (major type 3) where the data model entry value is a datetime: A datetime.
• CBOR string (major type 3), where the data model entry value type is string or unknown: A string.
• CBOR integer (major type 0 or 1), choosing the shortest byte representation: An integer.
• CBOR floating-point number (major type 7): A double.
• CBOR simple value (major type 7, subtype 24) with a simple value of 21 (True) or 20 (False): A boolean.
• CBOR simple value (major type 7, subtype 24) with a simple value of 22 (Null): A null value.
• CBOR indefinite-length items are not allowed and MUST produce an error.
• A duplicate key in the same CBOR map MUST produce an error.
• All CBOR tags MUST be retained for CBOR production regardless of whether they are optional.
• If media type information is available to a conforming consumer and the media type value is application/did+cbor, then the data structure being consumed is a DID document, and the root element MUST be a CBOR map (major type 5) where all members of the object are entries of the DID document.
• A conforming consumer for a CBOR representation that is consuming a DID document with a root element that is not a CBOR map (major type 5) MUST report an error.

[Manu Sporny]

I have reviewed all general Production and Consumption tests as well as all JSON-LD-specific Production and Consumption tests: All tests with ticked checkboxes exist in the test suite; all tests that are not checked are not mandatory or are human-only tests and do not have active/associated tests in the test suite.

The JSON-specific and CBOR-specific tests still need to be audited.

[Manu Sporny]

I have just implemented and audited the JSON-specific production and consumption tests. All JSON-specific production and consumption tests with ticked checkboxes exist in the test suite; there are no human-only tests for JSON production or consumption.

[Manu Sporny]

CBOR has been removed from the specification. This means that all tests that we intended to write for the Representations section have been written and audited. This issue can be closed now.