Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix editorial and substantive issues in JSON Production and Consumption section. #653

Merged
merged 5 commits into from
Feb 17, 2021
Merged

Fix editorial and substantive issues in JSON Production and Consumption section. #653

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d2bce4f
Fix editorial and substantive issues in JSON Production section.
msporny Feb 15, 2021
11c48bc
Fix editorial and substantive issues with JSON Consumption section.
msporny Feb 15, 2021
19fc979
Apply suggestions to JSON Production/Consumption from @rhiaro and @Ta…
msporny Feb 17, 2021
dea98e0
Apply fix to JSON Consumption from @rhiaro.
msporny Feb 17, 2021
fd066c8
Apply changes requested to JSON section by @peacekeeper.
msporny Feb 17, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 85 additions & 77 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand All @@ -2607,37 +2599,38 @@ <h3>Production</h3>
<a data-cite="INFRA#maps">ordered&nbsp;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>
<td>
<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>
<td>
<a data-cite="INFRA#ordered-set">ordered&nbsp;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>
<td>
<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>.
Expand All @@ -2648,55 +2641,62 @@ <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>
<td>
<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>
<td>
<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>
<td>
<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>
<td>
<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>
Expand All @@ -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>
Expand All @@ -2730,53 +2728,54 @@ <h3>Consumption</h3>
<a data-cite="RFC8259#section-4">JSON Object</a>
</td>
<td>
<a data-cite="INFRA#maps">ordered&nbsp;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&nbsp;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&nbsp;set</a>
</td>
<td>
<a data-cite="INFRA#ordered-set">ordered&nbsp;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&nbsp;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>
Expand All @@ -2785,52 +2784,61 @@ <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>
<td>
<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>
<td>
<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>
<h2>
Expand Down