diff --git a/index.html b/index.html index 2ed1a3ce..c4868d12 100644 --- a/index.html +++ b/index.html @@ -1,4 +1,4 @@ - + @@ -2565,28 +2565,20 @@ <h2>Representation Requirements</h2> </section> <section> - <h2> -JSON - </h2> + <h2>JSON</h2> <p> -This section sets out the requirements for producing and consuming <a>DID -documents</a> that are in plain JSON (as indicated by a -<code>contentType</code> of <code>application/did+json</code> in the resolver -metadata). +This section defines the <a>production</a> and <a>consumption</a> rules +for the JSON <a>representation</a>. </p> <section> <h3>Production</h3> <p> -A <a>DID document</a> MUST be a single <a data-cite="RFC8259#section-4">JSON -object</a> conforming to [[!RFC8259]]. All entries of the <a>DID -document</a> data model described in <a href="#data-model"></a> -MUST be represented by using the entry key as the name of the -member of the JSON object. The values of entries, -including all extensions, are encoded in JSON [[RFC8259]] by mapping entry -values to JSON types as follows: +The <a>DID document</a> and any DID document data structures expressed by the <a href="#data-model">data model</a> +MUST be serialized to the JSON <a>representation</a> according to the +following <a>production</a> rules: </p> <table class="simple" id="json-representation-production"> @@ -2607,9 +2599,10 @@ <h3>Production</h3> <a data-cite="INFRA#maps">ordered map</a> </td> <td> -<a data-cite="RFC8259#section-4">JSON Object</a>, each entry is represented -as a member of the JSON Object with the entry key as the member name and the -entry value according to its type, as defined in this section +A <a data-cite="RFC8259#section-4">JSON Object</a>, where each entry is +serialized as a member of the JSON Object with the entry key as a <a +data-cite="RFC8259#section-7">JSON String</a> member name and the entry value +according to its type, as defined in this table. </td> </tr> <tr> @@ -2617,9 +2610,9 @@ <h3>Production</h3> <a data-cite="INFRA#list">list</a> </td> <td> -<a data-cite="RFC8259#section-5">JSON Array</a>, each element of the list is -added, in order, as a value of the array according to its type, as defined in -this section +A <a data-cite="RFC8259#section-5">JSON Array</a>, 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. </td> </tr> <tr> @@ -2627,9 +2620,9 @@ <h3>Production</h3> <a data-cite="INFRA#ordered-set">ordered set</a> </td> <td> -<a data-cite="RFC8259#section-5">JSON Array</a>, each element of the set is -added, in order, as a value of the array according to its type, as defined in -this section +A <a data-cite="RFC8259#section-5">JSON Array</a>, 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. </td> </tr> <tr> @@ -2637,7 +2630,7 @@ <h3>Production</h3> <a>datetime</a> </td> <td> -<a data-cite="RFC8259#section-7">JSON String</a> formatted as an +A <a data-cite="RFC8259#section-7">JSON String</a> serialized as an <a data-cite="XMLSCHEMA11-2#dateTime">XML Datetime</a> normalized to UTC 00:00:00 and without sub-second decimal precision. For example: <code>2020-12-20T19:17:47Z</code>. @@ -2648,7 +2641,7 @@ <h3>Production</h3> <a data-cite="INFRA#string">string</a> </td> <td> -<a data-cite="RFC8259#section-7">JSON String</a> +A <a data-cite="RFC8259#section-7">JSON String</a>. </td> </tr> <tr> @@ -2656,8 +2649,8 @@ <h3>Production</h3> <a>integer</a> </td> <td> -<a data-cite="RFC8259#section-6">JSON Number</a> without a decimal or -fractional component +A <a data-cite="RFC8259#section-6">JSON Number</a> without a decimal or +fractional component. </td> </tr> <tr> @@ -2665,7 +2658,8 @@ <h3>Production</h3> <a>double</a> </td> <td> -<a data-cite="RFC8259#section-6">JSON Number</a> with a fractional component +A <a data-cite="RFC8259#section-6">JSON Number</a> with a decimal and +fractional component. </td> </tr> <tr> @@ -2673,7 +2667,7 @@ <h3>Production</h3> <a data-cite="INFRA#boolean">boolean</a> </td> <td> -<a data-cite="RFC8259#section-3">JSON Boolean</a> +A <a data-cite="RFC8259#section-3">JSON Boolean</a>. </td> </tr> <tr> @@ -2681,22 +2675,28 @@ <h3>Production</h3> <a data-cite="INFRA#null">null</a> </td> <td> -<a data-cite="RFC8259#section-3">JSON null literal</a> +A <a data-cite="RFC8259#section-3">JSON null literal</a>. </td> </tr> </tbody> </table> - <p> -Implementers producing JSON are advised to ensure that their algorithms are -aligned with the <a data-cite="INFRA#json">JSON serialization rules</a> in -the [[INFRA]] specification. + <p class="advisement" title="INFRA JSON serialization rules"> +All implementers creating <a>conforming producers</a> that produce JSON +<a>representations</a> are advised to ensure that their algorithms are aligned +with the <a data-cite="INFRA#json">JSON serialization rules</a> in the [[INFRA]] +specification and the +<a data-cite="RFC7159#section-6">precision advisements regarding Numbers</a> +in the JSON [[RFC7159]] specification. </p> <p> -All entries of the <a>DID document</a> MUST be included in -the root object. Entries MAY define additional data sub structures subject -to the value representation rules in the list above. +All entries of a <a>DID document</a> MUST be included in the root <a +data-cite="RFC8259#section-4">JSON Object</a>. Entries MAY contain additional +data substructures subject to the value representation rules in the list above. +When serializing a <a>DID document</a>, a <a>conforming producer</a> MUST +specify a media type of <code>application/did+json</code> to downstream +applications such as described in <a href="#did-resolution-metadata"></a>. </p> </section> @@ -2705,17 +2705,15 @@ <h3>Production</h3> <h3>Consumption</h3> <p> -The topmost element MUST be a JSON object. Any other data type at the topmost -level is an error and MUST be rejected. The topmost JSON object represents the -<a>DID document</a>, and all members of this object are entries of the <a>DID -document</a>. The object member name is the entry key, and the member value -is interpreted as follows: +The <a>DID document</a> and any DID document data structures expressed by a JSON <a>representation</a> MUST be +deserialized into the <a href="#data-model">data model</a> according to the +following <a>consumption</a> rules: </p> <table class="simple" id="json-representation-consumption"> <thead> <tr> - <th> + <th width="50%"> JSON Representation Type </th> <th> @@ -2730,53 +2728,54 @@ <h3>Consumption</h3> <a data-cite="RFC8259#section-4">JSON Object</a> </td> <td> -<a data-cite="INFRA#maps">ordered map</a>, each member of the JSON Object -is added as an entry to the ordered map with the entry key being the -member name and the value converted based on the JSON type and, if available, -entry definition, as defined here; as no order is specified by JSON Objects, -no insertion order is guaranteed +An <a data-cite="INFRA#maps">ordered map</a>, where each member of the JSON +Object is added as an entry to the ordered 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. </td> </tr> <tr> <td> -<a data-cite="RFC8259#section-5">JSON Array</a> where <a href="#data-model">data -model</a> entry value is a <a data-cite="INFRA#list">list</a> or unknown +<a data-cite="RFC8259#section-5">JSON Array</a> where the <a +href="#data-model">data model</a> entry value is a <a +data-cite="INFRA#list">list</a> or unknown </td> <td> -<a data-cite="INFRA#list">list</a>, each value of the JSON Array is added to the -list in order, converted based on the JSON type of the array value, as defined -here +A <a data-cite="INFRA#list">list</a>, 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. </td> </tr> <tr> <td> -<a data-cite="RFC8259#section-5">JSON Array</a> where <a href="#data-model">data -model</a> entry value is an <a +<a data-cite="RFC8259#section-5">JSON Array</a> where the <a +href="#data-model">data model</a> entry value is an <a data-cite="INFRA#ordered-set">ordered set</a> </td> <td> -<a data-cite="INFRA#ordered-set">ordered set</a>, each value of the JSON -Array is added to the ordered set in order, converted based on the JSON type of -the array value, as defined here +An <a data-cite="INFRA#ordered-set">ordered set</a>, where each value of +the JSON Array is added to the ordered set in order, converted based on the JSON +representation type of the array value, as defined in this table. </td> </tr> <tr> <td> <a data-cite="RFC8259#section-7">JSON String</a> where <a -href="#data-model">data model</a> entry value is an <a>datetime</a> +href="#data-model">data model</a> entry value is a <a>datetime</a> </td> <td> -<a>datetime</a> +A <a>datetime</a>. </td> </tr> <tr> <td> -<a data-cite="RFC8259#section-7">JSON String</a>, where <a +<a data-cite="RFC8259#section-7">JSON String</a>, where the <a href="#data-model">data model</a> entry value type is <a>string</a> or unknown </td> <td> -<a data-cite="INFRA#string">string</a> +A <a data-cite="INFRA#string">string</a>. </td> </tr> <tr> @@ -2785,17 +2784,17 @@ <h3>Consumption</h3> fractional component </td> <td> -<a>integer</a> +An <a>integer</a>. </td> </tr> <tr> <td> -<a data-cite="RFC8259#section-6">JSON Number</a> with a fractional component, or -when entry value is a <a>double</a> regardless of inclusion of fractional -component +<a data-cite="RFC8259#section-6">JSON Number</a> with a decimal and fractional +component, or when entry value is a <a>double</a> regardless of inclusion of +fractional component </td> <td> -<a>double</a> +A <a>double</a>. </td> </tr> <tr> @@ -2803,7 +2802,7 @@ <h3>Consumption</h3> <a data-cite="RFC8259#section-3">JSON Boolean</a> </td> <td> -<a data-cite="INFRA#boolean">boolean</a> +A <a data-cite="INFRA#boolean">boolean</a>. </td> </tr> <tr> @@ -2811,25 +2810,34 @@ <h3>Consumption</h3> <a data-cite="RFC8259#section-3">JSON null literal</a> </td> <td> -<a data-cite="INFRA#null">null</a> +A <a data-cite="INFRA#null">null</a> value. </td> </tr> </tbody> </table> - <p> -Implementers consuming JSON are advised to ensure that their algorithms are -aligned with the <a + <p class="advisement"> +All implementers creating <a>conforming consumers</a> that produce JSON +<a>representations</a> are advised to ensure that their algorithms are aligned +with the <a data-cite="INFRA#convert-a-json-derived-javascript-value-to-an-infra-value">JSON -consumption rules</a> in the [[INFRA]] specification. +conversion rules</a> in the [[INFRA]] specification and the <a +data-cite="RFC7159#section-6">precision advisements regarding Numbers</a> in the +JSON [[RFC7159]] specification. </p> + <p> -Note that the <code>@context</code> object member, if present, will not have -additional processing applied to its value, which will be added verbatim to the -<a href="#data-model">data model</a>. +If media type information is available to a <a>conforming consumer</a> and the +media type value is <code>application/did+json</code>: the data structure +being consumed is a <a>DID document</a> and the root element MUST be a <a +data-cite="RFC8259#section-4">JSON Object</a> where all members of the object +are entries of the <a>DID document</a>. A <a>conforming consumer</a> for a JSON +<a>representation</a> that is consuming a <a>DID document</a> with a root +element that is not a <a data-cite="RFC8259#section-4">JSON Object</a> MUST +report an error. </p> - </section> + </section> </section> <section>