--- a/spec/latest/json-ld-syntax/index.html Fri Mar 08 19:10:47 2013 +0100
+++ b/spec/latest/json-ld-syntax/index.html Fri Mar 08 20:08:47 2013 +0100
@@ -309,54 +309,56 @@
that are a core part of the language:</p>
<dl>
- <dt><code>@context</code></dt>
- <dd>Used to define the short-hand names that are used throughout a JSON-LD
- document. These short-hand names are called <tref title="term">terms</tref> and help
- developers to express specific identifiers in a compact manner. The
- <code>@context</code> keyword is described in detail in the section titled
- <a href="#the-context"></a>.</dd>
- <dt><code>@id</code></dt>
- <dd>Used to uniquely identify <em>things</em> that are being described in the document.
- This keyword is described in <a href="#node-identifiers"></a>.</dd>
- <dt><code>@value</code></dt>
- <dd>Used to specify the data that is associated with a particular
- <tref>property</tref> in the graph. This keyword is described in
- <a href="#string-internationalization"></a> and
- <a href="#typed-values"></a>.</dd>
- <dt><code>@language</code></dt>
- <dd>Used to specify the natural (human) language for a particular value or the default
- language of a JSON-LD document. This keyword is described in the section titled
- <a href="#string-internationalization"></a>.</dd>
- <dt><code>@type</code></dt>
- <dd>Used to set the data type of a <tref>node</tref> or
- <tref>typed value</tref>. This keyword is described in the section titled
- <a href="#typed-values"></a>.</dd>
- <dt><code>@container</code></dt>
- <dd>Used to set the default container type for a <tref>term</tref>.
- This keyword is described in the section titled <a href="#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="#sets-and-lists"></a>.</dd>
- <dt><code>@set</code></dt>
- <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>@index</code></dt>
- <dd>Used to specify that a container is used to index information and
- that processing should continue deeper into a JSON data structure.
- This keyword is described in the section titled
- <a href="#data-indexing"></a>.</dd>
- <dt><code>@base</code></dt>
- <dd>Used to set the base IRI against which <tref title="relative IRI">relative IRIs</tref>
- are resoled. This keyword is described in section <a href="#base-iri"></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="#default-vocabulary"></a>.</dd>
- <dt><code>@graph</code></dt><dd>Used to explicitly label a <tref>JSON-LD graph</tref>.
- This keyword is described in <a href="#named-graphs"></a>.</dd>
- <dt><code>:</code></dt>
- <dd>The separator for JSON keys and values that use
- <tref title="compact iri">compact IRIs</tref>.</dd>
+ <dt><code>@context</code></dt>
+ <dd>Used to define the short-hand names that are used throughout a JSON-LD
+ document. These short-hand names are called <tref title="term">terms</tref> and help
+ developers to express specific identifiers in a compact manner. The
+ <code>@context</code> keyword is described in detail in section
+ <a href="#the-context"></a>.</dd>
+ <dt><code>@id</code></dt>
+ <dd>Used to uniquely identify <em>things</em> that are being described in the document.
+ This keyword is described in section <a href="#node-identifiers"></a>.</dd>
+ <dt><code>@value</code></dt>
+ <dd>Used to specify the data that is associated with a particular
+ <tref>property</tref> in the graph. This keyword is described in section
+ <a href="#string-internationalization"></a> and
+ <a href="#typed-values"></a>.</dd>
+ <dt><code>@language</code></dt>
+ <dd>Used to specify the natural (human) language for a particular value or the default
+ language of a JSON-LD document. This keyword is described in section
+ <a href="#string-internationalization"></a>.</dd>
+ <dt><code>@type</code></dt>
+ <dd>Used to set the data type of a <tref>node</tref> or
+ <tref>typed value</tref>. This keyword is described in section
+ <a href="#typed-values"></a>.</dd>
+ <dt><code>@container</code></dt>
+ <dd>Used to set the default container type for a <tref>term</tref>.
+ This keyword is described in section <a href="#sets-and-lists"></a>.</dd>
+ <dt><code>@list</code></dt>
+ <dd>Used to express an ordered set of data.
+ This keyword is described in section <a href="#sets-and-lists"></a>.</dd>
+ <dt><code>@set</code></dt>
+ <dd>Used to express an unordered set of data and to ensure that values are always
+ represented as arrays. This keyword is described in section
+ <a href="#sets-and-lists"></a>.</dd>
+ <dt><code>@reverse</code></dt>
+ <dd>Used to express reverse properties. This keyword is described in section
+ <a href="#reverse-properties"></a>.</dd>
+ <dt><code>@index</code></dt>
+ <dd>Used to specify that a container is used to index information and
+ that processing should continue deeper into a JSON data structure.
+ This keyword is described in section <a href="#data-indexing"></a>.</dd>
+ <dt><code>@base</code></dt>
+ <dd>Used to set the base IRI against which <tref title="relative IRI">relative IRIs</tref>
+ are resoled. This keyword is described in section <a href="#base-iri"></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="#default-vocabulary"></a>.</dd>
+ <dt><code>@graph</code></dt><dd>Used to explicitly label a <tref>JSON-LD graph</tref>.
+ This keyword is described in section <a href="#named-graphs"></a>.</dd>
+ <dt><code>:</code></dt>
+ <dd>The separator for JSON keys and values that use
+ <tref title="compact iri">compact IRIs</tref>.</dd>
</dl>
<p>All keys, <tref title="keyword">keywords</tref>, and values in JSON-LD are case-sensitive.</p>
@@ -1942,6 +1944,97 @@
</section>
<section>
+ <h2>Reverse Properties</h2>
+
+ <p>JSON-LD serializes directed <tref title="JSON-LD graph">graphs</tref>. That means that
+ every <tref>property</tref> points from a <tref>node</tref> to another <tref>node</tref>
+ or <tref title="JSON-LD value">value</tref>. However, in some cases, it is desirable
+ to serialize in the reverse direction. Consider for example the case where a person
+ and its children should be described in a document. If the used vocabulary does not
+ provide a <em>children</em> <tref>property</tref> but just a <em>parent</em>
+ <tref>property</tref>, every <tref>node</tref> representing a child would have
+ to contain a <tref>property</tref> pointing to the parent as in the following
+ example.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="A document with children linking to their parent">
+ <!--
+ [
+ {
+ ****"@id": "#homer"****,
+ "http://example.com/vocab#name": "Homer"
+ },
+ {
+ "@id": "#bart",
+ "http://example.com/vocab#name": "Bart",
+ ****"http://example.com/vocab#parent": { "@id": "#homer" }****
+ },
+ {
+ "@id": "#lisa",
+ "http://example.com/vocab#name": "Lisa",
+ ****"http://example.com/vocab#parent": { "@id": "#homer" }****
+ }
+ ]
+ -->
+ </pre>
+
+ <p>Expressing such data is much simpler by using JSON-LD's <code>@reverse</code>
+ <tref>keyword</tref>:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="A person and its children using a reverse property">
+ <!--
+ {
+ "@id": "#homer",
+ "http://example.com/vocab#name": "Homer",
+ ****"@reverse"****: {
+ ****"http://example.com/vocab#parent"****: [
+ {
+ "@id": "#bart",
+ "http://example.com/vocab#name": "Bart"
+ },
+ {
+ "@id": "#lisa",
+ "http://example.com/vocab#name": "Lisa"
+ }
+ ]
+ }
+ }
+ -->
+ </pre>
+
+ <p>The <code>@reverse</code> <tref>keyword</tref> can also be used in
+ <tref title="expanded term definition">expanded term definitions</tref>
+ to create reverse properties as shown in the following example:</p>
+
+
+ <pre class="example" data-transform="updateExample"
+ title="Using @reverse to define reverse properties">
+ <!--
+ {
+ "@context": {
+ "name": "http://example.com/vocab#name",
+ ****"children": { "@reverse": "http://example.com/vocab#parent" }****
+ },
+ "@id": "#homer",
+ "name": "Homer",
+ ****"children"****: [
+ {
+ "@id": "#bart",
+ "name": "Bart"
+ },
+ {
+ "@id": "#lisa",
+ "name": "Lisa"
+ }
+ ]
+ }
+ -->
+ </pre>
+</section>
+
+
+<section>
<h2>Named Graphs</h2>
<p>At times, it is necessary to make statements about a <tref>JSON-LD graph</tref>
@@ -2559,7 +2652,8 @@
<li><code>@context</code>,</li>
<li><code>@graph</code>,</li>
<li><code>@id</code>,</li>
- <li><code>@type</code>, or</li>
+ <li><code>@type</code>,</li>
+ <li><code>@reverse</code>, or</li>
<li><code>@index</code></li>
</ul>
@@ -2605,6 +2699,12 @@
<tref>context</tref> to be defined which is shared by all of the constituent
<tref title="node object">node objects</tref>.</p>
+<p>If the <tref>node object</tref> contains the <code>@reverse</code> key,
+ its value MUST be a <tref>JSON object</tref> containing members representing reverse
+ properties. Each value of such a reverse property MUST be an <tref>absolute IRI</tref>,
+ a <tref>relative IRI</tref>, a <tref>compact IRI</tref>, a <tref>blank node identifier</tref>,
+ a <tref>node object</tref> or an <tref>array</tref> containing a combination of these.</p>
+
<p>If the <tref>node object</tref> contains the <code>@index</code> key,
its value MUST be a <tref>string</tref>. See section
<a href="#data-indexing"></a> for further discussion on <code>@index</code>
@@ -2793,10 +2893,15 @@
properties of the value associated with the <tref>term</tref> when it is
used as key in a <tref>node object</tref>.</p>
- <p>An <tref>expanded term definition</tref> SHOULD be a <tref>JSON object</tref>
- composed of zero or more keys from <code>@id</code>,
+ <p>An <tref>expanded term definition</tref> MUST be a <tref>JSON object</tref>
+ composed of zero or more keys from <code>@id</code>, <code>@reverse</code>,
<code>@type</code>, <code>@language</code> or <code>@container</code>. An
- <tref>expanded term definition</tref> SHOULD NOT contain any other keys.
+ <tref>expanded term definition</tref> SHOULD NOT contain any other keys.</p>
+
+ <p>If an <tref>expanded term definition</tref> has an <code>@reverse</code> member,
+ <code>@id</code>, <code>@type</code>, and <code>@language</code> are not allowed.
+ If an <code>@container</code> member exists, its value MUST be <tref>null</tref>
+ or <code>@index</code>.</p>
<p>If the <tref>term</tref> definition is not <tref>null</tref>, a <tref>compact IRI</tref>,
or an <tref>absolute IRI</tref> and the <tref>active context</tref> does not have an