--- 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>