--- a/spec/latest/json-ld-syntax/index.html Sun Jan 20 11:53:53 2013 +0100
+++ b/spec/latest/json-ld-syntax/index.html Sun Jan 20 18:29:32 2013 -0500
@@ -1,7 +1,7 @@
<!DOCTYPE html>
<html>
<head>
-<title>JSON-LD 1.0</title>
+<title>JSON-LD Syntax 1.0</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<!--
=== NOTA BENE ===
@@ -18,13 +18,13 @@
doRDFa: "1.1",
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
- specStatus: "ED",
+ specStatus: "CG-FINAL",
// if you wish the publication date to be other than today, set this
//publishDate: "2012-12-25",
copyrightStart: "2010",
// the specification's short name, as in http://www.w3.org/TR/short-name/
- shortName: "json-ld-syntax",
+ shortName: "json-ld",
subtitle: "A JSON-based Serialization for Linked Data",
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
@@ -32,9 +32,10 @@
previousPublishDate: "2012-09-30",
previousMaturity: "ED",
previousDiffURI: "http://dvcs.w3.org/hg/json-ld/raw-file/66d980964784/spec/ED/json-ld-syntax/20120930/index.html",
+ diffTool: "http://www.aptest.com/standards/htmldiff/htmldiff.pl",
// if there a publicly available Editor's Draft, this is the link
- edDraftURI: "http://json-ld.org/spec/latest/json-ld-syntax/index.html",
+ edDraftURI: "http://dvcs.w3.org/hg/json-ld/raw-file/default/spec/latest/json-ld-syntax/index.html",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
@@ -101,60 +102,64 @@
<body>
<section id="abstract">
- <p>JSON has proven to be a highly useful object serialization and messaging format.
- In an attempt to harmonize the representation of <tref>Linked Data</tref>
- in JSON, this specification outlines a common JSON representation format for
- expressing directed graphs; mixing both Linked Data and non-Linked Data in
- a single document.</p>
+<p>
+JSON has proven to be a highly useful object serialization and messaging format.
+In an attempt to harmonize the representation of <tref>Linked Data</tref>
+in JSON, this specification outlines a common JSON representation format for
+expressing directed graphs; mixing both Linked Data and non-Linked Data in
+a single document.
+</p>
</section>
-<section id="sotd">
- <p>This document has been under development for over 20 months in the
- JSON for Linking Data Community Group. The document has recently been
- transferred to the RDF Working Group for review, improvement, and publication
- along the Recommendation track. The specification has undergone significant
- development, review, and changes during the course of the last 20 months.</p>
-
- <p>There are several independent
- <a href="http://json-ld.org/#impl">interoperable implementations</a> of
- this specification. There is a
- <a href="https://github.com/json-ld/json-ld.org/tree/master/test-suite">fairly complete test suite</a>
- and a <a href="http://json-ld.org/playground/">live JSON-LD editor</a>
- that is capable of demonstrating the features described in
- this document. While development on implementations, the test suite
- and the live editor will continue, they are believed to be mature enough
- to be integrated into a non-production system at this point in time with
- the expectation that they could be used in a production system within the
- next year.</p>
-
- <p>There are a number of ways that one may participate in the development of
- this specification:</p>
-
- <ul>
- <li>If you want to make sure that your feedback is formally addressed by
- the RDF Working Group, you should send it to public-rdf-comments:
- <a href="http://lists.w3.org/Archives/Public/public-rdf-comments/">public-rdf-comments@w3.org</a></li>
-
- <li>Ad-hoc technical discussion primarily occurs on the public community mailing list:
- <a href="http://lists.w3.org/Archives/Public/public-linked-json/">public-linked-json@w3.org</a></li>
-
- <li><a href="http://json-ld.org/minutes/">Public JSON-LD Community Group teleconferences</a>
- are held on Tuesdays at 1500UTC every week.</li>
-
- <li>RDF Working Group teleconferences are held on Wednesdays at 1500UTC
- every week. Participation is limited to RDF Working Group members.</li>
-
- <li>Specification bugs and issues should be reported in the
- <a href="https://github.com/json-ld/json-ld.org/issues">issue tracker</a>
- if you do not want to send an e-mail to the public-rdf-comments mailing
- list.</li>
-
- <li><a href="https://github.com/json-ld/json-ld.org/tree/master/spec">Source code</a>
- for the specification can be found on Github.</li>
-
- <li>The <a href="http://webchat.freenode.net/?channels=json-ld">#json-ld</a>
- IRC channel is available for real-time discussion on irc.freenode.net.</li>
- </ul>
+<section id='sotd'>
+<p>This document has been under development for over 25 months in the
+JSON for Linking Data Community Group. The document has recently been
+transferred to the RDF Working Group for review, improvement, and publication.
+The specification has undergone significant
+development, review, and changes during the course of the last 25 months.
+</p>
+<p>There are several independent
+<a href="http://json-ld.org/#impl">interoperable implementations</a> of
+this specification. There is
+a <a href="https://github.com/json-ld/json-ld.org/tree/master/test-suite">fairly complete test suite</a>
+and a <a href="http://json-ld.org/playground/">live JSON-LD editor</a>
+that is capable of demonstrating the features described in
+this document. While development on implementations, the test suite
+and the live editor will continue, they are believed to be mature enough
+to be integrated into a non-production system at this point in time with
+the expectation that they could be used in a production system within the
+next year.
+</p>
+
+<p>There are a number of ways that one may participate in the development of
+this specification:</p>
+
+<ul>
+ <li>If you want to make sure that your feedback is formally addressed by
+ the RDF Working Group, you should send it to public-rdf-comments:
+ <a href="http://lists.w3.org/Archives/Public/public-rdf-comments/">public-rdf-comments@w3.org</a></li>
+
+ <li>Ad-hoc technical discussion primarily occurs on the public community mailing list:
+ <a href="http://lists.w3.org/Archives/Public/public-linked-json/">public-linked-json@w3.org</a></li>
+
+ <li><a href="http://json-ld.org/minutes/">Public JSON-LD Community Group teleconferences</a>
+ are held on Tuesdays at 1500UTC every week.</li>
+
+ <li>RDF Working Group teleconferences are held on Wednesdays at 1500UTC
+ every week. Participation is limited to RDF Working Group members.</li>
+
+ <li>Specification bugs and issues should be reported in the
+ <a href="https://github.com/json-ld/json-ld.org/issues">issue tracker</a>
+ if you do not want to send an e-mail to the public-rdf-comments mailing
+ list.</li>
+
+ <li><a href="https://github.com/json-ld/json-ld.org/tree/master/spec">Source code</a>
+ for the specification can be found on Github.</li>
+
+ <li>The <a href="http://webchat.freenode.net/?channels=json-ld">#json-ld</a>
+ IRC channel is available for real-time discussion on irc.freenode.net.</li>
+</ul>
+
</section>
<section class="informative">
@@ -180,8 +185,8 @@
JSON-LD introduces:</p>
<ul>
- <li>a universal identifier mechanism for <tref title="JSON object">JSON objects</tref>
- via the use of <tref title="IRI">IRIs</tref>,</li>
+ <li>a universal identifier mechanism for <tref title="JSON object">JSON objects</tref> via the
+ use of <tref title="IRI">IRIs</tref>,</li>
<li>a way to disambiguate the keys used between multiple JSON documents
by mapping them to <tref title="IRI">IRIs</tref> via a <tref>context</tref>,</li>
<li>a mechanism in which a value in a <tref>JSON object</tref> may refer
@@ -225,525 +230,432 @@
</section>
<section class="informative">
- <h1>Design Goals and Rationale</h1>
-
- <p>A number of design goals were established before the creation of this
- markup language:</p>
-
- <dl>
- <dt>Simplicity</dt>
- <dd>No extra processors or software libraries should be necessary to use JSON-LD
- in its most basic form. The language will provide developers with a very easy
- learning curve. Developers only need to know JSON and two
- <tref title="keyword">keywords</tref> (<code>@context</code>
- and <code>@id</code>) to use the basic functionality in JSON-LD.</dd>
- <dt>Compatibility</dt>
- <dd>The JSON-LD markup must be 100% compatible with JSON. This ensures that
- all of the standard JSON libraries work seamlessly with JSON-LD documents.</dd>
- <dt>Expressiveness</dt>
- <dd>The syntax must be able to express directed graphs, which have been proven
- to be able to express almost every real world data model.</dd>
- <dt>Terseness</dt>
- <dd>The JSON-LD syntax must be very terse and human readable, requiring as
- little effort as possible from the developer.</dd>
- <dt>Zero Edits, most of the time</dt>
- <dd>JSON-LD must provide a <a href="#referencing-contexts-from-json-documents">mechanism</a>
- that allows developers to reference <tref title="context">contexts</tref> in
- responses using plain old JSON. 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
- transparent to their current customers. At times, mapping JSON to
- a graph representation can become difficult. In these instances, rather than
- having JSON-LD support an esoteric use case, we chose not to support the
- use case and support a simplified syntax instead. So, while Zero Edits is
- a design goal, it is not always possible without adding great complexity to
- the language.</dd>
- <dt>One-pass Processing</dt>
- <dd>JSON-LD supports one-pass processing, which results in a very small memory
- footprint when processing documents. For example, to expand a JSON-LD document
- from a compacted form, only one pass is required over the data.</dd>
- </dl>
+<h1>Design Goals and Rationale</h1>
+
+<p>A number of design goals were established before the creation of this
+ markup language:</p>
+
+<dl>
+ <dt>Simplicity</dt>
+ <dd>No extra
+ processors or software libraries should be necessary to use JSON-LD in its most
+ basic form. The language will provide developers with a very easy
+ learning curve. Developers only need to know JSON and two
+ <tref title="keyword">keywords</tref> (<code>@context</code>
+ and <code>@id</code>) to use the basic functionality in JSON-LD.</dd>
+ <dt>Compatibility</dt>
+ <dd>The JSON-LD markup must be 100% compatible with JSON. This ensures that
+ all of the standard JSON libraries work seamlessly with JSON-LD documents.</dd>
+ <dt>Expressiveness</dt>
+ <dd>The syntax must be able to express directed graphs, which have been proven
+ to be able to express almost every real world data model.</dd>
+ <dt>Terseness</dt>
+ <dd>The JSON-LD syntax must be very terse and human readable, requiring as
+ little effort as possible from the developer.</dd>
+ <!--<dt>Pragmatism</dt>
+ <dd>Mixing the expression of pure Linked Data with data that is not
+ linked was an approach that was driven by pragmatism. JSON-LD attempts to be
+ more practical than theoretical in its approach to Linked Data.</dd>-->
+ <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="#referencing-contexts-from-json-documents"></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
+ transparent to their current customers. However, there are times where
+ mapping JSON to a graph representation is more complex than a simple one-line
+ change. In these instances, rather than extending JSON-LD to support an
+ esoteric use case, we chose not to support the use case. While Zero Edits is
+ a design goal, it is not always possible without adding great complexity
+ to the language. We should focus on simplicity when possible.
+ </dd>
+ <dt>One-pass Processing</dt>
+ <dd>JSON-LD supports one-pass processing, which results in a very small memory
+ footprint when processing documents. For example, to expand a JSON-LD document
+ from a compacted form, only one pass is required over the data. This mechanism
+ should make some forms of JSON-LD very useful when used in streaming
+ protocols.</dd>
+</dl>
</section>
<section class="normative">
<h1>Terminology</h1>
- <section>
- <h2>General Terminology</h2>
-
- <p>This document uses the following terms as defined in JSON [[!RFC4627]]. Refer
- to the <em>JSON Grammar</em> section in [[!RFC4627]] for formal definitions.</p>
-
- <dl>
- <dt><tdef>JSON object</tdef></dt><dd>
- An object structure is represented as a pair of curly brackets
- surrounding zero or more key-value pairs. A key is a
- <tref>string</tref>. A single colon comes after each key, separating the
- key from the value. A single comma separates a value from a following
- key.
- </dd>
- <dt><tdef>array</tdef></dt>
- <dd>
- An array structure is represented as square brackets surrounding zero
- or more values (or elements). Elements are separated by commas.
- In JSON, an array is an <em>ordered</em> sequence of zero or more values.
- 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
- unless specific markup is provided (see <a 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). A
- character is represented as a single character string.</dd>
- <dt><tdef>number</tdef></dt>
- <dd>
- A number is similar to that used in most programming languages, except
- that the octal and hexadecimal formats are not used and that leading
- zeros are not allowed.</dd>
- <dt><tdef>true</tdef> and <tdef>false</tdef></dt><dd>
- Values that are used to express one of two possible boolean states.</dd>
- <dt><tdef>null</tdef></dt>
- <dd>The <tref>null</tref> value. A key-value pair in the
- <code>@context</code> where the value, or the <code>@id</code> of the
- value, is <tref>null</tref> explicitly decouples a term's association
- with an IRI. A key-value pair in the body of a JSON-LD document whose
- value is <tref>null</tref> has the same meaning as if the key-value pair
- was not defined. If <code>@value</code>, <code>@list</code>, or
- <code>@set</code> is set to <tref>null</tref> in expanded form, then
- the entire <tref>JSON object</tref> is ignored.</dd>
- </dl>
- </section>
-
- <section>
- <h2>Syntax Tokens and Keywords</h2>
-
- <p>JSON-LD specifies a number of syntax tokens and <tdef title="keyword">keywords</tdef>
- 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 native 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 container of a particular value.
- 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>@annotation</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-annotations"></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>
- <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>
- </dl>
-
- <p>For the avoidance of doubt, all keys, <tref title="keyword">keywords</tref>,
- and values in JSON-LD are case-sensitive.</p>
- </section>
+<section>
+ <h2>General Terminology</h2>
+
+ <p>This document uses the following terms as defined in JSON [[!RFC4627]]. Refer
+ to the <em>JSON Grammar</em> section in [[!RFC4627]] for formal definitions.</p>
+
+ <dl>
+ <dt><tdef>JSON object</tdef></dt><dd>
+ An object structure is represented as a pair of curly brackets
+ surrounding zero or more key-value pairs. A key is a
+ <tref>string</tref>. A single colon comes after each key, separating the
+ key from the value. A single comma separates a value from a following
+ key.
+ </dd>
+ <dt><tdef>array</tdef></dt>
+ <dd>
+ An array structure is represented as square brackets surrounding zero
+ or more values. Values are separated by commas.
+ In JSON, an array is an <em>ordered</em> sequence of zero or more values.
+ 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
+ unless specific markup is provided (see <a 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). A
+ character is represented as a single character string.</dd>
+ <dt><tdef>number</tdef></dt>
+ <dd>
+ A number is similar to that used in most programming languages, except
+ that the octal and hexadecimal formats are not used and that leading
+ zeros are not allowed.</dd>
+ <dt><tdef>true</tdef> and <tdef>false</tdef></dt><dd>
+ Values that are used to express one of two possible boolean states.</dd>
+ <dt><tdef>null</tdef></dt>
+ <dd>The <tref>null</tref> value, which is typically used to clear or forget
+ data. For example, A key-value pair in the
+ <code>@context</code> where the value is <tref>null</tref> explicitly
+ decouples a <tref>term</tref>'s association with an <tref>IRI</tref>.
+ A key-value pair in the body of a JSON-LD document whose
+ value is <tref>null</tref> has the same meaning as if the key-value pair
+ was not defined. If <code>@value</code>, <code>@list</code>, or
+ <code>@set</code> is set to <tref>null</tref> in expanded form, then
+ the entire <tref>JSON object</tref> is ignored.</dd>
+ </dl>
+</section>
+
+<section>
+<h2>Syntax Tokens and Keywords</h2>
+
+<p>JSON-LD specifies a number of syntax tokens and <tdef title="keyword">keywords</tdef>
+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 native 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>@annotation</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-annotations"></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>
+<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>
+</dl>
+
+<p>For the avoidance of doubt, all keys, <tref title="keyword">keywords</tref>, and values in JSON-LD are
+case-sensitive.</p>
+</section>
+
</section>
<section class="normative">
- <h1>Conformance</h1>
-
- <p>The JSON-LD Syntax specification describes the conformance criteria for
- JSON-LD documents (relevant to authors and authoring tool implementors).</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
- can be interpreted as JSON-LD by following the normative statements in section
- <a href="#the-context"></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,
- RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this Recommendation have the
- meaning defined in [[!RFC2119]].</p>
+<h1>Conformance</h1>
+
+<p>The JSON-LD specification describes the conformance criteria for JSON-LD documents (relevant to authors and authoring tool implementors).</p>
+
+<p>A <tref>JSON-LD document</tref> complies with this specification if it follows the normative statements for documents defined in sections <a href="#referencing-contexts-from-json-documents"></a> and <a href="#json-ld-grammar"></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, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this Recommendation have the meaning defined in [[!RFC2119]].</p>
+
</section>
<section class="normative">
- <h1>Basic Concepts</h1>
-
- <p>JSON [[RFC4627]] is a lightweight, language-independent data-interchange format.
- It is easy to parse and easy to generate. However, it is difficult to integrate JSON
- from different sources as the data has just local meaning. Furthermore, JSON has no
- built-in support for hyperlinks - a fundamental building block on the Web. Let's look
- at an example that we will be using for the rest of this section:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Sample JSON document">
- <!--
+<h1>Basic Concepts</h1>
+
+<section>
+<h2>The Context</h2>
+
+<p>In JSON-LD, a <tdef>context</tdef> is used to map <tref title="term">terms</tref>, i.e., properties with associated
+ values in an JSON document, to <tref title="IRI">IRIs</tref>.</p>
+<p>The Web uses <tref title="IRI">IRIs</tref> for unambiguous identification. The
+ idea is that these <tref title="term">terms</tref> mean something that may be of use to other developers and that it is useful to
+ give them an unambiguous identifier. That is, it is useful for <tref title="term">terms</tref> to expand to IRIs so that
+ developers don't accidentally step on each other's <tdef>vocabulary</tdef> terms and other resources. Furthermore, developers, and
+ machines, are able to use this <tref>IRI</tref> (by plugging it directly into a web browser, for instance) to go to
+ the term and get a definition of what the term means. This mechanism is analogous to the way we can use
+ <a href="http://wordnet.princeton.edu/">WordNet</a> today to see the definition of words in the English language.
+ Developers and machines need the same sort of definition of terms. <tref title="IRI">IRIs</tref> provide a way to
+ ensure that these terms are unambiguous. For example, the term <code>name</code> may
+ map directly to the IRI <code>http://xmlns.com/foaf/0.1/name</code>. This allows JSON-LD documents to be constructed
+ using the common JSON practice of simple key-value pairs while ensuring that the data is useful outside of the
+ page, API or database in which it resides.</p>
+
+<p>Note that, to avoid forward-compatibility issues, terms starting with an <code>@</code> character are to be avoided as they might be used as keywords 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>
+
+<p>In a JSON-LD document, the mapping between <tref title="term">terms</tref> and
+ <tref title="IRI">IRIs</tref> is typically collected in a <tref>context definition</tref>
+ that would look something like this:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Context definition">
+<!--
+{
+ "@context":
{
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "depiction":
+ {
+ "@id": "http://xmlns.com/foaf/0.1/depiction",
+ "@type": "@id"
+ },
+ "homepage":
+ {
+ "@id": "http://xmlns.com/foaf/0.1/homepage",
+ "@type": "@id"
+ },
+ }
+}
+-->
+</pre>
+
+<p>
+Let's assume that a developer starts with the following JSON document:
+</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Sample JSON document">
+<!--
+{
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/",
+ "depiction": "http://twitter.com/account/profile_image/manusporny"
+}
+-->
+</pre>
+
+<p>The developer can add a single line to the JSON document above
+to reference the context and transform it into a JSON-LD document:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Referencing a JSON-LD context">
+<!--
+{
+ ****"@context": "http://json-ld.org/contexts/person.jsonld",****
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/",
+ "depiction": "http://twitter.com/account/profile_image/manusporny"
+}
+-->
+</pre>
+
+<p>The additions above transform the previous JSON document into a JSON document
+with added semantics because the <code>@context</code> specifies how the
+<strong>name</strong>, <strong>homepage</strong>, and <strong>depiction</strong>
+terms map to <tref title="IRI">IRIs</tref>.
+Mapping those keys to IRIs gives the data global context. If two
+developers use the same IRI to describe a property, they are more than likely
+expressing the same concept. This allows both developers to re-use each others'
+data without having to agree to how their data will interoperate on a
+site-by-site basis. Contexts may also contain type, language or additional information
+for certain <tref title="term">terms</tref>.</p>
+
+<p>External JSON-LD context documents may contain extra information
+located outside of the <code>@context</code> key, such as documentation about the
+<tref title="term">terms</tref> declared in the document. Information contained
+outside of the <code>@context</code> value is simply discarded when the document
+is used as an external JSON-LD context document
+(see <a href="#referencing-contexts-from-json-documents"></a>).</p>
+
+<p>Contexts may also be specified in-line. This ensures that
+ <tref title="JSON-LD document">JSON-LD documents</tref> can be understood
+ even in the absence of a connection to the Web.</p>
+
+<pre class="example" data-transform="updateExample"
+ title="In-line context definition">
+<!--
+{
+ ****"@context":
+ {
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "depiction":
+ {
+ "@id": "http://xmlns.com/foaf/0.1/depiction",
+ "@type": "@id"
+ },
+ "homepage":
+ {
+ "@id": "http://xmlns.com/foaf/0.1/homepage",
+ "@type": "@id"
+ },
+ },****
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/",
+ "depiction": "http://twitter.com/account/profile_image/manusporny"
+}
+-->
+</pre>
+
+<p>Contexts may be used at any time a <tref>node object</tref> is defined.
+ In particular, a <tref>JSON-LD document</tref> may define more than one context,
+ as in the following example:</p>
+<pre class="example" data-transform="updateExample"
+ title="Multiple separate contexts">
+<!--
+[
+ {
+ ****"@context": "http://example.org/contexts/person.jsonld",****
"name": "Manu Sporny",
"homepage": "http://manu.sporny.org/",
- "image": "http://twitter.com/account/profile_image/manusporny",
- "knows": [
- {
- "name": "Markus Lanthaler"
- },
- {
- "name": "Gregg Kellogg"
- }
- ]
+ "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>It's obvious for humans that the data is about a person whose name is "Manu Sporny"
- and that the <code>homepage</code> property contains the URL of that person's homepage.
- On the other hand, a machine doesn't have such an intuitive understanding and sometimes
- even for humans it is difficult to resolve ambiguities in such representations. This problem
- can be solved by using unambiguous identifiers to denote the different concepts instead of
- <tref title="term">terms</tref> such as "name", "homepage", etc.</p>
-
- <p><tref>Linked Data</tref>, and the Web in general, uses <tref title="IRI">IRIs</tref>
- (Internationalized Resource Identifiers as described in [[!RFC3987]]) for unambiguous
- identification. The idea is to assign <tref title="IRI">IRIs</tref> to something that may
- be of use to other developers and that it is useful to give them an unambiguous identifier.
- That is, it is useful for <tref title="term">terms</tref> to expand to <tref title="IRI">IRIs</tref>
- so that developers don't accidentally step on each other's terms. Furthermore, developers and
- machines, are able to use this <tref>IRI</tref> (by using a web browser, for instance) to go to
- the term and get a definition of what the term means. This mechanism is analogous to the way we
- can, e.g., use <a href="http://www.wikipedia.org/">Wikipedia</a> to see the definition of words.</p>
-
- <p>Leveraging the well-known <a href="http://xmlns.com/foaf/spec/">FOAF vocabulary</a>,
- the example above could thus be unambiguously expressed as follows:</p>
+]
+-->
+</pre>
+
+<p>This is useful when an author would like to use an existing context
+ and add application-specific terms to the existing context. Duplicate context
+ <tref title="term">terms</tref> are overridden using a last-defined-overrides
+ mechanism.</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Scoped contexts within node objects">
+<!--
+{
+ ****"@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>In the example above, the <code>name</code> prefix 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 there exist
+ legacy applications that depend on the specific structure of the
+ <tref>JSON object</tref>. If a <tref>term</tref> is re-defined within a
+ context, all previous rules associated with the previous definition are
+ removed. If that <tref>term</tref> is re-defined 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>A <tref>node object</tref> may specify multiple contexts, using an
+ <tref>array</tref>, processed in order. The set of contexts defined within a specific <tref>node object</tref> are
+ referred to as <tdef title="local context">local contexts</tdef>. Setting the context to <code>null</code>
+ effectively resets the <tref>active context</tref> to an empty context. 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. The following example
+ specifies an external context and then layers a local 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",
+ {
+ "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 class="note">To ensure the best possible performance, it is a best practice to
+ put the <tref>context</tref> definition at the top of the JSON-LD document. If it isn't listed
+ first, processors have to save each key-value pair until the <tref>context</tref> is processed.
+ This creates a memory and complexity burden for certain types of
+ low-memory footprint JSON-LD processors.</p>
+
+</section>
+
+<section>
+ <h2>From JSON to JSON-LD</h2>
+
+ <p>If a set of <tref title="term">terms</tref> such as, <strong>name</strong>,
+ <strong>homepage</strong>, and <strong>depiction</strong>,
+ are defined in a <tref>context</tref>, and that context is used to resolve the
+ names in <tref title="JSON object">JSON objects</tref>, machines are able to automatically expand the terms to
+ something unambiguous like this:</p>
<pre class="example" data-transform="updateExample"
- title="Sample JSON-LD document using full IRIs instead of terms">
+ title="Expanded terms">
<!--
{
"****http://xmlns.com/foaf/0.1/name****": "Manu Sporny",
- "****http://xmlns.com/foaf/0.1/homepage****": { "****@id****": "http://manu.sporny.org/" },
- "****http://xmlns.com/foaf/0.1/img****": { "****@id****": "http://twitter.com/account/profile_image/manusporny" },
- "****http://xmlns.com/foaf/0.1/knows****": [
- {
- "****http://xmlns.com/foaf/0.1/name****": "Markus Lanthaler"
- },
- {
- "****http://xmlns.com/foaf/0.1/name****": "Gregg Kellogg"
- }
- ]
+ "****http://xmlns.com/foaf/0.1/homepage****": "http://manu.sporny.org"
+ "****http://xmlns.com/foaf/0.1/depiction****": "http://twitter.com/account/profile_image/manusporny"
}
- -->
+ -->
</pre>
- <p>Every property is unambiguously identified by an <tref>IRI</tref> and all values
- representing <tref title="IRI">IRIs</tref> are explicitly marked as such by the
- <code>@id</code> <tref>keyword</tref>. While this is a completely valid JSON-LD
- document that is unambiguous and very specific, it also very verbose and difficult
- to work with for human users. To address this issue, JSON-LD introduces the notion
- of a <tref>context</tref> as described in the next section.</p>
-
- <section>
- <h2>The Context</h2>
-
- <p>Simply speaking, a <tdef>context</tdef> is used to map <tref title="term">terms</tref>,
- i.e., <tref title="property">properties</tref> with associated values, to
- <tref title="IRI">IRIs</tref>. Any valid <tref>string</tref> that is not a
- reserved JSON-LD <tref>keyword</tref> can be used as a <tref>term</tref>. 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
- keywords 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>
-
- <p>For the sample document in the previous section, a <tref>context</tref> would
- look something like this:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Context for the sample document in the previous section">
- <!--
- {
- "****@context****":
- {
- "name": "http://xmlns.com/foaf/0.1/name",
- "image": {
- "@id": "http://xmlns.com/foaf/0.1/img",
- "@type": "@id"
- },
- "homepage": {
- "@id": "http://xmlns.com/foaf/0.1/homepage",
- "@type": "@id"
- },
- "knows": "http://xmlns.com/foaf/0.1/knows"
- }
- }
- -->
- </pre>
-
- <p>As <tref>context</tref> above shows, the value of a <tdef>term definition</tdef> can
- either be 1) a simple string mapping the <tref>term</tref> to an <tref>IRI</tref>,
- or 2) an <tref>expanded term definition</tref> in the form of a <tref>JSON object</tref>
- to allow additional information to be associated with the term.</p>
-
- <p><tref title="expanded term definition">Expanded term definitions</tref> may
- be used to associate <a href="#type-coercion">type</a> or
- <a href="#string-internationalization">language information</a> (as in the
- example above which specifies that the values of <code>image</code> and
- <code>homepage</code> are <tref title="IRI">IRIs</tref>) with a term.
- Furthermore, they allow terms to be used for <a href="#data-annotations">annotation 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
- be defined using <tref title="absolute IRI">absolute</tref> or
- <tref title="compact IRI">compact IRIs</tref> as keys. This mechanism is
- mainly used to associate type or language information with an
- <tref title="absolute IRI">absolute</tref> or <tref>compact IRI</tref>.</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><tref title="context">Contexts</tref> can either be directly embedded
- into the document or be referenced. Assuming the context document in the previous
- example can be retrieved at <code>http://json-ld.org/contexts/person.jsonld</code>,
- it can be referenced by adding a single line and allows a JSON-LD document to
- be expressed much more concisely as shown in the example below:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Referencing a JSON-LD context">
- <!--
- {
- ****"@context": "http://json-ld.org/contexts/person.jsonld",****
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/",
- "image": "http://twitter.com/account/profile_image/manusporny",
- "knows": [
- {
- "name": "Markus Lanthaler"
- },
- {
- "name": "Gregg Kellogg"
- }
- ]
- }
- -->
- </pre>
-
- <p>The referenced context not only specifies how the terms map to
- <tref title="IRI">IRIs</tref> in the FOAF 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 gives the
- data global context and allows developers to re-use each others 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
- documentation about the <tref title="term">terms</tref> declared in the
- document. Information contained outside of the <code>@context</code> value
- is ignored when the document is used as an external JSON-LD context document.</p>
-
- <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 workflow 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="Referening 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/",
- "depiction": "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>
-
- <p>As already mentioned, in <tref title="JSON-LD document">JSON-LD documents</tref>
- it is also possible to embed <tref title="context">contexts</tref> directly
- into the document. This has the advantage that
- <tref title="JSON-LD document">JSON-LD documents</tref> can be processed
- even in the absence of a connection to the Web.</p>
-
- <pre class="example" data-transform="updateExample"
- title="In-line context definition">
- <!--
- {
- ****"@context":
- {
- "name": "http://xmlns.com/foaf/0.1/name",
- "image": {
- "@id": "http://xmlns.com/foaf/0.1/img",
- "@type": "@id"
- },
- "homepage": {
- "@id": "http://xmlns.com/foaf/0.1/homepage",
- "@type": "@id"
- }
- },****
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/",
- "image": "http://twitter.com/account/profile_image/manusporny"
- }
- -->
- </pre>
-
- <p>Contexts may be used at any time a <tref>JSON object</tref> is defined
- (except inside a context definition). In particular, a
- <tref>JSON-LD document</tref> may define more than one context, as in the
- following example:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Multiple separate 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>This is useful when an author would like to use an existing context
- and add application-specific terms to the existing context. Duplicate context
- <tref title="term">terms</tref> are overridden using a last-defined-overrides
- mechanism.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Scoped contexts within node objects">
- <!--
- {
- ****"@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>In the example above, the <code>name</code> prefix 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 there exist
- legacy applications that depend on the specific structure of the
- <tref>JSON object</tref>. If a <tref>term</tref> is re-defined within a
- context, all previous rules associated with the previous definition are
- removed. If that <tref>term</tref> is re-defined 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> is
- referred to as <tdef title="local context">local contexts</tdef>. Setting a
- <tref>local context</tref> to <code>null</code> effectively resets the
- <tref>active context</tref> to an empty context. 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. 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",
- {
- "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 class="note">To ensure the best possible performance, it is a best practice to
- put the <tref>context</tref> definition at the top of the JSON-LD document. If it isn't listed
- first, processors have to save each key-value pair until the <tref>context</tref> is processed.
- This creates a memory and complexity burden for certain types of
- low-memory footprint JSON-LD processors.</p>
- </section>
+ <p>Doing this allows JSON to be unambiguously machine-readable without
+ requiring developers to drastically change their workflow. A <tref>JSON object</tref>
+ used to define property values of a <tref>node</tref> is called a <tref>node object</tref>.</p>
+
+ <p class="note">The example above does not use the <code>@id</code> <tref>keyword</tref>
+ to identify the node being described above. This type of node is called a
+ <tref>blank node</tref>. It is advised that all <tref title="node object">node objects</tref>
+ in JSON-LD are identified by <tref title="IRI">IRIs</tref> via the <code>@id</code>
+ keyword unless the data is not intended to be linked to from other data sets.</p>
+</section>
<section>
<h2>IRIs</h2>
@@ -915,7 +827,8 @@
an unambiguous identifier. <tref title="IRI">IRIs</tref> are a fundamental concept of
<tref>Linked Data</tref>, and nodes should have a de-referencable
identifier used to name and locate them. For nodes to be truly linked,
- de-referencing the identifier should result in a representation of that node.
+ de-referencing the identifier should result in a representation of that node
+ (for example, using a URL to retrieve a web page).
Associating an IRI with a node tells an application that the returned
document contains a description of the node requested.</p>
@@ -1152,9 +1065,10 @@
<h2>Compact IRIs</h2>
<p>
<tref title="term">Terms</tref> in <tref>Linked Data</tref> documents may draw from
- a number of different vocabularies. At times, declaring every single <tref>term</tref>
- that a document uses can require the developer to declare tens, if not hundreds of potential
- vocabulary <tref title="term">terms</tref> that are used across an
+ a number of different <tref title="vocabulary">vocabularies</tref>.
+ At times, declaring every single <tref>term</tref> that a document uses can require the
+ developer to declare tens, if not hundreds of potential
+ <tref>vocabulary</tref> <tref title="term">terms</tref> that are used across an
application. This is a concern for at least two reasons: the
first is the cognitive load on the developer of remembering all of the
<tref title="term">terms</tref>, and the second is the serialized size of the
@@ -1170,11 +1084,12 @@
For example, the prefix <code>foaf</code> may be used as a short
hand for the Friend-of-a-Friend vocabulary, which is identified using
the IRI <code>http://xmlns.com/foaf/0.1/</code>. A developer may append
- any of the FOAF vocabulary terms to the end of the prefix to specify a short-hand
- version of the <tref>absolute IRI</tref> for the vocabulary term. For example,
- <code>foaf:name</code> would be expanded out to the IRI
- <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.
+ any of the FOAF <tref>vocabulary</tref> terms to the end of the prefix
+ to specify a short-hand version of the <tref>absolute IRI</tref> for the
+ <tref>vocabulary</tref> term. For example, <code>foaf:name</code> would
+ be expanded out to the IRI <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>Terms are interpreted as <tref title="compact IRI">compact IRIs</tref> if they contain at least one
colon and the first colon is not followed by two slashes (<code>//</code>, as in
@@ -1216,14 +1131,13 @@
}
-->
</pre>
-
- <p>In this example, two different vocabularies are referred to using prefixes.
- Those prefixes are then used as type and property values using the compact
- IRI <code>prefix:suffix</code> notation.</p>
-
+ <p>
+ In this example, two different <tref title="vocabulary">vocabularies</tref>
+ are referred to using prefixes. Those prefixes are then used as type and
+ property values using the compact IRI <code>prefix:suffix</code> notation.
+ </p>
<p>It's also possible to use compact IRIs within the context as shown in the
following example:</p>
-
<pre class="example" data-transform="updateExample"
title="Using vocabularies">
<!--
@@ -1473,6 +1387,144 @@
</section>
<section>
+<h2>Referencing Contexts from JSON Documents</h2>
+
+<p>Ordinary JSON documents can be transformed into JSON-LD documents by referencing
+to an external JSON-LD <tref>context</tref> in an HTTP Link Header. Doing this
+allows JSON to be unambiguously machine-readable without requiring developers to
+drastically change their workflow 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>node object</tref>. The
+<code>@context</code> subtree within that object is added to the top-level
+<tref>node 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="node object">node 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.
+</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="Specifing context through HTTP 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/",
+ "depiction": "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>
+
+</section>
+
+<section>
+<h3>Expanded Term Definition</h3>
+
+<p>Within a <tref>context</tref> definition, <tref title="term">terms</tref> may be
+ defined using an <tref>expanded term definition</tref> to allow for additional information
+ associated with the <tref>term</tref> to be specified (see also
+ <a href="#type-coercion"></a> and
+ <a href="#sets-and-lists"></a>).</p>
+
+<p>Instead of using a string representation of an IRI, the IRI may be
+specified using a <tref>JSON object</tref> having an <code>@id</code> key,
+and a <tref>term</tref>, a <tref>compact IRI</tref>, or an
+<tref>absolute IRI</tref> as value.</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Expanded term definition">
+<!--
+{
+ "@context":
+ {
+ "foaf": ****{ "@id": "http://xmlns.com/foaf/0.1/" }****,
+ "name": ****{ "@id": "http://xmlns.com/foaf/0.1/name" }****,
+ "homepage": ****{ "@id": "foaf:homepage" }****,
+ "depiction": ****{ "@id": "foaf:depiction" }****
+ },
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/",
+ "depiction": "http://twitter.com/account/profile_image/manusporny"
+}
+-->
+</pre>
+
+<p>This allows additional information to be associated with the term. This
+ may be used for <a href="#type-coercion"></a>,
+ <a href="#sets-and-lists"></a>, or to associate language
+ information with a <tref>term</tref> as shown in the following example:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Expanded term definition with language">
+<!--
+{
+ "@context": {
+ ...
+ "ex": "http://example.com/",
+ "@language": "ja",
+ "name": { "@id": "ex:name", ****"@language": null**** },
+ "occupation": { "@id": "ex:occupation" },
+ "occupation_en": { "@id": "ex:occupation", ****"@language": "en"**** },
+ "occupation_cs": { "@id": "ex:occupation", ****"@language": "cs"**** }
+ },
+ ****"name": "Yagyū Muneyoshi",
+ "occupation": "忍者",
+ "occupation_en": "Ninja",
+ "occupation_cs": "Nindža",****
+ ...
+}
+-->
+</pre>
+
+<p>The example above would associate <em>忍者</em> with the specified default
+ language code <code>ja</code>, <em>Ninja</em> with the language code
+ <code>en</code>, and <em>Nindža</em> with the language code <code>cs</code>.
+ The value of <code>name</code>, <em>Yagyū Muneyoshi</em> wouldn't be
+ associated with any language code since <code>@language</code> was reset to
+ <tref>null</tref> in the <tref>expanded term definition</tref>.</p>
+
+<p>Expanded terms may also be defined using <tref title="compact_iri">compact IRIs</tref> or
+ <tref title="absolute_IRI">absolute IRIs</tref> as keys. If the definition does not include an
+ <code>@id</code> key, the expanded IRI is determined by performing expansion of the key
+ within the current <tref>active context</tref>. This mechanism is mainly used to associate type or language
+ information with a <tref>compact IRI</tref> or an <tref>absolute IRI</tref>.</p>
+
+<p class="note">While it is possible to define a
+ <tref>compact IRI</tref>, or an absolute IRI to expand to some
+ other unrelated IRI (for example, <code>foaf:name</code> expanding to
+ <code>http://example.org/unrelated#species</code>),
+ such usage is strongly discouraged.</p>
+</section>
+
+<section>
<h2>Type Coercion</h2>
<p>JSON-LD supports the coercion of values to particular data types.
@@ -1487,7 +1539,7 @@
that within the body of a JSON-LD document, a string value of a <tref>term</tref> coerced to
<code>@id</code> is to be interpreted as an <tref>IRI</tref>.</p>
-<p><tref title="term">Terms</tref> or <tref title="compact IRI">compact IRIs</tref> used as the value of a
+<p><tref title="term">Terms</tref> or <tref title="compact_iri">compact IRIs</tref> used as the value of a
<code>@type</code> key may be defined within the same context. This means that one may specify a
<tref>term</tref> like <code>xsd</code> and then use <code>xsd:integer</code> within the same
context definition.</p>
@@ -1564,7 +1616,7 @@
</tbody>
</table>
-<p>Terms may also be defined using <tref title="absolute iri">absolute IRIs</tref> or <tref title="compact IRI">compact IRIs</tref>.
+<p>Terms may also be defined using <tref title="absolute iri">absolute IRIs</tref> or <tref title="compact_iri">compact IRIs</tref>.
This allows coercion rules to be applied to keys which are not represented as a simple <tref>term</tref>.
For example:</p>
@@ -1755,8 +1807,8 @@
-->
</pre>
-<p><tref title="compact IRI">Compact IRIs</tref>
- and <tref title="IRI">IRIs</tref> may be used on the left-hand side of a
+<p><tref title="compact iri">Compact IRIs</tref>
+ and <tref title="iri">IRIs</tref> may be used on the left-hand side of a
<tref>term</tref> definition.</p>
<pre class="example" data-transform="updateExample"
@@ -1796,7 +1848,7 @@
</p>
<p>
-<tref title="absolute IRI">Absolute IRIs</tref> may also be used in the key position in a <tref>context</tref>:
+<tref title="absolute iri">Absolute IRIs</tref> may also be used in the key position in a <tref>context</tref>:
</p>
<pre class="example" data-transform="updateExample"
@@ -2613,7 +2665,7 @@
a <tref>JSON-LD value</tref>, or a <tref>list</tref>.</li>
<li>A node 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>,
+ <li>A <tref>JSON-LD graph</tref> SHOULD NOT contain unconnected <tref title="node">nodes</tref>,
i.e., nodes which are not connected by an <tref>edge</tref> to any other <tref>node</tref>.</li>
<li>An <tdef><abbr title="Internationalized Resource Identifier">IRI</abbr></tdef>
(Internationalized Resource Identifier) is a string that conforms to the syntax
@@ -2657,6 +2709,8 @@
<h2>JSON-LD Grammar</h2>
<em>This section is normative</em>
+<p class="issue" data-number="114">This section is an attempt to formalize
+a normative grammar for JSON-LD.</p>
<p>This appendix restates the syntactic conventions described in the
previous sections more formally.</p>
@@ -2725,16 +2779,16 @@
</ul>
<p>If the <tref>node object</tref> contains the <code>@id</code> key,
- 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>).
+ its value MUST be an <tref>IRI</tref>, a <tref>compact IRI</tref>
+ (including <tref title="blank node identifier">blank node identifiers</tref>), or
+ a <tref>term</tref> defined in the <tref>active context</tref> expanding
+ into an <tref>IRI</tref> or a <tref>blank node identifier</tref>.
See <a href="#node-identifiers"></a>, <a href="#compact-iris"></a>,
and <a href="#identifying-blank-nodes"></a> for further discussion on
<code>@id</code> values.</p>
<p>If the <tref>node object</tref> contains the <code>@type</code>
- key, its value MUST be either an <tref>absolute IRI</tref>, a
- <tref>relative IRI</tref>, a <tref>compact IRI</tref>
+ key, its value MUST be either an <tref>IRI</tref>, a <tref>compact IRI</tref>
(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.
@@ -2865,7 +2919,7 @@
<p>The value associated with the <code>@type</code> key MUST be a
<tref>term</tref>, a <tref>compact IRI</tref>,
- an <tref>absolute IRI</tref>, a <tref>relative IRI</tref>, or <tref>null</tref>.</p>
+ an <tref>IRI</tref>, or <tref>null</tref>.</p>
<p>The value associated with the <code>@language</code> key MUST have the
lexical form described in [[!BCP47]], or be <tref>null</tref>.</p>
@@ -2987,6 +3041,9 @@
<tref title="IRI">IRIs</tref> or <tref title="blank node">blank nodes</tref>
whereas in RDF properties (predicates) have to be
<tref title="IRI">IRIs</tref>.</li>
+ <li>In contrast to RDF graphs <tref title="JSON-LD graph">JSON-LD graphs</tref>
+ support unconnected <tref title="node">nodes</tref>, i.e., nodes which are not
+ connected to any other node.</li>
<li>In JSON-LD lists are part of the data model whereas in RDF they are part of
a vocabulary, namely [[RDF-SCHEMA]].</li>
<li>RDF values are either typed <em>literals</em>
@@ -3152,13 +3209,13 @@
<div ****prefix="foaf: http://xmlns.com/foaf/0.1/"****>
<ul>
<li ****typeof="foaf:Person"****>
- <a ****rel="foaf:homepage" href="http://example.com/bob/" property="foaf:name"****>Bob</a>
+ <a ****rel="foaf:homepage" href="http://example.com/bob/" property="foaf:name" ****>Bob</a>
</li>
<li ****typeof="foaf:Person"****>
- <a ****rel="foaf:homepage" href="http://example.com/eve/" property="foaf:name"****>Eve</a>
+ <a ****rel="foaf:homepage" href="http://example.com/eve/" property="foaf:name" ****>Eve</a>
</li>
<li ****typeof="foaf:Person"****>
- <a ****rel="foaf:homepage" href="http://example.com/manu/" property="foaf:name"****>Manu</a>
+ <a ****rel="foaf:homepage" href="http://example.com/manu/" property="foaf:name" ****>Manu</a>
</li>
</ul>
</div>