--- a/spec/latest/json-ld-syntax/index.html Fri Feb 01 15:57:54 2013 -0500
+++ b/spec/latest/json-ld-syntax/index.html Sat Feb 02 11:59:50 2013 -0500
@@ -354,7 +354,7 @@
<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-annotations"></a>.</dd>
+ <a href="#data-indexing"></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>
@@ -481,14 +481,14 @@
or a <tref>JSON object</tref>.</p>
<p>When a <tref>JSON object</tref> is
- associated with a term, it is called an <tref>expanded term definition</tref>.
+ associated with a term, it is called an <tref>expanded term definition</tref>.
<tdef title="expanded term definition">Expanded term definitions</tdef> may
be used to associate <a href="#type-coercion">type</a> or
- <a href="#string-internationalization">language information</a> with a
+ <a href="#string-internationalization">language information</a> with a
term.
The example above specifies that the values of <code>image</code> and
<code>homepage</code> terms are <tref title="IRI">IRIs</tref>.
- They also allow terms to be used for <a href="#data-annotations">index maps</a>
+ They also allow terms to be used for <a href="#data-indexing">index maps</a>
and to specify whether <tref title="array">array</tref> values are to be
interpreted as <a href="#sets-and-lists">sets or lists</a>.
<tref title="expanded term definition">Expanded term definitions</tref> may
@@ -518,7 +518,7 @@
<p>The referenced context not only specifies how the terms map to
<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>,
+ can be interpreted as an <tref>IRI</tref> (e.g. <code>"@type": "@id"</code>,
see section <a href="#iris"></a> for more details). This information gives the
data global context and allows developers to re-use each other's data
without having to agree to how their data will interoperate on a
@@ -706,17 +706,17 @@
<section>
<h2>Node Identifiers</h2>
- <p>To be able to externally reference <tref title="node">nodes</tref>
- in a <tref title="json-ld_graph">graph</tref>, it is important that each <tref>node</tref> has
+ <p>To be able to externally reference <tref title="node">nodes</tref>
+ in a <tref title="json-ld_graph">graph</tref>, it is important that each <tref>node</tref> have
an unambiguous identifier. <tref title="IRI">IRIs</tref> are a fundamental concept of
<tref>Linked Data</tref>, and <tref title="node">nodes</tref> should have a de-referenceable
identifier used to name and locate them. For <tref title="node">nodes</tref> to be truly linked,
de-referencing the identifier should result in a representation of that <tref>node</tref>.
Associating an <tref>IRI</tref> with a <tref>node</tref> tells an application that it
- can fetch the resource associated with the IRI and get back a description of the
+ can fetch the resource associated with the IRI and get back a description of the
<tref>node</tref>.</p>
- <p><tref title="json-ld_document">JSON-LD documents</tref> may also contain descriptions
+ <p><tref title="json-ld_document">JSON-LD documents</tref> may also contain descriptions
of other <tref title="node">nodes</tref>, so it is necessary to be able to
uniquely identify each <tref>node</tref> so that the data is associated
with the correct <tref>node</tref> in an unambiguous way.</p>
@@ -814,7 +814,7 @@
<section>
<h2>Compact IRIs</h2>
<p>A document on the Web that defines one or more IRIs for use as
- <tref title="property">properties</tref> in Linked Data is called a
+ <tref title="property">properties</tref> in Linked Data is called a
<tdef>vocabulary</tdef>.
<tref title="term">Terms</tref> in <tref>Linked Data</tref> documents may draw from
a number of different <tref title="vocabulary">vocabularies</tref>s. At times, declaring every single <tref>term</tref>
@@ -841,7 +841,7 @@
<code>http://xmlns.com/foaf/0.1/name</code>. Instead of having to remember and
type out the entire IRI, the developer can instead use the prefix in their JSON-LD markup.
</p>
-
+
<p><tref title="prefix">Prefixes</tref> are expanded when the form of the value
is a <tref>compact IRI</tref> represented as a <code>prefix:suffix</code>
combination, and the prefix matches a <tref>term</tref> defined within the
@@ -1030,11 +1030,11 @@
<p>The <code>@type</code> <tref>keyword</tref> is also used to associate a type
with a <tref>node</tref>. The concept of a <tref>node type</tref> and
a <tref>value type</tref> are different.</p>
-
-<p>Generally speaking, a
- <tdef>node type</tdef> specifies the type of thing that is being described,
- like a person, place, event, or web page. A <tdef>value type</tdef> specifies
- the unit of measurement for a particular value, such as a date, meter,
+
+<p>Generally speaking, a
+ <tdef>node type</tdef> specifies the type of thing that is being described,
+ like a person, place, event, or web page. A <tdef>value type</tdef> specifies
+ the unit of measurement for a particular value, such as a date, meter,
or light year.</p>
<pre class="example" data-transform="updateExample"
@@ -1233,169 +1233,175 @@
</section>
<section>
- <h2>Advanced Context Usage</h2>
-
- <p>Section <a 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>
-
- <p>In general, contexts may be used at any time a
- <tref>JSON object</tref> is defined. The only time that one cannot
- express a context is inside a context definition itself. For example, a
- <tref>JSON-LD document</tref> may use more than one context at different
- points in a document:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Using multiple contexts">
- <!--
- [
+ <h2>Advanced Context Usage</h2>
+
+ <p>Section <a 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>
+
+ <p>In general, contexts may be used at any time a
+ <tref>JSON object</tref> is defined. The only time that one cannot
+ express a context is inside a context definition itself. For example, a
+ <tref>JSON-LD document</tref> may use more than one context at different
+ points in a document:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Using multiple contexts">
+ <!--
+ [
+ {
+ ****"@context": "http://example.org/contexts/person.jsonld",****
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/",
+ "depiction": "http://twitter.com/account/profile_image/manusporny"
+ },
+ {
+ ****"@context": "http://example.org/contexts/place.jsonld",****
+ "name": "The Empire State Building",
+ "description": "The Empire State Building is a 102-story landmark in New York City.",
+ "geo": {
+ "latitude": "40.75",
+ "longitude": "73.98"
+ }
+ }
+ ]
+ -->
+ </pre>
+
+ <p>Duplicate context <tref title="term">terms</tref> are overridden using a
+ last-defined-wins mechanism.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Scoped contexts within node objects">
+ <!--
{
- ****"@context": "http://example.org/contexts/person.jsonld",****
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/",
- "depiction": "http://twitter.com/account/profile_image/manusporny"
- },
- {
- ****"@context": "http://example.org/contexts/place.jsonld",****
- "name": "The Empire State Building",
- "description": "The Empire State Building is a 102-story landmark in New York City.",
- "geo": {
- "latitude": "40.75",
- "longitude": "73.98"
+ ****"@context":
+ {
+ "name": "http://example.com/person#name",
+ "details": "http://example.com/person#details"
+ },****
+ "****name****": "Markus Lanthaler",
+ ...
+ "details":
+ {
+ ****"@context": {
+ "name": "http://example.com/organization#name"
+ },****
+ "****name****": "Graz University of Technology"
}
}
- ]
- -->
- </pre>
-
- <p>Duplicate context <tref title="term">terms</tref> are overridden using a
- last-defined-wins mechanism.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Scoped contexts within node objects">
- <!--
- {
- ****"@context":
+ -->
+ </pre>
+
+ <p>In the example above, the <code>name</code> <tref>term</tref> is overridden
+ in the more deeply nested <code>details</code> structure. Note that this is
+ rarely a good authoring practice and is typically used when working with
+ legacy applications that depend on a specific structure of the
+ <tref>JSON object</tref>. If a <tref>term</tref> is redefined within a
+ context, all previous rules associated with the previous definition are
+ removed. If a <tref>term</tref> is redefined to <code>null</code>,
+ the <tref>term</tref> is effectively removed from the list of
+ <tref title="term">terms</tref> defined in the <tref>active context</tref>.</p>
+
+ <p>Multiple contexts may be combined using an <tref>array</tref>, which is processed
+ in order. The set of contexts defined within a specific <tref>JSON object</tref> are
+ referred to as <tdef title="local context">local contexts</tdef>. The
+ <tdef>active context</tdef> refers to the accumulation of
+ <tref title="local context">local contexts</tref> that are in scope at a
+ specific point within the document. Setting a <tref>local context</tref>
+ to <code>null</code> effectively resets the <tref>active context</tref>
+ to an empty context. The following example specifies an external context
+ and then layers an embedded context on top of the external context:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Combining external and local contexts">
+ <!--
{
- "name": "http://example.com/person#name",
- "details": "http://example.com/person#details"
- },****
- "****name****": "Markus Lanthaler",
- ...
- "details":
- {
- ****"@context": {
- "name": "http://example.com/organization#name"
- },****
- "****name****": "Graz University of Technology"
+ ****"@context": [
+ "http://json-ld.org/contexts/person.jsonld",
+ {
+ "pic": "http://xmlns.com/foaf/0.1/depiction"
+ }
+ ],****
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/",
+ ****"pic": "http://twitter.com/account/profile_image/manusporny"****
}
- }
- -->
- </pre>
-
- <p>In the example above, the <code>name</code> <tref>term</tref> is overridden
- in the more deeply nested <code>details</code> structure. Note that this is
- rarely a good authoring practice and is typically used when working with
- legacy applications that depend on a specific structure of the
- <tref>JSON object</tref>. If a <tref>term</tref> is redefined within a
- context, all previous rules associated with the previous definition are
- removed. If a <tref>term</tref> is redefined to <code>null</code>,
- the <tref>term</tref> is effectively removed from the list of
- <tref title="term">terms</tref> defined in the <tref>active context</tref>.</p>
-
- <p>Multiple contexts may be combined using an <tref>array</tref>, which is processed
- in order. The set of contexts defined within a specific <tref>JSON object</tref> are
- referred to as <tdef title="local context">local contexts</tdef>. The
- <tdef>active context</tdef> refers to the accumulation of
- <tref title="local context">local contexts</tref> that are in scope at a
- specific point within the document. Setting a <tref>local context</tref>
- to <code>null</code> effectively resets the <tref>active context</tref>
- to an empty context. The following example specifies an external context
- and then layers an embedded context on top of the external context:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Combining external and local contexts">
- <!--
- {
- ****"@context": [
- "http://json-ld.org/contexts/person.jsonld",
+ -->
+ </pre>
+
+ <p class="note">It is a best practice to put the <tref>context</tref> definition
+ at the top of the JSON-LD document.</p>
+
+ <p class="note">While it is possible to define a <tref>compact IRI</tref>, or
+ an <tref>absolute IRI</tref> to expand to some other unrelated <tref>IRI</tref>
+ (for example, <code>foaf:name</code> expanding to
+ <code>http://example.org/unrelated#species</code>), such usage is strongly
+ discouraged.</p>
+
+ <p class="note">To avoid forward-compatibility issues,
+ <tref title="term">terms</tref> starting with an <code>@</code> character are
+ to be avoided as they might be used as <tref title="keyword">keywords</tref>
+ in future versions of JSON-LD. Furthermore, the use of empty
+ <tref title="term">terms</tref> (<code>""</code>) is discouraged as not all
+ programming languages are able to handle empty property names.</p>
+
+ <section>
+ <h2>Context via HTTP Link Header</h2>
+
+ <p>Ordinary JSON documents can be interpreted as JSON-LD by referencing a JSON-LD
+ <tref>context</tref> document in an HTTP Link Header. Doing so allows JSON to
+ be unambiguously machine-readable without requiring developers to drastically
+ change their markup and provides an upgrade path for existing infrastructure
+ without breaking existing clients that rely on the <code>application/json</code>
+ media type.</p>
+
+ <p>In order to use an external context with an ordinary JSON document, an author
+ MUST specify an <tref>IRI</tref> to a valid <tref>JSON-LD document</tref> in
+ an HTTP Link Header [[!RFC5988]] using the <code>http://www.w3.org/ns/json-ld#context</code>
+ link relation. The referenced document MUST have a top-level <tref>JSON object</tref>.
+ The <code>@context</code> subtree within that object is added to the top-level
+ <tref>JSON object</tref> of the referencing document. If an <tref>array</tref>
+ is at the top-level of the referencing document and its items are
+ <tref title="JSON object">JSON objects</tref>, the <code>@context</code>
+ subtree is added to all <tref>array</tref> items. All extra information located outside
+ of the <code>@context</code> subtree in the referenced document MUST be
+ discarded. Effectively this means that the <tref>active context</tref> is
+ initialized with the referenced external <tref>context</tref>.</p>
+
+ <p>The following example demonstrates the use of an external context with an
+ ordinary JSON document:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Referencing a JSON-LD context from a JSON document via an HTTP Link Header">
+ <!--
+ GET /ordinary-json-document.json HTTP/1.1
+ Host: example.com
+ Accept: application/ld+json,application/json,*/*;q=0.1
+
+ ====================================
+
+ HTTP/1.0 200 OK
+ ...
+ Content-Type: ****application/json****
+ ****Link: <http://json-ld.org/contexts/person.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"****
+
{
- "pic": "http://xmlns.com/foaf/0.1/depiction"
+ "name": "Markus Lanthaler",
+ "homepage": "http://www.markus-lanthaler.com/",
+ "image": "http://twitter.com/account/profile_image/markuslanthaler"
}
- ],****
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/",
- ****"pic": "http://twitter.com/account/profile_image/manusporny"****
- }
- -->
- </pre>
-
- <p class="note">It is a best practice to put the <tref>context</tref> definition
- at the top of the JSON-LD document.</p>
-
- <p class="note">To avoid forward-compatibility issues,
- <tref title="term">terms</tref> starting with an <code>@</code> character are
- to be avoided as they might be used as <tref title="keyword">keywords</tref>
- in future versions of JSON-LD. Furthermore, the use of empty
- <tref title="term">terms</tref> (<code>""</code>) is discouraged as not all
- programming languages are able to handle empty property names.</p>
-</section>
-
-<section>
- <h2>Interpreting JSON as JSON-LD</h2>
-
- <p>Ordinary JSON documents can be interpreted as JSON-LD by referencing a JSON-LD
- <tref>context</tref> document in an HTTP Link Header. Doing so allows JSON to
- be unambiguously machine-readable without requiring developers to drastically
- change their markup and provides an upgrade path for existing infrastructure
- without breaking existing clients that rely on the <code>application/json</code>
- media type.</p>
-
- <p>In order to use an external context with an ordinary JSON document, an author
- MUST specify an <tref>IRI</tref> to a valid <tref>JSON-LD document</tref> in
- an HTTP Link Header [[!RFC5988]] using the <code>http://www.w3.org/ns/json-ld#context</code>
- link relation. The referenced document MUST have a top-level <tref>JSON object</tref>.
- The <code>@context</code> subtree within that object is added to the top-level
- <tref>JSON object</tref> of the referencing document. If an <tref>array</tref>
- is at the top-level of the referencing document and its items are
- <tref title="JSON object">JSON objects</tref>, the <code>@context</code>
- subtree is added to all <tref>array</tref> items. All extra information located outside
- of the <code>@context</code> subtree in the referenced document MUST be
- discarded. Effectively this means that the <tref>active context</tref> is
- initialized with the referenced external <tref>context</tref>.</p>
-
- <p>The following example demonstrates the use of an external context with an
- ordinary JSON document:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Referencing a JSON-LD context from a JSON document via an HTTP Link Header">
- <!--
- GET /ordinary-json-document.json HTTP/1.1
- Host: example.com
- Accept: application/ld+json,application/json,*/*;q=0.1
-
- ====================================
-
- HTTP/1.0 200 OK
- ...
- Content-Type: ****application/json****
- ****Link: <http://json-ld.org/contexts/person.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"****
-
- {
- "name": "Markus Lanthaler",
- "homepage": "http://www.markus-lanthaler.com/",
- "image": "http://twitter.com/account/profile_image/markuslanthaler"
- }
- -->
- </pre>
-
- <p>Please note that <tref title="JSON-LD document">JSON-LD documents</tref>
- served with the <code>application/ld+json</code>
- media type MUST have all context information, including references to external
- contexts, within the body of the document. Contexts linked via a
- <code>http://www.w3.org/ns/json-ld#context</code> HTTP Link Header MUST be
- ignored for such documents.</p>
+ -->
+ </pre>
+
+ <p>Please note that <tref title="JSON-LD document">JSON-LD documents</tref>
+ served with the <code>application/ld+json</code>
+ media type MUST have all context information, including references to external
+ contexts, within the body of the document. Contexts linked via a
+ <code>http://www.w3.org/ns/json-ld#context</code> HTTP Link Header MUST be
+ ignored for such documents.</p>
+ </section>
</section>
<section>
@@ -1480,7 +1486,7 @@
<tref>null</tref> in the <tref>expanded term definition</tref>.</p>
<p class="note">Language associations can only be applied to plain
- literal <tref title="string">strings</tref>.
+ literal <tref title="string">strings</tref>.
<tref title="typed value">Typed values</tref> or values that are subject
to <a href="#type-coercion"></a> cannot be language tagged.</p>
@@ -1799,18 +1805,14 @@
-->
</pre>
-<p>In order for the <tref>absolute IRI</tref> to match above, the <tref>absolute IRI</tref>
- needs to be used in the <tref>JSON-LD document</tref>. Also note that <code>foaf:homepage</code>
- will not use the <code>{ "@type": "@id" }</code> declaration because
- <code>foaf:homepage</code> is not the same as <code>http://xmlns.com/foaf/0.1/homepage</code>.
- That is, <tref title="term">terms</tref> are looked up in a <tref>context</tref> using
- direct string comparison before the <tref>prefix</tref> lookup mechanism is applied.</p>
-
-<p class="note">While it is possible to define a <tref>compact IRI</tref>, or
- an <tref>absolute IRI</tref> to expand to some other unrelated <tref>IRI</tref>
- (for example, <code>foaf:name</code> expanding to
- <code>http://example.org/unrelated#species</code>), such usage is strongly
- discouraged.</p>
+<p>
+In order for the <tref>absolute IRI</tref> to match above, the <tref>absolute IRI</tref> needs to be used in the <tref>JSON-LD document</tref>. Also note that <code>foaf:homepage</code>
+will not use the <code>{ "@type": "@id" }</code> declaration because
+<code>foaf:homepage</code> is not the same as
+<code>http://xmlns.com/foaf/0.1/homepage</code>. That is, <tref title="term">terms</tref>
+are looked up in a <tref>context</tref> using direct string comparison before the
+<tref>prefix</tref> lookup mechanism is applied.
+</p>
<p>The only exception for using terms in the <tref>context</tref> is that
circular definitions are not allowed. That is,
@@ -1977,22 +1979,22 @@
This decision was made due to the extreme amount of added complexity when
processing lists of lists.</p>
-<p>While <code>@list</code> is used to describe <em>ordered lists</em>,
- the <code>@set</code> keyword is used to describe <em>unordered sets</em>.
+<p>While <code>@list</code> is used to describe <em>ordered sets</em>,
+ the <code>@set</code> keyword is used to describe <em>unordered sets</em>.
The use of <code>@set</code> in the body of a JSON-LD document
is optimized away when processing the document, as it is just syntactic
- sugar. However, <code>@set</code> is helpful when used within the context
+ sugar. However, <code>@set</code> is helpful when used within the context
of a document.
Values of terms associated with a <code>@set</code> or <code>@list</code> container
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
+ 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
JSON-LD documents easier as the data is always in array form, even if the
array only contains a single value.</p>
<p class="note">The use of <code>@container</code> in the body of a JSON-LD
- document has no meaning and is not allowed by the JSON-LD grammar
+ document has no meaning and is not allowed by the JSON-LD grammar
(see <a href="#json-ld-grammar"></a>).</p>
</section>
@@ -2207,7 +2209,7 @@
<h2>Identifying Blank Nodes</h2>
<p>At times, it becomes necessary to be able to express information without
- being able to uniquely identify the <tref>node</tref>.
+ being able to uniquely identify the <tref>node</tref>.
This type of node is called a <tref>blank node</tref>
(see <cite><a href="http://www.w3.org/TR/rdf11-concepts/#section-blank-nodes">Section 3.4: Blank Nodes</a></cite>
of [[!RDF-CONCEPTS]]). In JSON-LD, <tref title="blank node identifier">blank node identifiers</tref> are
@@ -2275,121 +2277,8 @@
</section>
<section>
- <h2>Data Annotations</h2>
-
- <p class="issue" data-number="216">The prose of this section needs to be
- updated.</p>
-
- <p>Indexes can be used to structure data into a form that is more efficient
- to access, but fundamentally does not convey any additional semantic meaning.
- The index feature allows an author to structure data using a simple
- key-value map where the keys do not map to <tref title="IRI">IRIs</tref>.
- This enables direct access to data instead of having to scan an array in
- search of a specific item. The following example illustrates this use
- case:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Index maps">
- <!--
- {
- "@context":
- {
- "schema": "http://schema.org/",
- "name": "schema:name",
- "body": "schema:articleBody",
- "words": "schema:wordCount",
- "post": {
- "@id": "schema:blogPost",
- ****"@container": "@index"****
- }
- },
- "@id": "http://example.com/",
- "@type": "schema:Blog",
- "name": "World Financial News",
- ****"post": {
- "en": {
- "@id": "http://example.com/posts/1/en",
- "body": "World commodities were up today with heavy trading of crude oil...",
- "words": 1539
- },
- "de": {
- "@id": "http://example.com/posts/1/de",
- "body": "Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...",
- "words": 1204
- }****
- }
- }
- -->
- </pre>
-
- <p>In the example above, the <strong>blogPost</strong> <tref>term</tref> has
- been marked as an <tref>index map</tref>. The <strong>en</strong>,
- <strong>de</strong>, and <strong>ja</strong> keys will be ignored
- semantically, but preserved syntactically, by the JSON-LD Processor.
- This allows a developer to access the German version
- of the <strong>blogPost</strong> using the following code snippet:
- <code>obj.blogPost.de</code>.</p>
-
- <p>The interpretation of the data above is expressed in
- the table below. Note how the indexes 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>
-
- <table class="example">
- <thead>
- <th>Subject</th>
- <th>Property</th>
- <th>Value</th>
- </thead>
- <tbody>
- <tr>
- <td>http://example.com/</td>
- <td>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</td>
- <td>http://schema.org/Blog</td>
- </tr>
- <tr>
- <td>http://example.com/</td>
- <td>http://schema.org/name</td>
- <td>World Financial News</td>
- </tr>
- <tr>
- <td>http://example.com/</td>
- <td>http://schema.org/blogPost</td>
- <td>http://example.com/posts/1/en</td>
- </tr>
- <tr>
- <td>http://example.com/</td>
- <td>http://schema.org/blogPost</td>
- <td>http://example.com/posts/1/de</td>
- </tr>
- <tr>
- <td>http://example.com/posts/1/en</td>
- <td>http://schema.org/articleBody</td>
- <td>World commodities were up today with heavy trading of crude oil...</td>
- </tr>
- <tr>
- <td>http://example.com/posts/1/en</td>
- <td>http://schema.org/wordCount</td>
- <td>1539</td>
- </tr>
- <tr>
- <td>http://example.com/posts/1/de</td>
- <td>http://schema.org/articleBody</td>
- <td>Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...</td>
- </tr>
- <tr>
- <td>http://example.com/posts/1/de</td>
- <td>http://schema.org/wordCount</td>
- <td>1204</td>
- </tr>
- </tbody>
- </table>
-</section>
-
-<section>
<h3>Expanded Document Form</h3>
-<p>The JSON-LD Algorithms and API specification [[JSON-LD-API]]
+<p>The JSON-LD Algorithms and API specification [[JSON-LD-API]]
defines a method for <em>expanding</em> a JSON-LD document.
Expansion is the process of taking a JSON-LD document and applying a
<code>@context</code> such that all IRIs, types, and values
@@ -2444,12 +2333,12 @@
<section>
<h3>Compact Document Form</h3>
-<p>The JSON-LD Algorithms and API specification [[JSON-LD-API]]
+<p>The JSON-LD Algorithms and API specification [[JSON-LD-API]]
defines a method for <em>compacting</em> a JSON-LD document.
Compaction is the process of taking a JSON-LD document and applying a
context such that a very compact form of the document is generated.
- At times, a JSON-LD document may be received that is not in its most
- compact form. The JSON-LD Algorithms, via an API, provides a way to compact a
+ At times, a JSON-LD document may be received that is not in its most
+ compact form. The JSON-LD Algorithms, via an API, provides a way to compact a
JSON-LD document.</p>
<p>For example, assume the following JSON-LD input document:</p>
@@ -2513,12 +2402,130 @@
expanding the document (see <a href="#expanded-document-form"></a>) and then
using a developer-supplied context to compact the expanded document.
While the context provided above mapped <code>http://xmlns.com/foaf/0.1/name</code>
- to <strong>name</strong>, it could have also mapped it to any arbitrary
- <tref>term</tref> provided by the developer. This powerful mechanism allows
- the developer to re-shape the incoming JSON data into a format that is
+ to <strong>name</strong>, it could have also mapped it to any arbitrary
+ <tref>term</tref> provided by the developer. This powerful mechanism allows
+ the developer to re-shape the incoming JSON data into a format that is
optimized for their application.</p>
</section>
+<section>
+ <h2>Data Indexing</h2>
+
+ <p>Databases are typically used to make access to
+ data more efficient. Developers often extend this sort of functionality into
+ their application data to deliver similar performance gains. Often this
+ data does not have any meaning from a Linked Data standpoint, but is
+ still useful for an application.</p>
+
+ <p>JSON-LD introduces the notion of <tref title="index map">index maps</tref>
+ that can be used to structure data into a form that is
+ more efficient to access. The data indexing feature allows an author to
+ structure data using a simpley key-value map where the keys do not map
+ to <tref title="IRI">IRIs</tref>. This enables direct access to data
+ instead of having to scan an array in search of a specific item.
+ In JSON-LD such data can be specified by associating the
+ <code>@index</code> <tref>keyword</tref> with a
+ <code>@container</code> declaration in the context:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Indexing data in JSON-LD">
+ <!--
+ {
+ "@context":
+ {
+ "schema": "http://schema.org/",
+ "name": "schema:name",
+ "body": "schema:articleBody",
+ "words": "schema:wordCount",
+ "post": {
+ "@id": "schema:blogPost",
+ ****"@container": "@index"****
+ }
+ },
+ "@id": "http://example.com/",
+ "@type": "schema:Blog",
+ "name": "World Financial News",
+ ****"post": {
+ "en": {
+ "@id": "http://example.com/posts/1/en",
+ "body": "World commodities were up today with heavy trading of crude oil...",
+ "words": 1539
+ },
+ "de": {
+ "@id": "http://example.com/posts/1/de",
+ "body": "Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...",
+ "words": 1204
+ }****
+ }
+ }
+ -->
+ </pre>
+
+ <p>In the example above, the <strong>blogPost</strong> <tref>term</tref> has
+ been marked as an <tref>index map</tref>. The <strong>en</strong>,
+ <strong>de</strong>, and <strong>ja</strong> keys will be ignored
+ semantically, but preserved syntactically, by the JSON-LD Processor.
+ This allows a developer to access the German version
+ of the <strong>blogPost</strong> using the following code snippet:
+ <code>obj.blogPost.de</code>.</p>
+
+ <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>
+
+ <table class="example">
+ <thead>
+ <th>Subject</th>
+ <th>Property</th>
+ <th>Value</th>
+ </thead>
+ <tbody>
+ <tr>
+ <td>http://example.com/</td>
+ <td>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</td>
+ <td>http://schema.org/Blog</td>
+ </tr>
+ <tr>
+ <td>http://example.com/</td>
+ <td>http://schema.org/name</td>
+ <td>World Financial News</td>
+ </tr>
+ <tr>
+ <td>http://example.com/</td>
+ <td>http://schema.org/blogPost</td>
+ <td>http://example.com/posts/1/en</td>
+ </tr>
+ <tr>
+ <td>http://example.com/</td>
+ <td>http://schema.org/blogPost</td>
+ <td>http://example.com/posts/1/de</td>
+ </tr>
+ <tr>
+ <td>http://example.com/posts/1/en</td>
+ <td>http://schema.org/articleBody</td>
+ <td>World commodities were up today with heavy trading of crude oil...</td>
+ </tr>
+ <tr>
+ <td>http://example.com/posts/1/en</td>
+ <td>http://schema.org/wordCount</td>
+ <td>1539</td>
+ </tr>
+ <tr>
+ <td>http://example.com/posts/1/de</td>
+ <td>http://schema.org/articleBody</td>
+ <td>Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...</td>
+ </tr>
+ <tr>
+ <td>http://example.com/posts/1/de</td>
+ <td>http://schema.org/wordCount</td>
+ <td>1204</td>
+ </tr>
+ </tbody>
+ </table>
+</section>
+
</section>
<section class="appendix normative">
@@ -2534,17 +2541,21 @@
<tref title="JSON-LD graph">JSON-LD graphs</tref> and comprises exactly one
<tdef>default graph</tdef> and zero or more <tdef title="named graph">named graphs</tdef>.</li>
<li>The <tref>default graph</tref> does not have a name and MAY be empty.</li>
- <li>Each <tref>named graph</tref> is a pair consisting of an <tref>IRI</tref> or
- <tref>blank node identifier</tref> (the <tdef>graph name</tdef>) and a <tref>JSON-LD graph</tref>.
- Whenever possible, the <tref>graph name</tref> SHOULD be an <tref>IRI</tref>.</li>
- <li>A <tdef>JSON-LD graph</tdef> is a labeled directed graph, i.e., a set of
- <tref title="node">nodes</tref> connected by <tref title="edge">edges</tref>.</li>
+ <li>Each <tref>named graph</tref> is a pair consisting of a <tdef>graph name</tdef>
+ and a <tref>JSON-LD graph</tref>. The
+ <tref>graph name</tref> SHOULD be an <tref>IRI</tref> or
+ <tref>blank node identifier</tref>.</li>
+ <li>A <tdef>JSON-LD graph</tdef> is a labeled directed graph containing
+ a set of zero or more <tref title="node">nodes</tref> connected by
+ <tref title="edge">edges</tref>.</li>
<li>Every <tdef>edge</tdef> has a direction associated with it and is labeled with
an <tref>IRI</tref> or a <tref>blank node identifier</tref>. Within the JSON-LD syntax
- these edge labels are called <tdef title="property">properties</tdef>. Whenever possible, an
- <tref>edge</tref> SHOULD be labeled with an <tref>IRI</tref>.</li>
- <li>Every <tdef>node</tdef> is an <tref>IRI</tref>, a <tref>blank node</tref>,
- a <tref>JSON-LD value</tref>, or a <tref>list</tref>.</li>
+ these edge labels are called <tdef title="property">properties</tdef>.</li>
+ <li>Every <tdef>node</tdef> represents a <tdef>resource</tdef> or a
+ <tdef>value</tdef>. <tref title="resource">Resources</tref> are labeled
+ using either an <tref>IRI</tref> or a <tref>blank node identifier</tref>.
+ <tref title="value">Values</tref> are a
+ <tref>JSON-LD value</tref> or a <tref>list</tref>.</li>
<li>A <tref>node</tref> having an outgoing edge MUST be an <tref>IRI</tref> or a
<tref>blank node</tref>.</li>
<li>A <tref>JSON-LD graph</tref> MUST NOT contain unconnected <tref title="node">nodes</tref>,
@@ -2553,9 +2564,9 @@
(Internationalized Resource Identifier) is a string that conforms to the syntax
defined in [[RFC3987]]. <tref title="IRI">IRIs</tref> used within a
<tref>JSON-LD graph</tref> SHOULD return a <tref>Linked Data</tref> document describing
- the resource denoted by that <tref>IRI</tref> when being dereferenced.</li>
- <li>A <tdef>blank node</tdef> is a <tref>node</tref> which is neither an <tref>IRI</tref>,
- nor a <tref>JSON-LD value</tref>, or a <tref>list</tref>. A blank node MAY be identified
+ the resource denoted by that IRI when being dereferenced.</li>
+ <li>A <tdef>blank node</tdef> is a <tref>resource</tref> which is not
+ labeled with an <tref>IRI</tref>. A blank node MAY be identified
using a <tref>blank node identifier</tref>.</li>
<li>A <tdef>blank node identifier</tdef> is a string that can be used as an identifier
for a <tref>blank node</tref> within the scope of a <tref>JSON-LD document</tref>.
@@ -2563,13 +2574,12 @@
<li>A <tdef>JSON-LD value</tdef> is a <tref>string</tref>, a <tref>number</tref>,
<tref>true</tref> or <tref>false</tref>, a <tref>typed value</tref>, or a
<tref>language-tagged string</tref>.</li>
- <li>A <tdef>typed value</tdef> consists of a value, which is a string, and a type, which is an
- <tref>IRI</tref>.</li>
+ <li>A <tdef>typed value</tdef> consists of a value, which is a string, and a type, which is an IRI.</li>
<li>A <tdef>language-tagged string</tdef> consists of a string and a non-empty language
tag as defined by [[BCP47]]. The language tag MUST be well-formed according to section
<a href="http://tools.ietf.org/html/bcp47#section-2.2.9">2.2.9</a> of [[BCP47]], and MUST
be lowercase.</li>
- <li>A <tdef>list</tdef> is an ordered sequence of zero or more
+ <li>A <tdef>list</tdef> is an ordered sequence of zero or more
<tref title="IRI">IRIs</tref>,
<tref title="blank node">blank nodes</tref>, and
<tref title="JSON-LD value">JSON-LD values</tref>.</li>
@@ -2695,7 +2705,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-annotations"></a> for further discussion on <code>@index</code>
+ <a href="#data-indexing"></a> for further discussion on <code>@index</code>
values.</p>
@@ -2761,7 +2771,7 @@
An <tref>index map</tref> may
be used as a <tref>term</tref> value within a <tref>node object</tref> if the
term is defined with <code>@container</code> set to <code>@index</code>.
- The values of the members of an <tref>index map</tref> MUST be any
+ The values of the members of an <tref>index map</tref> MUST be one
of the following types:</p>
<ul>
<li><tref>string</tref>,</li>
@@ -2773,7 +2783,7 @@
<li><tref>expanded value</tref>,</li>
<li>an <tref>array</tref> of zero or more of the above possibilities</li>
</ul>
-<p>See <a href="#data-annotations"></a> for further information on this
+<p>See <a href="#data-indexing"></a> for further information on this
topic.</p>
</section>
@@ -2938,7 +2948,7 @@
<p>Summarized these differences mean that JSON-LD is capable of serializing any RDF
graph or dataset and most, but not all, JSON-LD documents can be transformed to RDF.
A complete description of the algorithms to convert from RDF to JSON-LD and from
- JSON-LD to RDF is included in the JSON-LD Algorithms and API specification
+ JSON-LD to RDF is included in the JSON-LD Algorithms and API specification
[[JSON-LD-API]].</p>
<p>Even though JSON-LD serializes RDF datasets, it can also be used as a RDF graph source.
@@ -2963,7 +2973,7 @@
<section>
<h3>Turtle</h3>
- <p>The following are examples of converting RDF expressed in Turtle [[TURTLE-TR]]
+ <p>The following are examples of converting RDF expressed in [[TURTLE-TR]]
into JSON-LD.</p>
<section>
@@ -2998,7 +3008,7 @@
-->
</pre>
-<p class="note">JSON-LD has no equivalent for the Turtle <code>@base</code>
+<p class="note">JSON-LD has no equivalent for the Turtle <code>@base</code>
declaration, but can use a prefix such as <code>base</code> to encode the
information in the document.</p>
@@ -3082,7 +3092,7 @@
<h3>RDFa</h3>
<p>The following example describes three people with their respective names and
- homepages in RDFa [[RDFA-CORE]].</p>
+homepages in [[RDFA-CORE]].</p>
<pre class="example" data-transform="updateExample"
title="RDFa fragment that describes three people">
@@ -3104,7 +3114,7 @@
</pre>
<p>An example JSON-LD implementation using a single <tref>context</tref> is
- described below.</p>
+described below.</p>
<pre class="example" data-transform="updateExample"
title="Same description in JSON-LD (context shared among node objects)">
@@ -3141,8 +3151,8 @@
<section>
<h3>Microformats</h3>
-<p>The following example uses a simple Microformats hCard example to express
- how Microformats [[MICROFORMATS]] are represented in JSON-LD.</p>
+<p>The following example uses a simple Microformats hCard ([[MICROFORMATS]]) example to express
+how the Microformat is represented in JSON-LD.</p>
<pre class="example" data-transform="updateExample"
title="HTML fragment with a simple Microformats hCard">
@@ -3154,9 +3164,9 @@
</pre>
<p>The representation of the hCard expresses the Microformat terms in the
- <tref>context</tref> and uses them directly for the <code>url</code> and <code>fn</code>
- properties. Also note that the Microformat to JSON-LD processor has
- generated the proper URL type for <code>http://tantek.com/</code>.</p>
+<tref>context</tref> and uses them directly for the <code>url</code> and <code>fn</code>
+properties. Also note that the Microformat to JSON-LD processor has
+generated the proper URL type for <code>http://tantek.com/</code>.</p>
<pre class="example" data-transform="updateExample"
title="Same hCard representation in JSON-LD">
@@ -3184,8 +3194,9 @@
<section>
<h3>Microdata</h3>
-<p>The HTML Microdata [[MICRODATA]] example below expresses book information as
- a Microdata Work item.</p>
+<p>The [[MICRODATA]] example below expresses book information as a microdata Work
+item.
+</p>
<pre class="example" data-transform="updateExample"
title="HTML fragments that describes a book using microdata">
@@ -3217,8 +3228,8 @@
</pre>
<p>Note that the JSON-LD representation of the Microdata information stays
- true to the desires of the Microdata community to avoid contexts and
- instead refer to items by their full <tref>IRI</tref>.</p>
+true to the desires of the Microdata community to avoid contexts and
+instead refer to items by their full <tref>IRI</tref>.</p>
<pre class="example" data-transform="updateExample"
title="Same book description in JSON-LD (avoiding contexts)">
@@ -3255,8 +3266,8 @@
<h1>IANA Considerations</h1>
<p>This section is included merely for standards community review and will be
- submitted to the Internet Engineering Steering Group if this specification
- becomes a W3C Recommendation.</p>
+submitted to the Internet Engineering Steering Group if this specification
+becomes a W3C Recommendation.</p>
<h3>application/ld+json</h3>
<dl>
@@ -3301,9 +3312,9 @@
directly evaluate the JSON-LD serialization and instead purely parse the
input into a language-native data structure. <br/>
JSON-LD contexts that are loaded from the Web over non-secure connections,
- such as HTTP, run the risk of modifying the JSON-LD
+ such as HTTP, run the risk of modifying the JSON-LD
<tref>active context</tref> in a way that could compromise security. It
- is advised that any application that depends on a remote context for mission
+ is advised that any application that depends on a remote context for mission
critical purposes vet and cache the remote context before allowing the
system to use it.</dd>
<dt>Interoperability considerations:</dt>
@@ -3350,19 +3361,19 @@
<h1>Acknowledgements</h1>
<p>The authors would like to extend a deep appreciation and the most sincere
- thanks to Mark Birbeck, who contributed foundational concepts
- to JSON-LD via his work on RDFj. JSON-LD uses a number of core concepts
+ thanks to Mark Birbeck, who contributed foundational concepts
+ to JSON-LD via his work on RDFj. JSON-LD uses a number of core concepts
introduced in RDFj, such as the context as a mechanism to provide an
environment for interpreting JSON data. Mark had also been very involved in
the work on RDFa as well. RDFj built upon that work. JSON-LD exists
because of the work and ideas he started nearly a decade ago in 2004.</p>
- <p>A large amount of thanks goes out to the JSON-LD Community Group
- participants who worked through many of the technical issues on the mailing
- list and the weekly telecons - of special mention are François Daoust,
+ <p>A large amount of thanks goes out to the JSON-LD Community Group
+ participants who worked through many of the technical issues on the mailing
+ list and the weekly telecons - of special mention are François Daoust,
Stéphane Corlosquet, Lin Clark, and Zdenko 'Denny' Vrandečić.</p>
- <p>The work of David I. Lehn and Mike Johnson are appreciated for
+ <p>The work of David I. Lehn and Mike Johnson are appreciated for
reviewing, and performing several implementations
of the specification. Thanks to Ian Davis for this work on RDF/JSON. Thanks also
to Nathan Rixham, Bradley P. Allen, Kingsley Idehen, Glenn McDonald, Alexandre Passant,