--- a/spec/latest/json-ld-syntax/index.html Tue Mar 19 12:29:00 2013 -0700
+++ b/spec/latest/json-ld-syntax/index.html Tue Mar 19 13:39:37 2013 -0700
@@ -242,7 +242,7 @@
<dt>Zero Edits, most of the time</dt>
<dd>JSON-LD must make the transition to JSON-LD as simple as possible. In many cases,
zero edits to the JSON document and the addition of one line to the HTTP response
- should suffice (see <a href="#interpreting-json-as-json-ld">Interpreting JSON as JSON-LD</a>).
+ should suffice (see <a class="sectionRef" href="#interpreting-json-as-json-ld"></a>).
This allows organizations that have
already deployed large JSON-based infrastructure to use JSON-LD's features
in a way that is not disruptive to their day-to-day operations and is
@@ -278,7 +278,7 @@
While JSON-LD uses the same array representation as JSON,
the collection is <em>unordered</em> by default. While order is
preserved in regular JSON arrays, it is not in regular JSON-LD arrays
- specifically defined (see <a href="#sets-and-lists"></a>).</dd>
+ specifically defined (see <a class="sectionRef" href="#sets-and-lists"></a>).</dd>
<dt><tdef>string</tdef></dt><dd>
A string is a sequence of zero or more Unicode characters,
wrapped in double quotes, using backslash escapes (if necessary).</dd>
@@ -313,48 +313,48 @@
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>
+ <a class="sectionRef" 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>
+ This keyword is described in <a class="sectionRef" 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>
+ <a class="sectionRef" href="#string-internationalization"></a> and
+ <a class="sectionRef" 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>
+ <a class="sectionRef" 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>
+ <a class="sectionRef" 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>
+ This keyword is described in <a class="sectionRef" 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>
+ This keyword is described in <a class="sectionRef" 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>
+ represented as arrays. This keyword is described in
+ <a class="sectionRef" 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>
+ <dd>Used to express reverse properties. This keyword is described in
+ <a class="sectionRef" 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>
+ This keyword is described in <a class="sectionRef" 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 resolved. This keyword is described in section <a href="#base-iri"></a>.</dd>
+ are resolved. This keyword is described in <a class="sectionRef" 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>
+ <tref>IRI</tref>. This keyword is described in <a class="sectionRef" 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>
+ This keyword is described in <a class="sectionRef" 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>
@@ -371,9 +371,9 @@
This criteria is relevant to authors and authoring tool implementers.</p>
<p>A <tref>JSON-LD document</tref> complies with this specification if it follows
- the normative statements in section <a href="#json-ld-grammar"></a>. JSON documents
+ the normative statements in <a class="sectionRef" href="#json-ld-grammar"></a>. JSON documents
can be interpreted as JSON-LD by following the normative statements in section
- <a href="#interpreting-json-as-json-ld">Interpreting JSON as JSON-LD</a>. For convenience, normative
+ <a class="sectionRef" href="#interpreting-json-as-json-ld"></a>. For convenience, normative
statements for documents are often phrased as statements on the properties of the document.</p>
<p>The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT,
@@ -508,7 +508,7 @@
<tref title="IRI">IRIs</tref> in the Schema.org vocabulary but also specifies that
the values of the <code>homepage</code> and <code>image</code> property
can be interpreted as an <tref>IRI</tref> (<code>"@type": "@id"</code>,
- see section <a href="#iris"></a> for more details). This information allows developers
+ see <a class="sectionRef" href="#iris"></a> for more details). This information allows developers
to re-use each other's data without having to agree to how their data will interoperate
on a site-by-site basis. External JSON-LD context documents may contain extra
information located outside of the <code>@context</code> key, such as
@@ -518,7 +518,7 @@
<p>JSON documents can be transformed to JSON-LD without having to be modified by
referencing a <tref>context</tref> via an HTTP Link Header
- as described in section <a href="#interpreting-json-as-json-ld"></a>. It is also
+ as described in <a class="sectionRef" href="#interpreting-json-as-json-ld"></a>. It is also
possible to apply a custom context using the JSON-LD API [[JSON-LD-API]].</p>
<p>In <tref title="JSON-LD document">JSON-LD documents</tref>
@@ -585,7 +585,7 @@
<code>http://example.com/about/</code>, the <tref>relative IRI</tref>
<code>../</code> would expand to <code>http://example.com/</code> (for more
information on where <tref title="relative IRI">relative IRIs</tref> can be
- used, please refer to appendix <a href="#json-ld-grammar"></a>).</p>
+ used, please refer to appendix <a class="sectionRef" href="#json-ld-grammar"></a>).</p>
<pre class="example" data-transform="updateExample"
title="IRIs can be relative">
@@ -664,7 +664,7 @@
<p>In the example above, even though the value <code>http://manu.sporny.org/</code>
is expressed as a JSON <tref>string</tref>, the type <tref>coercion</tref>
rules will transform the value into an IRI when generating the
- <tref>JSON-LD graph</tref>. See <a href="#type-coercion"></a> for more
+ <tref>JSON-LD graph</tref>. See <a class="sectionRef" href="#type-coercion"></a> for more
details about this feature.</p>
<p>In summary, <tref title="IRI">IRIs</tref> can be expressed in a variety of
@@ -1290,7 +1290,7 @@
<section>
<h2>Advanced Context Usage</h2>
- <p>Section <a href="#the-context"></a> introduced the basics of what makes
+ <p>Section <a class="sectionRef" href="#the-context"></a> introduced the basics of what makes
JSON-LD work. This section expands on the basic principles of the
<tref>context</tref> and demonstrates how more advanced use cases can
be achieved using JSON-LD. </p>
@@ -1535,7 +1535,7 @@
<p>The example above would associate the <code>ja</code> language
code with the two <tref title="string">strings</tref> <em>花澄</em> and <em>科学者</em>.
Languages codes are defined in [[!BCP47]]. The default language applies to all
- <tref>string</tref> values that are not <a href="#type-coercion">type coerced</a>.</p>
+ <tref>string</tref> values that are not <a class="sectionRef" href="#type-coercion">type coerced</a>.</p>
<p>To clear the default language for a subtree, <code>@language</code> can
be set to <code>null</code> in a <tref>local context</tref> as follows:</p>
@@ -1593,7 +1593,7 @@
<p class="note">Language associations are only applied to plain
<tref title="string">strings</tref>. <tref title="typed value">Typed values</tref>
- or values that are subject to <a href="#type-coercion"></a> are not language tagged.</p>
+ or values that are subject to <a class="sectionRef" href="#type-coercion"></a> are not language tagged.</p>
<p>Just as in the example above, systems often need to express the value of a
property in multiple languages. Typically, such systems also try to ensure that
@@ -1679,7 +1679,7 @@
<section>
<h2>IRI Expansion within a Context</h2>
<p>In general, normal IRI expansion rules apply
- anywhere an IRI is expected (see <a href="#iris"></a>). Within
+ anywhere an IRI is expected (see <a class="sectionRef" href="#iris"></a>). Within
a <tref>context</tref> definition, this can mean that terms defined
within the context may also be used within that context as long as
there are no circular dependencies. For example, it is common to use
@@ -1997,7 +1997,7 @@
are always represented in the form of an <tref>array</tref>,
even if there is just a single value that would otherwise be optimized to
a non-array form in compact form (see
- <a href="#compact-document-form"></a>). This makes post-processing of
+ <a class="sectionRef" href="#compact-document-form"></a>). This makes post-processing of
JSON-LD documents easier as the data is always in array form, even if the
array only contains a single value.</p>
@@ -2413,8 +2413,8 @@
<p>The interpretation of the data above is expressed in
the table below. Note how the index keys do not appear in the Linked Data
below, but would continue to exist if the document were compacted or
- expanded (see <a href="#compact-document-form"></a> and
- <a href="#expanded-document-form"></a>) using a JSON-LD processor:</p>
+ expanded (see <a class="sectionRef" href="#compact-document-form"></a> and
+ <a class="sectionRef" href="#expanded-document-form"></a>) using a JSON-LD processor:</p>
<table class="example">
<thead>
@@ -2746,7 +2746,7 @@
MUST be unique.</p>
<p class="note">JSON-LD allows <tref title="keyword">keywords</tref> to be aliased
- (see <a href="#aliasing-keywords"></a> for details). Whenever a <tref>keyword</tref> is
+ (see <a class="sectionRef" href="#aliasing-keywords"></a> for details). Whenever a <tref>keyword</tref> is
discussed in this grammar, the statements also apply to an alias for
that <tref>keyword</tref>. For example, if the <tref>active context</tref>
defines the <tref>term</tref> <code>id</code> as an alias for <code>@id</code>,
@@ -2769,7 +2769,7 @@
be an empty <tref>string</tref> (<code>""</code>) as not all programming languages
are able to handle empty property names.</p>
- <p>See section <a href="#the-context"></a> and <a href="#iris"></a> for further discussion
+ <p>See <a class="sectionRef" href="#the-context"></a> and <a class="sectionRef" href="#iris"></a> for further discussion
on mapping <tref title="term">terms</tref> to <tref title="IRI">IRIs</tref>.</p>
</section>
@@ -2821,8 +2821,8 @@
its value MUST be an <tref>absolute IRI</tref>, a <tref>relative IRI</tref>,
or a <tref>compact IRI</tref> (including
<tref title="blank node identifier">blank node identifiers</tref>).
- See <a href="#node-identifiers"></a>, <a href="#compact-iris"></a>,
- and <a href="#identifying-blank-nodes"></a> for further discussion on
+ See <a class="sectionRef" href="#node-identifiers"></a>, <a href="#compact-iris"></a>,
+ and <a class="sectionRef" href="#identifying-blank-nodes"></a> for further discussion on
<code>@id</code> values.</p>
<p>If the <tref>node object</tref> contains the <code>@graph</code>
@@ -2831,7 +2831,7 @@
an <tref>array</tref> of zero or more <tref title="node object">node objects</tref>.
If the <tref>node object</tref> contains an <code>@id</code> keyword,
its value is used as the label of a named graph.
- See <a href="#named-graphs"></a> for further discussion on
+ See <a class="sectionRef" href="#named-graphs"></a> for further discussion on
<code>@graph</code> values. As a special case, if a <tref>JSON object</tref>
contains no keys other than <code>@graph</code> and <code>@context</code>, and the
<tref>JSON object</tref> is the root of the JSON-LD document, the
@@ -2847,7 +2847,7 @@
(including <tref title="blank node identifier">blank node identifiers</tref>),
a <tref>term</tref> defined in the <tref>active context</tref> expanding into an <tref>absolute IRI</tref>, or
an <tref>array</tref> of any of these.
- See <a href="#specifying-the-type"></a> for further discussion on
+ See <a class="sectionRef" href="#specifying-the-type"></a> for further discussion on
<code>@type</code> values.</p>
<p>If the <tref>node object</tref> contains the <code>@reverse</code> key,
@@ -2858,7 +2858,7 @@
<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>
+ <a class="sectionRef" href="#data-indexing"></a> for further discussion on <code>@index</code>
values.</p>
<p>Keys in a <tref>node object</tref> that are not
@@ -2910,7 +2910,7 @@
<p>The value associated with the <code>@index</code> key MUST be a
<tref>string</tref>.</p>
- <p>See section <a href="#typed-values"></a> and <a href="#string-internationalization"></a>
+ <p>See <a class="sectionRef" href="#typed-values"></a> and <a class="sectionRef" href="#string-internationalization"></a>
for more information on <tref title="value object">value objects</tref>.</p>
</section>
@@ -2926,7 +2926,7 @@
of terms associated with a <code>@set</code> or <code>@list</code> container
will always be represented in the form of an <tref>array</tref> 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>.
+ a non-array form in <a hclass="sectionRef" ref="#compact-document-form"></a>.
This simplifies post-processing of the data as the data is always in a
deterministic form.</p>
@@ -2952,7 +2952,7 @@
<li>an <tref>array</tref> of zero or more of the above possibilities</li>
</ul>
- <p>See section <a href="#sets-and-lists"></a> for further discussion on sets and lists.</p>
+ <p>See <a class="sectionRef" href="#sets-and-lists"></a> for further discussion on sets and lists.</p>
</section>
<section>
@@ -2971,7 +2971,7 @@
<li>an <tref>array</tref> of zero or more of the above possibilities</li>
</ul>
- <p>See section <a href="#string-internationalization"></a> for further discussion
+ <p>See <a class="sectionRef" href="#string-internationalization"></a> for further discussion
on language maps.</p>
</section>
@@ -2999,7 +2999,7 @@
<li>an <tref>array</tref> of zero or more of the above possibilities</li>
</ul>
- <p>See section <a href="#data-indexing"></a> for further information on this topic.</p>
+ <p>See <a class="sectionRef" href="#data-indexing"></a> for further information on this topic.</p>
</section>
<section>
@@ -3075,7 +3075,7 @@
the definition of a term cannot depend on the definition of another term if that other
term also depends on the first term.</p>
- <p>See section <a href="#the-context"></a> for further discussion on contexts.</p>
+ <p>See <a class="sectionRef" href="#the-context"></a> for further discussion on contexts.</p>
</section>
</section>
@@ -3123,6 +3123,106 @@
<p class="note">Publishers supporting both dataset and graph syntaxes have to ensure that
the primary data is stored in the default graph to enable consumers that do not support
datasets to process the information.</p>
+
+ <section>
+ <h3>Transformation from JSON-LD to RDF</h3>
+ <p>The process of turning a JSON-LD document depends on excersizing the
+ algorithms defined in
+ <cite><a href="../json-ld-api/#convert-to-rdf-algorithm">
+ JSON-LD-API Convert to RDF Algorithm
+ </a></cite>
+ [[JSON-LD-API]]. It is beyond the scope of this document to detail these
+ algorithms any further, but a summary of the necessary operations is provided
+ to illustrate the process.</p>
+ <p>The procedure involves the following steps:</p>
+ <ol>
+ <li>Expand the JSON-LD document, removing any context; this ensures
+ that properties, types and values are given their full representation
+ as <tref title="IRI">IRIs</tref> and expanded values. The process of expanding
+ is discussed further in
+ <a class="sectionRef" href="#expanded-document-form"></a>.</li>
+ <li>Flatten the document, which turns the document into an array of
+ <tref title="node object">node objects</tref>. Flattening is discussed
+ further in <a class="sectionRef" href="#flattened-document-form"></a>.</li>
+ <li>Turn each <tref>node object</tref> into a series of
+ <tref href="http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple">RDF triples</tref>.</li>
+ </ol>
+
+ <p>For example, consider the following JSON-LD document in compact form:</p>
+ <pre class="example" data-transform="updateExample"
+ title="Sample JSON-LD document">
+ <!--
+ {
+ "@context": {
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "knows": "http://xmlns.com/foaf/0.1/knows"
+ },
+ "@id": "http://me.markus-lanthaler.com/",
+ "name": "Markus Lanthaler",
+ "knows": [
+ {
+ "@id": "http://manu.sporny.org/",
+ "name": "Manu Sporny"
+ },
+ {
+ "name": "Dave Longley"
+ }
+ ]
+ }
+ -->
+ </pre>
+
+ <p>Running the JSON-LD Flattening algorithm against the JSON-LD input document in
+ the example above and using the same context would result in the following
+ output:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Flattened and expanded form for the previous example">
+ <!--
+ [{
+ "@id": "_:b0",
+ "http://xmlns.com/foaf/0.1/name": "Dave Longley"
+ }, {
+ "@id": "http://manu.sporny.org/",
+ "http://xmlns.com/foaf/0.1/name": "Manu Sporny"
+ }, {
+ "@id": "http://me.markus-lanthaler.com/",
+ "http://xmlns.com/foaf/0.1/knows": [{
+ "@id": "http://manu.sporny.org/"
+ }, {
+ "@id": "_:b0"
+ }],
+ "http://xmlns.com/foaf/0.1/name": "Markus Lanthaler"
+ }]
+ -->
+ </pre>
+
+ <p>Transforming this to RDF not is a straight-forward process of turning each
+ <tref>node object</tref> into one or more RDF triples. This can be expressed
+ in Turtle as follows:</p>
+
+
+ <pre class="example" data-transform="updateExample"
+ title="Turtle representation of expanded/flattend document">
+ <!--
+ _:b0 <http://xmlns.com/foaf/0.1/name> "Dave Longley" .
+
+ <http://manu.sporny.org/> <http://xmlns.com/foaf/0.1/name> "Manu Sporny" .
+
+ <http://me.markus-lanthaler.com/> <http://xmlns.com/foaf/0.1/knows>
+ <http://manu.sporny.org/>, _:b0 .
+ -->
+ </pre>
+
+ <p>The process of turning RDF into JSON-LD can be thought of as the
+ inverse of this last step, creating an expanded JSON-LD document closely
+ matching the triples from RDF, using a single <tref>node object</tref>
+ for all triples having a common subject, and a single <tref>property</tref>
+ for those triples also having a common predicate.</p>
+
+ <p>For more complicated use cases, including the use of <code>@list</code>
+ and <a href="#named-graphs">Named Graphs</a>, see [[JSON-LD-API]].</p>
+ </section>
</section>
<section class="appendix informative">