Skip to content

Commit 05ef43f

Browse files
committed
Clarify why the @set keyword exists in the JSON-LD Syntax specification
This addresses #170.
1 parent 16e4dc8 commit 05ef43f

File tree

1 file changed

+12
-6
lines changed

1 file changed

+12
-6
lines changed

spec/latest/json-ld-syntax/index.html

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -376,8 +376,9 @@ <h2>Syntax Tokens and Keywords</h2>
376376
<dd>Used to express an ordered set of data.
377377
This keyword is described in the section titled <a href="#sets-and-lists"></a>.</dd>
378378
<dt><code>@set</code></dt>
379-
<dd>Used to express an unordered set of data.
380-
This keyword is described in the section titled <a href="#sets-and-lists"></a>.</dd>
379+
<dd>Used to express an unordered set of data and to ensure that values are always
380+
represented as arrays. This keyword is described in the section titled
381+
<a href="#sets-and-lists"></a>.</dd>
381382
<dt><code>@vocab</code></dt>
382383
<dd>Used to expand properties and values in <code>@type</code> with a common prefix
383384
<tref>IRI</tref>. This keyword is described in section <a href="#iris"></a>.</dd>
@@ -2778,10 +2779,15 @@ <h2>List and Set Values</h2>
27782779
<p>A <tref>list</tref> represents an <em>ordered</em> set of values.
27792780
A <tdef>set</tdef> represents an <em>unordered</em> set of values.
27802781
Unless otherwise specified (typically through the use of a <tref>list</tref>),
2781-
<tref title="array">arrays</tref> are unordered in JSON-LD.
2782-
As such, the <code>@set</code> keyword is not stricto senso necessary.
2783-
It is defined for symmetry with the <code>@list</code> keyword.</p>
2784-
</p>
2782+
<tref title="array">arrays</tref> are unordered in JSON-LD. As such, the
2783+
<code>@set</code> keyword, when used in the body of a JSON-LD document,
2784+
represents just syntactic sugar which is optimized away when processing the document.
2785+
However, it is very helpful when used within the context of a document. Values
2786+
of terms associated with a <code>@set</code> or <code>@list</code> container
2787+
will always be represented in the form of an array when a document is processed -
2788+
even if there is just a single value that would otherwise be optimized to
2789+
a non-array form in <a href="#compact-document-form">compact document form</a>.
2790+
This simplifies post-processing of the data as the data is always in array form.</p>
27852791

27862792
<p>A <tref>list</tref> MUST be a <tref>JSON object</tref> that contains a single key-value pair where the key is <code>@list</code>.</p>
27872793

0 commit comments

Comments
 (0)