--- a/spec/latest/json-ld-syntax/index.html Tue Jan 15 18:30:32 2013 +0100
+++ b/spec/latest/json-ld-syntax/index.html Wed Jan 16 14:44:53 2013 +0100
@@ -101,64 +101,60 @@
<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 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>
<section class="informative">
@@ -184,8 +180,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
@@ -229,184 +225,169 @@
</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>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 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>
- <!--<dt>Linked Data-centric</dt>
- <dd>The focus on Linked Data is placed at a much higher priority than the
- focus on the Semantic Web. One outcome of this ordering of
- priorities is an aggressively reduced focus on the Semantic Web stack.
- While this may be off-putting to proponents of the Semantic Web, the audience
- for this specification are Web developers that want a gentler introduction
- and a simpler technology stack for using Linked Data in their Web applications.
- Semantic Web concepts, such as conversion to and from RDF, are fully supported
- by JSON-LD, but the implementation of these features are not elaborated upon
- in this specification. See <a href="#relationship-to-other-linked-data-formats"></a>
- for more information about how JSON-LD integrates into the more traditional
- Semantic Web stack.
- </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>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>
</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 (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>
<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 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>
-
+ <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 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">