--- a/spec/latest/json-ld-syntax/index.html Fri Dec 28 17:59:31 2012 +0100
+++ b/spec/latest/json-ld-syntax/index.html Fri Dec 28 18:48:31 2012 +0100
@@ -2352,138 +2352,134 @@
</section>
<section>
-<h2>Data Annotations</h2>
-
-<p>It is common for developers using JSON to organize their data in ways
-that makes working with the data more efficient. It is often that these methods
-of organizing data are not meant to express Linked Data, but should survive
-transformation by JSON-LD. For example, if a developer
-organizes employees in a JSON-LD document by a company-issued ID number,
-JSON-LD should not destroy that 'database index' when transforming the data.
-Data annotations allow content that would otherwise be removed from
-a JSON-LD graph to be
-preserved by instructing the JSON-LD processor to syntactically preserve
-the annotation information and continue processing deeper into the JSON
-data structure.</p>
-
-<pre class="example" data-transform="updateExample"
- title="Data annotations">
-<!--
-{
- "@context":
+ <h2>Data Annotations</h2>
+
+ <p>Sometimes it is desirable to include comments or annotations in the data
+ that is not meant to express Linked Data but should nevertheless survive
+ processing and transformation. In JSON-LD such data can be included by
+ using the <code>@annotation</code> <tref>keyword</tref> as shown in the
+ following example:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Data annotations">
+ <!--
{
- "schema": "http://schema.org/",
- "Article": "schema:Blog",
- "name": "schema:name",
- "articleBody": "schema:articleBody",
- "wordCount": "schema:wordCount",
- "commentCount": "http://example.com/schema/wordCount",
- "blogPost": {
- "@id": "schema:blogPost",
- ****"@container": "@annotation"****
- },
- "@id": "http://example.com/",
- "@type": "Blog",
- "name": "World Financial News",
- ****"blogPost": {
- "en": {
- "@id": "http://example.com/posts/1/en",
- "articleBody": "World commodities were up today with heavy trading of crude oil...",
- "wordCount": 1539,
- "commentCount": 64
- },
- "de": {
- "@id": "http://example.com/posts/1/de",
- "articleBody": "Welt Rohstoffe waren bis heute mit schweren Handel mit Rohöl...",
- "wordCount": 1204,
- "commentCount": 23
- }****
+ "@context":
+ {
+ "schema": "http://schema.org/",
+ "articleBody": "schema:articleBody",
+ "wordCount": "schema:wordCount"
+ },
+ "@id": "http://example.com/posts/1/en",
+ "articleBody": "World commodities were up today with heavy trading of crude oil...",
+ "wordCount": 1539,
+ ****"@annotation": "Generated in 0.00128 sec"****
}
-}
--->
-</pre>
-
-<p>In the example above, the <strong>blogPost</strong> <tref>term</tref> has
-been marked as a <em>data annotation container</em>. The <strong>en</strong>,
-<strong>de</strong>, and <strong>ja</strong> keys will effectively be ignored
-semantically, but preserved syntactically, by the JSON-LD Processor as
-<em>annotations</em>. The interpretation of the data above is expressed in
-the table below. Note how the annotations do not appear in the Linked Data
-below, but would continue to exist if the document were compacted or expanded
-using a JSON-LD processor:
-</p>
+ -->
+ </pre>
+
+ <p>Annotations can also be used to structure data in forms that are more
+ efficient to work with - a feature commonly used with JSON. The annotation
+ feature allows to structure the data in the form of maps which allows to
+ access specific members directly instead of having to filter an array to
+ access a specific member. The following example illustrates this use case:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Annotation maps">
+ <!--
+ {
+ "@context":
+ {
+ "schema": "http://schema.org/",
+ "name": "schema:name",
+ "body": "schema:articleBody",
+ "words": "schema:wordCount",
+ "post": {
+ "@id": "schema:blogPost",
+ ****"@container": "@annotation"****
+ }
+ },
+ "@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>annotation map</tref>. The <strong>en</strong>,
+ <strong>de</strong>, and <strong>ja</strong> keys will effectively be ignored
+ semantically, but preserved syntactically, by the JSON-LD Processor as
+ <em>annotations</em>. This allows, for example, 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 annotations do not appear in the Linked Data
+ below, but would continue to exist if the document were compacted or expanded
+ using a JSON-LD processor:</p>
<table class="example">
- <thead>
- <th>Subject</th>
- <th>Property</th>
- <th>Object</th>
- <th>Datatype</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>
- <td></td>
- </tr>
- <tr>
- <td>http://example.com/</td>
- <td>http://schema.org/name</td>
- <td>World Financial News</td>
- <td></td>
- </tr>
- <tr>
- <td>http://example.com/</td>
- <td>http://schema.org/blogPost</td>
- <td>http://example.com/posts/1/en</td>
- <td></td>
- </tr>
- <tr>
- <td>http://example.com/</td>
- <td>http://schema.org/blogPost</td>
- <td>http://example.com/posts/1/de</td>
- <td></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>
- <td></td>
- </tr>
- <tr>
- <td>http://example.com/posts/1/en</td>
- <td>http://schema.org/wordCount</td>
- <td>1539</td>
- <td>http://www.w3.org/2001/XMLSchema#integer</td>
- </tr>
- <tr>
- <td>http://example.com/posts/1/en</td>
- <td>http://example.com/schema/commentCount</td>
- <td>64</td>
- <td>http://www.w3.org/2001/XMLSchema#integer</td>
- </tr>
- <tr>
- <td>http://example.com/posts/1/de</td>
- <td>http://schema.org/articleBody</td>
- <td>Welt Rohstoffe waren bis heute mit schweren Handel mit Rohöl...</td>
- <td></td>
- </tr>
- <tr>
- <td>http://example.com/posts/1/de</td>
- <td>http://schema.org/wordCount</td>
- <td>1204</td>
- <td>http://www.w3.org/2001/XMLSchema#integer</td>
- </tr>
- <tr>
- <td>http://example.com/posts/1/de</td>
- <td>http://example.com/schema/commentCount</td>
- <td>23</td>
- <td>http://www.w3.org/2001/XMLSchema#integer</td>
- </tr>
- </tbody>
+ <thead>
+ <th>Subject</th>
+ <th>Property</th>
+ <th>Object</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>
@@ -2917,11 +2913,12 @@
string</tref>.</p>
<p>An <tref>expanded value</tref> MUST be a <tref>JSON object</tref> containing the
- <code>@value</code> key. It MAY also contain a <code>@type</code> or
- a <code>@language</code> key but MUST NOT contain both a <code>@type</code>
- and a <code>@language</code> key. An <tref>expanded value</tref> MUST NOT
- contain keys other than <code>@value</code>, <code>@language</code>, and
- <code>@type</code>. An <tref>expanded value</tref> that contains a
+ <code>@value</code> key. It MAY also contain a <code>@type</code>,
+ a <code>@language</code>, or an <code>@annotation</code> key but MUST NOT contain
+ both a <code>@type</code> and a <code>@language</code> key at the same time.
+ An <tref>expanded value</tref> MUST NOT contain keys other than
+ <code>@value</code>, <code>@type</code>, <code>@language</code>, and
+ <code>@annotation</code>. An <tref>expanded value</tref> that contains a
<code>@type</code> key is called an <tdef>expanded typed value</tdef>.
An <tref>expanded value</tref> that contains a <code>@language</code> key
is called an <tdef>expanded language-tagged string</tdef>.</p>
@@ -2930,16 +2927,16 @@
<tref>string</tref>, <tref>number</tref>, <tref>true</tref>,
<tref>false</tref> or <tref>null</tref>.</p>
+<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>, or <code>null</code>.</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>
<p>The value associated with the <code>@annotation</code> key MUST be a
<tref>string</tref>.</p>
-<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>, or <code>null</code>.</p>
-
<p>See <a href="#typed-values"></a> and <a href="#language-tagged-strings"></a>
for more information on
<tref title="expanded value">expanded values</tref>.</p>
@@ -2948,9 +2945,8 @@
<section id="grammar-set-list">
<h2>List and Set Values</h2>
-<p>A <tref>list</tref> represents an <em>ordered</em> set of values.
- A <tdef>set</tdef> represents an <em>unordered</em> set of values.
- Unless otherwise specified (typically through the use of a <tref>list</tref>),
+<p>A <tref>list</tref> represents an <em>ordered</em> set of values. A <tdef>set</tdef>
+ represents an <em>unordered</em> set of values. Unless otherwise specified,
<tref title="array">arrays</tref> are unordered in JSON-LD. As such, the
<code>@set</code> keyword, when used in the body of a JSON-LD document,
represents just syntactic sugar which is optimized away when processing the document.
@@ -2961,20 +2957,24 @@
a non-array form in <a href="#compact-document-form">compact document form</a>.
This simplifies post-processing of the data as the data is always in array form.</p>
-<p>A <tref>list</tref> MUST be a <tref>JSON object</tref> that contains a single key-value pair where the key is <code>@list</code>.</p>
-
-<p>A <tref>set</tref> MUST be a <tref>JSON object</tref> that contains a single key-value pair where the key is <code>@set</code>.</p>
-
-<p>In both cases, the value associated with the key MUST be an <tref>array</tref> of any of the following:</p>
+<p>A <tref>list</tref> MUST be a <tref>JSON object</tref> that contains no other
+ keys than <code>@list</code>, <code>@context</code>, and <code>@annotation</code>.</p>
+
+<p>A <tref>set</tref> MUST be a <tref>JSON object</tref> that that contains no other
+ keys than <code>@set</code>, <code>@context</code>, and <code>@annotation</code>.
+ Please note that the <code>@annotation</code> key will be ignored, and thus be dropped,
+ when being processed.</p>
+
+<p>In both cases, the value associated with the keys <code>@list</code> and <code>@set</code>
+ MUST be an <tref>array</tref> of any of the following:</p>
<ul>
<li><tref>string</tref>,</li>
<li><tref>number</tref>,</li>
<li><tref>true</tref>,</li>
<li><tref>false</tref>,</li>
<li><tref>null</tref>,</li>
- <li><tref>node object</tref>,</li>
- <li><tref>expanded typed value</tref>, or</li>
- <li><tref>expanded language-tagged string</tref></li>
+ <li><tref>node object</tref>, or</li>
+ <li><tref>expanded value</tref></li>
</ul>
<p>See <a href="#sets-and-lists"></a> for further discussion on List and Set Values.</p>