Skip to content

Commit 5015a51

Browse files
mspornymsporny
committed
Added Data Annotations to JSON-LD Syntax specification.
This partially addresses #196.
1 parent d64c560 commit 5015a51

File tree

1 file changed

+131
-0
lines changed

1 file changed

+131
-0
lines changed

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

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -378,6 +378,11 @@ <h2>Syntax Tokens and Keywords</h2>
378378
<dd>Used to express an unordered set of data and to ensure that values are always
379379
represented as arrays. This keyword is described in the section titled
380380
<a href="#sets-and-lists"></a>.</dd>
381+
<dt><code>@annotation</code></dt>
382+
<dd>Used to specify that a container is used to index information and
383+
that processing should continue deeper into a JSON data structure.
384+
This keyword is described in the section titled
385+
<a href="#data-annotations"></a>.</dd>
381386
<dt><code>@vocab</code></dt>
382387
<dd>Used to expand properties and values in <code>@type</code> with a common prefix
383388
<tref>IRI</tref>. This keyword is described in section <a href="#iris"></a>.</dd>
@@ -2357,6 +2362,132 @@ <h2>Aliasing Keywords</h2>
23572362

23582363
</section>
23592364

2365+
<section>
2366+
<h2>Data Annotations</h2>
2367+
2368+
<p>It is common for developers using JSON to utilize database-like
2369+
index information in their markup. For example, indexing article information
2370+
by language or employees by a government issued ID number. Data annotations
2371+
allow content that would otherwise be disconnected in a JSON-LD graph to be
2372+
connected by instructing the JSON-LD processor to ignore the indexing
2373+
information an continue processing deeper into the JSON data structure.</p>
2374+
2375+
<pre class="example" data-transform="updateExample"
2376+
title="Data annotations">
2377+
<!--
2378+
{
2379+
"@context":
2380+
{
2381+
"schema": "http://schema.org/",
2382+
"Article": "schema:Blog",
2383+
"name": "schema:name",
2384+
"articleBody": "schema:articleBody",
2385+
"wordCount": "schema:wordCount",
2386+
"commentCount": "http://example.com/schema/wordCount",
2387+
"blogPost": {
2388+
"@id": "schema:blogPost",
2389+
****"@container": "@annotation"****
2390+
},
2391+
"@id": "http://example.com/",
2392+
"@type": "Blog",
2393+
"name": "World Financial News",
2394+
****"blogPost": {
2395+
"en": {
2396+
"@id": "http://example.com/posts/1/en",
2397+
"articleBody": "World commodities were up today with heavy trading of crude oil...",
2398+
"wordCount": 1539,
2399+
"commentCount": 64
2400+
},
2401+
"de": {
2402+
"@id": "http://example.com/posts/1/de",
2403+
"articleBody": "Welt Rohstoffe waren bis heute mit schweren Handel mit Rohöl...",
2404+
"wordCount": 1204,
2405+
"commentCount": 23
2406+
}****
2407+
}
2408+
}
2409+
-->
2410+
</pre>
2411+
2412+
<p>In the example above, the <strong>blogPost</strong> <tref>term</tref> has
2413+
been marked as a <em>data annotation container</em>. The <strong>en</strong>,
2414+
<strong>de</strong>, and <strong>ja</strong> keys will effectively be ignored
2415+
by the JSON-LD Processor as <em>annotations</em>. The interpretation of the
2416+
data above is expressed in the table below:
2417+
</p>
2418+
2419+
<table class="example">
2420+
<thead>
2421+
<th>Subject</th>
2422+
<th>Property</th>
2423+
<th>Object</th>
2424+
<th>Datatype</th>
2425+
</thead>
2426+
<tbody>
2427+
<tr>
2428+
<td>http://example.com/</td>
2429+
<td>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</td>
2430+
<td>http://schema.org/Blog</td>
2431+
<td></td>
2432+
</tr>
2433+
<tr>
2434+
<td>http://example.com/</td>
2435+
<td>http://schema.org/name</td>
2436+
<td>World Financial News</td>
2437+
<td></td>
2438+
</tr>
2439+
<tr>
2440+
<td>http://example.com/</td>
2441+
<td>http://schema.org/blogPost</td>
2442+
<td>http://example.com/posts/1/en</td>
2443+
<td></td>
2444+
</tr>
2445+
<tr>
2446+
<td>http://example.com/</td>
2447+
<td>http://schema.org/blogPost</td>
2448+
<td>http://example.com/posts/1/de</td>
2449+
<td></td>
2450+
</tr>
2451+
<tr>
2452+
<td>http://example.com/posts/1/en</td>
2453+
<td>http://schema.org/articleBody</td>
2454+
<td>World commodities were up today with heavy trading of crude oil...</td>
2455+
<td></td>
2456+
</tr>
2457+
<tr>
2458+
<td>http://example.com/posts/1/en</td>
2459+
<td>http://schema.org/wordCount</td>
2460+
<td>1539</td>
2461+
<td>http://www.w3.org/2001/XMLSchema#integer</td>
2462+
</tr>
2463+
<tr>
2464+
<td>http://example.com/posts/1/en</td>
2465+
<td>http://example.com/schema/commentCount</td>
2466+
<td>64</td>
2467+
<td>http://www.w3.org/2001/XMLSchema#integer</td>
2468+
</tr>
2469+
<tr>
2470+
<td>http://example.com/posts/1/de</td>
2471+
<td>http://schema.org/articleBody</td>
2472+
<td>Welt Rohstoffe waren bis heute mit schweren Handel mit Rohöl...</td>
2473+
<td></td>
2474+
</tr>
2475+
<tr>
2476+
<td>http://example.com/posts/1/de</td>
2477+
<td>http://schema.org/wordCount</td>
2478+
<td>1204</td>
2479+
<td>http://www.w3.org/2001/XMLSchema#integer</td>
2480+
</tr>
2481+
<tr>
2482+
<td>http://example.com/posts/1/de</td>
2483+
<td>http://example.com/schema/commentCount</td>
2484+
<td>23</td>
2485+
<td>http://www.w3.org/2001/XMLSchema#integer</td>
2486+
</tr>
2487+
</tbody>
2488+
</table>
2489+
2490+
</section>
23602491

23612492
<section>
23622493
<h2>Explicitly Ignoring Data</h2>

0 commit comments

Comments
 (0)