Clarify why the @set keyword exists in the JSON-LD Syntax specification
authorMarkus Lanthaler <mark_lanthaler@gmx.net>
Tue, 04 Dec 2012 22:54:18 +0100
changeset 990 a44c5d256b0b
parent 989 3c7ad5946d51
child 991 a982f900734e
Clarify why the @set keyword exists in the JSON-LD Syntax specification

This addresses #170.
spec/latest/json-ld-syntax/index.html
--- a/spec/latest/json-ld-syntax/index.html	Tue Dec 04 22:37:08 2012 +0100
+++ b/spec/latest/json-ld-syntax/index.html	Tue Dec 04 22:54:18 2012 +0100
@@ -376,8 +376,9 @@
 <dd>Used to express an ordered set of data.
   This keyword is described in the section titled <a href="#sets-and-lists"></a>.</dd>
 <dt><code>@set</code></dt>
-<dd>Used to express an unordered set of data.
-  This keyword is described in the section titled <a href="#sets-and-lists"></a>.</dd>
+<dd>Used to express an unordered set of data and to ensure that values are always
+  represented as arrays. This keyword is described in the section titled
+  <a href="#sets-and-lists"></a>.</dd>
 <dt><code>@vocab</code></dt>
 <dd>Used to expand properties and values in <code>@type</code> with a common prefix
   <tref>IRI</tref>. This keyword is described in section <a href="#iris"></a>.</dd>
@@ -2778,10 +2779,15 @@
 <p>A <tref>list</tref> represents an <em>ordered</em> set of values.
   A <tdef>set</tdef> represents an <em>unordered</em> set of values.
   Unless otherwise specified (typically through the use of a <tref>list</tref>),
-  <tref title="array">arrays</tref> are unordered in JSON-LD.
-  As such, the <code>@set</code> keyword is not stricto senso necessary.
-  It is defined for symmetry with the <code>@list</code> keyword.</p>
-</p>
+  <tref title="array">arrays</tref> are unordered in JSON-LD. As such, the
+  <code>@set</code> keyword, when used in the body of a JSON-LD document,
+  represents just syntactic sugar which is optimized away when processing the document.
+  However, it is very helpful when used within the context of a document. Values
+  of terms associated with a <code>@set</code> or <code>@list</code> container
+  will always be represented in the form of an array when a document is processed -
+  even if there is just a single value that would otherwise be optimized to
+  a non-array form in <a href="#compact-document-form">compact document form</a>.
+  This simplifies post-processing of the data as the data is always in array form.</p>
 
 <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>