Skip to content

Commit 961bda9

Browse files
lanthalerlanthaler
committed
Update Data Annotations and Grammar sections
This addresses #196.
1 parent 24540bb commit 961bda9

File tree

1 file changed

+143
-143
lines changed

1 file changed

+143
-143
lines changed

‎spec/latest/json-ld-syntax/index.html

Lines changed: 143 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -2352,138 +2352,134 @@ <h2>Aliasing Keywords</h2>
23522352
</section>
23532353

23542354
<section>
2355-
<h2>Data Annotations</h2>
2356-
2357-
<p>It is common for developers using JSON to organize their data in ways
2358-
that makes working with the data more efficient. It is often that these methods
2359-
of organizing data are not meant to express Linked Data, but should survive
2360-
transformation by JSON-LD. For example, if a developer
2361-
organizes employees in a JSON-LD document by a company-issued ID number,
2362-
JSON-LD should not destroy that 'database index' when transforming the data.
2363-
Data annotations allow content that would otherwise be removed from
2364-
a JSON-LD graph to be
2365-
preserved by instructing the JSON-LD processor to syntactically preserve
2366-
the annotation information and continue processing deeper into the JSON
2367-
data structure.</p>
2355+
<h2>Data Annotations</h2>
23682356

2369-
<pre class="example" data-transform="updateExample"
2370-
title="Data annotations">
2371-
<!--
2372-
{
2373-
"@context":
2357+
<p>Sometimes it is desirable to include comments or annotations in the data
2358+
that is not meant to express Linked Data but should nevertheless survive
2359+
processing and transformation. In JSON-LD such data can be included by
2360+
using the <code>@annotation</code> <tref>keyword</tref> as shown in the
2361+
following example:</p>
2362+
2363+
<pre class="example" data-transform="updateExample"
2364+
title="Data annotations">
2365+
<!--
23742366
{
2375-
"schema": "http://schema.org/",
2376-
"Article": "schema:Blog",
2377-
"name": "schema:name",
2378-
"articleBody": "schema:articleBody",
2379-
"wordCount": "schema:wordCount",
2380-
"commentCount": "http://example.com/schema/wordCount",
2381-
"blogPost": {
2382-
"@id": "schema:blogPost",
2383-
****"@container": "@annotation"****
2384-
},
2385-
"@id": "http://example.com/",
2386-
"@type": "Blog",
2387-
"name": "World Financial News",
2388-
****"blogPost": {
2389-
"en": {
2390-
"@id": "http://example.com/posts/1/en",
2391-
"articleBody": "World commodities were up today with heavy trading of crude oil...",
2392-
"wordCount": 1539,
2393-
"commentCount": 64
2394-
},
2395-
"de": {
2396-
"@id": "http://example.com/posts/1/de",
2397-
"articleBody": "Welt Rohstoffe waren bis heute mit schweren Handel mit Rohöl...",
2398-
"wordCount": 1204,
2399-
"commentCount": 23
2400-
}****
2367+
"@context":
2368+
{
2369+
"schema": "http://schema.org/",
2370+
"articleBody": "schema:articleBody",
2371+
"wordCount": "schema:wordCount"
2372+
},
2373+
"@id": "http://example.com/posts/1/en",
2374+
"articleBody": "World commodities were up today with heavy trading of crude oil...",
2375+
"wordCount": 1539,
2376+
****"@annotation": "Generated in 0.00128 sec"****
24012377
}
2402-
}
2403-
-->
2404-
</pre>
2378+
-->
2379+
</pre>
24052380

2406-
<p>In the example above, the <strong>blogPost</strong> <tref>term</tref> has
2407-
been marked as a <em>data annotation container</em>. The <strong>en</strong>,
2408-
<strong>de</strong>, and <strong>ja</strong> keys will effectively be ignored
2409-
semantically, but preserved syntactically, by the JSON-LD Processor as
2410-
<em>annotations</em>. The interpretation of the data above is expressed in
2411-
the table below. Note how the annotations do not appear in the Linked Data
2412-
below, but would continue to exist if the document were compacted or expanded
2413-
using a JSON-LD processor:
2414-
</p>
2381+
<p>Annotations can also be used to structure data in forms that are more
2382+
efficient to work with - a feature commonly used with JSON. The annotation
2383+
feature allows to structure the data in the form of maps which allows to
2384+
access specific members directly instead of having to filter an array to
2385+
access a specific member. The following example illustrates this use case:</p>
2386+
2387+
<pre class="example" data-transform="updateExample"
2388+
title="Annotation maps">
2389+
<!--
2390+
{
2391+
"@context":
2392+
{
2393+
"schema": "http://schema.org/",
2394+
"name": "schema:name",
2395+
"body": "schema:articleBody",
2396+
"words": "schema:wordCount",
2397+
"post": {
2398+
"@id": "schema:blogPost",
2399+
****"@container": "@annotation"****
2400+
}
2401+
},
2402+
"@id": "http://example.com/",
2403+
"@type": "schema:Blog",
2404+
"name": "World Financial News",
2405+
****"post": {
2406+
"en": {
2407+
"@id": "http://example.com/posts/1/en",
2408+
"body": "World commodities were up today with heavy trading of crude oil...",
2409+
"words": 1539
2410+
},
2411+
"de": {
2412+
"@id": "http://example.com/posts/1/de",
2413+
"body": "Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...",
2414+
"words": 1204
2415+
}****
2416+
}
2417+
}
2418+
-->
2419+
</pre>
2420+
2421+
<p>In the example above, the <strong>blogPost</strong> <tref>term</tref> has
2422+
been marked as an <tref>annotation map</tref>. The <strong>en</strong>,
2423+
<strong>de</strong>, and <strong>ja</strong> keys will effectively be ignored
2424+
semantically, but preserved syntactically, by the JSON-LD Processor as
2425+
<em>annotations</em>. This allows, for example, to access the German version
2426+
of the <strong>blogPost</strong>, using the following code snippet:
2427+
<code>obj.blogPost.de</code>.</p>
2428+
2429+
<p>The interpretation of the data above is expressed in
2430+
the table below. Note how the annotations do not appear in the Linked Data
2431+
below, but would continue to exist if the document were compacted or expanded
2432+
using a JSON-LD processor:</p>
24152433

24162434
<table class="example">
2417-
<thead>
2418-
<th>Subject</th>
2419-
<th>Property</th>
2420-
<th>Object</th>
2421-
<th>Datatype</th>
2422-
</thead>
2423-
<tbody>
2424-
<tr>
2425-
<td>http://example.com/</td>
2426-
<td>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</td>
2427-
<td>http://schema.org/Blog</td>
2428-
<td></td>
2429-
</tr>
2430-
<tr>
2431-
<td>http://example.com/</td>
2432-
<td>http://schema.org/name</td>
2433-
<td>World Financial News</td>
2434-
<td></td>
2435-
</tr>
2436-
<tr>
2437-
<td>http://example.com/</td>
2438-
<td>http://schema.org/blogPost</td>
2439-
<td>http://example.com/posts/1/en</td>
2440-
<td></td>
2441-
</tr>
2442-
<tr>
2443-
<td>http://example.com/</td>
2444-
<td>http://schema.org/blogPost</td>
2445-
<td>http://example.com/posts/1/de</td>
2446-
<td></td>
2447-
</tr>
2448-
<tr>
2449-
<td>http://example.com/posts/1/en</td>
2450-
<td>http://schema.org/articleBody</td>
2451-
<td>World commodities were up today with heavy trading of crude oil...</td>
2452-
<td></td>
2453-
</tr>
2454-
<tr>
2455-
<td>http://example.com/posts/1/en</td>
2456-
<td>http://schema.org/wordCount</td>
2457-
<td>1539</td>
2458-
<td>http://www.w3.org/2001/XMLSchema#integer</td>
2459-
</tr>
2460-
<tr>
2461-
<td>http://example.com/posts/1/en</td>
2462-
<td>http://example.com/schema/commentCount</td>
2463-
<td>64</td>
2464-
<td>http://www.w3.org/2001/XMLSchema#integer</td>
2465-
</tr>
2466-
<tr>
2467-
<td>http://example.com/posts/1/de</td>
2468-
<td>http://schema.org/articleBody</td>
2469-
<td>Welt Rohstoffe waren bis heute mit schweren Handel mit Rohöl...</td>
2470-
<td></td>
2471-
</tr>
2472-
<tr>
2473-
<td>http://example.com/posts/1/de</td>
2474-
<td>http://schema.org/wordCount</td>
2475-
<td>1204</td>
2476-
<td>http://www.w3.org/2001/XMLSchema#integer</td>
2477-
</tr>
2478-
<tr>
2479-
<td>http://example.com/posts/1/de</td>
2480-
<td>http://example.com/schema/commentCount</td>
2481-
<td>23</td>
2482-
<td>http://www.w3.org/2001/XMLSchema#integer</td>
2483-
</tr>
2484-
</tbody>
2435+
<thead>
2436+
<th>Subject</th>
2437+
<th>Property</th>
2438+
<th>Object</th>
2439+
</thead>
2440+
<tbody>
2441+
<tr>
2442+
<td>http://example.com/</td>
2443+
<td>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</td>
2444+
<td>http://schema.org/Blog</td>
2445+
</tr>
2446+
<tr>
2447+
<td>http://example.com/</td>
2448+
<td>http://schema.org/name</td>
2449+
<td>World Financial News</td>
2450+
</tr>
2451+
<tr>
2452+
<td>http://example.com/</td>
2453+
<td>http://schema.org/blogPost</td>
2454+
<td>http://example.com/posts/1/en</td>
2455+
</tr>
2456+
<tr>
2457+
<td>http://example.com/</td>
2458+
<td>http://schema.org/blogPost</td>
2459+
<td>http://example.com/posts/1/de</td>
2460+
</tr>
2461+
<tr>
2462+
<td>http://example.com/posts/1/en</td>
2463+
<td>http://schema.org/articleBody</td>
2464+
<td>World commodities were up today with heavy trading of crude oil...</td>
2465+
</tr>
2466+
<tr>
2467+
<td>http://example.com/posts/1/en</td>
2468+
<td>http://schema.org/wordCount</td>
2469+
<td>1539</td>
2470+
</tr>
2471+
<tr>
2472+
<td>http://example.com/posts/1/de</td>
2473+
<td>http://schema.org/articleBody</td>
2474+
<td>Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...</td>
2475+
</tr>
2476+
<tr>
2477+
<td>http://example.com/posts/1/de</td>
2478+
<td>http://schema.org/wordCount</td>
2479+
<td>1204</td>
2480+
</tr>
2481+
</tbody>
24852482
</table>
2486-
24872483
</section>
24882484

24892485
<section>
@@ -2917,11 +2913,12 @@ <h2>Expanded Values</h2>
29172913
string</tref>.</p>
29182914

29192915
<p>An <tref>expanded value</tref> MUST be a <tref>JSON object</tref> containing the
2920-
<code>@value</code> key. It MAY also contain a <code>@type</code> or
2921-
a <code>@language</code> key but MUST NOT contain both a <code>@type</code>
2922-
and a <code>@language</code> key. An <tref>expanded value</tref> MUST NOT
2923-
contain keys other than <code>@value</code>, <code>@language</code>, and
2924-
<code>@type</code>. An <tref>expanded value</tref> that contains a
2916+
<code>@value</code> key. It MAY also contain a <code>@type</code>,
2917+
a <code>@language</code>, or an <code>@annotation</code> key but MUST NOT contain
2918+
both a <code>@type</code> and a <code>@language</code> key at the same time.
2919+
An <tref>expanded value</tref> MUST NOT contain keys other than
2920+
<code>@value</code>, <code>@type</code>, <code>@language</code>, and
2921+
<code>@annotation</code>. An <tref>expanded value</tref> that contains a
29252922
<code>@type</code> key is called an <tdef>expanded typed value</tdef>.
29262923
An <tref>expanded value</tref> that contains a <code>@language</code> key
29272924
is called an <tdef>expanded language-tagged string</tdef>.</p>
@@ -2930,16 +2927,16 @@ <h2>Expanded Values</h2>
29302927
<tref>string</tref>, <tref>number</tref>, <tref>true</tref>,
29312928
<tref>false</tref> or <tref>null</tref>.</p>
29322929

2930+
<p>The value associated with the <code>@type</code> key MUST be a
2931+
<tref>term</tref>, a <tref>compact IRI</tref>,
2932+
an <tref>absolute IRI</tref>, or <code>null</code>.</p>
2933+
29332934
<p>The value associated with the <code>@language</code> key MUST have the
29342935
lexical form described in [[!BCP47]], or be <tref>null</tref>.</p>
29352936

29362937
<p>The value associated with the <code>@annotation</code> key MUST be a
29372938
<tref>string</tref>.</p>
29382939

2939-
<p>The value associated with the <code>@type</code> key MUST be a
2940-
<tref>term</tref>, a <tref>compact IRI</tref>,
2941-
an <tref>absolute IRI</tref>, or <code>null</code>.</p>
2942-
29432940
<p>See <a href="#typed-values"></a> and <a href="#language-tagged-strings"></a>
29442941
for more information on
29452942
<tref title="expanded value">expanded values</tref>.</p>
@@ -2948,9 +2945,8 @@ <h2>Expanded Values</h2>
29482945
<section id="grammar-set-list">
29492946
<h2>List and Set Values</h2>
29502947

2951-
<p>A <tref>list</tref> represents an <em>ordered</em> set of values.
2952-
A <tdef>set</tdef> represents an <em>unordered</em> set of values.
2953-
Unless otherwise specified (typically through the use of a <tref>list</tref>),
2948+
<p>A <tref>list</tref> represents an <em>ordered</em> set of values. A <tdef>set</tdef>
2949+
represents an <em>unordered</em> set of values. Unless otherwise specified,
29542950
<tref title="array">arrays</tref> are unordered in JSON-LD. As such, the
29552951
<code>@set</code> keyword, when used in the body of a JSON-LD document,
29562952
represents just syntactic sugar which is optimized away when processing the document.
@@ -2961,20 +2957,24 @@ <h2>List and Set Values</h2>
29612957
a non-array form in <a href="#compact-document-form">compact document form</a>.
29622958
This simplifies post-processing of the data as the data is always in array form.</p>
29632959

2964-
<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>
2960+
<p>A <tref>list</tref> MUST be a <tref>JSON object</tref> that contains no other
2961+
keys than <code>@list</code>, <code>@context</code>, and <code>@annotation</code>.</p>
29652962

2966-
<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>
2963+
<p>A <tref>set</tref> MUST be a <tref>JSON object</tref> that that contains no other
2964+
keys than <code>@set</code>, <code>@context</code>, and <code>@annotation</code>.
2965+
Please note that the <code>@annotation</code> key will be ignored, and thus be dropped,
2966+
when being processed.</p>
29672967

2968-
<p>In both cases, the value associated with the key MUST be an <tref>array</tref> of any of the following:</p>
2968+
<p>In both cases, the value associated with the keys <code>@list</code> and <code>@set</code>
2969+
MUST be an <tref>array</tref> of any of the following:</p>
29692970
<ul>
29702971
<li><tref>string</tref>,</li>
29712972
<li><tref>number</tref>,</li>
29722973
<li><tref>true</tref>,</li>
29732974
<li><tref>false</tref>,</li>
29742975
<li><tref>null</tref>,</li>
2975-
<li><tref>node object</tref>,</li>
2976-
<li><tref>expanded typed value</tref>, or</li>
2977-
<li><tref>expanded language-tagged string</tref></li>
2976+
<li><tref>node object</tref>, or</li>
2977+
<li><tref>expanded value</tref></li>
29782978
</ul>
29792979

29802980
<p>See <a href="#sets-and-lists"></a> for further discussion on List and Set Values.</p>

0 commit comments

Comments
 (0)