--- a/spec/latest/json-ld-api/index.html Thu Mar 22 17:24:58 2012 +0800
+++ b/spec/latest/json-ld-api/index.html Thu Mar 22 20:09:13 2012 +0800
@@ -711,6 +711,7 @@
<dt><code>@value</code></dt><dd>Used to specify the value of a literal.</dd>
<dt><code>@container</code></dt><dd>Used to set the container of a particular value.</dd>
<dt><code>@list</code></dt><dd>Used to express an ordered set of data.</dd>
+ <dt><code>@set</code></dt><dd>Used to express an unordered set of data.</dd>
<dt><code>:</code></dt><dd>The separator for JSON keys and values that use <tref title="compact_iri">compact IRIs</tref>.</dd>
</dl>
@@ -811,8 +812,8 @@
<p>The <tref>active context</tref> is used for expanding keys and values of a <tref>JSON object</tref> (or elements
of a list (see <span a="#list-processing">List Processing</span>)) using a <tdef>term mapping</tdef>.
It is also used to maintain
- <tdef>coercion mapping</tdef>s from <tref>IRI</tref>s associated with terms to datatypes, and
- <tdef>list mapping</tdef>s for IRIs associated with terms.</p>
+ <tdef>coercion mapping</tdef>s from <tref>IRI</tref>s associated with terms to datatypes,
+ <tdef>list mapping</tdef>s, and <tdef>set mapping</tdef>s for IRIs associated with terms.</p>
<p>A <tref>local context</tref> is identified within a <tref>JSON object</tref> having a key of
<code>@context</code> with <tref>string</tref>, <tref>array</tref> or a <tref>JSON object</tref> value.
When processing a <tref>local context</tref>, special processing rules apply:</p>
@@ -868,8 +869,8 @@
IRI mapping is an <tref>absolute IRI</tref> or <code>@id</code>, merge into the <tref>local context</tref>
<tref>coercion mapping</tref>.</li>
<li>If the value has a <code>@container</code> key, the value MUST be
- <code>@list</code>. Merge into the <tref>local context</tref> <tref>list
- mapping</tref>.</li>
+ <code>@list</code> or <code>@set</code>. Merge the <tref>list mapping</tref> or
+ <tref>set mapping</tref> into the <tref>local context</tref>.</li>
</ol>
</li>
<li>Merge the <tref>local context</tref> into the <tref>active context</tref>.</li>
@@ -1073,13 +1074,14 @@
<li>For each key and value in <em>value</em>:
<ol class="algorithm">
<li>If value is <tref>null</tref>, skip this key/value pair and remove key from <em>value</em></li>
- <li>Otherwise, if value is a <tref>JSON object</tref> having either a <code>@value</code> or
- <code>@list</code> key with a <tref>null</tref> value, skip this key/value pair and
+ <li>Otherwise, if value is a <tref>JSON object</tref> having either a <code>@value</code>,
+ <code>@list</code>, or <code>@set</code> key with a <tref>null</tref> value, skip this key/value pair
+ <li>Otherwise, if <em>value</em> is a <tref>JSON object</tref> having a <code>@set</code> key with a
+ non-<tref>null</tref> value, replace <em>value</em> with the value of <code>@set</code>.
<li>Otherwise, if the key is <code>@id</code> or <code>@type</code> and the value is a <tref>string</tref>,
expand the value according to <a href="#iri-expansion">IRI Expansion</a>.</li>
remove key from <em>value</em></li>
- <li>Otherwise, if the key is <code>@value</code>, the value MUST be a <tref>string</tref> and
- is not subject to further expansion.</li>
+ <li>Otherwise, if the key is <code>@value</code>, the value is not subject to further expansion.</li>
<li>Otherwise, if the key is not a <tref>keyword</tref>, expand the key according to
<a href="#iri-expansion">IRI Expansion</a> rules and set as <tref>active property</tref>.</li>
<li>If the value is an <tref>array</tref>, and <tref>active property</tref> is subject to <code>@list</code>
@@ -1207,6 +1209,8 @@
<li>Otherwise, if the value contains only a <code>@list</code> key, and the
<tref>active property</tref> is subject to list coercion, the compacted value is the result of
performing this algorithm on that value.</li>
+ <li>Otherwise, if the value contains only a <code>@set</code> key, the compacted value is the
+ value of <code>@set</code>.</li>
<li>Otherwise, the compacted value is the result of performing this algorithm on the value.</li>
</ol>
</li>
--- a/spec/latest/json-ld-syntax/index.html Thu Mar 22 17:24:58 2012 +0800
+++ b/spec/latest/json-ld-syntax/index.html Thu Mar 22 20:09:13 2012 +0800
@@ -370,7 +370,7 @@
<dt><tdef>array</tdef></dt>
<dd>
An array is an ordered collection of values. An array structure is represented as square brackets surrounding zero or more values (or elements). Elements are separated by commas. Within JSON-LD, array order is not preserved by default, unless
- specific markup is provided (see <a href="#lists">Lists</a>). This is because the basic data model of JSON-LD
+ specific markup is provided (see <a href="#sets-and-lists">Sets and Lists</a>). This is because the basic data model of JSON-LD
is a <tref>linked data graph</tref>, which is inherently unordered.
</dd>
<dt><tdef>string</tdef></dt><dd>
@@ -427,10 +427,13 @@
<a href="#typed-values">Typed Values</a>.</dd>
<dt><code>@container</code></dt>
<dd>Used to set the container of a particular value.
- This keyword is described in the section titled <a href="#lists">Lists</a>.</dd>
+ This keyword is described in the section titled <a href="#sets-and-lists">Sets and Lists</a>.</dd>
<dt><code>@list</code></dt>
<dd>Used to express an ordered set of data.
- This keyword is described in the section titled <a href="#lists">Lists</a>.</dd>
+ This keyword is described in the section titled <a href="#sets-and-lists">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">Sets and Lists</a>.</dd>
<dt><code>:</code></dt>
<dd>The separator for JSON keys and values that use
<tref title="compact_iri">compact IRIs</tref>.</dd>
@@ -1093,18 +1096,14 @@
</section>
<section>
-<h2>Multiple Objects for a Single Property</h2>
+<h2>Sets and Lists</h2>
<p>A JSON-LD author can express multiple values in a compact way by using
-<tref>array</tref>s. If a subject has multiple values for the same property,
-the author MAY express each property as an <tref>array</tref>.</p>
-
-<p class="note">In JSON-LD, multiple objects on a property are not ordered.
-This is because graphs are inherently unordered data structures. To learn
-more about creating ordered collections in JSON-LD, see the
-section on <a href="#lists">Lists</a>.
-</p>
-
+ <tref>array</tref>s. But, because graphs do not describe ordering for links
+ between nodes, in contrast to plain JSON, arrays in JSON-LD do not provide
+ an ordering of the listed objects by default. For example, consider the
+ following
+ simple document:</p>
<pre class="example" data-transform="updateExample">
<!--
{
@@ -1116,8 +1115,8 @@
-->
</pre>
-<p>The markup shown above would generate the following triples:</p>
-
+<p>The markup shown above would result in three triples being generated,
+ each relating the subject to an individual object, with no inherent order:</p>
<pre class="example" data-transform="updateExample">
<!--
<http://example.org/people#joebob>
@@ -1132,13 +1131,7 @@
-->
</pre>
-</section>
-
-<section>
-<h2>Multiple Values for a Single Property</h2>
-
-<p>Multiple <tref>value</tref>s may also be expressed using the expanded
-form for <tref>object</tref>s:</p>
+<p>Multiple values may also be expressed using the expanded object form:</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -1158,7 +1151,8 @@
}-->
</pre>
-<p>The markup shown above would generate the following triples:</p>
+<p>The markup shown above would generate the following triples, again with
+ no inherent order:</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -1171,79 +1165,68 @@
-->
</pre>
-</section>
-<section>
- <h2>Lists</h2>
- <p>
- Because graphs do not describe ordering for links between nodes, in contrast to plain JSON, multi-valued properties
- in JSON-LD do not provide an ordering of the listed objects. For example, consider the following
- simple document:
- </p>
- <pre class="example" data-transform="updateExample">
- <!--
- {
- ...
- "@id": "http://example.org/people#joebob",
- "nick": ****[ "joe", "bob", "jaybee" ]****,
- ...
- }
- -->
- </pre>
- <p>
- This results in three triples being generated, each relating the subject
- to an individual object, with no inherent order.</p>
- <p>
- As the notion of ordered collections is rather important in data
- modeling, it is useful to have specific language support. In JSON-LD,
- a list may be represented using the <code>@list</code> keyword as follows:
- </p>
- <pre class="example" data-transform="updateExample">
- <!--
+<p>As the notion of ordered collections is rather important in data
+ modeling, it is useful to have specific language support. In JSON-LD,
+ a list may be represented using the <code>@list</code> keyword as follows:</p>
+<pre class="example" data-transform="updateExample">
+<!--
+{
+...
+ "@id": "http://example.org/people#joebob",
+ "foaf:nick":
+ ****{
+ "@list": [ "joe", "bob", "jaybee" ]
+ }****,
+...
+}
+-->
+</pre>
+
+<p>This describes the use of this <tref>array</tref> as being ordered,
+ and order is maintained through operations such as
+ <a href="expansion">Expansion</a>, <a href="compaction">Compaction</a>,
+ <a href="framing">Framing</a>, and <a href="normalization">Normalization</a>.
+ If every use of a given multi-valued property is a list, this may be
+ abbreviated by setting <code>@container</code> to <code>@list</code> in
+ the <tref>context</tref>:</p>
+<pre class="example" data-transform="updateExample">
+<!--
+{
+ ****"@context":
{
- ...
- "@id": "http://example.org/people#joebob",
- "foaf:nick":
- ****{
- "@list": [ "joe", "bob", "jaybee" ]
- }****,
- ...
- }
- -->
- </pre>
- <p>
- This describes the use of this <tref>array</tref> as being ordered,
- and order is maintained through alternate representations as
- described in [[JSON-LD-API]]. If every use of a given multi-valued property
- is a list, this may be abbreviated by setting <code>@container</code> to
- <code>@list</code> in the <tref>context</tref>:
- </p>
- <pre class="example" data-transform="updateExample">
- <!--
- {
- ****"@context":
+ ...
+ "nick":
{
- ...
- "nick":
- {
- "@id": "http://xmlns.com/foaf/0.1/nick",
- "@container": "@list"
- }
- }****,
- ...
- "@id": "http://example.org/people#joebob",
- "nick": ****[ "joe", "bob", "jaybee" ]****,
- ...
- }
- -->
- </pre>
- <p>List coercion is specified within an expanded <tref>term</tref>
- definition using the <code>@container</code> key. The value of this key,
- if present, MUST be <code>@list</code>. This indicates that array values
- of keys coerced as <code>@list</code> are to be serialized as a
- <a href="#lists">List</a>.</p>
- <p class="note">List of lists are not allowed in this version of JSON-LD.
- If a list of lists is detected, a JSON-LD processor will throw an exception.</p>
+ "@id": "http://xmlns.com/foaf/0.1/nick",
+ "@container": "@list"
+ }
+ }****,
+...
+ "@id": "http://example.org/people#joebob",
+ "nick": ****[ "joe", "bob", "jaybee" ]****,
+...
+}
+-->
+</pre>
+
+<p class="note">List of lists are not allowed in this version of JSON-LD.
+ If a list of lists is detected, a JSON-LD processor will throw an exception.</p>
+
+<p>Similarly to <code>@list</code>, there exists the keyword <code>@set</code> to
+ describe unordered sets. While its use in the body of a JSON-LD document
+ represents just syntactic sugar that MUST be optimized away when processing
+ the document, it is very helpful for <a href="compaction">Compaction</a>
+ and <a href="framing">Framing</a>. The value of terms associated with a
+ <code>@set</code> or <code>@list</code> <code>@container</code> are always
+ represented in the form of an <tref>array</tref> - even if there is just a
+ single value. This makes post-processing of the data easier as the data is
+ in a deterministic form. If no such <code>@container</code> is specified,
+ single values are optimized to a non-array form.</p>
+
+<p class="note">The use of <code>@container</code> in the body of a JSON-LD
+ document, i.e., outside <code>@context</code> is ignored by JSON-LD processors.</p>
+
</section>
</section>
@@ -1664,7 +1647,7 @@
defined using an expanded notation to allow for additional information
associated with the term to be specified (see
<a href="#type-coerceion">Type Coercion</a> and
- <a href="#lists">Lists</a>).</p>
+ <a href="#sets-and-lists">Sets and Lists</a>).</p>
<p>Instead of using a string representation of an IRI, the IRI MAY be
specified using an object having an <code>@id</code> key.