--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/spec/latest/index.html Thu Mar 28 15:14:23 2013 +0100
@@ -0,0 +1,69 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN"
+ "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">
+<html version="XHTML+RDFa 1.0" xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:xhv="http://www.w3.org/1999/xhtml/vocab#"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
+ xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
+ xmlns:dcterms="http://purl.org/dc/terms/"
+ xmlns:vcard="http://www.w3.org/2006/vcard/ns#"
+ xmlns:v="http://rdf.data-vocabulary.org/#"
+ >
+ <head>
+ <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
+ <title>JSON-LD - Specifications</title>
+ <link href="../../site.css" rel="stylesheet" type="text/css" />
+ <link rel="shortcut icon" href="../../favicon.ico" />
+ </head>
+
+ <body>
+ <div id="container">
+ <div id="header">
+ <span class="col">
+ <img class="banner" src="../../images/json-ld-logo-1.png" />
+ <img class="banner" src="../../images/json-ld-logo-2.png" />
+ <img class="banner" src="../../images/json-ld-logo-3.png" />
+ <h1>Latest Specifications</h1>
+ </span>
+ </div>
+
+ <div id="content">
+ <div class="breadcrumbs"><a href="../../">JSON-LD</a> > <a href="../">Specifications</a> > Latest</div>
+ <div id="info">
+ <h1>Latest Specifications</h1>
+ <p>There are four specifications that are being actively developed
+ at the moment:</p>
+ <ul>
+ <li><a href="json-ld/">The JSON-LD Syntax</a> -
+ The JSON-LD language syntax describes how to author documents
+ in JSON-LD, including all of the features of the language
+ as well as the syntax constraints of the language.</li>
+ <li><a href="json-ld-api/">The JSON-LD API</a> - The JSON-LD
+ API describes the Application Programming Interface that can
+ be used by developers to interface with JSON-LD documents at
+ a higher level.</li>
+ <li><a href="json-ld-framing/">JSON-LD Framing</a> - JSON-LD
+ Framing describes the Application Programming Interface for
+ flattening and framing JSON-LD documents.</li>
+ <li><a href="json-ld-rdf/">JSON-LD RDF API</a> - JSON-LD
+ RDF AP describes the Application Programming Interface for
+ transforming JSON-LD to RDF.</li>
+ <li><a href="rdf-graph-normalization/">RDF Graph Normalization</a> -
+ The RDF Graph Normalization document is a general algorithm for
+ serializing RDF graphs. It is most useful when comparing
+ differences of graphs, creating serializations of graphs and
+ digitally signing graphs.</li>
+ </ul>
+ </div>
+ </div>
+
+ <div id="footer">
+ <p id="copyright">
+ Website content released under a <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution Share-Alike license</a> except where an alternate is specified.
+ </p>
+ <p id="legal">
+ Part of the <a href="http://payswarm.com/">payswarm.com</a> initiative.
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
--- a/spec/latest/index.php Thu Mar 28 14:29:18 2013 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,76 +0,0 @@
-<?php
-print <<< htmlcode
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN"
- "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">
-<html version="XHTML+RDFa 1.0" xmlns="http://www.w3.org/1999/xhtml"
- xmlns:xhv="http://www.w3.org/1999/xhtml/vocab#"
- xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
- xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
- xmlns:dcterms="http://purl.org/dc/terms/"
- xmlns:vcard="http://www.w3.org/2006/vcard/ns#"
- xmlns:v="http://rdf.data-vocabulary.org/#"
- >
- <head>
- <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
- <title>JSON-LD - Specifications</title>
- <link href="../../site.css" rel="stylesheet" type="text/css" />
- <link rel="shortcut icon" href="../../favicon.ico" />
- </head>
-
- <body>
- <div id="container">
- <div id="header">
- <span class="col">
- <img class="banner" src="../../images/json-ld-logo-1.png" />
- <img class="banner" src="../../images/json-ld-logo-2.png" />
- <img class="banner" src="../../images/json-ld-logo-3.png" />
- <h1>Latest Specifications</h1>
- </span>
- </div>
-
- <div id="content">
- <div class="breadcrumbs"><a href="../../">JSON-LD</a> > <a href="../">Specifications</a> > Latest</div>
- <div id="info">
- <h1>Latest Specifications</h1>
- <p>There are four specifications that are being actively developed
- at the moment:</p>
- <ul>
- <li><a href="json-ld-syntax/">The JSON-LD Syntax</a> -
- The JSON-LD language syntax describes how to author documents
- in JSON-LD, including all of the features of the language
- as well as the syntax constraints of the language.</li>
- <li><a href="json-ld-api/">The JSON-LD API</a> - The JSON-LD
- API describes the Application Programming Interface that can
- be used by developers to interface with JSON-LD documents at
- a higher level.</li>
- <li><a href="json-ld-framing/">JSON-LD Framing</a> - JSON-LD
- Framing describes the Application Programming Interface for
- flattening and framing JSON-LD documents.</li>
- <li><a href="json-ld-rdf/">JSON-LD RDF API</a> - JSON-LD
- RDF AP describes the Application Programming Interface for
- transforming JSON-LD to RDF.</li>
- <li><a href="rdf-graph-normalization/">RDF Graph Normalization</a> -
- The RDF Graph Normalization document is a general algorithm for
- serializing RDF graphs. It is most useful when comparing
- differences of graphs, creating serializations of graphs and
- digitally signing graphs.</li>
- </ul>
- </div>
- </div>
-
- <div id="footer">
- <p id="copyright">
- Website content released under a <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution Share-Alike license</a> except where an alternate is specified.
- </p>
- <p id="legal">
- Part of the <a href="http://payswarm.com/">payswarm.com</a> initiative.
- </p>
- </div>
- </div>
- </body>
-</html>
-
-htmlcode;
-
-?>
-
--- a/spec/latest/json-ld-api/index.html Thu Mar 28 14:29:18 2013 +0100
+++ b/spec/latest/json-ld-api/index.html Thu Mar 28 15:14:23 2013 +0100
@@ -642,10 +642,10 @@
<dt><tdef>keyword</tdef></dt>
<dd>A JSON key that is specific to JSON-LD, specified in the JSON-LD Syntax specification [[!JSON-LD]]
in the section titled
- <cite><a href="../json-ld-syntax/#syntax-tokens-and-keywords">Syntax Tokens and Keywords</a></cite>.</dd>
+ <cite><a href="../json-ld/#syntax-tokens-and-keywords">Syntax Tokens and Keywords</a></cite>.</dd>
<dt><tdef>context</tdef></dt>
<dd>A a set of rules for interpreting a JSON-LD document as specified in
- <cite><a href="../json-ld-syntax/#the-context">The Context</a></cite> of the
+ <cite><a href="../json-ld/#the-context">The Context</a></cite> of the
[[!JSON-LD]] specification.</dd>
<dt><tdef>JSON-LD document</tdef></dt>
<dd>A <tref>JSON-LD document</tref> is a serialization of a collection of
@@ -659,7 +659,7 @@
<dt><tdef>JSON-LD graph</tdef></dt>
<dd>A labeled directed graph, i.e., a set of <tref title="node">nodes</tref>
connected by <tref title="edge">edges</tref>,
- as specified in the <cite><a href="../json-ld-syntax/#data-model">Data Model</a></cite>
+ as specified in the <cite><a href="../json-ld/#data-model">Data Model</a></cite>
section of the JSON-LD syntax specification [[!JSON-LD]].</dd>
<dt><tdef>edge</tdef></dt>
<dd>Every <tref>edge</tref> has a direction associated with it and is labeled with
@@ -1552,7 +1552,7 @@
<li>Otherwise, if <i>key</i>'s <tref>container mapping</tref> in
<tref>active context</tref> is <code>@language</code> and
<i>value</i> is a <tref>JSON object</tref> then <i>value</i>
- is expanded from a <tref href="../json-ld-syntax/#dfn-language-map">language map</tref>
+ is expanded from a <tref href="../json-ld/#dfn-language-map">language map</tref>
as follows:
<ol class="algorithm">
<li>Initialize <i>expanded value</i> to an empty
@@ -2756,7 +2756,7 @@
which collects all properties of a <tref>node</tref> in a single
<tref>JSON object</tref>. In the next step, the <i>node map</i> is
converted to a JSON-LD document in
- <tref href="../json-ld-syntax/#flattened-document-form">flattened document form</tref>.
+ <tref href="../json-ld/#flattened-document-form">flattened document form</tref>.
Finally, if a <tref>context</tref> has been passed, the flattened document
is compacted using the <a href="#compaction-algorithm">Compaction algorithm</a>
before being returned.</p>
@@ -3985,7 +3985,7 @@
<dd>A <tref>set object</tref> or <tref>list object</tref> with
disallowed members has been detected.</dd>
<dt>invalid language map value</dt>
- <dd>An invalid value in a <tref href="../json-ld-syntax/#dfn-language-map">language map</tref>
+ <dd>An invalid value in a <tref href="../json-ld/#dfn-language-map">language map</tref>
has been detected. It has to be a <tref>string</tref> or an <tref>array</tref> of
<tref title="string">strings</tref>.</dd>
<dt>compaction to list of lists</dt>
--- a/spec/latest/json-ld-connect/index.html Thu Mar 28 14:29:18 2013 +0100
+++ b/spec/latest/json-ld-connect/index.html Thu Mar 28 15:14:23 2013 +0100
@@ -182,10 +182,10 @@
<dd>The use of the <tref>null</tref> value within JSON-LD is used to ignore or reset values.</dd>
<dt><tdef>keyword</tdef></dt>
<dd>A JSON key that is specific to JSON-LD, specified in the JSON-LD Syntax specification [[!JSON-LD]]
- in the section titled <cite><a href="../json-ld-syntax/#syntax-tokens-and-keywords">Syntax Tokens and Keywords</a></cite>.</dd>
+ in the section titled <cite><a href="../json-ld/#syntax-tokens-and-keywords">Syntax Tokens and Keywords</a></cite>.</dd>
<dt><tdef>context</tdef></dt>
<dd>A a set of rules for interpreting a JSON-LD document as specified in
- <cite><a href="../json-ld-syntax/#the-context">The Context</a></cite> of the [[JSON-LD]] specification.</dd>
+ <cite><a href="../json-ld/#the-context">The Context</a></cite> of the [[JSON-LD]] specification.</dd>
<dt><tdef><abbr title="Internationalized Resource Identifier">IRI</abbr></tdef></dt>
<dd>An Internationalized Resource Identifier as described in [[!RFC3987]].</dd>
<dt><tdef>Linked Data</tdef></dt>
--- a/spec/latest/json-ld-framing/index.html Thu Mar 28 14:29:18 2013 +0100
+++ b/spec/latest/json-ld-framing/index.html Thu Mar 28 15:14:23 2013 +0100
@@ -186,10 +186,10 @@
<dd>The use of the <tref>null</tref> value within JSON-LD is used to ignore or reset values.</dd>
<dt><tdef>keyword</tdef></dt>
<dd>A JSON key that is specific to JSON-LD, specified in the JSON-LD Syntax specification [[!JSON-LD]]
- in the section titled <cite><a href="../json-ld-syntax/#syntax-tokens-and-keywords">Syntax Tokens and Keywords</a></cite>.</dd>
+ in the section titled <cite><a href="../json-ld/#syntax-tokens-and-keywords">Syntax Tokens and Keywords</a></cite>.</dd>
<dt><tdef>context</tdef></dt>
<dd>A a set of rules for interpreting a JSON-LD document as specified in
- <cite><a href="../json-ld-syntax/#the-context">The Context</a></cite> of the [[JSON-LD]] specification.</dd>
+ <cite><a href="../json-ld/#the-context">The Context</a></cite> of the [[JSON-LD]] specification.</dd>
<dt><tdef><abbr title="Internationalized Resource Identifier">IRI</abbr></tdef></dt>
<dd>An Internationalized Resource Identifier as described in [[!RFC3987]].</dd>
<dt><tdef>Linked Data</tdef></dt>
--- a/spec/latest/json-ld-rdf/index.html Thu Mar 28 14:29:18 2013 +0100
+++ b/spec/latest/json-ld-rdf/index.html Thu Mar 28 15:14:23 2013 +0100
@@ -166,10 +166,10 @@
<dd>The use of the <tref>null</tref> value within JSON-LD is used to ignore or reset values.</dd>
<dt><tdef>keyword</tdef></dt>
<dd>A JSON key that is specific to JSON-LD, specified in the JSON-LD Syntax specification [[!JSON-LD]]
- in the section titled <cite><a href="../json-ld-syntax/#syntax-tokens-and-keywords">Syntax Tokens and Keywords</a></cite>.</dd>
+ in the section titled <cite><a href="../json-ld/#syntax-tokens-and-keywords">Syntax Tokens and Keywords</a></cite>.</dd>
<dt><tdef>context</tdef></dt>
<dd>A a set of rules for interpreting a JSON-LD document as specified in
- <cite><a href="../json-ld-syntax/#the-context">The Context</a></cite> of the [[JSON-LD]] specification.</dd>
+ <cite><a href="../json-ld/#the-context">The Context</a></cite> of the [[JSON-LD]] specification.</dd>
<dt><tdef><abbr title="Internationalized Resource Identifier">IRI</abbr></tdef></dt>
<dd>An Internationalized Resource Identifier as described in [[!RFC3987]].</dd>
<dt><tdef>Absolute IRI</tdef></dt>
--- a/spec/latest/json-ld-syntax/index.html Thu Mar 28 14:29:18 2013 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,3712 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-<title>JSON-LD 1.0</title>
-<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
-<script type="text/javascript" src="../respec-w3c-common.js" class="remove"></script>
-<script type="text/javascript" src="../respec-w3c-extensions.js" class="remove"></script>
-<script type="text/javascript" class="remove">
-//<![CDATA[
- var respecConfig = {
- // extend the bibliography entries
- "localBiblio": localBibliography,
-
- doRDFa: "1.1",
- // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
- specStatus: "ED",
- // 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",
- subtitle: "A JSON-based Serialization for Linked Data",
-
- // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
- // and its maturity status
- previousPublishDate: "2013-02-02",
- previousMaturity: "CG-FINAL",
- previousDiffURI: "http://json-ld.org/spec/FCGS/json-ld-syntax/20130222/",
-
- // if there a publicly available Editor's Draft, this is the link
- 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",
-
- issueBase: "https://github.com/json-ld/json-ld.org/issues/",
-
- // if you want to have extra CSS, append them to this list
- // it is recommended that the respec.css stylesheet be kept
- // extraCSS: [],
-
- // editors, add as many as you like
- // only "name" is required
- editors: [
- { name: "Manu Sporny", url: "http://manu.sporny.org/",
- company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },
- { name: "Gregg Kellogg", url: "http://greggkellogg.net/",
- company: "Kellogg Associates", companyURL: "http://kellogg-assoc.com/" },
- { name: "Markus Lanthaler", url: "http://www.markus-lanthaler.com/",
- company: "Graz University of Technology", companyURL: "http://www.tugraz.at/" }
- ],
-
- // authors, add as many as you like.
- // This is optional, uncomment if you have authors as well as editors.
- // only "name" is required. Same format as editors.
- authors: [
- { name: "Manu Sporny", url: "http://digitalbazaar.com/",
- company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },
- { name: "Dave Longley", url: "http://digitalbazaar.com/",
- company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/"},
- { name: "Gregg Kellogg", url: "http://greggkellogg.net/",
- company: "Kellogg Associates", companyURL: "http://kellogg-assoc.com/" },
- { name: "Markus Lanthaler", url: "http://www.markus-lanthaler.com/",
- company: "Graz University of Technology", companyURL: "http://www.tugraz.at/" },
- { name: "Niklas Lindström", url: "http://neverspace.net/" }
- ],
-
- // name of the WG
- wg: "RDF Working Group",
-
- // URI of the public WG page
- wgURI: "http://www.w3.org/2011/rdf-wg/",
-
- // name (with the @w3c.org) of the public mailing to which comments are due
- wgPublicList: "public-rdf-comments",
-
- // URI of the patent status for this WG, for Rec-track documents
- // !!!! IMPORTANT !!!!
- // This is important for Rec-track documents, do not copy a patent URI from a random
- // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
- // Team Contact.
- wgPatentURI: "http://www.w3.org/2004/01/pp-impl/46168/status",
- maxTocLevel: 2,
- preProcess: [ preProc ]
- // alternateFormats: [ {uri: "diff-20130202.html", label: "diff to previous version"} ]
- };
-//]]>
-</script>
-<style type="text/css">
- .diff { font-weight:bold; color:#0a3; }
- table, thead, tr, td { padding: 5px; border-width: 1px; border-spacing: 0px; border-style: solid; border-collapse: collapse;}
-</style>
-</head>
-
-<body>
-<section id="abstract">
- <p>JSON has proven to be a highly useful object serialization and messaging
- format. This specification defines JSON-LD, a JSON-based format to serialize
- Linked Data. The syntax is designed to not disturb already deployed systems
- running on JSON, but provide a smooth upgrade path from JSON to JSON-LD.
- It is primarily intended to be a way to use Linked Data in Web-based
- programming environments, to build interoperable Web services, and to
- store Linked Data in JSON-based storage engines.</p>
-</section>
-
-<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 six months.</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">
- <h1>Introduction</h1>
-
- <p><tdef>Linked Data</tdef> is a technique for creating a network
- of inter-connected data across different documents and Web sites. In general,
- Linked Data has four properties: 1) it uses <tref title="IRI">IRIs</tref>
- to name things; 2) it uses HTTP <tref title="IRI">IRIs</tref>
- for those names; 3) the name <tref title="IRI">IRIs</tref>, when dereferenced,
- provide more information about the thing; and 4) the data expresses links
- to data on other Web sites. These properties allow data published on the Web
- to work much like Web pages do today. One can start at one piece of Linked Data,
- and follow the links to other pieces of data that are hosted on different
- sites across the Web.</p>
-
- <p>JSON-LD is a lightweight syntax to serialize <tref>Linked Data</tref> in
- JSON [[!RFC4627]]. Its design allows existing JSON to be transformed to
- Linked Data with minimal changes. JSON-LD is primarily intended to be a
- way to use Linked Data in Web-based programming environments, to build
- interoperable Web services, and to store Linked Data in JSON-based storage engines. Since
- JSON-LD is 100% compatible with JSON, the large number of JSON parsers and libraries
- available today can be reused. In addition to all the features JSON provides,
- 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 way to disambiguate keys shared among different 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
- to a <tref>JSON object</tref> on a different site on the Web,</li>
- <li>the ability to annotate <tref title="string">strings</tref> with their language,</li>
- <li>a way to associate datatypes with values such as dates and times,</li>
- <li>and a facility to express one or more directed graphs, such as a social
- network, in a single document.</li>
- </ul>
-
- <p>Developers that require any of the facilities listed above or need to serialize
- an RDF graph or dataset [[RDF11-CONCEPTS]] in a JSON-based syntax will find
- JSON-LD of interest. The syntax is designed to not disturb already deployed
- systems running on JSON, but provide a smooth upgrade path from JSON to
- JSON-LD. Since the shape of such data varies wildly, JSON-LD features mechanisms
- to reshape documents into a deterministic structure which simplifies their
- processing.</p>
-
- <section class="informative">
- <h2>How to Read this Document</h2>
-
- <p>This document is a detailed specification for a serialization of Linked
- Data in JSON. The document is primarily intended for the following audiences:</p>
-
- <ul>
- <li>Software developers who want to encode Linked Data in a variety of
- programming languages that can use JSON.</li>
- <li>Software developers who want to convert existing JSON to JSON-LD.</li>
- <li>Software developers who want to understand the design decisions and
- language syntax for JSON-LD.</li>
- <li>Software developers who want to implement processors and APIs for
- JSON-LD.</li>
- </ul>
-
- <p>A companion document, the JSON-LD Processing Algorithms and API specification
- [[JSON-LD-API]], specifies how to work with JSON-LD at a higher level by
- providing a standard library interface for common JSON-LD operations. Although that
- document is not required for understanding and working with JSON-LD, for some
- readers it will be a better starting point.</p>
-
- <p>To understand the basics in this specification you must first be familiar with
- JSON, which is detailed in [[!RFC4627]].</p>
- </section>
-</section>
-
-<section class="informative">
- <h1>Design Goals and Rationale</h1>
-
- <p>JSON-LD satisfies the following design goals:</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>A JSON-LD document 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 serialize directed graphs. This ensures that almost
- every real world data model can be expressed.</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 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 class="sectionRef" href="#interpreting-json-as-json-ld"></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>
- </dl>
-</section>
-
-<section class="normative">
- <h1>Terminology</h1>
-
- <section class="normative">
- <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. In contrast to JSON,
- in JSON-LD the keys in an object must be unique.</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
- specifically defined (see <a class="sectionRef" 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).</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 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 class="normative">
- <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
- <a class="sectionRef" 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 class="sectionRef" 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 class="sectionRef" href="#string-internationalization"></a> and
- <a class="sectionRef" href="#typed-values"></a>.</dd>
- <dt><code>@language</code></dt>
- <dd>Used to specify the natural (human) language for a particular value or the default
- language of a JSON-LD document. This keyword is described in
- <a class="sectionRef" 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
- <a class="sectionRef" 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 <a class="sectionRef" 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 <a class="sectionRef" 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
- <a class="sectionRef" href="#sets-and-lists"></a>.</dd>
- <dt><code>@reverse</code></dt>
- <dd>Used to express reverse properties. This keyword is described in
- <a class="sectionRef" href="#reverse-properties"></a>.</dd>
- <dt><code>@index</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 <a class="sectionRef" href="#data-indexing"></a>.</dd>
- <dt><code>@base</code></dt>
- <dd>Used to set the base IRI against which <tref title="relative IRI">relative IRIs</tref>
- are resolved. This keyword is described in <a class="sectionRef" href="#base-iri"></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 <a class="sectionRef" href="#default-vocabulary"></a>.</dd>
- <dt><code>@graph</code></dt><dd>Used to explicitly label a <tref>JSON-LD graph</tref>.
- This keyword is described in <a class="sectionRef" 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>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>This specification describes the conformance criteria for JSON-LD documents.
- This criteria is relevant to authors and authoring tool implementers. As well
- as sections marked as non-normative, all authoring guidelines, diagrams, examples,
- and notes in this specification are non-normative. Everything else in this
- specification is normative.</p>
-
- <p>A <tref>JSON-LD document</tref> complies with this specification if it follows
- the normative statements in appendix <a href="#json-ld-grammar"></a>. JSON documents
- can be interpreted as JSON-LD by following the normative statements in
- <a class="sectionRef" href="#interpreting-json-as-json-ld"></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 specification have the
- meaning defined in [[!RFC2119]].</p>
-</section>
-
-<section class="informative">
- <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">
- <!--
- {
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/",
- "image": "http://manu.sporny.org/images/manu.png"
- }
- -->
- </pre>
-
- <p>It's obvious to 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.
- 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
- tokens 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.</p>
-
- <p>Leveraging the well-known <a href="http://schema.org/">schema.org vocabulary</a>,
- the example above could be unambiguously expressed as follows:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Sample JSON-LD document using full IRIs instead of terms">
- <!--
- {
- "****http://schema.org/name****": "Manu Sporny",
- "****http://schema.org/url****": ****{ "@id": ****"http://manu.sporny.org/" ****}****,
- "****http://schema.org/image****": ****{ "@id": ****"http://manu.sporny.org/images/manu.png" ****}****
- }
- -->
- </pre>
-
- <p>In the example above, 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 valid JSON-LD
- document that is very specific about its data, the document is also overly verbose and difficult
- to work with for human developers. To address this issue, JSON-LD introduces the notion
- of a <tref>context</tref> as described in the next section.</p>
-
- <section class="informative">
- <h2>The Context</h2>
-
- <p>Simply speaking, a <tdef>context</tdef> is used to map <tref title="term">terms</tref>, to
- <tref title="IRI">IRIs</tref>. <tref title="term">Terms</tref> are case sensitive
- and any valid <tref>string</tref> that is not a reserved JSON-LD <tref>keyword</tref>
- can be used as a <tref>term</tref>.</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://schema.org/name",
- "image": {
- "@id": "http://schema.org/image",
- "@type": "@id"
- },
- "homepage": {
- "@id": "http://schema.org/url",
- "@type": "@id"
- }
- }****
- }
- -->
- </pre>
-
- <p>As the <tref>context</tref> above shows, the value of a <tdef>term definition</tdef> can
- either be a simple string, mapping the <tref>term</tref> to an <tref>IRI</tref>,
- or a <tref>JSON object</tref>.</p>
-
- <p>When a <tref>JSON object</tref> is
- associated with a term, it is called an <tdef>expanded term definition</tdef>.
- The example above specifies that the values of <code>image</code> and
- <code>homepage</code> terms are <tref title="IRI">IRIs</tref>.
- They also allow terms to be used for <a href="#data-indexing">index 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, which is
- mainly used to associate type or language information with an
- <tref title="absolute iri">absolute</tref> or <tref>compact IRI</tref>.</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://manu.sporny.org/images/manu.png"
- }
- -->
- </pre>
-
- <p>The referenced context not only specifies how the terms map to
- <tref title="IRI">IRIs</tref> in the Schema.org 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 <a class="sectionRef" href="#iris"></a> for more details). This information allows developers
- to re-use each other's 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>JSON documents can be transformed to JSON-LD without having to be modified by
- referencing a <tref>context</tref> via an HTTP Link Header
- as described in <a class="sectionRef" href="#interpreting-json-as-json-ld"></a>. It is also
- possible to apply a custom context using the JSON-LD API [[JSON-LD-API]].</p>
-
- <p>In <tref title="JSON-LD document">JSON-LD documents</tref>
- <tref title="context">contexts</tref> may also be specified in-line.
- This has the advantage that documents 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://schema.org/name",
- "image": {
- "@id": "http://schema.org/image",
- "@type": "@id"
- },
- "homepage": {
- "@id": "http://schema.org/url",
- "@type": "@id"
- }
- },****
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/",
- "image": "http://manu.sporny.org/images/manu.png"
- }
- -->
- </pre>
- </section>
-
-<section class="informative">
- <h2>IRIs</h2>
-
- <p><tref title="IRI">IRIs</tref> (Internationalized Resource Identifiers
- [[!RFC3987]]) are fundamental to <tref>Linked Data</tref> as that is how most
- <tref title="node">nodes</tref> and <tref title="property">properties</tref>
- are identified. In JSON-LD, IRIs may be represented as an
- <tref>absolute IRI</tref> or a <tref>relative IRI</tref>. An
- <tdef>absolute IRI</tdef> is defined in [[!RFC3987]] as containing a
- <em>scheme</em> along with <em>path</em> and optional <em>query</em> and
- <em>fragment</em> segments. A <tdef>relative IRI</tdef> is an IRI
- that is relative to some other <tref>absolute IRI</tref>.
- In JSON-LD all <tref title="relative IRI">relative IRIs</tref> are resolved
- relative to the <tdef>base IRI</tdef> associated with the document.</p>
-
- <p>A <tref>string</tref> is interpreted as an <tref>IRI</tref> when it is the
- value of an <code>@id</code> member:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Values of @id are interpreted as IRI">
- <!--
- {
- ...
- "homepage": { "****@id****": "http://example.com/" }
- ...
- }
- -->
- </pre>
-
- <p>Values that are interpreted as <tref title="IRI">IRIs</tref>, can also be
- expressed as <tref title="relative IRI">relative IRIs</tref>. For example,
- assuming that the following document is located at
- <code>http://example.com/about/</code>, the <tref>relative IRI</tref>
- <code>../</code> would expand to <code>http://example.com/</code> (for more
- information on where <tref title="relative IRI">relative IRIs</tref> can be
- used, please refer to appendix <a href="#json-ld-grammar"></a>).</p>
-
- <pre class="example" data-transform="updateExample"
- title="IRIs can be relative">
- <!--
- {
- ...
- "homepage": { "****@id****": "../" }
- ...
- }
- -->
- </pre>
-
- <p><tref title="absolute iri">Absolute IRIs</tref> can be expressed directly
- in the key position like so:</p>
-
- <pre class="example" data-transform="updateExample"
- title="IRI as a key">
- <!--
- {
- ...
- "****http://schema.org/name****": "Manu Sporny",
- ...
- }
- -->
- </pre>
-
- <p>In the example above, the key <code>http://schema.org/name</code>
- is interpreted as an <tref>absolute IRI</tref> because it contains a colon
- (<code>:</code>) and it is neither a <tref>compact IRI</tref> nor a
- <tref>blank node identifier</tref>.</p>
-
- <p>Term-to-IRI expansion occurs if the key matches a <tref>term</tref> defined
- within the <tref>active context</tref>:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Term expansion from context definition">
- <!--
- {
- "****@context****":
- {
- "****name****": "****http://schema.org/name****"
- },
- "****name****": "Manu Sporny",
- "status": "trollin'"
- }
- -->
- </pre>
-
- <p>JSON keys that do not expand to an <tref>IRI</tref>, such as <code>status</code>
- in the example above, are not Linked Data and thus ignored when processed.</p>
-
- <p>If type <tref>coercion</tref> rules are specified in the <code>@context</code> for
- a particular <tref>term</tref> or property IRI, an IRI is generated:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Type coercion">
- <!--
- {****
- "@context":
- {
- ...
- "homepage":
- {
- "@id": "http://schema.org/homepage",
- "@type": "@id"
- }
- ...
- }****
- ...
- "homepage": "http://manu.sporny.org/",
- ...
- }
- -->
- </pre>
-
- <p>In the example above, even though the value <code>http://manu.sporny.org/</code>
- is expressed as a JSON <tref>string</tref>, the type <tref>coercion</tref>
- rules will transform the value into an IRI when generating the
- <tref>JSON-LD graph</tref>. See <a class="sectionRef" href="#type-coercion"></a> for more
- details about this feature.</p>
-
- <p>In summary, <tref title="IRI">IRIs</tref> can be expressed in a variety of
- different ways in JSON-LD:</p>
-
- <ol>
- <li><tref>JSON object</tref> keys that have a <tref>term</tref> mapping in
- the <tref>active context</tref> expand to an <tref>IRI</tref>
- (only applies outside of the <tref>context definition</tref>).</li>
- <li>An <tref>IRI</tref> is generated for the <tref>string</tref> value specified using
- <code>@id</code> or <code>@type</code>.</li>
- <li>An <tref>IRI</tref> is generated for the <tref>string</tref> value of any key for which there
- are <tref>coercion</tref> rules that contain a <code>@type</code> key that is
- set to a value of <code>@id</code> or <code>@vocab</code>.</li>
- </ol>
-</section>
-
-<section class="informative">
- <h2>Node Identifiers</h2>
-
- <p>To be able to externally reference <tref title="node">nodes</tref>
- in a <tref title="json-ld graph">graph</tref>, it is important that
- <tref title="node">nodes</tref> have an identifier. <tref title="IRI">IRIs</tref>
- are a fundamental concept of <tref>Linked Data</tref>, for
- <tref title="node">nodes</tref> to be truly linked, dereferencing the
- identifier should result in a representation of that <tref>node</tref>.
- This may allow an application to retrieve further information about a
- <tref>node</tref>.</p>
-
- <p>In JSON-LD, a <tref>node</tref> is identified using the <code>@id</code>
- <tref>keyword</tref>:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Identifying a node">
- <!--
- {
- "@context":
- {
- ...
- "name": "http://schema.org/name"
- },
- ****"@id": "http://me.markus-lanthaler.com/"****,
- "name": "Markus Lanthaler",
- ...
- }
- -->
- </pre>
-
- <p>The example above contains a <tref>node object</tref> identified by the IRI
- <code>http://me.markus-lanthaler.com/</code>.</p>
-</section>
-
-<section class="informative">
-<h2>Specifying the Type</h2>
-
-<p>The type of a particular node can be specified using the <code>@type</code>
- <tref>keyword</tref>. In <tref>Linked Data</tref>, types are uniquely
- identified with an <tref>IRI</tref>.</p>
-
-<pre class="example" data-transform="updateExample"
- title="Specifying the type for a node">
-<!--
-{
-...
- "@id": "http://example.org/places#BrewEats",
- "****@type****": "****http://schema.org/Restaurant****",
-...
-}
--->
-</pre>
-
-<p>A node can be assigned more than one type by using an <tref>array</tref>:</p>
-
-<pre class="example" data-transform="updateExample"
- title="Specifying multiple types for a node">
-<!--
-{
-...
- "@id": "http://example.org/places#BrewEats",
- "****@type****": ****[ "http://schema.org/Restaurant", "http://schema.org/Brewery" ],****
-...
-}
--->
-</pre>
-
-<p>The value of a <code>@type</code> key may also be a <tref>term</tref> defined in the <tref>active context</tref>:</p>
-<pre class="example" data-transform="updateExample"
- title="Using a term to specify the type">
-<!--
-{
- "@context": {
- ...
- ****"Restaurant": "http://schema.org/Restaurant", ****
- ****"Brewery": "http://schema.org/Brewery"****
- }
- "@id": "http://example.org/places#BrewEats",
- ****"@type": [ "Restaurant", "Brewery" ]****,
- ...
-}
--->
-</pre>
-</section>
-</section>
-
-<section class="normative">
-<h1>Advanced Concepts</h1>
-
-<p>JSON-LD has a number of features that provide functionality above and beyond
- the core functionality described above. The following section describes this
- advanced functionality in more detail.</p>
-
-<section class="informative">
- <h2>Base IRI</h2>
-
- <p class="issue atrisk" data-number="223" title="Feature at risk">This feature is
- at risk as the fact that a document may have multiple base IRIs is potentially
- confusing for developers. It is also being discussed whether relative IRIs
- are allowed as values of <code>@base</code> or whether the empty string
- should be used to explicitly specify that there isn't a base IRI, which
- could be used to ensure that relative IRIs remain relative when expanding.</p>
-
- <p>JSON-LD allows <tref>IRI</tref>s to be specified in a relative form which is
- resolved against the document base according
- <cite><a href="http://tools.ietf.org/html/rfc3986#section-5.1">section 5.1 Establishing a Base URI</a></cite>
- of [[RFC3986]]. The base IRI may be explicitly set with a <tref>context</tref>
- using the <code>@base</code> keyword.</p>
-
- <p>For example, if a JSON-LD document was retrieved from <code>http://example.com/document.jsonld</code>,
- relative IRIs would resolve against that IRI:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Use a relative IRI as node identifier">
- <!--
- {
- "@context": {
- "label": "http://www.w3.org/2000/01/rdf-schema#label"
- },
- ****"@id": ""****,
- "label": "Just a simple document"
- }
- -->
- </pre>
-
- <p>This document uses an empty <code>@id</code>, which resolves to the document base.
- However, if the document is moved to a different location, the <tref>IRI</tref> would change.
- To prevent this without having to use an <tref>absolute IRI</tref>, a <tref>context</tref>
- may define a <code>@base</code> mapping, to overwrite the base IRI for the document.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Setting the document base in a document">
- <!--
- {
- "@context": {
- ****"@base": "http://example.com/document.jsonld"****
- },
- "@id": "",
- "label": "Just a simple document"
- }
- -->
- </pre>
-</section>
-
-<section class="informative">
- <h2>Default Vocabulary</h2>
-
- <p>At times, all properties and types may come from the same vocabulary. JSON-LD's
- <code>@vocab</code> keyword allows an author to set a common prefix to be used
- for all properties and types that do not match a <tref>term</tref> or are neither
- a <tref>compact IRI</tref> nor an <tref>absolute IRI</tref> (i.e., they do
- not contain a colon).</p>
-
- <pre class="example" data-transform="updateExample"
- title="Using a common vocabulary prefix">
- <!--
- {
- "@context": {
- ****"@vocab": "http://schema.org/"****
- }
- "@id": "http://example.org/places#BrewEats",
- "@type": ****"Restaurant"****,
- ****"name"****: "Brew Eats"
- ...
- }
- -->
- </pre>
-
- <p>If <code>@vocab</code> is used but certain keys in an
- <tref title="JSON object">object</tref> should not be expanded using
- the vocabulary <tref>IRI</tref>, a <tref>term</tref> can be explicitly set
- to <tref>null</tref> in the <tref>context</tref>. For instance, in the
- example below the <code>databaseId</code> member would not expand to an
- <tref>IRI</tref>.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Using the null keyword to ignore data">
- <!--
- {
- "@context":
- {
- "@vocab": "http://schema.org/",
- ****"databaseId": null****
- },
- "@id": "http://example.org/places#BrewEats",
- "@type": "Restaurant",
- "name": "Brew Eats",
- ****"databaseId"****: "23987520"
- }
- -->
- </pre>
-</section>
-
-<section class="informative">
- <h2>Compact IRIs</h2>
-
- <p>A <tdef>compact IRI</tdef> is a way of expressing an <tref>IRI</tref>
- using a <em>prefix</em> and <em>suffix</em> separated by a colon (<code>:</code>).
- The <tdef>prefix</tdef> is a <tref>term</tref> taken from the
- <tref>active context</tref> and is a short string identifying a
- particular <tref>IRI</tref> in a JSON-LD document. 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 <tref>IRI</tref>
- <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 to the IRI
- <code>http://xmlns.com/foaf/0.1/name</code>.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Prefix expansion">
- <!--
- {
- "****@context****":
- {
- "****foaf****": "****http://xmlns.com/foaf/0.1/****"
- ...
- },
- "@type": "****foaf:Person****"
- "****foaf:name****": "Dave Longley",
- ...
- }
- -->
- </pre>
-
- <p>In the example above, <code>foaf:name</code> expands to the <tref>IRI</tref>
- <code>http://xmlns.com/foaf/0.1/name</code> and <code>foaf:Person</code> expands
- to <code>http://xmlns.com/foaf/0.1/Person</code>.</p>
-
- <p><tref title="prefix">Prefixes</tref> are expanded when the form of the value
- is a <tref>compact IRI</tref> represented as a <code>prefix:suffix</code>
- combination, the <em>prefix</em> matches a <tref>term</tref> defined within the
- <tref>active context</tref>, and the <em>suffix</em> does not begin with two
- slashes (<code>//</code>). The <tref>compact IRI</tref> is expanded by
- concatenating the <tref>IRI</tref> mapped to the <em>prefix</em> to the (possibly empty)
- <em>suffix</em>. If the <em>prefix</em> is not defined in the <tref>active context</tref>,
- or the suffix begins with two slashes (such as in <code>http://example.com</code>),
- the value is interpreted as <tref>absolute IRI</tref> instead. If the prefix is an
- underscore (<code>_</code>), the value is interpreted as <tref>blank node identifier</tref>
- instead.</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">
- <!--
- {
- "@context":
- {
- "xsd": "http://www.w3.org/2001/XMLSchema#",
- ****"foaf": "http://xmlns.com/foaf/0.1/"****,
- ****"foaf:homepage"****: { "@type": "@id" },
- "picture": { "@id": ****"foaf:depiction"****, "@type": "@id" }
- },
- "@id": "http://me.markus-lanthaler.com/",
- "@type": "foaf:Person",
- "foaf:name": "Markus Lanthaler",
- "foaf:homepage": "http://www.markus-lanthaler.com/",
- "picture": "http://twitter.com/account/profile_image/markuslanthaler"
- }
- -->
- </pre>
-</section>
-
-<section class="informative">
-<h2>Typed Values</h2>
-
-<p>
- A value with an associated type, also known as a
- <tref>typed value</tref>, is indicated by associating a value with
- an <tref>IRI</tref> which indicates the value's type. Typed values may be
- expressed in JSON-LD in three ways:
-</p>
-
-<ol>
- <li>By utilizing the <code>@type</code> <tref>keyword</tref> when defining
- a <tref>term</tref> within a <code>@context</code> section.</li>
- <li>By utilizing a <tref>value object</tref>.</li>
- <li>By using a native JSON type such as <tref>number</tref>, <tref>true</tref>, or <tref>false</tref>.</li>
-</ol>
-
-<p>The first example uses the <code>@type</code> keyword to associate a
-type with a particular <tref>term</tref> in the <code>@context</code>:</p>
-
-<pre class="example" data-transform="updateExample"
- title="Expanded term definition with type coercion">
-<!--
-{
- ****"@context":
- {
- "modified":
- {
- "@id": "http://purl.org/dc/terms/modified",
- "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
- }
- },****
-...
- "@id": "http://example.com/docs/1",
- "modified": "2010-05-29T14:17:39+02:00",
-...
-}
--->
-</pre>
-
-<p>The <em>modified</em> key's value above is automatically type coerced to a
- <em>dateTime</em> value because of the information specified in the
- <code>@context</code>. A JSON-LD processor will interpret the example above
- as follows:</p>
-
-<table class="example">
-<thead>
- <th>Subject</th>
- <th>Property</th>
- <th>Value</th>
- <th>Value Type</th>
-</thead>
-<tbody>
-<tr>
- <td>http://example.com/docs/1</td>
- <td>http://purl.org/dc/terms/modified</td>
- <td>2010-05-29T14:17:39+02:00</td>
- <td>http://www.w3.org/2001/XMLSchema#dateTime</td>
-</tr>
-</tbody>
-</table>
-
-<p>The second example uses the expanded form of setting the type information
-in the body of a JSON-LD document:</p>
-
-<pre class="example" data-transform="updateExample"
- title="Expanded value with type">
-<!--
-{
- "@context":
- {
- "modified":
- {
- "@id": "http://purl.org/dc/terms/modified"
- }
- },
-...
- "modified":
- ****{
- "@value": "2010-05-29T14:17:39+02:00",
- "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
- }****
-...
-}
--->
-</pre>
-
-<p>Both examples above would generate the value
- <code>2010-05-29T14:17:39+02:00</code> with the type
- <code>http://www.w3.org/2001/XMLSchema#dateTime</code>. Note that it is
- also possible to use a <tref>term</tref> or a <tref>compact IRI</tref> to
- express the value of a type.</p>
-
-<p>The <code>@type</code> <tref>keyword</tref> is also used to associate a type
- with a <tref>node</tref>. The concept of a <tref>node type</tref> and
- a <tref>value type</tref> are different.</p>
-
-<p>Generally speaking, a <tdef>node type</tdef> specifies the type of thing
- that is being described, like a person, place, event, or web page. A
- <tdef>value type</tdef> specifies the data type of a particular value, such
- as an integer, a floating point number, or a date.</p>
-
-<pre class="example" data-transform="updateExample"
- title="Example demonstrating the context-sensitivity for @type">
-<!--
-{
-...
- "@id": "http://example.org/posts#TripToWestVirginia",
- ****"@type": "http://schema.org/BlogPosting"****, <- This is a node type
- "modified":
- {
- "@value": "2010-05-29T14:17:39+02:00",
- ****"@type": "http://www.w3.org/2001/XMLSchema#dateTime"**** <- This is a value type
- }
-...
-}
--->
-</pre>
-
-<p>The first use of <code>@type</code> associates a <tref>node type</tref>
- (<code>http://schema.org/BlogPosting</code>) with the <tref>node</tref>,
- which is expressed using the <code>@id</code> <tref>keyword</tref>.
- The second use of <code>@type</code> associates a <tref>value type</tref>
- (<code>http://www.w3.org/2001/XMLSchema#dateTime</code>) with the
- value expressed using the <code>@value</code> <tref>keyword</tref>. As a
- general rule, when <code>@value</code> and <code>@type</code> are used in
- the same <tref>JSON object</tref>, the <code>@type</code>
- <tref>keyword</tref> is expressing a <tref>value type</tref>.
- Otherwise, the <code>@type</code> <tref>keyword</tref> is expressing a
- <tref>node type</tref>. The example above expresses the following data:</p>
-
-<table class="example">
-<thead>
- <th>Subject</th>
- <th>Property</th>
- <th>Value</th>
- <th>Value Type</th>
-</thead>
-<tbody>
-<tr>
- <td>http://example.org/posts#TripToWestVirginia</td>
- <td>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</td>
- <td>http://schema.org/BlogPosting</td>
- <td style="text-align:center;">-</td>
-</tr>
-<tr>
- <td>http://example.org/posts#TripToWestVirginia</td>
- <td>http://purl.org/dc/terms/modified</td>
- <td>2010-05-29T14:17:39+02:00</td>
- <td>http://www.w3.org/2001/XMLSchema#dateTime</td>
-</tr>
-</tbody>
-</table>
-
-</section>
-
-<section class="informative">
-<h2>Type Coercion</h2>
-
-<p>JSON-LD supports the coercion of values to particular data types.
-Type <tdef>coercion</tdef> allows someone deploying JSON-LD to coerce the incoming or
-outgoing values to the proper data type based on a mapping of data type <tref title="IRI">IRIs</tref> to
-<tref title="term">terms</tref>. Using type coercion, value representation is preserved without requiring
-the data type to be specified with each piece of data.</p>
-
-<p>Type coercion is specified within an <tref>expanded term definition</tref>
- using the <code>@type</code> key. The value of this key expands to an <tref>IRI</tref>.
- Alternatively, the <tref title="keyword">keywords</tref> <code>@id</code> or <code>@vocab</code> may be used
- as value to indicate that within the body of a JSON-LD document, a <tref>string</tref> value of a
- <tref>term</tref> coerced to <code>@id</code> or <code>@vocab</code> is to be interpreted as an
- <tref>IRI</tref>. The difference between <code>@id</code> and <code>@vocab</code> is how values are expanded
- to <tref title="absolute IRI">absolute IRIs</tref>. <code>@vocab</code> first tries to expand the value
- by interpreting it as <tref>term</tref>. If no matching <tref>term</tref> is found in the
- <tref>active context</tref>, it tries to expand it as <tref>compact IRI</tref> or <tref>absolute IRI</tref>
- if there's a colon in the value; otherwise, it will expand the value using the
- <tref title="active context">active context's</tref> vocabulary mapping, if present, or by interpreting it
- as <tref>relative IRI</tref>. Values coerced to <code>@id</code> in contrast are expanded as
- <tref>compact IRI</tref> or <tref>absolute IRI</tref> if a colon is present; otherwise, they are interpreted
- as <tref>relative IRI</tref>.</p>
-
-<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>
-
-<p>The example below demonstrates how a JSON-LD author can coerce values to
-<tref title="typed value">typed values</tref> and <tref title="IRI">IRIs</tref>.</p>
-
-<pre class="example" data-transform="updateExample"
- title="Expanded term definition with types">
-<!--
-{
- "@context":
- {
- "xsd": "http://www.w3.org/2001/XMLSchema#",
- "name": "http://xmlns.com/foaf/0.1/name",
- "age":
- ****{
- "@id": "http://xmlns.com/foaf/0.1/age",
- "@type": "xsd:integer"
- }****,
- "homepage":
- ****{
- "@id": "http://xmlns.com/foaf/0.1/homepage",
- "@type": "@id"
- }****
- },
- "@id": "http://example.com/people#john",
- "name": "John Smith",
- "age": ****"41"****,
- "homepage":
- ****[
- "http://personal.example.org/",
- "http://work.example.com/jsmith/"
- ]****
-}
--->
-</pre>
-
-<p>The example shown above would generate the following data.</p>
-
-<table class="example">
-<thead>
- <th>Subject</th>
- <th>Property</th>
- <th>Value</th>
- <th>Value Type</th>
-</thead>
-<tbody>
-<tr>
- <td>http://example.com/people#john</td>
- <td>http://xmlns.com/foaf/0.1/name</td>
- <td>John Smith</td>
- <td> </td>
-</tr>
-<tr>
- <td>http://example.com/people#john</td>
- <td>http://xmlns.com/foaf/0.1/age</td>
- <td>41</td>
- <td>http://www.w3.org/2001/XMLSchema#integer</td>
-</tr>
-<tr>
- <td rowspan="2">http://example.com/people#john</td>
- <td rowspan="2">http://xmlns.com/foaf/0.1/homepage</td>
- <td>http://personal.example.org/</td>
- <td><tref>IRI</tref></td>
-</tr>
-<tr>
- <td>http://work.example.com/jsmith/</td>
- <td><tref>IRI</tref></td>
-</tr>
-</tbody>
-</table>
-
-<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>
-
-<pre class="example" data-transform="updateExample"
- title="Term definitions using compact and absolute IRIs">
-<!--
-{
- "@context":
- {
- "foaf": "http://xmlns.com/foaf/0.1/",
- "****foaf:age****":
- {
- ****"@id": "http://xmlns.com/foaf/0.1/age"****,
- "@type": "xsd:integer"
- },
- "****http://xmlns.com/foaf/0.1/homepage****":
- {
- "@type": "@id"
- }
- },
- "foaf:name": "John Smith",
- "****foaf:age****": "41",
- "****http://xmlns.com/foaf/0.1/homepage****":
- [
- "http://personal.example.org/",
- "http://work.example.com/jsmith/"
- ]
-}
--->
-</pre>
-
-<p>In this case the <code>@id</code> definition in the term definition is optional.
- If it does exist, the <tref>compact IRI</tref> or <tref>IRI</tref> representing
- the term will always be expanded to <tref>IRI</tref> defined by the <code>@id</code>
- key—regardless of whether a prefix is defined or not.</p>
-
-<p>Type coercion is always performed using the unexpanded value of the key. In the
- example above, that means that type coercion is done looking for <code>foaf:age</code>
- in the <tref>active context</tref> and not for the corresponding, expanded
- <tref>IRI</tref> <code>http://xmlns.com/foaf/0.1/age</code>.</p>
-
-<p class="note">Keys in the context are treated as <tref title="term">terms</tref> for the purpose of
- expansion and value coercion. At times, this may result in multiple representations for the same expanded IRI.
- For example, one could specify that <code>dog</code> and <code>cat</code> both expanded to <code>http://example.com/vocab#animal</code>.
- Doing this could be useful for establishing different type coercion or language specification rules. It also allows a <tref>compact IRI</tref> (or even an
- absolute <tref>IRI</tref>) to be defined as something else entirely. For example, one could specify that
- the <tref>term</tref> <code>http://example.org/zoo</code> should expand to
- <code>http://example.org/river</code>, but this usage is discouraged because it would lead to a
- great deal of confusion among developers attempting to understand the JSON-LD document.</p>
-
-
-</section>
-
-<section class="informative">
- <h2>Embedding</h2>
-
- <p><tdef>Embedding</tdef> is a JSON-LD feature that allows an author to
- use <tref title="node object">node objects</tref> as
- <tref>property</tref> values. This is a commonly used mechanism for
- creating a parent-child relationship between two <tref title="node">nodes</tref>.</p>
-
- <p>The example shows two nodes related by a property from the first node:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Embedding a node object as property value of another node object">
- <!--
- {
- ...
- "name": "Manu Sporny",
- "****knows****":
- {
- "****@type****": "****Person****",
- "****name****": "****Gregg Kellogg****",
- }
- ...
- }
- -->
- </pre>
-
- <p>
- A <tref>node object</tref>, like the one used above, may be used in
- any value position in the body of a JSON-LD document.</p>
-</section>
-
-<section class="informative">
- <h2>Advanced Context Usage</h2>
-
- <p>Section <a href="#the-context"></a> introduced the basics of what makes
- JSON-LD work. This section expands on the basic principles of the
- <tref>context</tref> and demonstrates how more advanced use cases can
- be achieved using JSON-LD. </p>
-
- <p>In general, contexts may be used at any time a
- <tref>JSON object</tref> is defined. The only time that one cannot
- express a context is inside a context definition itself. For example, a
- <tref>JSON-LD document</tref> may use more than one context at different
- points in a document:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Using multiple 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>Duplicate context <tref title="term">terms</tref> are overridden using a
- most-recently-defined-wins 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> <tref>term</tref> 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 working with
- legacy applications that depend on a specific structure of the
- <tref>JSON object</tref>. If a <tref>term</tref> is redefined within a
- context, all previous rules associated with the previous definition are
- removed. If a <tref>term</tref> is redefined 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> are
- referred to as <tdef title="local context">local contexts</tdef>. 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. Setting a <tref>local context</tref>
- to <code>null</code> effectively resets the <tref>active context</tref>
- to an empty context. 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">When possible, the <tref>context</tref> definition should be put
- at the top of a JSON-LD document. This makes the document easier to read and
- might make streaming parsers more efficient. Documents that do not have the
- <tref>context</tref> at the top are still conformant JSON-LD.</p>
-
- <p class="note">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 <tref title="keyword">keywords</tref> in future versions
- of JSON-LD. Terms starting with an <code>@</code> character that are not
- <tref title="keyword">JSON-LD 1.0 keywords</tref> are treated as any other term, i.e.,
- they are ignored unless mapped to an <tref>IRI</tref>. Furthermore, the use of
- empty <tref title="term">terms</tref> (<code>""</code>) is not allowed as
- not all programming languages are able to handle empty property names.</p>
-</section>
-
-<section class="normative">
- <h2>Interpreting JSON as JSON-LD</h2>
-
- <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 documents 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="Referencing 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/",
- "image": "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 class="informative">
- <h2>String Internationalization</h2>
-
- <p>At times, it is important to annotate a <tref>string</tref>
- with its language. In JSON-LD this is possible in a variety of ways.
- First, it is possible to define a default language for a JSON-LD document
- by setting the <code>@language</code> key in the <tref>context</tref>:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Setting the default language of a JSON-LD document">
- <!--
- {
- ****"@context":
- {
- ...
- "@language": "ja"
- }****,
- "name": ****"花澄"****,
- "occupation": ****"科学者"****
- }
- -->
- </pre>
-
- <p>The example above would associate the <code>ja</code> language
- code with the two <tref title="string">strings</tref> <em>花澄</em> and <em>科学者</em>.
- Languages codes are defined in [[!BCP47]]. The default language applies to all
- <tref>string</tref> values that are not <a href="#type-coercion">type coerced</a>.</p>
-
- <p>To clear the default language for a subtree, <code>@language</code> can
- be set to <code>null</code> in a <tref>local context</tref> as follows:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Clearing default language">
- <!--
- {
- "@context": {
- ...
- "@language": "ja"
- },
- "name": "花澄",
- "details": {
- **** "@context": {
- "@language": null
- }****,
- "occupation": "Ninja"
- }
- }
- -->
- </pre>
-
- <p>Second, it is possible to associate a language with a specific <tref>term</tref>
- using an <tref>expanded term definition</tref>:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Expanded term definition with language">
- <!--
- {
- "@context": {
- ...
- "ex": "http://example.com/vocab/",
- "@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 class="note">Language associations are only applied to plain
- <tref title="string">strings</tref>. <tref title="typed value">Typed values</tref>
- or values that are subject to <a href="#type-coercion">type coercion</a>
- are not language tagged.</p>
-
- <p>Just as in the example above, systems often need to express the value of a
- property in multiple languages. Typically, such systems also try to ensure that
- developers have a programmatically easy way to navigate the data structures for
- the language-specific data. In this case, <tref title="language map">language maps</tref>
- may be utilized.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Language map expressing a property in three languages">
- <!--
- {
- "@context":
- {
- ...
- "occupation": { "@id": "ex:occupation", ****"@container": "@language"**** }
- },
- "name": "Yagyū Muneyoshi",
- "occupation":
- ****{
- "ja": "忍者",
- "en": "Ninja",
- "cs": "Nindža"
- }****
- ...
- }
- -->
- </pre>
-
- <p>The example above expresses exactly the same information as the previous
- example but consolidates all values in a single property. To access the
- value in a specific language in a programming language supporting dot-notation
- accessors for object properties, a developer may use the
- <code>property.language</code> pattern. For example, to access the occupation
- in English, a developer would use the following code snippet:
- <code>obj.occupation.en</code>.</p>
-
- <p>Third, it is possible to override the default language by using a
- <tref>value object</tref>:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Overriding default language using an expanded value">
- <!--
- {
- "@context": {
- ...
- "@language": "ja"
- },
- "name": "花澄",
- "occupation": ****{
- "@value": "Scientist",
- "@language": "en"
- }****
- }
- -->
- </pre>
-
- <p>This makes it possible to specify a plain string by omitting the
- <code>@language</code> tag or setting it to <code>null</code> when expressing
- it using a <tref>value object</tref>:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Removing language information using an expanded value">
- <!--
- {
- "@context": {
- ...
- "@language": "ja"
- },
- "name": ****{
- "@value": "Frank"
- }****,
- "occupation": {
- "@value": "Ninja",
- "@language": "en"
- },
- "speciality": "手裏剣"
- }
- -->
- </pre>
-
-</section>
-
-<section class="informative">
- <h2>IRI Expansion within a Context</h2>
- <p>In general, normal IRI expansion rules apply
- anywhere an IRI is expected (see <a class="sectionRef" href="#iris"></a>). Within
- a <tref>context</tref> definition, this can mean that terms defined
- within the context may also be used within that context as long as
- there are no circular dependencies. For example, it is common to use
- the <code>xsd</code> namespace when defining <tref>typed value</tref>s:</p>
-
-<pre class="example" data-transform="updateExample"
- title="IRI expansion within a context">
-<!--
-{
- "@context":
- {
- ****"xsd": "http://www.w3.org/2001/XMLSchema#"****,
- "name": "http://xmlns.com/foaf/0.1/name",
- "age":
- {
- "@id": "http://xmlns.com/foaf/0.1/age",
- "@type": ****"xsd:integer"****
- },
- "homepage":
- {
- "@id": "http://xmlns.com/foaf/0.1/homepage",
- "@type": "@id"
- }
- },
- ...
-}
--->
-</pre>
-
-<p>In this example, the <code>xsd</code> <tref>term</tref> is defined
- and used as a <tref>prefix</tref> for the <code>@type</code> coercion
- of the <code>age</code> property.</p>
-
-<p><tref title="term">Terms</tref> may also be used when defining the IRI of another
-<tref>term</tref>:</p>
-
-<pre class="example" data-transform="updateExample"
- title="Using a term to define the IRI of another term within a context">
-<!--
-{
- "@context":
- {
- ****"foaf": "http://xmlns.com/foaf/0.1/"****,
- "xsd": "http://www.w3.org/2001/XMLSchema#",
- "name": ****"foaf:name"****,
- "age":
- {
- "@id": ****"foaf:age"****,
- "@type": "xsd:integer"
- },
- "homepage":
- {
- "@id": ****"foaf:homepage"****,
- "@type": "@id"
- }
- },
- ...
-}
--->
-</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
- <tref>term</tref> definition.</p>
-
-<pre class="example" data-transform="updateExample"
- title="Using a compact IRI as a term">
-<!--
-{
- "@context":
- {
- ****"foaf": "http://xmlns.com/foaf/0.1/"****,
- "xsd": "http://www.w3.org/2001/XMLSchema#",
- "name": "foaf:name",
- "****foaf:age****":
- {
- "@type": "xsd:integer"
- },
- "****foaf:homepage****":
- ****{
- "@type": "@id"
- }****
- },
- ...
-}
--->
-</pre>
-
-<p>
-In this example, the <tref>compact IRI</tref> form is used in two different
-ways.
-In the first approach, <code>foaf:age</code> declares both the
-<tref>IRI</tref> for the <tref>term</tref> (using short-form) as well as the
-<code>@type</code> associated with the <tref>term</tref>. In the second
-approach, only the <code>@type</code> associated with the <tref>term</tref> is
-specified. The full <tref>IRI</tref> for
-<code>foaf:homepage</code> is determined by looking up the <code>foaf</code>
-<tref>prefix</tref> in the
-<tref>context</tref>.
-</p>
-
-<p>
-<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"
- title="Associating context definitions with absolute IRIs">
-<!--
-{
- "@context":
- {
- "foaf": "http://xmlns.com/foaf/0.1/",
- "xsd": "http://www.w3.org/2001/XMLSchema#",
- "name": "foaf:name",
- "foaf:age":
- {
- "@id": "foaf:age",
- "@type": "xsd:integer"
- },
- "****http://xmlns.com/foaf/0.1/homepage****":
- {
- "@type": "@id"
- }
- },
- ...
-}
--->
-</pre>
-
-<p>In order for the <tref>absolute IRI</tref> to match above, the <tref>absolute IRI</tref>
- needs to be used in the <tref>JSON-LD document</tref>. Also note that <code>foaf:homepage</code>
- will not use the <code>{ "@type": "@id" }</code> declaration because
- <code>foaf:homepage</code> is not the same as <code>http://xmlns.com/foaf/0.1/homepage</code>.
- That is, <tref title="term">terms</tref> are looked up in a <tref>context</tref> using
- direct string comparison before the <tref>prefix</tref> lookup mechanism is applied.</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>The only exception for using terms in the <tref>context</tref> is that
- circular definitions are not allowed. That is,
- a definition of <em>term1</em> cannot depend on the
- definition of <em>term2</em> if <em>term2</em> also depends on
- <em>term1</em>. For example, the following <tref>context</tref> definition
- is illegal:</p>
-<pre class="example" data-transform="updateExample"
- title="Illegal circular definition of terms within a context">
-<!--
-{
- "@context":
- {
- ****"term1": "term2:foo",
- "term2": "term1:bar"****
- },
- ...
-}
--->
-</pre>
-</section>
-
-<section class="informative">
-<h2>Sets and Lists</h2>
-
-<p>A JSON-LD author can express multiple values in a compact way by using
- <tref title="array">arrays</tref>. Since graphs do not describe ordering for links
- between nodes, arrays in JSON-LD do not provide an ordering of the
- contained elements by default. This is exactly the opposite from regular JSON
- arrays, which are ordered by default. For example, consider the following
- simple document:</p>
-
-<pre class="example" data-transform="updateExample"
- title="Multiple values with no inherent order">
-<!--
-{
-...
- "@id": "http://example.org/people#joebob",
- "nick": ****[ "joe", "bob", "JB" ]****,
-...
-}
--->
-</pre>
-
-<p>The example shown above would result in the following data being generated,
- each relating the node to an individual value, with no inherent order:</p>
-
-<table class="example">
-<thead>
- <th>Subject</th>
- <th>Property</th>
- <th>Value</th>
-</thead>
-<tbody>
-<tr>
- <td>http://example.org/people#joebob</td>
- <td>http://xmlns.com/foaf/0.1/nick</td>
- <td>joe</td>
-</tr>
-<tr>
- <td>http://example.org/people#joebob</td>
- <td>http://xmlns.com/foaf/0.1/nick</td>
- <td>bob</td>
-</tr>
-<tr>
- <td>http://example.org/people#joebob</td>
- <td>http://xmlns.com/foaf/0.1/nick</td>
- <td>JB</td>
-</tr>
-</tbody>
-</table>
-
-<p>Multiple values may also be expressed using the expanded form:</p>
-
-<pre class="example" data-transform="updateExample"
- title="Using an expanded form to set multiple values">
-<!--
-{
- "@id": "http://example.org/articles/8",
- "dc:title": ****
- [
- {
- "@value": "Das Kapital",
- "@language": "de"
- },
- {
- "@value": "Capital",
- "@language": "en"
- }
- ]****
-}-->
-</pre>
-
-<p>The example shown above would generate the following data, again with
- no inherent order:</p>
-
-<table class="example">
-<thead>
- <th>Subject</th>
- <th>Property</th>
- <th>Value</th>
- <th>Language</th>
-</thead>
-<tbody>
-<tr>
- <td>http://example.org/articles/8</td>
- <td>http://purl.org/dc/terms/title</td>
- <td>Das Kapital</td>
- <td>de</td>
-</tr>
-<tr>
- <td>http://example.org/articles/8</td>
- <td>http://purl.org/dc/terms/title</td>
- <td>Capital</td>
- <td>en</td>
-</tr>
-</tbody>
-</table>
-
-<p>As the notion of ordered collections is rather important in data
- modeling, it is useful to have specific language support. In JSON-LD,
- a list may be represented using the <code>@list</code> <tref>keyword</tref> as follows:</p>
-<pre class="example" data-transform="updateExample"
- title="An ordered collection of values in JSON-LD">
-<!--
-{
-...
- "@id": "http://example.org/people#joebob",
- "foaf:nick":
- ****{
- "@list": [ "joe", "bob", "jaybee" ]
- }****,
-...
-}
--->
-</pre>
-
-<p>This describes the use of this <tref>array</tref> as being ordered,
- and order is maintained when processing a document. If every use of a given multi-valued
- property is a list, this may be abbreviated by setting <code>@container</code>
- to <code>@list</code> in the <tref>context</tref>:</p>
-<pre class="example" data-transform="updateExample"
- title="Specifying that a collection is ordered in the context">
-<!--
-{
- ****"@context":
- {
- ...
- "nick":
- {
- "@id": "http://xmlns.com/foaf/0.1/nick",
- "@container": "@list"
- }
- }****,
-...
- "@id": "http://example.org/people#joebob",
- "nick": ****[ "joe", "bob", "jaybee" ]****,
-...
-}
--->
-</pre>
-
-<p class="note">List of lists are not allowed in this version of JSON-LD.
- This decision was made due to the extreme amount of added complexity when
- processing lists of lists.</p>
-
-<p>While <code>@list</code> is used to describe <em>ordered lists</em>,
- the <code>@set</code> keyword is used to describe <em>unordered sets</em>.
- The use of <code>@set</code> in the body of a JSON-LD document
- is optimized away when processing the document, as it is just syntactic
- sugar. However, <code>@set</code> is helpful when used within the context
- of a document.
- Values of terms associated with a <code>@set</code> or <code>@list</code> container
- are always represented in the form of an <tref>array</tref>,
- even if there is just a single value that would otherwise be optimized to
- a non-array form in compact form (see
- <a class="sectionRef" href="#compact-document-form"></a>). This makes post-processing of
- JSON-LD documents easier as the data is always in array form, even if the
- array only contains a single value.</p>
-
-</section>
-
-<section class="informative">
- <h2>Reverse Properties</h2>
-
- <p class="issue atrisk">This feature is at risk.</p>
-
- <p>JSON-LD serializes directed <tref title="JSON-LD graph">graphs</tref>. That means that
- every <tref>property</tref> points from a <tref>node</tref> to another <tref>node</tref>
- or <tref title="JSON-LD value">value</tref>. However, in some cases, it is desirable
- to serialize in the reverse direction. Consider for example the case where a person
- and its children should be described in a document. If the used vocabulary does not
- provide a <em>children</em> <tref>property</tref> but just a <em>parent</em>
- <tref>property</tref>, every <tref>node</tref> representing a child would have to
- be expressed with a <tref>property</tref> pointing to the parent as in the following
- example.</p>
-
- <pre class="example" data-transform="updateExample"
- title="A document with children linking to their parent">
- <!--
- [
- {
- ****"@id": "#homer"****,
- "http://example.com/vocab#name": "Homer"
- },
- {
- "@id": "#bart",
- "http://example.com/vocab#name": "Bart",
- ****"http://example.com/vocab#parent": { "@id": "#homer" }****
- },
- {
- "@id": "#lisa",
- "http://example.com/vocab#name": "Lisa",
- ****"http://example.com/vocab#parent": { "@id": "#homer" }****
- }
- ]
- -->
- </pre>
-
- <p>Expressing such data is much simpler by using JSON-LD's <code>@reverse</code>
- <tref>keyword</tref>:</p>
-
- <pre class="example" data-transform="updateExample"
- title="A person and its children using a reverse property">
- <!--
- {
- "@id": "#homer",
- "http://example.com/vocab#name": "Homer",
- ****"@reverse"****: {
- ****"http://example.com/vocab#parent"****: [
- {
- "@id": "#bart",
- "http://example.com/vocab#name": "Bart"
- },
- {
- "@id": "#lisa",
- "http://example.com/vocab#name": "Lisa"
- }
- ]
- }
- }
- -->
- </pre>
-
- <p>The <code>@reverse</code> <tref>keyword</tref> can also be used in
- <tref title="expanded term definition">expanded term definitions</tref>
- to create reverse properties as shown in the following example:</p>
-
-
- <pre class="example" data-transform="updateExample"
- title="Using @reverse to define reverse properties">
- <!--
- {
- "@context": {
- "name": "http://example.com/vocab#name",
- ****"children": { "@reverse": "http://example.com/vocab#parent" }****
- },
- "@id": "#homer",
- "name": "Homer",
- ****"children"****: [
- {
- "@id": "#bart",
- "name": "Bart"
- },
- {
- "@id": "#lisa",
- "name": "Lisa"
- }
- ]
- }
- -->
- </pre>
-</section>
-
-
-<section class="informative">
- <h2>Named Graphs</h2>
-
- <p>At times, it is necessary to make statements about a <tref>JSON-LD graph</tref>
- itself, rather than just a single <tref>node</tref>. This can be done by
- grouping a set of <tref title="node">nodes</tref> using the <code>@graph</code>
- <tref>keyword</tref>. A developer may also name data expressed using the
- <code>@graph</code> <tref>keyword</tref> by pairing it with an
- <code>@id</code> <tref>keyword</tref> as shown in the following example:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Identifying and making statements about a graph">
- <!--
- {
- "@context": {
- "generatedAt": {
- "@id": "http://www.w3.org/ns/prov#generatedAtTime",
- "@type": "http://www.w3.org/2001/XMLSchema#date"
- },
- "Person": "http://xmlns.com/foaf/0.1/Person",
- "name": "http://xmlns.com/foaf/0.1/name",
- "knows": "http://xmlns.com/foaf/0.1/knows"
- },
- ****"@id": "http://example.org/graphs/73",
- "generatedAt": "2012-04-09",
- "@graph":****
- [
- {
- "@id": "http://manu.sporny.org/i/public",
- "@type": "Person",
- "name": "Manu Sporny",
- "knows": "http://greggkellogg.net/foaf#me"
- },
- {
- "@id": "http://greggkellogg.net/foaf#me",
- "@type": "Person",
- "name": "Gregg Kellogg",
- "knows": "http://manu.sporny.org/i/public"
- }
- ]
- }
- -->
- </pre>
-
- <p>The example above expresses a <tref>named graph</tref> that is identified
- by the <tref>IRI</tref> <code>http://example.org/graphs/73</code>. That
- graph is composed of the statements about Manu and Gregg. Metadata about
- the graph itself is expressed via the <code>generatedAt</code> property,
- which specifies when the graph was generated. An alternative view of the
- information above is represented in table form below:</p>
-
- <table class="example">
- <thead>
- <th>Graph</th>
- <th>Subject</th>
- <th>Property</th>
- <th>Value</th>
- <th>Value Type</th>
- </thead>
- <tbody>
- <tr>
- <td> </td>
- <td>http://example.org/graphs/73</td>
- <td>http://www.w3.org/ns/prov#generatedAtTime</td>
- <td>2012-04-09</td>
- <td>http://www.w3.org/2001/XMLSchema#date</td>
- </tr>
- <tr>
- <td>http://example.org/graphs/73</td>
- <td>http://manu.sporny.org/i/public</td>
- <td>http://www.w3.org/2001/XMLSchema#type</td>
- <td>http://xmlns.com/foaf/0.1/Person</td>
- <td></td>
- </tr>
- <tr>
- <td>http://example.org/graphs/73</td>
- <td>http://manu.sporny.org/i/public</td>
- <td>http://xmlns.com/foaf/0.1/name</td>
- <td>Manu Sporny</td>
- <td></td>
- </tr>
- <tr>
- <td>http://example.org/graphs/73</td>
- <td>http://manu.sporny.org/i/public</td>
- <td>http://xmlns.com/foaf/0.1/knows</td>
- <td>http://greggkellogg.net/foaf#me</td>
- <td></td>
- </tr>
- <tr>
- <td>http://example.org/graphs/73</td>
- <td>http://greggkellogg.net/foaf#me</td>
- <td>http://www.w3.org/2001/XMLSchema#type</td>
- <td>http://xmlns.com/foaf/0.1/Person</td>
- <td></td>
- </tr>
- <tr>
- <td>http://example.org/graphs/73</td>
- <td>http://greggkellogg.net/foaf#me</td>
- <td>http://xmlns.com/foaf/0.1/name</td>
- <td>Gregg Kellogg</td>
- <td></td>
- </tr>
- <tr>
- <td>http://example.org/graphs/73</td>
- <td>http://greggkellogg.net/foaf#me</td>
- <td>http://xmlns.com/foaf/0.1/knows</td>
- <td>http://manu.sporny.org/i/public</td>
- <td></td>
- </tr>
- </tbody>
- </table>
-
- <p>When a JSON-LD document's top-level structure is an
- <tref title="JSON object">object</tref> that contains no other
- <tref title="property">properties</tref> than <code>@graph</code> and
- optionally <code>@context</code> (properties that are not mapped to an
- <tref>IRI</tref> or a <tref>keyword</tref> are ignored),
- <code>@graph</code> is considered to express the otherwise implicit
- <tref>default graph</tref>. This mechanism can be useful when a number
- of <tref title="node">nodes</tref> exist at the document's top level that
- share the same <tref>context</tref>, which is, e.g., the case when a
- document is <a href="#flattened-document-form">flattened</a>. The
- <code>@graph</code> keyword collects such nodes in an <tref>array</tref>
- and allows the use of a shared context.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Using @graph to explicitly express the default graph">
- <!--
- {
- "@context": ...,
- "****@graph****":
- [
- {
- "@id": "http://manu.sporny.org/i/public",
- "@type": "foaf:Person",
- "name": "Manu Sporny",
- "knows": "http://greggkellogg.net/foaf#me"
- },
- {
- "@id": "http://greggkellogg.net/foaf#me",
- "@type": "foaf:Person",
- "name": "Gregg Kellogg",
- "knows": "http://manu.sporny.org/i/public"
- }
- ]
- }
- -->
- </pre>
-
- <p>In this case, embedding doesn't work as each <tref>node object</tref>
- references the other. This is equivalent to using multiple
- <tref title="node object">node objects</tref> in array and defining
- the <code>@context</code> within each <tref>node object</tref>:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Context needs to be duplicated if @graph is not used">
- <!--
- [
- {
- ****"@context": ...,****
- "@id": "http://manu.sporny.org/i/public",
- "@type": "foaf:Person",
- "name": "Manu Sporny",
- "knows": "http://greggkellogg.net/foaf#me"
- },
- {
- ****"@context": ...,****
- "@id": "http://greggkellogg.net/foaf#me",
- "@type": "foaf:Person",
- "name": "Gregg Kellogg",
- "knows": "http://manu.sporny.org/i/public"
- }
- ]
- -->
- </pre>
-
-</section>
-
-<section class="informative">
- <h2>Identifying Blank Nodes</h2>
-
- <p>At times, it becomes necessary to be able to express information without
- being able to uniquely identify the <tref>node</tref> with an <tref>IRI</tref>.
- This type of node is called a <tref>blank node</tref>. JSON-LD does not require
- all nodes to be identified using <code>@id</code>. However, some graph topologies
- may require identifiers to be serializable. Graphs containing loops, e.g., cannot
- be serialized using embedding alone, <code>@id</code> must be used to connect the nodes.
- In these situations, one can use <tref title="blank node identifier">blank node identifiers</tref>,
- which look like <tref title="IRI">IRIs</tref> using an underscore (<code>_</code>)
- as scheme. This allows one to reference the node locally within the document, but
- makes it impossible to reference the node from an external document. The
- <tref>blank node identifier</tref> is scoped to the document in which it is used.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Specifying a local blank node identifier">
- <!--
- {
- ...
- "@id": "****_:n1****",
- "name": "Secret Agent 1",
- "knows":
- {
- "name": "Secret Agent 2",
- "knows": { "@id": "****_:n1****" }
- }
- }
- -->
- </pre>
-
- <p>The example above contains information about to secrete agents that cannot be identified
- with an <tref>IRI</tref>. While expressing that <em>agent 1</em> knows <em>agent 2</em> is possible
- without using <tref title="blank node identifier">blank node identifiers</tref>, it is
- necessary assign <em>agent 1</em> an identifier so that it can be referenced from
- <em>agent 2</em>.</p>
- <p>It is worth nothing that blank node identifiers may be relabeled during processing.
- If a developer finds that they refer to the <tref>blank node</tref> more than once,
- they should consider naming the node using a dereferenceable <tref>IRI</tref> so that
- it can also be referenced from other documents.</p>
-</section>
-
-<section class="informative">
- <h2>Aliasing Keywords</h2>
-
- <p>Each of the JSON-LD <tref title="keyword">keywords</tref>,
- except for <code>@context</code>, may be aliased to application-specific
- keywords. This feature allows legacy JSON content to be utilized
- by JSON-LD by re-using JSON keys that already exist in legacy documents.
- This feature also allows developers to design domain-specific implementations
- using only the JSON-LD <tref>context</tref>.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Aliasing keywords">
- <!--
- {
- "@context":
- {
- ****"url": "@id"****,
- ****"a": "@type"****,
- "name": "http://xmlns.com/foaf/0.1/name"
- },
- "****url****": "http://example.com/about#gregg",
- "****a****": "http://xmlns.com/foaf/0.1/Person",
- "name": "Gregg Kellogg"
- }
- -->
- </pre>
-
- <p>In the example above, the <code>@id</code> and <code>@type</code>
- <tref title="keyword">keywords</tref> have been given the aliases
- <strong>url</strong> and <strong>a</strong>, respectively.</p>
-
- <p>Since keywords cannot be redefined, they can also not be aliased to
- other keywords.</p>
-</section>
-
-<section class="informative">
- <h2>Data Indexing</h2>
-
- <p>Databases are typically used to make access to
- data more efficient. Developers often extend this sort of functionality into
- their application data to deliver similar performance gains. Often this
- data does not have any meaning from a Linked Data standpoint, but is
- still useful for an application.</p>
-
- <p>JSON-LD introduces the notion of <tref title="index map">index maps</tref>
- that can be used to structure data into a form that is
- more efficient to access. The data indexing feature allows an author to
- structure data using a simple key-value map where the keys do not map
- to <tref title="IRI">IRIs</tref>. This enables direct access to data
- instead of having to scan an array in search of a specific item.
- In JSON-LD such data can be specified by associating the
- <code>@index</code> <tref>keyword</tref> with a
- <code>@container</code> declaration in the context:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Indexing data in JSON-LD">
- <!--
- {
- "@context":
- {
- "schema": "http://schema.org/",
- "name": "schema:name",
- "body": "schema:articleBody",
- "words": "schema:wordCount",
- "post": {
- "@id": "schema:blogPost",
- ****"@container": "@index"****
- }
- },
- "@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>index map</tref>. The <strong>en</strong>,
- <strong>de</strong>, and <strong>ja</strong> keys will be ignored
- semantically, but preserved syntactically, by the JSON-LD Processor.
- This allows a developer 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 index keys do not appear in the Linked Data
- below, but would continue to exist if the document were compacted or
- expanded (see <a class="sectionRef" href="#compact-document-form"></a> and
- <a class="sectionRef" href="#expanded-document-form"></a>) using a JSON-LD processor:</p>
-
- <table class="example">
- <thead>
- <th>Subject</th>
- <th>Property</th>
- <th>Value</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 class="informative">
- <h3>Expanded Document Form</h3>
-
- <p>The JSON-LD Processing Algorithms and API specification [[JSON-LD-API]]
- defines a method for <em>expanding</em> a JSON-LD document.
- Expansion is the process of taking a JSON-LD document and applying a
- <code>@context</code> such that all IRIs, types, and values
- are expanded so that the <code>@context</code> is no longer necessary.</p>
-
- <p>For example, assume the following JSON-LD input document:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Sample JSON-LD document">
- <!--
- {
- "@context":
- {
- "name": "http://xmlns.com/foaf/0.1/name",
- "homepage": {
- "@id": "http://xmlns.com/foaf/0.1/homepage",
- "@type": "@id"
- }
- },
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/"
- }
- -->
- </pre>
-
- <p>Running the JSON-LD Expansion algorithm against the JSON-LD input document
- provided above would result in the following output:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Expanded form for the previous example">
- <!--
- [
- {
- "http://xmlns.com/foaf/0.1/name": [
- { "@value": "Manu Sporny" }
- ],
- "http://xmlns.com/foaf/0.1/homepage": [
- { "@id": "http://manu.sporny.org/" }
- ]
- }
- ]
- -->
- </pre>
-</section>
-
-<section class="informative">
- <h3>Compact Document Form</h3>
-
- <p>The JSON-LD Processing Algorithms and API specification [[JSON-LD-API]] defines
- a method for <em>compacting</em> a JSON-LD document. Compaction is the process
- of applying a developer-supplied context to shorten <tref title="IRI">IRIs</tref>
- to <tref title="term">terms</tref> or <tref title="compact IRI">compact IRIs</tref>
- and JSON-LD values expressed in expanded form to simple values such as
- <tref title="string">strings</tref> or <tref title="number">numbers</tref>.
- Often this makes it simpler to work with document as the data is expressed in
- application-specific terms. Compacted documents are also typically easier to read
- for humans.</p>
-
- <p>For example, assume the following JSON-LD input document:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Sample expanded JSON-LD document">
- <!--
- [
- {
- "http://xmlns.com/foaf/0.1/name": [ "Manu Sporny" ],
- "http://xmlns.com/foaf/0.1/homepage": [
- {
- "@id": "http://manu.sporny.org/"
- }
- ]
- }
- ]
- -->
- </pre>
-
- <p>Additionally, assume the following developer-supplied JSON-LD context:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Sample context">
- <!--
- {
- "@context": {
- "name": "http://xmlns.com/foaf/0.1/name",
- "homepage": {
- "@id": "http://xmlns.com/foaf/0.1/homepage",
- "@type": "@id"
- }
- }
- }
- -->
- </pre>
-
- <p>Running the JSON-LD Compaction algorithm given the context supplied above
- against the JSON-LD input document provided above would result in the following
- output:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Compact form of the sample document once sample context has been applied">
- <!--
- {
- "@context": {
- "name": "http://xmlns.com/foaf/0.1/name",
- "homepage": {
- "@id": "http://xmlns.com/foaf/0.1/homepage",
- "@type": "@id"
- }
- },
- "name": "Manu Sporny",
- "homepage": "http://manu.sporny.org/"
- }
- -->
- </pre>
-</section>
-
-<section class="informative">
- <h3>Flattened Document Form</h3>
-
- <p>The JSON-LD Processing Algorithms and API specification [[JSON-LD-API]] defines
- a method for <em>flattening</em> a JSON-LD document. Flattening collects all
- properties of a <tref>node</tref> in a single <tref>JSON object</tref> and labels
- all <tref title="blank node">blank nodes</tref> with
- <tref title="blank node identifier">blank node identifiers</tref>.
- This ensures a shape of the data and consequently may drastically simplify the code
- required to process JSON-LD in certain applications.</p>
-
- <p>For example, assume the following JSON-LD input document:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Sample JSON-LD document">
- <!--
- {
- "@context": {
- "name": "http://xmlns.com/foaf/0.1/name",
- "knows": "http://xmlns.com/foaf/0.1/knows"
- },
- "@id": "http://me.markus-lanthaler.com/",
- "name": "Markus Lanthaler",
- "knows": [
- {
- "@id": "http://manu.sporny.org/",
- "name": "Manu Sporny"
- },
- {
- "name": "Dave Longley"
- }
- ]
- }
- -->
- </pre>
-
- <p>Running the JSON-LD Flattening algorithm against the JSON-LD input document in
- the example above and using the same context would result in the following
- output:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Flattened and compacted form for the previous example">
- <!--
- {
- "@context": {
- "name": "http://xmlns.com/foaf/0.1/name",
- "knows": "http://xmlns.com/foaf/0.1/knows"
- },
- "@graph": [
- {
- "@id": "_:b0",
- "name": "Dave Longley"
- },
- {
- "@id": "http://manu.sporny.org/",
- "name": "Manu Sporny"
- },
- {
- "@id": "http://me.markus-lanthaler.com/",
- "name": "Markus Lanthaler",
- "knows": [
- { "@id": "http://manu.sporny.org/" },
- { "@id": "_:b0" }
- ]
- }
- ]
- }
- -->
- </pre>
-</section>
-
-<section class="informative">
- <h2>Embedding JSON-LD in HTML Documents</h2>
-
- <p>HTML script tags can be used to embed blocks of data in documents.
- This way, JSON-LD content can be easily embedded in HTML by placing
- it in a script element with the <code>type</code> attribute set to
- <code>application/ld+json</code>.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Embedding JSON-LD in HTML">
- <!--
- ****<script type="application/ld+json">****
- {
- "@context": "http://json-ld.org/contexts/person.jsonld",
- "@id": "http://dbpedia.org/resource/John_Lennon",
- "name": "John Lennon",
- "born": "1940-10-09",
- "spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
- }
- ****</script>****
- -->
- </pre>
-
- <p>Depending on how the HTML document is served, certain strings may need
- to be escaped.</p>
-
- <p>Defining how such data may be used is beyond the scope of this specification.
- The embedded JSON-LD document might be extracted as is or, e.g., be converted
- to RDF.</p>
-
- <p>If JSON-LD content is extracted as RDF [[RDF11-CONCEPTS]], it should be expanded into an
- <tref href="http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset">RDF dataset</tref> using the
- <cite><a href="../json-ld-api/#convert-to-rdf-algorithm">Convert to RDF Algorithm</a></cite>
- [[JSON-LD-API]]. If multiple embedded JSON-LD documents are extracted as RDF,
- the result is the RDF merge of the extracted datasets.</p>
-</section>
-
-</section>
-
-<section class="appendix normative">
- <h1>Data Model</h1>
-
- <p>JSON-LD is a serialization format for <tref>Linked Data</tref> based on JSON.
- It is therefore important to distinguish between the syntax, which is defined
- by JSON in [[RFC4627]], and <tdef title="JSON-LD data model">JSON-LD's data model</tdef>
- which is defined as follows:</p>
-
- <ul>
- <li>A <tdef>JSON-LD document</tdef> serializes a collection of
- <tref title="JSON-LD graph">JSON-LD graphs</tref> and comprises exactly one
- <tdef>default graph</tdef> and zero or more <tdef title="named graph">named graphs</tdef>.</li>
- <li>The <tref>default graph</tref> does not have a name and MAY be empty.</li>
- <li>Each <tref>named graph</tref> is a pair consisting of an <tref>IRI</tref> or
- <tref>blank node identifier</tref> (the <tdef>graph name</tdef>) and a <tref>JSON-LD graph</tref>.
- Whenever possible, the <tref>graph name</tref> SHOULD be an <tref>IRI</tref>.</li>
- <li>A <tdef>JSON-LD graph</tdef> is a labeled directed graph, i.e., a set of
- <tref title="node">nodes</tref> connected by <tref title="edge">edges</tref>.</li>
- <li>Every <tdef>edge</tdef> has a direction associated with it and is labeled with
- an <tref>IRI</tref> or a <tref>blank node identifier</tref>. Within the JSON-LD syntax
- these edge labels are called <tdef title="property">properties</tdef>. Whenever possible, an
- <tref>edge</tref> SHOULD be labeled with an <tref>IRI</tref>.</li>
- <li>Every <tdef>node</tdef> is an <tref>IRI</tref>, a <tref>blank node</tref>,
- a <tref>JSON-LD value</tref>, or a <tref>list</tref>.</li>
- <li>A <tref>node</tref> 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>,
- 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
- defined in [[RFC3987]]. <tref title="IRI">IRIs</tref> used within a
- <tref>JSON-LD graph</tref> SHOULD return a <tref>Linked Data</tref> document describing
- the resource denoted by that <tref>IRI</tref> when being dereferenced.</li>
- <li>A <tdef>blank node</tdef> is a <tref>node</tref> which is neither an <tref>IRI</tref>,
- nor a <tref>JSON-LD value</tref>, nor a <tref>list</tref>. A blank node MAY be identified
- using a <tref>blank node identifier</tref>.</li>
- <li>A <tdef>blank node identifier</tdef> is a string that can be used as an identifier
- for a <tref>blank node</tref> within the scope of a <tref>JSON-LD document</tref>.
- Blank node identifiers begin with <code>_:</code>.</li>
- <li>A <tdef>JSON-LD value</tdef> is a <tref>string</tref>, a <tref>number</tref>,
- <tref>true</tref> or <tref>false</tref>, a <tref>typed value</tref>, or a
- <tref>language-tagged string</tref>.</li>
- <li>A <tdef>typed value</tdef> consists of a value, which is a string, and a type, which is an
- <tref>IRI</tref>.</li>
- <li>A <tdef>language-tagged string</tdef> consists of a string and a non-empty language
- tag as defined by [[BCP47]]. The language tag MUST be well-formed according to section
- <a href="http://tools.ietf.org/html/bcp47#section-2.2.9">2.2.9</a> of [[BCP47]], and MUST
- be lowercase.</li>
- <li>A <tdef>list</tdef> is an ordered sequence of zero or more
- <tref title="IRI">IRIs</tref>,
- <tref title="blank node">blank nodes</tref>, and
- <tref title="JSON-LD value">JSON-LD values</tref>.</li>
- </ul>
-
- <p class="issue atrisk" data-number="217">In contrast to the RDF data model as defined in
- [[RDF11-CONCEPTS]], JSON-LD allows blank nodes as property labels and graph names. Thus,
- some data that is valid JSON-LD cannot be converted to RDF. This feature may be removed
- in the future.</p>
-
- <p><tref title="JSON-LD document">JSON-LD documents</tref> MAY contain data that cannot be
- represented by the <tref title="JSON-LD data model">data model</tref> defined above.
- Unless otherwise specified, such data is ignored when a <tref>JSON-LD document</tref>
- is being processed. This means, e.g., that properties which are not mapped to an
- <tref>IRI</tref> or <tref>blank node</tref> will be ignored.</p>
-
- <p style="text-align: center"><img src="linked-data-graph.png" title="An illustration of JSON-LD's data model"/></p>
- <p style="text-align: center">Figure 1: An illustration of JSON-LD's data model.</p>
-</section>
-
-<section class="appendix normative">
- <h1>JSON-LD Grammar</h1>
-
- <p>This appendix restates the syntactic conventions described in the
- previous sections more formally.</p>
-
- <p>A <tref>JSON-LD document</tref> MUST be a valid JSON document as described
- in [[!RFC4627]].</p>
-
- <p>A <tref>JSON-LD document</tref> MUST be a single <tref>node object</tref>
- or a JSON <tref>array</tref> containing a set of one or more
- <tref title="node object">node objects</tref> at the top level.</p>
-
- <p>In contrast to JSON, in JSON-LD the keys in <tref title="JSON object">objects</tref>
- MUST be unique.</p>
-
- <p class="note">JSON-LD allows <tref title="keyword">keywords</tref> to be aliased
- (see <a class="sectionRef" href="#aliasing-keywords"></a> for details). Whenever a <tref>keyword</tref> is
- discussed in this grammar, the statements also apply to an alias for
- that <tref>keyword</tref>. For example, if the <tref>active context</tref>
- defines the <tref>term</tref> <code>id</code> as an alias for <code>@id</code>,
- that alias may be legitimately used as a substitution for <code>@id</code>.
- Note that <tref>keyword</tref> aliases are not expanded during context
- processing.</p>
-
- <section class="normative">
- <h2>Terms</h2>
-
- <p>A <tdef>term</tdef> is a short-hand <tref>string</tref> that expands
- to an <tref>IRI</tref> or a <tref>blank node identifier</tref>.</p>
-
- <p>A <tref>term</tref> MUST NOT equal any of the JSON-LD
- <tref title="keyword">keywords</tref>.</p>
-
- <p>To avoid forward-compatibility issues, a <tref>term</tref> SHOULD NOT start
- with an <code>@</code> character as future versions of JSON-LD may introduce
- additional <tref title="keyword">keywords</tref>. Furthermore, the term MUST NOT
- be an empty <tref>string</tref> (<code>""</code>) as not all programming languages
- are able to handle empty property names.</p>
-
- <p>See <a class="sectionRef" href="#the-context"></a> and
- <a class="sectionRef" href="#iris"></a> for further discussion
- on mapping <tref title="term">terms</tref> to <tref title="IRI">IRIs</tref>.</p>
- </section>
-
- <section class="normative">
- <h2>Node Objects</h2>
-
- <p>A <tdef>node object</tdef> represents zero or more properties of a
- <tref>node</tref> in the <tref>JSON-LD graph</tref> serialized by the
- <tref>JSON-LD document</tref>. A <tref>JSON object</tref> is a
- <tref>node object</tref> if it exists outside of a JSON-LD
- <tref>context</tref> and:</p>
-
- <ul>
- <li>it does not contain the <code>@value</code>, <code>@list</code>,
- or <code>@set</code> keywords, and</li>
- <li>it is not the top-most <tref>JSON object</tref> in the JSON-LD document
- consisting of no other members than <code>@graph</code> and
- <code>@context</code>.</li>
- </ul>
-
- <p>The <tref title="property">properties</tref> of a <tref>node</tref> in
- a <tref>JSON-LD graph</tref> may be spread among different
- <tref title="node object">node objects</tref> within a document. When
- that happens, the keys of the different
- <tref title="node object">node objects</tref> are merged to create the
- properties of the resulting <tref>node</tref>.</p>
-
- <p>A <tref>node object</tref> MUST be a <tref>JSON object</tref>. All keys
- which are not <tref title="IRI">IRIs</tref>,
- <tref title="compact iri">compact IRIs</tref>, <tref title="term">terms</tref>
- valid in the <tref>active context</tref>, or one of the following
- <tref title="keyword">keywords</tref> MUST be ignored when processed:</p>
-
- <ul>
- <li><code>@context</code>,</li>
- <li><code>@id</code>,</li>
- <li><code>@graph</code>,</li>
- <li><code>@type</code>,</li>
- <li><code>@reverse</code>, or</li>
- <li><code>@index</code></li>
- </ul>
-
- <p>If the <tref>node object</tref> contains the <code>@context</code>
- key, its value MUST be <tref>null</tref>, an <tref>absolute IRI</tref>,
- a <tref>relative IRI</tref>, a <tref>context definition</tref>, or
- an <tref>array</tref> composed of any of these.</p>
-
- <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>).
- See <a class="sectionRef" href="#node-identifiers"></a>,
- <a class="sectionRef" href="#compact-iris"></a>, and
- <a class="sectionRef" href="#identifying-blank-nodes"></a> for further discussion on
- <code>@id</code> values.</p>
-
- <p>If the <tref>node object</tref> contains the <code>@graph</code>
- key, its value MUST be
- a <tref>node object</tref> or
- an <tref>array</tref> of zero or more <tref title="node object">node objects</tref>.
- If the <tref>node object</tref> contains an <code>@id</code> keyword,
- its value is used as the label of a named graph.
- See <a class="sectionRef" href="#named-graphs"></a> for further discussion on
- <code>@graph</code> values. As a special case, if a <tref>JSON object</tref>
- contains no keys other than <code>@graph</code> and <code>@context</code>, and the
- <tref>JSON object</tref> is the root of the JSON-LD document, the
- <tref>JSON object</tref> is not treated as a <tref>node object</tref>; this
- is used as a way of defining <tref title="node object">node
- definitions</tref> that may not form a connected graph. This allows a
- <tref>context</tref> to be defined which is shared by all of the constituent
- <tref title="node object">node objects</tref>.</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>
- (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.
- See <a class="sectionRef" href="#specifying-the-type"></a> for further discussion on
- <code>@type</code> values.</p>
-
- <p>If the <tref>node object</tref> contains the <code>@reverse</code> key,
- its value MUST be a <tref>JSON object</tref> containing members representing reverse
- properties. Each value of such a reverse property MUST be an <tref>absolute IRI</tref>,
- a <tref>relative IRI</tref>, a <tref>compact IRI</tref>, a <tref>blank node identifier</tref>,
- a <tref>node object</tref> or an <tref>array</tref> containing a combination of these.</p>
-
- <p>If the <tref>node object</tref> contains the <code>@index</code> key,
- its value MUST be a <tref>string</tref>. See
- <a class="sectionRef" href="#data-indexing"></a> for further discussion
- on <code>@index</code> values.</p>
-
- <p>Keys in a <tref>node object</tref> that are not
- <tref title="keyword">keywords</tref> MAY expand to an <tref>absolute IRI</tref>
- using the <tref>active context</tref>. The values associated with keys that expand
- to an <tref>absolute IRI</tref> MUST be one 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>value object</tref>,</li>
- <li><tref>list object</tref>,</li>
- <li><tref>set object</tref>,</li>
- <li>an <tref>array</tref> of zero or more of the possibilities above,</li>
- <li>a <tref>language map</tref>, or </li>
- <li>an <tref>index map</tref></li>
- </ul>
- </section>
-
- <section class="normative">
- <h2>Value Objects</h2>
-
- <p>A <tdef>value object</tdef> is used to explicitly associate a type or a
- language with a value to create a <tref>typed value</tref> or a <tref>language-tagged
- string</tref>.</p>
-
- <p>A <tref>value object</tref> MUST be a <tref>JSON object</tref> containing the
- <code>@value</code> key. It MAY also contain a <code>@type</code>,
- a <code>@language</code>, an <code>@index</code>, or an <code>@context</code> key but MUST NOT contain
- both a <code>@type</code> and a <code>@language</code> key at the same time.
- A <tref>value object</tref> MUST NOT contain any other keys that expand to an
- <tref>absolute IRI</tref> or <tref>keyword</tref>.</p>
-
- <p>The value associated with the <code>@value</code> key MUST be either a
- <tref>string</tref>, a <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>, a <tref>relative 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>
-
- <p>The value associated with the <code>@index</code> key MUST be a
- <tref>string</tref>.</p>
-
- <p>See <a class="sectionRef" href="#typed-values"></a> and
- <a class="sectionRef" href="#string-internationalization"></a>
- for more information on <tref title="value object">value objects</tref>.</p>
- </section>
-
- <section class="normative">
- <h2>Lists and Sets</h2>
-
- <p>A <tref>list</tref> represents an <em>ordered</em> set of values. A set
- 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.
- However, it is very helpful when used within the context of a document. Values
- of terms associated with a <code>@set</code> or <code>@list</code> container
- will always be represented in the form of an <tref>array</tref> when a document
- is processed—even if there is just a single value that would otherwise be optimized to
- 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 a
- deterministic form.</p>
-
- <p>A <tdef>list object</tdef> MUST be a <tref>JSON object</tref> that contains no
- keys that expand to an <tref>absolute IRI</tref> or <tref>keyword</tref> other
- than <code>@list</code>, <code>@context</code>, and <code>@index</code>.</p>
-
- <p>A <tdef>set object</tdef> MUST be a <tref>JSON object</tref> that contains no
- keys that expand to an <tref>absolute IRI</tref> or <tref>keyword</tref> other
- than <code>@list</code>, <code>@context</code>, and <code>@index</code>.
- Please note that the <code>@index</code> key will be ignored when being processed.</p>
-
- <p>In both cases, the value associated with the keys <code>@list</code> and <code>@set</code>
- MUST be one of the following types:</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>value object</tref>, or</li>
- <li>an <tref>array</tref> of zero or more of the above possibilities</li>
- </ul>
-
- <p>See <a class="sectionRef" href="#sets-and-lists"></a> for further discussion on sets and lists.</p>
- </section>
-
- <section class="normative">
- <h2>Language Maps</h2>
-
- <p>A <tdef>language map</tdef> is used to associate a language with a value in a
- way that allows easy programmatic access. A <tref>language map</tref> may be
- used as a term value within a <tref>node object</tref> if the term is defined
- with <code>@container</code> set to <code>@language</code>. The keys of a
- <tref>language map</tref> MUST be <tref title="string">strings</tref> representing
- [[BCP47]] language codes with and the values MUST be any of the following types:</p>
-
- <ul>
- <li><tref>null</tref>,</li>
- <li><tref>string</tref>, or</li>
- <li>an <tref>array</tref> of zero or more of the above possibilities</li>
- </ul>
-
- <p>See <a class="sectionRef" href="#string-internationalization"></a> for further discussion
- on language maps.</p>
- </section>
-
- <section class="normative">
- <h2>Index Maps</h2>
-
- <p>An <tdef>index map</tdef> allows keys that have no semantic meaning,
- but should be preserved regardless, to be used in JSON-LD documents.
- An <tref>index map</tref> may
- be used as a <tref>term</tref> value within a <tref>node object</tref> if the
- term is defined with <code>@container</code> set to <code>@index</code>.
- The values of the members of an <tref>index map</tref> MUST be one
- of the following types:</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>value object</tref>,</li>
- <li><tref>list object</tref>,</li>
- <li><tref>set object</tref>,</li>
- <li>an <tref>array</tref> of zero or more of the above possibilities</li>
- </ul>
-
- <p>See <a class="sectionRef" href="#data-indexing"></a> for further information on this topic.</p>
- </section>
-
-<section class="normative">
- <h2>Context Definitions</h2>
-
- <p>A <tdef>context definition</tdef> defines a <tref>local context</tref> in a
- <tref>node object</tref>.</p>
-
- <p>A <tref>context definition</tref> MUST be a <tref>JSON object</tref> whose
- keys MUST either be <tref title="term">terms</tref>,
- <tref title="compact IRI">compact IRIs</tref>, <tref title="absolute IRI">absolute IRIs</tref>,
- or the <tref title="keyword">keywords</tref> <code>@language</code>, <code>@base</code>,
- and <code>@vocab</code>.</p>
-
- <p>If the <tref>context definition</tref> has a <code>@language</code> key,
- its value MUST have the lexical form described in [[!BCP47]] or be <tref>null</tref>.</p>
-
- <p>If the <tref>context definition</tref> has a <code>@base</code> key,
- its value MUST be an <tref>absolute IRI</tref> or <tref>null</tref>.</p>
-
- <p class="issue atrisk" data-number="223" title="Feature at risk">This feature is
- at risk as the fact that a document may have multiple base IRIs is potentially
- confusing for developers. It is also being discussed whether relative IRIs
- are allowed as values of <code>@base</code> or whether the empty string
- should be used to explicitly specify that there isn't a base IRI, which
- could be used to ensure that relative IRIs remain relative when expanding.</p>
-
- <p>If the <tref>context definition</tref> has a <code>@vocab</code> key,
- its value MUST be a <tref>absolute IRI</tref>, a <tref>compact IRI</tref>,
- a <tref>term</tref>, or <tref>null</tref>.</p>
-
- <p>The value of keys that are not <tref title="keyword">keywords</tref> MUST be either an
- <tref>absolute IRI</tref>, a <tref>compact IRI</tref>, a <tref>term</tref>,
- a <tref>blank node identifier</tref>, a <tref>keyword</tref>, <tref>null</tref>,
- or an <tref>expanded term definition</tref>.</p>
-
- <p>An <tref>expanded term definition</tref> is used to describe the mapping
- between a <tref>term</tref> and its expanded identifier, as well as other
- properties of the value associated with the <tref>term</tref> when it is
- used as key in a <tref>node object</tref>.</p>
-
- <p>An <tref>expanded term definition</tref> MUST be a <tref>JSON object</tref>
- composed of zero or more keys from <code>@id</code>, <code>@reverse</code>,
- <code>@type</code>, <code>@language</code> or <code>@container</code>. An
- <tref>expanded term definition</tref> SHOULD NOT contain any other keys.</p>
-
- <p>If an <tref>expanded term definition</tref> has an <code>@reverse</code> member,
- <code>@id</code>, <code>@type</code>, and <code>@language</code> are not allowed.
- If an <code>@container</code> member exists, its value MUST be <tref>null</tref>
- or <code>@index</code>.</p>
-
- <p>If the term being defined is not a <tref>compact IRI</tref> or
- <tref>absolute IRI</tref> and the <tref>active context</tref> does not have an
- <code>@vocab</code> mapping, the <tref>expanded term definition</tref> MUST
- include the <code>@id</code> key.</p>
-
- <p>If the <tref>expanded term definition</tref> contains the <code>@id</code>
- <tref>keyword</tref>, its value MUST be <tref>null</tref>, an <tref>absolute IRI</tref>,
- a <tref>blank node identifier</tref>, a <tref>compact IRI</tref>, or a <tref>term</tref>.</p>
-
- <p>If the <tref>expanded term definition</tref> contains the <code>@type</code>
- <tref>keyword</tref>, its value MUST be an <tref>absolute IRI</tref>, a
- <tref>compact IRI</tref>, a <tref>blank node identifier</tref>, a <tref>term</tref> or
- the <tref>active context</tref>, <tref>null</tref>, or the one of the
- <tref title="keyword">keywords</tref> <code>@id</code> or <code>@vocab</code>.</p>
-
- <p>If the <tref>expanded term definition</tref> contains the <code>@language</code> <tref>keyword</tref>,
- its value MUST have the lexical form described in [[!BCP47]] or be <tref>null</tref>.</p>
-
- <p>If the <tref>expanded term definition</tref> contains the <code>@container</code>
- <tref>keyword</tref>, its value MUST be either <code>@list</code>, <code>@set</code>,
- <code>@language</code>, <code>@index</code>, or be <tref>null</tref>. If the value
- is <code>@language</code>, when the <tref>term</tref> is used outside of the
- <code>@context</code>, the associated value MUST be a <tref>language map</tref>.
- If the value is <code>@index</code>, when the <tref>term</tref> is used outside of
- the <code>@context</code>, the associated value MUST be an
- <tref>index map</tref>.</p>
-
- <p><tref title="term">Terms</tref> MUST NOT be used in a circular manner. That is,
- the definition of a term cannot depend on the definition of another term if that other
- term also depends on the first term.</p>
-
- <p>See <a class="sectionRef" href="#the-context"></a> for further discussion on contexts.</p>
-</section>
-
-</section>
-
-<section class="appendix normative">
- <h2>Relationship to RDF</h2>
-
- <p>The RDF data model, as outlined in [[RDF11-CONCEPTS]], is an abstract syntax for
- representing a directed graph of information. It is a subset of
- <tref title="JSON-LD data model">JSON-LD's data model</tref> with a few
- additional constraints. The differences between the two data models are:</p>
-
- <ul>
- <li>In JSON-LD <tref title="graph name">graph names</tref> can be
- <tref title="IRI">IRIs</tref> or <tref title="blank node">blank nodes</tref>
- whereas in RDF graph names have to be <tref title="IRI">IRIs</tref>.</li>
- <li>In JSON-LD <tref title="property">properties</tref> can be
- <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 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>
- (<tref title="typed value">typed values</tref>) or <em>language-tagged strings</em>
- (<tref title="language-tagged string">language-tagged strings</tref>) whereas
- JSON-LD also supports JSON's native data types, i.e., <tref title="number">number</tref>,
- <tref title="string">strings</tref>, and the boolean values <tref>true</tref>
- and <tref>false</tref>. The JSON-LD Processing Algorithms and API specification [[JSON-LD-API]]
- defines the conversion rules between JSON's native data types and RDF's counterparts to
- allow full round-tripping.</li>
-
- </ul>
-
- <p>Summarized these differences mean that JSON-LD is capable of serializing any RDF
- graph or dataset and most, but not all, JSON-LD documents can be transformed to RDF.
- A complete description of the algorithms to convert from RDF to JSON-LD and from
- JSON-LD to RDF is included in the JSON-LD Processing Algorithms and API specification
- [[JSON-LD-API]].</p>
-
- <p>Even though JSON-LD serializes RDF datasets, it can also be used as a RDF graph source.
- In that case, a consumer MUST only use the default graph and ignore all named graphs.
- This allows servers to expose data in, e.g., both Turtle and JSON-LD using content
- negotiation.</p>
-
- <p class="note">Publishers supporting both dataset and graph syntaxes have to ensure that
- the primary data is stored in the default graph to enable consumers that do not support
- datasets to process the information.</p>
-
- <section class="informative">
- <h3>Transformation from JSON-LD to RDF</h3>
-
- <p>The process of turning a JSON-LD document depends on executing the
- algorithms defined in
- <cite><a href="../json-ld-api/#rdf-conversion-algorithms">RDF Conversion Algorithms</a></cite>
- in the JSON-LD Processing Algorithms and API specification [[JSON-LD-API]].
- It is beyond the scope of this document to detail these algorithms any further,
- but a summary of the necessary operations is provided to illustrate the process.</p>
-
- <p>The procedure involves the following steps:</p>
-
- <ol>
- <li>Expand the JSON-LD document, removing any context; this ensures
- that properties, types, and values are given their full representation
- as <tref title="IRI">IRIs</tref> and expanded values. Expansion
- is discussed further in <a class="sectionRef" href="#expanded-document-form"></a>.</li>
- <li>Flatten the document, which turns the document into an array of
- <tref title="node object">node objects</tref>. Flattening is discussed
- further in <a class="sectionRef" href="#flattened-document-form"></a>.</li>
- <li>Turn each <tref>node object</tref> into a series of
- <tref href="http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple">RDF triples</tref>.</li>
- </ol>
-
- <p>For example, consider the following JSON-LD document in compact form:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Sample JSON-LD document">
- <!--
- {
- "@context": {
- "name": "http://xmlns.com/foaf/0.1/name",
- "knows": "http://xmlns.com/foaf/0.1/knows"
- },
- "@id": "http://me.markus-lanthaler.com/",
- "name": "Markus Lanthaler",
- "knows": [
- {
- "@id": "http://manu.sporny.org/",
- "name": "Manu Sporny"
- },
- {
- "name": "Dave Longley"
- }
- ]
- }
- -->
- </pre>
-
- <p>Running the JSON-LD Expansion and Flattening algorithms against the
- JSON-LD input document in the example above would result in the
- following output:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Flattened and expanded form for the previous example">
- <!--
- [
- {
- "@id": "_:b0",
- "http://xmlns.com/foaf/0.1/name": "Dave Longley"
- },
- {
- "@id": "http://manu.sporny.org/",
- "http://xmlns.com/foaf/0.1/name": "Manu Sporny"
- },
- {
- "@id": "http://me.markus-lanthaler.com/",
- "http://xmlns.com/foaf/0.1/name": "Markus Lanthaler",
- "http://xmlns.com/foaf/0.1/knows": [
- { "@id": "http://manu.sporny.org/" },
- { "@id": "_:b0" }
- ]
- }
- ]
- -->
- </pre>
-
- <p>Transforming this to RDF now is a straightforward process of turning
- each <tref>node object</tref> into one or more RDF triples. This can be
- expressed in Turtle as follows:</p>
-
- <pre class="example" data-transform="updateExample"
- title="Turtle representation of expanded/flattend document">
- <!--
- _:b0 <http://xmlns.com/foaf/0.1/name> "Dave Longley" .
-
- <http://manu.sporny.org/> <http://xmlns.com/foaf/0.1/name> "Manu Sporny" .
-
- <http://me.markus-lanthaler.com/> <http://xmlns.com/foaf/0.1/name> "Markus Lanthaler" ;
- <http://xmlns.com/foaf/0.1/knows> <http://manu.sporny.org/>, _:b0 .
- -->
- </pre>
-
- <p>The process of turning RDF into JSON-LD can be thought of as the
- inverse of this last step, creating an expanded JSON-LD document closely
- matching the triples from RDF, using a single <tref>node object</tref>
- for all triples having a common subject, and a single <tref>property</tref>
- for those triples also having a common predicate.</p>
- </section>
-</section>
-
-<section class="appendix informative">
- <h2>Relationship to Other Linked Data Formats</h2>
-
- <p>The JSON-LD examples below demonstrate how JSON-LD can be used to
- express semantic data marked up in other linked data formats such as Turtle,
- RDFa, Microformats, and Microdata. These sections are merely provided as
- evidence that JSON-LD is very flexible in what it can express across different
- <tref>Linked Data</tref> approaches.</p>
-
- <section class="informative">
- <h3>Turtle</h3>
-
- <p>The following are examples of converting RDF expressed in Turtle [[TURTLE]]
- into JSON-LD.</p>
-
- <section>
- <h4>Prefix definitions</h4>
-
- <p>The JSON-LD context has direct equivalents for the Turtle
- <code>@prefix</code> declaration:</p>
-
- <pre class="example" data-transform="updateExample"
- title="A set of statements serialized in Turtle">
- <!--
- @prefix foaf: <http://xmlns.com/foaf/0.1/> .
-
- <http://manu.sporny.org/i/public> a foaf:Person;
- foaf:name "Manu Sporny";
- foaf:homepage <http://manu.sporny.org/> .
- -->
- </pre>
-
- <pre class="example" data-transform="updateExample"
- title="The same set of statements serialized in JSON-LD">
- <!--
- {
- "@context":
- {
- "foaf": "http://xmlns.com/foaf/0.1/"
- },
- "@id": "http://manu.sporny.org/i/public",
- "@type": "foaf:Person",
- "foaf:name": "Manu Sporny",
- "foaf:homepage": { "@id": "http://manu.sporny.org/" }
- }
- -->
- </pre>
- </section>
-
- <section>
- <h4>Embedding</h4>
-
- <p>Both Turtle and JSON-LD allow embedding, although Turtle only allows embedding of
- <tref title="blank node">blank nodes</tref>.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Embedding in Turtle">
- <!--
- @prefix foaf: <http://xmlns.com/foaf/0.1/> .
-
- <http://manu.sporny.org/i/public>
- a foaf:Person;
- foaf:name "Manu Sporny";
- foaf:knows [ a foaf:Person; foaf:name "Gregg Kellogg" ] .
- -->
- </pre>
-
- <pre class="example" data-transform="updateExample"
- title="Same embedding example in JSON-LD">
- <!--
- {
- "@context":
- {
- "foaf": "http://xmlns.com/foaf/0.1/"
- },
- "@id": "http://manu.sporny.org/i/public",
- "@type": "foaf:Person",
- "foaf:name": "Manu Sporny",
- "foaf:knows":
- {
- "@type": "foaf:Person",
- "foaf:name": "Gregg Kellogg"
- }
- }
- -->
- </pre>
- </section>
-
- <section>
- <h4>Conversion of native data types</h4>
-
- <p>In JSON-LD numbers and boolean values are native data types. While Turtle
- has a shorthand syntax to express such values, RDF's abstract syntax requires
- that numbers and boolean values are represented as typed literals. Thus,
- to allow full round-tripping, the JSON-LD Processing Algorithms and API specification [[JSON-LD-API]]
- defines conversion rules between JSON-LD's native data types and RDF's
- counterparts. <tref title="number">Numbers</tref> without fractions are
- converted to <code>xsd:integer</code>-typed literals, numbers with fractions
- to <code>xsd:double</code>-typed literals and the two boolean values
- <tref>true</tref> and <tref>false</tref> to a <code>xsd:boolean</code>-typed
- literal. All typed literals are in canonical lexical form.</p>
-
- <pre class="example" data-transform="updateExample"
- title="JSON-LD using native data types for numbers and boolean values">
- <!--
- {
- "@context":
- {
- "ex": "http://example.com/vocab#"
- },
- "@id": "http://example.com/",
- "ex:numbers": [ 14, 2.78 ],
- "ex:booleans": [ true, false ]
- }
- -->
- </pre>
-
- <pre class="example" data-transform="updateExample"
- title="Same example in Turtle using typed literals">
- <!--
- @prefix ex: <http://example.com/vocab#> .
- @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
-
- <http://example.com/>
- ex:numbers "14"^^xsd:integer, "2.78E0"^^xsd:double ;
- ex:booleans "true"^^xsd:boolean, "false"^^xsd:boolean .
- -->
- </pre>
-
- </section>
-
- <section>
- <h4>Lists</h4>
- <p>Both JSON-LD and Turtle can represent sequential lists of values.</p>
-
- <pre class="example" data-transform="updateExample"
- title="A list of values in Turtle">
- <!--
- @prefix foaf: <http://xmlns.com/foaf/0.1/> .
-
- <http://example.org/people#joebob> a foaf:Person;
- foaf:name "Joe Bob";
- foaf:nick ( "joe" "bob" "jaybee" ) .
- -->
- </pre>
-
- <pre class="example" data-transform="updateExample"
- title="Same example with a list of values in JSON-LD">
- <!--
- {
- "@context":
- {
- "foaf": "http://xmlns.com/foaf/0.1/"
- },
- "@id": "http://example.org/people#joebob",
- "@type": "foaf:Person",
- "foaf:name": "Joe Bob",
- "foaf:nick":
- {
- "@list": [ "joe", "bob", "jaybee" ]
- }
- }
- -->
- </pre>
- </section>
- </section>
-
- <section class="informative">
- <h3>RDFa</h3>
-
- <p>The following example describes three people with their respective names and
- homepages in RDFa [[RDFA-CORE]].</p>
-
- <pre class="example" data-transform="updateExample"
- title="RDFa fragment that describes three people">
- <!--
- <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>
- </li>
- <li ****typeof="foaf:Person"****>
- <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>
- </li>
- </ul>
- </div>
- -->
- </pre>
-
- <p>An example JSON-LD implementation using a single <tref>context</tref> is
- described below.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Same description in JSON-LD (context shared among node objects)">
- <!--
- {
- "@context":
- {
- "foaf": "http://xmlns.com/foaf/0.1/"
- },
- "@graph":
- [
- {
- "@type": "foaf:Person",
- "foaf:homepage": "http://example.com/bob/",
- "foaf:name": "Bob"
- },
- {
- "@type": "foaf:Person",
- "foaf:homepage": "http://example.com/eve/",
- "foaf:name": "Eve"
- },
- {
- "@type": "foaf:Person",
- "foaf:homepage": "http://example.com/manu/",
- "foaf:name": "Manu"
- }
- ]
- }
- -->
- </pre>
- </section>
-
- <section class="informative">
- <h3>Microformats</h3>
-
- <p>The following example uses a simple Microformats hCard example to express
- how Microformats [[MICROFORMATS]] are represented in JSON-LD.</p>
-
- <pre class="example" data-transform="updateExample"
- title="HTML fragment with a simple Microformats hCard">
- <!--
- <div class="vcard">
- <a class="url fn" href="http://tantek.com/">Tantek Çelik</a>
- </div>
- -->
- </pre>
-
- <p>The representation of the hCard expresses the Microformat terms in the
- <tref>context</tref> and uses them directly for the <code>url</code> and <code>fn</code>
- properties. Also note that the Microformat to JSON-LD processor has
- generated the proper URL type for <code>http://tantek.com/</code>.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Same hCard representation in JSON-LD">
- <!--
- {
- "@context":
- {
- "vcard": "http://microformats.org/profile/hcard#vcard",
- "url":
- {
- "@id": "http://microformats.org/profile/hcard#url",
- "@type": "@id"
- },
- "fn": "http://microformats.org/profile/hcard#fn"
- },
- "@type": "vcard",
- "url": "http://tantek.com/",
- "fn": "Tantek Çelik"
- }
- -->
- </pre>
- </section>
-
- <section class="informative">
- <h3>Microdata</h3>
-
- <p>The HTML Microdata [[MICRODATA]] example below expresses book information as
- a Microdata Work item.</p>
-
- <pre class="example" data-transform="updateExample"
- title="HTML fragments that describes a book using microdata">
- <!--
- <dl itemscope
- itemtype="http://purl.org/vocab/frbr/core#Work"
- itemid="http://purl.oreilly.com/works/45U8QJGZSQKDH8N">
- <dt>Title</dt>
- <dd><cite itemprop="http://purl.org/dc/terms/title">Just a Geek</cite></dd>
- <dt>By</dt>
- <dd><span itemprop="http://purl.org/dc/terms/creator">Wil Wheaton</span></dd>
- <dt>Format</dt>
- <dd itemprop="http://purl.org/vocab/frbr/core#realization"
- itemscope
- itemtype="http://purl.org/vocab/frbr/core#Expression"
- itemid="http://purl.oreilly.com/products/9780596007683.BOOK">
- <link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/BOOK">
- Print
- </dd>
- <dd itemprop="http://purl.org/vocab/frbr/core#realization"
- itemscope
- itemtype="http://purl.org/vocab/frbr/core#Expression"
- itemid="http://purl.oreilly.com/products/9780596802189.EBOOK">
- <link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/EBOOK">
- Ebook
- </dd>
- </dl>
- -->
- </pre>
-
- <p>Note that the JSON-LD representation of the Microdata information stays
- true to the desires of the Microdata community to avoid contexts and
- instead refer to items by their full <tref>IRI</tref>.</p>
-
- <pre class="example" data-transform="updateExample"
- title="Same book description in JSON-LD (avoiding contexts)">
- <!--
- [
- {
- "@id": "http://purl.oreilly.com/works/45U8QJGZSQKDH8N",
- "@type": "http://purl.org/vocab/frbr/core#Work",
- "http://purl.org/dc/terms/title": "Just a Geek",
- "http://purl.org/dc/terms/creator": "Whil Wheaton",
- "http://purl.org/vocab/frbr/core#realization":
- [
- "http://purl.oreilly.com/products/9780596007683.BOOK",
- "http://purl.oreilly.com/products/9780596802189.EBOOK"
- ]
- },
- {
- "@id": "http://purl.oreilly.com/products/9780596007683.BOOK",
- "@type": "http://purl.org/vocab/frbr/core#Expression",
- "http://purl.org/dc/terms/type": "http://purl.oreilly.com/product-types/BOOK"
- },
- {
- "@id": "http://purl.oreilly.com/products/9780596802189.EBOOK",
- "@type": "http://purl.org/vocab/frbr/core#Expression",
- "http://purl.org/dc/terms/type": "http://purl.oreilly.com/product-types/EBOOK"
- }
- ]
- -->
- </pre>
- </section>
-</section>
-
-<section class="appendix normative">
- <h2>IANA Considerations</h2>
-
- <p>This section is included for community review and will be submitted to the
- Internet Engineering Steering Group (IESG) as part of the Last Call announcement
- for this specification.</p>
-
- <h3>application/ld+json</h3>
- <dl>
- <dt>Type name:</dt>
- <dd>application</dd>
- <dt>Subtype name:</dt>
- <dd>ld+json</dd>
- <dt>Required parameters:</dt>
- <dd>None</dd>
- <dt>Optional parameters:</dt>
- <dd>
- <dl>
- <dt><code>profile</code></dt>
- <dd>
- <p>A whitespace-separated list of IRIs identifying specific constraints
- or conventions that apply to a JSON-LD document. A profile MUST NOT change
- the semantics of the resource representation when processed without profile
- knowledge, so that clients both with and without knowledge of a profiled
- resource can safely use the same representation. The <code>profile</code>
- parameter MAY also be used by clients to express their preferences in the
- content negotiation process. It is RECOMMENDED that profile IRIs are
- dereferenceable and provide useful documentation at that IRI. For more
- information and background please refer to [[RFC6906]].</p>
- <p>This specification defines four values for the <code>profile</code> parameter.
- To request or specify Expanded JSON-LD document form, the IRI
- <code>http://www.w3.org/ns/json-ld#expanded</code> SHOULD be used.
- To request or specify Expanded, Flattened JSON-LD document form, the IRI
- <code>http://www.w3.org/ns/json-ld#expanded-flattened</code> SHOULD
- be used. To request or specify Compacted JSON-LD document form, the IRI
- <code>http://www.w3.org/ns/json-ld#compacted</code> SHOULD be used.
- To request or specify Compacted, Flattened JSON-LD document form, the IRI
- <code>http://www.w3.org/ns/json-ld#compacted-flattened</code> SHOULD be used.
- Please note that, according [[HTTP11]], the value of the <code>profile</code>
- parameter has to be enclosed in quotes (<code>"</code>) because it contains
- special characters and, in some cases, whitespace.</p>
- </dd>
- </dl>
- </dd>
- <dt>Encoding considerations:</dt>
- <dd>See RFC 6839, section 3.1.</dd>
- <dt>Security considerations:</dt>
- <dd>Since JSON-LD is intended to be a pure data exchange format for
- directed graphs, the serialization SHOULD NOT be passed through a
- code execution mechanism such as JavaScript's <code>eval()</code>
- function to be parsed.<br/>
- JSON-LD contexts that are loaded from the Web over non-secure connections,
- such as HTTP, run the risk of modifying the JSON-LD
- <tref>active context</tref> in a way that could compromise security. It
- is advised that any application that depends on a remote context for mission
- critical purposes vet and cache the remote context before allowing the
- system to use it.<br />
- Given that JSON-LD allows the substitution of long IRIs with short terms,
- JSON-LD documents may expand considerably when processed and, in the worst case,
- the resulting data might consume all of the recipient's resources. Applications
- should treat any data with due skepticism.
- </dd>
- <dt>Interoperability considerations:</dt>
- <dd>Not Applicable</dd>
- <dt>Published specification:</dt>
- <dd>http://www.w3.org/TR/json-ld</dd>
- <dt>Applications that use this media type:</dt>
- <dd>Any programming environment that requires the exchange of
- directed graphs. Implementations of JSON-LD have been created for
- JavaScript, Python, Ruby, PHP, and C++.
- </dd>
- <dt>Additional information:</dt>
- <dd>
- <dl>
- <dt>Magic number(s):</dt>
- <dd>Not Applicable</dd>
- <dt>File extension(s):</dt>
- <dd>.jsonld</dd>
- <dt>Macintosh file type code(s):</dt>
- <dd>TEXT</dd>
- </dl>
- </dd>
- <dt>Person & email address to contact for further information:</dt>
- <dd>Manu Sporny <msporny@digitalbazaar.com></dd>
- <dt>Intended usage:</dt>
- <dd>Common</dd>
- <dt>Restrictions on usage:</dt>
- <dd>None</dd>
- <dt>Author(s):</dt>
- <dd>Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Niklas Lindström</dd>
- <dt>Change controller:</dt>
- <dd>W3C</dd>
- </dl>
-
- <p>Fragment identifiers used with <a href="#application-ld-json">application/ld+json</a>
- are treated as in RDF syntaxes, as per
- <cite><a href="http://www.w3.org/TR/rdf11-concepts/#section-fragID">RDF 1.1 Concepts and Abstract Syntax</a></cite>
- [[RDF11-CONCEPTS]].</p>
-</section>
-
-<section class="appendix informative">
- <h2>Acknowledgements</h2>
-
- <p>The authors would like to extend a deep appreciation and the most sincere
- thanks to Mark Birbeck, who contributed foundational concepts
- to JSON-LD via his work on RDFj. JSON-LD uses a number of core concepts
- introduced in RDFj, such as the context as a mechanism to provide an
- environment for interpreting JSON data. Mark had also been very involved in
- the work on RDFa as well. RDFj built upon that work. JSON-LD exists
- because of the work and ideas he started nearly a decade ago in 2004.</p>
-
- <p>A large amount of thanks goes out to the JSON-LD Community Group
- participants who worked through many of the technical issues on the mailing
- list and the weekly telecons - of special mention are François Daoust,
- Stéphane Corlosquet, Lin Clark, and Zdenko 'Denny' Vrandečić.</p>
-
- <p>The work of David I. Lehn and Mike Johnson are appreciated for
- reviewing, and performing several early implementations
- of the specification. Thanks also to Ian Davis for this work on RDF/JSON.</p>
-
- <p>Thanks to the following individuals, in order of their first name, for
- their input on the specification: Adrian Walker, Alexandre Passant,
- Andy Seaborne, Ben Adida, Blaine Cook, Bradley Allen, Brian Peterson,
- Bryan Thompson, Conal Tuohy, Dan Brickley, Danny Ayers, Daniel Leja,
- Dave Reynolds, David I. Lehn, David Wood, Dean Landolt, Ed Summers, elf Pavlik,
- Eric Prud'hommeaux, Erik Wilde, Fabian Christ, Jon A. Frost, Gavin Carothers,
- Glenn McDonald, Guus Schreiber, Henri Bergius, Jose María Alvarez Rodríguez,
- Ivan Herman, Jack Moffitt, Josh Mandel, KANZAKI Masahide, Kingsley Idehen,
- Kuno Woudt, Larry Garfield, Mark Baker, Mark MacGillivray, Marko Rodriguez,
- Melvin Carvalho, Nathan Rixham, Olivier Grisel, Paolo Ciccarese, Pat Hayes,
- Patrick Logan, Paul Kuykendall, Pelle Braendgaard, Peter Williams, Pierre-Antoine Champin,
- Richard Cyganiak, Roy T. Fielding, Sandro Hawke, Srecko Joksimovic,
- Stephane Fellah, Steve Harris, Ted Thibodeau Jr., Thomas Steiner, Tim Bray,
- Tom Morris, Tristan King, Sergio Fernández, Werner Wilms, and William Waites.</p>
-</section>
-
-</body>
-</html>
Binary file spec/latest/json-ld-syntax/linked-data-graph.dia has changed
Binary file spec/latest/json-ld-syntax/linked-data-graph.png has changed
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/spec/latest/json-ld/index.html Thu Mar 28 15:14:23 2013 +0100
@@ -0,0 +1,3712 @@
+<!DOCTYPE html>
+<html>
+<head>
+<title>JSON-LD 1.0</title>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
+<script type="text/javascript" src="../respec-w3c-common.js" class="remove"></script>
+<script type="text/javascript" src="../respec-w3c-extensions.js" class="remove"></script>
+<script type="text/javascript" class="remove">
+//<![CDATA[
+ var respecConfig = {
+ // extend the bibliography entries
+ "localBiblio": localBibliography,
+
+ doRDFa: "1.1",
+ // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
+ specStatus: "ED",
+ // 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",
+ subtitle: "A JSON-based Serialization for Linked Data",
+
+ // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
+ // and its maturity status
+ previousPublishDate: "2013-02-02",
+ previousMaturity: "CG-FINAL",
+ previousDiffURI: "http://json-ld.org/spec/FCGS/json-ld-syntax/20130222/",
+
+ // if there a publicly available Editor's Draft, this is the link
+ edDraftURI: "http://dvcs.w3.org/hg/json-ld/raw-file/default/spec/latest/json-ld/index.html",
+
+ // if this is a LCWD, uncomment and set the end of its review period
+ // lcEnd: "2009-08-05",
+
+ issueBase: "https://github.com/json-ld/json-ld.org/issues/",
+
+ // if you want to have extra CSS, append them to this list
+ // it is recommended that the respec.css stylesheet be kept
+ // extraCSS: [],
+
+ // editors, add as many as you like
+ // only "name" is required
+ editors: [
+ { name: "Manu Sporny", url: "http://manu.sporny.org/",
+ company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },
+ { name: "Gregg Kellogg", url: "http://greggkellogg.net/",
+ company: "Kellogg Associates", companyURL: "http://kellogg-assoc.com/" },
+ { name: "Markus Lanthaler", url: "http://www.markus-lanthaler.com/",
+ company: "Graz University of Technology", companyURL: "http://www.tugraz.at/" }
+ ],
+
+ // authors, add as many as you like.
+ // This is optional, uncomment if you have authors as well as editors.
+ // only "name" is required. Same format as editors.
+ authors: [
+ { name: "Manu Sporny", url: "http://digitalbazaar.com/",
+ company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/" },
+ { name: "Dave Longley", url: "http://digitalbazaar.com/",
+ company: "Digital Bazaar", companyURL: "http://digitalbazaar.com/"},
+ { name: "Gregg Kellogg", url: "http://greggkellogg.net/",
+ company: "Kellogg Associates", companyURL: "http://kellogg-assoc.com/" },
+ { name: "Markus Lanthaler", url: "http://www.markus-lanthaler.com/",
+ company: "Graz University of Technology", companyURL: "http://www.tugraz.at/" },
+ { name: "Niklas Lindström", url: "http://neverspace.net/" }
+ ],
+
+ // name of the WG
+ wg: "RDF Working Group",
+
+ // URI of the public WG page
+ wgURI: "http://www.w3.org/2011/rdf-wg/",
+
+ // name (with the @w3c.org) of the public mailing to which comments are due
+ wgPublicList: "public-rdf-comments",
+
+ // URI of the patent status for this WG, for Rec-track documents
+ // !!!! IMPORTANT !!!!
+ // This is important for Rec-track documents, do not copy a patent URI from a random
+ // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
+ // Team Contact.
+ wgPatentURI: "http://www.w3.org/2004/01/pp-impl/46168/status",
+ maxTocLevel: 2,
+ preProcess: [ preProc ]
+ // alternateFormats: [ {uri: "diff-20130202.html", label: "diff to previous version"} ]
+ };
+//]]>
+</script>
+<style type="text/css">
+ .diff { font-weight:bold; color:#0a3; }
+ table, thead, tr, td { padding: 5px; border-width: 1px; border-spacing: 0px; border-style: solid; border-collapse: collapse;}
+</style>
+</head>
+
+<body>
+<section id="abstract">
+ <p>JSON has proven to be a highly useful object serialization and messaging
+ format. This specification defines JSON-LD, a JSON-based format to serialize
+ Linked Data. The syntax is designed to not disturb already deployed systems
+ running on JSON, but provide a smooth upgrade path from JSON to JSON-LD.
+ It is primarily intended to be a way to use Linked Data in Web-based
+ programming environments, to build interoperable Web services, and to
+ store Linked Data in JSON-based storage engines.</p>
+</section>
+
+<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 six months.</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">
+ <h1>Introduction</h1>
+
+ <p><tdef>Linked Data</tdef> is a technique for creating a network
+ of inter-connected data across different documents and Web sites. In general,
+ Linked Data has four properties: 1) it uses <tref title="IRI">IRIs</tref>
+ to name things; 2) it uses HTTP <tref title="IRI">IRIs</tref>
+ for those names; 3) the name <tref title="IRI">IRIs</tref>, when dereferenced,
+ provide more information about the thing; and 4) the data expresses links
+ to data on other Web sites. These properties allow data published on the Web
+ to work much like Web pages do today. One can start at one piece of Linked Data,
+ and follow the links to other pieces of data that are hosted on different
+ sites across the Web.</p>
+
+ <p>JSON-LD is a lightweight syntax to serialize <tref>Linked Data</tref> in
+ JSON [[!RFC4627]]. Its design allows existing JSON to be transformed to
+ Linked Data with minimal changes. JSON-LD is primarily intended to be a
+ way to use Linked Data in Web-based programming environments, to build
+ interoperable Web services, and to store Linked Data in JSON-based storage engines. Since
+ JSON-LD is 100% compatible with JSON, the large number of JSON parsers and libraries
+ available today can be reused. In addition to all the features JSON provides,
+ 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 way to disambiguate keys shared among different 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
+ to a <tref>JSON object</tref> on a different site on the Web,</li>
+ <li>the ability to annotate <tref title="string">strings</tref> with their language,</li>
+ <li>a way to associate datatypes with values such as dates and times,</li>
+ <li>and a facility to express one or more directed graphs, such as a social
+ network, in a single document.</li>
+ </ul>
+
+ <p>Developers that require any of the facilities listed above or need to serialize
+ an RDF graph or dataset [[RDF11-CONCEPTS]] in a JSON-based syntax will find
+ JSON-LD of interest. The syntax is designed to not disturb already deployed
+ systems running on JSON, but provide a smooth upgrade path from JSON to
+ JSON-LD. Since the shape of such data varies wildly, JSON-LD features mechanisms
+ to reshape documents into a deterministic structure which simplifies their
+ processing.</p>
+
+ <section class="informative">
+ <h2>How to Read this Document</h2>
+
+ <p>This document is a detailed specification for a serialization of Linked
+ Data in JSON. The document is primarily intended for the following audiences:</p>
+
+ <ul>
+ <li>Software developers who want to encode Linked Data in a variety of
+ programming languages that can use JSON.</li>
+ <li>Software developers who want to convert existing JSON to JSON-LD.</li>
+ <li>Software developers who want to understand the design decisions and
+ language syntax for JSON-LD.</li>
+ <li>Software developers who want to implement processors and APIs for
+ JSON-LD.</li>
+ </ul>
+
+ <p>A companion document, the JSON-LD Processing Algorithms and API specification
+ [[JSON-LD-API]], specifies how to work with JSON-LD at a higher level by
+ providing a standard library interface for common JSON-LD operations. Although that
+ document is not required for understanding and working with JSON-LD, for some
+ readers it will be a better starting point.</p>
+
+ <p>To understand the basics in this specification you must first be familiar with
+ JSON, which is detailed in [[!RFC4627]].</p>
+ </section>
+</section>
+
+<section class="informative">
+ <h1>Design Goals and Rationale</h1>
+
+ <p>JSON-LD satisfies the following design goals:</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>A JSON-LD document 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 serialize directed graphs. This ensures that almost
+ every real world data model can be expressed.</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 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 class="sectionRef" href="#interpreting-json-as-json-ld"></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>
+ </dl>
+</section>
+
+<section class="normative">
+ <h1>Terminology</h1>
+
+ <section class="normative">
+ <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. In contrast to JSON,
+ in JSON-LD the keys in an object must be unique.</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
+ specifically defined (see <a class="sectionRef" 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).</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 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 class="normative">
+ <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
+ <a class="sectionRef" 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 class="sectionRef" 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 class="sectionRef" href="#string-internationalization"></a> and
+ <a class="sectionRef" href="#typed-values"></a>.</dd>
+ <dt><code>@language</code></dt>
+ <dd>Used to specify the natural (human) language for a particular value or the default
+ language of a JSON-LD document. This keyword is described in
+ <a class="sectionRef" 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
+ <a class="sectionRef" 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 <a class="sectionRef" 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 <a class="sectionRef" 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
+ <a class="sectionRef" href="#sets-and-lists"></a>.</dd>
+ <dt><code>@reverse</code></dt>
+ <dd>Used to express reverse properties. This keyword is described in
+ <a class="sectionRef" href="#reverse-properties"></a>.</dd>
+ <dt><code>@index</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 <a class="sectionRef" href="#data-indexing"></a>.</dd>
+ <dt><code>@base</code></dt>
+ <dd>Used to set the base IRI against which <tref title="relative IRI">relative IRIs</tref>
+ are resolved. This keyword is described in <a class="sectionRef" href="#base-iri"></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 <a class="sectionRef" href="#default-vocabulary"></a>.</dd>
+ <dt><code>@graph</code></dt><dd>Used to explicitly label a <tref>JSON-LD graph</tref>.
+ This keyword is described in <a class="sectionRef" 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>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>This specification describes the conformance criteria for JSON-LD documents.
+ This criteria is relevant to authors and authoring tool implementers. As well
+ as sections marked as non-normative, all authoring guidelines, diagrams, examples,
+ and notes in this specification are non-normative. Everything else in this
+ specification is normative.</p>
+
+ <p>A <tref>JSON-LD document</tref> complies with this specification if it follows
+ the normative statements in appendix <a href="#json-ld-grammar"></a>. JSON documents
+ can be interpreted as JSON-LD by following the normative statements in
+ <a class="sectionRef" href="#interpreting-json-as-json-ld"></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 specification have the
+ meaning defined in [[!RFC2119]].</p>
+</section>
+
+<section class="informative">
+ <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">
+ <!--
+ {
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/",
+ "image": "http://manu.sporny.org/images/manu.png"
+ }
+ -->
+ </pre>
+
+ <p>It's obvious to 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.
+ 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
+ tokens 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.</p>
+
+ <p>Leveraging the well-known <a href="http://schema.org/">schema.org vocabulary</a>,
+ the example above could be unambiguously expressed as follows:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Sample JSON-LD document using full IRIs instead of terms">
+ <!--
+ {
+ "****http://schema.org/name****": "Manu Sporny",
+ "****http://schema.org/url****": ****{ "@id": ****"http://manu.sporny.org/" ****}****,
+ "****http://schema.org/image****": ****{ "@id": ****"http://manu.sporny.org/images/manu.png" ****}****
+ }
+ -->
+ </pre>
+
+ <p>In the example above, 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 valid JSON-LD
+ document that is very specific about its data, the document is also overly verbose and difficult
+ to work with for human developers. To address this issue, JSON-LD introduces the notion
+ of a <tref>context</tref> as described in the next section.</p>
+
+ <section class="informative">
+ <h2>The Context</h2>
+
+ <p>Simply speaking, a <tdef>context</tdef> is used to map <tref title="term">terms</tref>, to
+ <tref title="IRI">IRIs</tref>. <tref title="term">Terms</tref> are case sensitive
+ and any valid <tref>string</tref> that is not a reserved JSON-LD <tref>keyword</tref>
+ can be used as a <tref>term</tref>.</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://schema.org/name",
+ "image": {
+ "@id": "http://schema.org/image",
+ "@type": "@id"
+ },
+ "homepage": {
+ "@id": "http://schema.org/url",
+ "@type": "@id"
+ }
+ }****
+ }
+ -->
+ </pre>
+
+ <p>As the <tref>context</tref> above shows, the value of a <tdef>term definition</tdef> can
+ either be a simple string, mapping the <tref>term</tref> to an <tref>IRI</tref>,
+ or a <tref>JSON object</tref>.</p>
+
+ <p>When a <tref>JSON object</tref> is
+ associated with a term, it is called an <tdef>expanded term definition</tdef>.
+ The example above specifies that the values of <code>image</code> and
+ <code>homepage</code> terms are <tref title="IRI">IRIs</tref>.
+ They also allow terms to be used for <a href="#data-indexing">index 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, which is
+ mainly used to associate type or language information with an
+ <tref title="absolute iri">absolute</tref> or <tref>compact IRI</tref>.</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://manu.sporny.org/images/manu.png"
+ }
+ -->
+ </pre>
+
+ <p>The referenced context not only specifies how the terms map to
+ <tref title="IRI">IRIs</tref> in the Schema.org 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 <a class="sectionRef" href="#iris"></a> for more details). This information allows developers
+ to re-use each other's 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>JSON documents can be transformed to JSON-LD without having to be modified by
+ referencing a <tref>context</tref> via an HTTP Link Header
+ as described in <a class="sectionRef" href="#interpreting-json-as-json-ld"></a>. It is also
+ possible to apply a custom context using the JSON-LD API [[JSON-LD-API]].</p>
+
+ <p>In <tref title="JSON-LD document">JSON-LD documents</tref>
+ <tref title="context">contexts</tref> may also be specified in-line.
+ This has the advantage that documents 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://schema.org/name",
+ "image": {
+ "@id": "http://schema.org/image",
+ "@type": "@id"
+ },
+ "homepage": {
+ "@id": "http://schema.org/url",
+ "@type": "@id"
+ }
+ },****
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/",
+ "image": "http://manu.sporny.org/images/manu.png"
+ }
+ -->
+ </pre>
+ </section>
+
+<section class="informative">
+ <h2>IRIs</h2>
+
+ <p><tref title="IRI">IRIs</tref> (Internationalized Resource Identifiers
+ [[!RFC3987]]) are fundamental to <tref>Linked Data</tref> as that is how most
+ <tref title="node">nodes</tref> and <tref title="property">properties</tref>
+ are identified. In JSON-LD, IRIs may be represented as an
+ <tref>absolute IRI</tref> or a <tref>relative IRI</tref>. An
+ <tdef>absolute IRI</tdef> is defined in [[!RFC3987]] as containing a
+ <em>scheme</em> along with <em>path</em> and optional <em>query</em> and
+ <em>fragment</em> segments. A <tdef>relative IRI</tdef> is an IRI
+ that is relative to some other <tref>absolute IRI</tref>.
+ In JSON-LD all <tref title="relative IRI">relative IRIs</tref> are resolved
+ relative to the <tdef>base IRI</tdef> associated with the document.</p>
+
+ <p>A <tref>string</tref> is interpreted as an <tref>IRI</tref> when it is the
+ value of an <code>@id</code> member:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Values of @id are interpreted as IRI">
+ <!--
+ {
+ ...
+ "homepage": { "****@id****": "http://example.com/" }
+ ...
+ }
+ -->
+ </pre>
+
+ <p>Values that are interpreted as <tref title="IRI">IRIs</tref>, can also be
+ expressed as <tref title="relative IRI">relative IRIs</tref>. For example,
+ assuming that the following document is located at
+ <code>http://example.com/about/</code>, the <tref>relative IRI</tref>
+ <code>../</code> would expand to <code>http://example.com/</code> (for more
+ information on where <tref title="relative IRI">relative IRIs</tref> can be
+ used, please refer to appendix <a href="#json-ld-grammar"></a>).</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="IRIs can be relative">
+ <!--
+ {
+ ...
+ "homepage": { "****@id****": "../" }
+ ...
+ }
+ -->
+ </pre>
+
+ <p><tref title="absolute iri">Absolute IRIs</tref> can be expressed directly
+ in the key position like so:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="IRI as a key">
+ <!--
+ {
+ ...
+ "****http://schema.org/name****": "Manu Sporny",
+ ...
+ }
+ -->
+ </pre>
+
+ <p>In the example above, the key <code>http://schema.org/name</code>
+ is interpreted as an <tref>absolute IRI</tref> because it contains a colon
+ (<code>:</code>) and it is neither a <tref>compact IRI</tref> nor a
+ <tref>blank node identifier</tref>.</p>
+
+ <p>Term-to-IRI expansion occurs if the key matches a <tref>term</tref> defined
+ within the <tref>active context</tref>:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Term expansion from context definition">
+ <!--
+ {
+ "****@context****":
+ {
+ "****name****": "****http://schema.org/name****"
+ },
+ "****name****": "Manu Sporny",
+ "status": "trollin'"
+ }
+ -->
+ </pre>
+
+ <p>JSON keys that do not expand to an <tref>IRI</tref>, such as <code>status</code>
+ in the example above, are not Linked Data and thus ignored when processed.</p>
+
+ <p>If type <tref>coercion</tref> rules are specified in the <code>@context</code> for
+ a particular <tref>term</tref> or property IRI, an IRI is generated:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Type coercion">
+ <!--
+ {****
+ "@context":
+ {
+ ...
+ "homepage":
+ {
+ "@id": "http://schema.org/homepage",
+ "@type": "@id"
+ }
+ ...
+ }****
+ ...
+ "homepage": "http://manu.sporny.org/",
+ ...
+ }
+ -->
+ </pre>
+
+ <p>In the example above, even though the value <code>http://manu.sporny.org/</code>
+ is expressed as a JSON <tref>string</tref>, the type <tref>coercion</tref>
+ rules will transform the value into an IRI when generating the
+ <tref>JSON-LD graph</tref>. See <a class="sectionRef" href="#type-coercion"></a> for more
+ details about this feature.</p>
+
+ <p>In summary, <tref title="IRI">IRIs</tref> can be expressed in a variety of
+ different ways in JSON-LD:</p>
+
+ <ol>
+ <li><tref>JSON object</tref> keys that have a <tref>term</tref> mapping in
+ the <tref>active context</tref> expand to an <tref>IRI</tref>
+ (only applies outside of the <tref>context definition</tref>).</li>
+ <li>An <tref>IRI</tref> is generated for the <tref>string</tref> value specified using
+ <code>@id</code> or <code>@type</code>.</li>
+ <li>An <tref>IRI</tref> is generated for the <tref>string</tref> value of any key for which there
+ are <tref>coercion</tref> rules that contain a <code>@type</code> key that is
+ set to a value of <code>@id</code> or <code>@vocab</code>.</li>
+ </ol>
+</section>
+
+<section class="informative">
+ <h2>Node Identifiers</h2>
+
+ <p>To be able to externally reference <tref title="node">nodes</tref>
+ in a <tref title="json-ld graph">graph</tref>, it is important that
+ <tref title="node">nodes</tref> have an identifier. <tref title="IRI">IRIs</tref>
+ are a fundamental concept of <tref>Linked Data</tref>, for
+ <tref title="node">nodes</tref> to be truly linked, dereferencing the
+ identifier should result in a representation of that <tref>node</tref>.
+ This may allow an application to retrieve further information about a
+ <tref>node</tref>.</p>
+
+ <p>In JSON-LD, a <tref>node</tref> is identified using the <code>@id</code>
+ <tref>keyword</tref>:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Identifying a node">
+ <!--
+ {
+ "@context":
+ {
+ ...
+ "name": "http://schema.org/name"
+ },
+ ****"@id": "http://me.markus-lanthaler.com/"****,
+ "name": "Markus Lanthaler",
+ ...
+ }
+ -->
+ </pre>
+
+ <p>The example above contains a <tref>node object</tref> identified by the IRI
+ <code>http://me.markus-lanthaler.com/</code>.</p>
+</section>
+
+<section class="informative">
+<h2>Specifying the Type</h2>
+
+<p>The type of a particular node can be specified using the <code>@type</code>
+ <tref>keyword</tref>. In <tref>Linked Data</tref>, types are uniquely
+ identified with an <tref>IRI</tref>.</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Specifying the type for a node">
+<!--
+{
+...
+ "@id": "http://example.org/places#BrewEats",
+ "****@type****": "****http://schema.org/Restaurant****",
+...
+}
+-->
+</pre>
+
+<p>A node can be assigned more than one type by using an <tref>array</tref>:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Specifying multiple types for a node">
+<!--
+{
+...
+ "@id": "http://example.org/places#BrewEats",
+ "****@type****": ****[ "http://schema.org/Restaurant", "http://schema.org/Brewery" ],****
+...
+}
+-->
+</pre>
+
+<p>The value of a <code>@type</code> key may also be a <tref>term</tref> defined in the <tref>active context</tref>:</p>
+<pre class="example" data-transform="updateExample"
+ title="Using a term to specify the type">
+<!--
+{
+ "@context": {
+ ...
+ ****"Restaurant": "http://schema.org/Restaurant", ****
+ ****"Brewery": "http://schema.org/Brewery"****
+ }
+ "@id": "http://example.org/places#BrewEats",
+ ****"@type": [ "Restaurant", "Brewery" ]****,
+ ...
+}
+-->
+</pre>
+</section>
+</section>
+
+<section class="normative">
+<h1>Advanced Concepts</h1>
+
+<p>JSON-LD has a number of features that provide functionality above and beyond
+ the core functionality described above. The following section describes this
+ advanced functionality in more detail.</p>
+
+<section class="informative">
+ <h2>Base IRI</h2>
+
+ <p class="issue atrisk" data-number="223" title="Feature at risk">This feature is
+ at risk as the fact that a document may have multiple base IRIs is potentially
+ confusing for developers. It is also being discussed whether relative IRIs
+ are allowed as values of <code>@base</code> or whether the empty string
+ should be used to explicitly specify that there isn't a base IRI, which
+ could be used to ensure that relative IRIs remain relative when expanding.</p>
+
+ <p>JSON-LD allows <tref>IRI</tref>s to be specified in a relative form which is
+ resolved against the document base according
+ <cite><a href="http://tools.ietf.org/html/rfc3986#section-5.1">section 5.1 Establishing a Base URI</a></cite>
+ of [[RFC3986]]. The base IRI may be explicitly set with a <tref>context</tref>
+ using the <code>@base</code> keyword.</p>
+
+ <p>For example, if a JSON-LD document was retrieved from <code>http://example.com/document.jsonld</code>,
+ relative IRIs would resolve against that IRI:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Use a relative IRI as node identifier">
+ <!--
+ {
+ "@context": {
+ "label": "http://www.w3.org/2000/01/rdf-schema#label"
+ },
+ ****"@id": ""****,
+ "label": "Just a simple document"
+ }
+ -->
+ </pre>
+
+ <p>This document uses an empty <code>@id</code>, which resolves to the document base.
+ However, if the document is moved to a different location, the <tref>IRI</tref> would change.
+ To prevent this without having to use an <tref>absolute IRI</tref>, a <tref>context</tref>
+ may define a <code>@base</code> mapping, to overwrite the base IRI for the document.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Setting the document base in a document">
+ <!--
+ {
+ "@context": {
+ ****"@base": "http://example.com/document.jsonld"****
+ },
+ "@id": "",
+ "label": "Just a simple document"
+ }
+ -->
+ </pre>
+</section>
+
+<section class="informative">
+ <h2>Default Vocabulary</h2>
+
+ <p>At times, all properties and types may come from the same vocabulary. JSON-LD's
+ <code>@vocab</code> keyword allows an author to set a common prefix to be used
+ for all properties and types that do not match a <tref>term</tref> or are neither
+ a <tref>compact IRI</tref> nor an <tref>absolute IRI</tref> (i.e., they do
+ not contain a colon).</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Using a common vocabulary prefix">
+ <!--
+ {
+ "@context": {
+ ****"@vocab": "http://schema.org/"****
+ }
+ "@id": "http://example.org/places#BrewEats",
+ "@type": ****"Restaurant"****,
+ ****"name"****: "Brew Eats"
+ ...
+ }
+ -->
+ </pre>
+
+ <p>If <code>@vocab</code> is used but certain keys in an
+ <tref title="JSON object">object</tref> should not be expanded using
+ the vocabulary <tref>IRI</tref>, a <tref>term</tref> can be explicitly set
+ to <tref>null</tref> in the <tref>context</tref>. For instance, in the
+ example below the <code>databaseId</code> member would not expand to an
+ <tref>IRI</tref>.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Using the null keyword to ignore data">
+ <!--
+ {
+ "@context":
+ {
+ "@vocab": "http://schema.org/",
+ ****"databaseId": null****
+ },
+ "@id": "http://example.org/places#BrewEats",
+ "@type": "Restaurant",
+ "name": "Brew Eats",
+ ****"databaseId"****: "23987520"
+ }
+ -->
+ </pre>
+</section>
+
+<section class="informative">
+ <h2>Compact IRIs</h2>
+
+ <p>A <tdef>compact IRI</tdef> is a way of expressing an <tref>IRI</tref>
+ using a <em>prefix</em> and <em>suffix</em> separated by a colon (<code>:</code>).
+ The <tdef>prefix</tdef> is a <tref>term</tref> taken from the
+ <tref>active context</tref> and is a short string identifying a
+ particular <tref>IRI</tref> in a JSON-LD document. 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 <tref>IRI</tref>
+ <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 to the IRI
+ <code>http://xmlns.com/foaf/0.1/name</code>.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Prefix expansion">
+ <!--
+ {
+ "****@context****":
+ {
+ "****foaf****": "****http://xmlns.com/foaf/0.1/****"
+ ...
+ },
+ "@type": "****foaf:Person****"
+ "****foaf:name****": "Dave Longley",
+ ...
+ }
+ -->
+ </pre>
+
+ <p>In the example above, <code>foaf:name</code> expands to the <tref>IRI</tref>
+ <code>http://xmlns.com/foaf/0.1/name</code> and <code>foaf:Person</code> expands
+ to <code>http://xmlns.com/foaf/0.1/Person</code>.</p>
+
+ <p><tref title="prefix">Prefixes</tref> are expanded when the form of the value
+ is a <tref>compact IRI</tref> represented as a <code>prefix:suffix</code>
+ combination, the <em>prefix</em> matches a <tref>term</tref> defined within the
+ <tref>active context</tref>, and the <em>suffix</em> does not begin with two
+ slashes (<code>//</code>). The <tref>compact IRI</tref> is expanded by
+ concatenating the <tref>IRI</tref> mapped to the <em>prefix</em> to the (possibly empty)
+ <em>suffix</em>. If the <em>prefix</em> is not defined in the <tref>active context</tref>,
+ or the suffix begins with two slashes (such as in <code>http://example.com</code>),
+ the value is interpreted as <tref>absolute IRI</tref> instead. If the prefix is an
+ underscore (<code>_</code>), the value is interpreted as <tref>blank node identifier</tref>
+ instead.</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">
+ <!--
+ {
+ "@context":
+ {
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
+ ****"foaf": "http://xmlns.com/foaf/0.1/"****,
+ ****"foaf:homepage"****: { "@type": "@id" },
+ "picture": { "@id": ****"foaf:depiction"****, "@type": "@id" }
+ },
+ "@id": "http://me.markus-lanthaler.com/",
+ "@type": "foaf:Person",
+ "foaf:name": "Markus Lanthaler",
+ "foaf:homepage": "http://www.markus-lanthaler.com/",
+ "picture": "http://twitter.com/account/profile_image/markuslanthaler"
+ }
+ -->
+ </pre>
+</section>
+
+<section class="informative">
+<h2>Typed Values</h2>
+
+<p>
+ A value with an associated type, also known as a
+ <tref>typed value</tref>, is indicated by associating a value with
+ an <tref>IRI</tref> which indicates the value's type. Typed values may be
+ expressed in JSON-LD in three ways:
+</p>
+
+<ol>
+ <li>By utilizing the <code>@type</code> <tref>keyword</tref> when defining
+ a <tref>term</tref> within a <code>@context</code> section.</li>
+ <li>By utilizing a <tref>value object</tref>.</li>
+ <li>By using a native JSON type such as <tref>number</tref>, <tref>true</tref>, or <tref>false</tref>.</li>
+</ol>
+
+<p>The first example uses the <code>@type</code> keyword to associate a
+type with a particular <tref>term</tref> in the <code>@context</code>:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Expanded term definition with type coercion">
+<!--
+{
+ ****"@context":
+ {
+ "modified":
+ {
+ "@id": "http://purl.org/dc/terms/modified",
+ "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+ }
+ },****
+...
+ "@id": "http://example.com/docs/1",
+ "modified": "2010-05-29T14:17:39+02:00",
+...
+}
+-->
+</pre>
+
+<p>The <em>modified</em> key's value above is automatically type coerced to a
+ <em>dateTime</em> value because of the information specified in the
+ <code>@context</code>. A JSON-LD processor will interpret the example above
+ as follows:</p>
+
+<table class="example">
+<thead>
+ <th>Subject</th>
+ <th>Property</th>
+ <th>Value</th>
+ <th>Value Type</th>
+</thead>
+<tbody>
+<tr>
+ <td>http://example.com/docs/1</td>
+ <td>http://purl.org/dc/terms/modified</td>
+ <td>2010-05-29T14:17:39+02:00</td>
+ <td>http://www.w3.org/2001/XMLSchema#dateTime</td>
+</tr>
+</tbody>
+</table>
+
+<p>The second example uses the expanded form of setting the type information
+in the body of a JSON-LD document:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Expanded value with type">
+<!--
+{
+ "@context":
+ {
+ "modified":
+ {
+ "@id": "http://purl.org/dc/terms/modified"
+ }
+ },
+...
+ "modified":
+ ****{
+ "@value": "2010-05-29T14:17:39+02:00",
+ "@type": "http://www.w3.org/2001/XMLSchema#dateTime"
+ }****
+...
+}
+-->
+</pre>
+
+<p>Both examples above would generate the value
+ <code>2010-05-29T14:17:39+02:00</code> with the type
+ <code>http://www.w3.org/2001/XMLSchema#dateTime</code>. Note that it is
+ also possible to use a <tref>term</tref> or a <tref>compact IRI</tref> to
+ express the value of a type.</p>
+
+<p>The <code>@type</code> <tref>keyword</tref> is also used to associate a type
+ with a <tref>node</tref>. The concept of a <tref>node type</tref> and
+ a <tref>value type</tref> are different.</p>
+
+<p>Generally speaking, a <tdef>node type</tdef> specifies the type of thing
+ that is being described, like a person, place, event, or web page. A
+ <tdef>value type</tdef> specifies the data type of a particular value, such
+ as an integer, a floating point number, or a date.</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Example demonstrating the context-sensitivity for @type">
+<!--
+{
+...
+ "@id": "http://example.org/posts#TripToWestVirginia",
+ ****"@type": "http://schema.org/BlogPosting"****, <- This is a node type
+ "modified":
+ {
+ "@value": "2010-05-29T14:17:39+02:00",
+ ****"@type": "http://www.w3.org/2001/XMLSchema#dateTime"**** <- This is a value type
+ }
+...
+}
+-->
+</pre>
+
+<p>The first use of <code>@type</code> associates a <tref>node type</tref>
+ (<code>http://schema.org/BlogPosting</code>) with the <tref>node</tref>,
+ which is expressed using the <code>@id</code> <tref>keyword</tref>.
+ The second use of <code>@type</code> associates a <tref>value type</tref>
+ (<code>http://www.w3.org/2001/XMLSchema#dateTime</code>) with the
+ value expressed using the <code>@value</code> <tref>keyword</tref>. As a
+ general rule, when <code>@value</code> and <code>@type</code> are used in
+ the same <tref>JSON object</tref>, the <code>@type</code>
+ <tref>keyword</tref> is expressing a <tref>value type</tref>.
+ Otherwise, the <code>@type</code> <tref>keyword</tref> is expressing a
+ <tref>node type</tref>. The example above expresses the following data:</p>
+
+<table class="example">
+<thead>
+ <th>Subject</th>
+ <th>Property</th>
+ <th>Value</th>
+ <th>Value Type</th>
+</thead>
+<tbody>
+<tr>
+ <td>http://example.org/posts#TripToWestVirginia</td>
+ <td>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</td>
+ <td>http://schema.org/BlogPosting</td>
+ <td style="text-align:center;">-</td>
+</tr>
+<tr>
+ <td>http://example.org/posts#TripToWestVirginia</td>
+ <td>http://purl.org/dc/terms/modified</td>
+ <td>2010-05-29T14:17:39+02:00</td>
+ <td>http://www.w3.org/2001/XMLSchema#dateTime</td>
+</tr>
+</tbody>
+</table>
+
+</section>
+
+<section class="informative">
+<h2>Type Coercion</h2>
+
+<p>JSON-LD supports the coercion of values to particular data types.
+Type <tdef>coercion</tdef> allows someone deploying JSON-LD to coerce the incoming or
+outgoing values to the proper data type based on a mapping of data type <tref title="IRI">IRIs</tref> to
+<tref title="term">terms</tref>. Using type coercion, value representation is preserved without requiring
+the data type to be specified with each piece of data.</p>
+
+<p>Type coercion is specified within an <tref>expanded term definition</tref>
+ using the <code>@type</code> key. The value of this key expands to an <tref>IRI</tref>.
+ Alternatively, the <tref title="keyword">keywords</tref> <code>@id</code> or <code>@vocab</code> may be used
+ as value to indicate that within the body of a JSON-LD document, a <tref>string</tref> value of a
+ <tref>term</tref> coerced to <code>@id</code> or <code>@vocab</code> is to be interpreted as an
+ <tref>IRI</tref>. The difference between <code>@id</code> and <code>@vocab</code> is how values are expanded
+ to <tref title="absolute IRI">absolute IRIs</tref>. <code>@vocab</code> first tries to expand the value
+ by interpreting it as <tref>term</tref>. If no matching <tref>term</tref> is found in the
+ <tref>active context</tref>, it tries to expand it as <tref>compact IRI</tref> or <tref>absolute IRI</tref>
+ if there's a colon in the value; otherwise, it will expand the value using the
+ <tref title="active context">active context's</tref> vocabulary mapping, if present, or by interpreting it
+ as <tref>relative IRI</tref>. Values coerced to <code>@id</code> in contrast are expanded as
+ <tref>compact IRI</tref> or <tref>absolute IRI</tref> if a colon is present; otherwise, they are interpreted
+ as <tref>relative IRI</tref>.</p>
+
+<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>
+
+<p>The example below demonstrates how a JSON-LD author can coerce values to
+<tref title="typed value">typed values</tref> and <tref title="IRI">IRIs</tref>.</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Expanded term definition with types">
+<!--
+{
+ "@context":
+ {
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "age":
+ ****{
+ "@id": "http://xmlns.com/foaf/0.1/age",
+ "@type": "xsd:integer"
+ }****,
+ "homepage":
+ ****{
+ "@id": "http://xmlns.com/foaf/0.1/homepage",
+ "@type": "@id"
+ }****
+ },
+ "@id": "http://example.com/people#john",
+ "name": "John Smith",
+ "age": ****"41"****,
+ "homepage":
+ ****[
+ "http://personal.example.org/",
+ "http://work.example.com/jsmith/"
+ ]****
+}
+-->
+</pre>
+
+<p>The example shown above would generate the following data.</p>
+
+<table class="example">
+<thead>
+ <th>Subject</th>
+ <th>Property</th>
+ <th>Value</th>
+ <th>Value Type</th>
+</thead>
+<tbody>
+<tr>
+ <td>http://example.com/people#john</td>
+ <td>http://xmlns.com/foaf/0.1/name</td>
+ <td>John Smith</td>
+ <td> </td>
+</tr>
+<tr>
+ <td>http://example.com/people#john</td>
+ <td>http://xmlns.com/foaf/0.1/age</td>
+ <td>41</td>
+ <td>http://www.w3.org/2001/XMLSchema#integer</td>
+</tr>
+<tr>
+ <td rowspan="2">http://example.com/people#john</td>
+ <td rowspan="2">http://xmlns.com/foaf/0.1/homepage</td>
+ <td>http://personal.example.org/</td>
+ <td><tref>IRI</tref></td>
+</tr>
+<tr>
+ <td>http://work.example.com/jsmith/</td>
+ <td><tref>IRI</tref></td>
+</tr>
+</tbody>
+</table>
+
+<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>
+
+<pre class="example" data-transform="updateExample"
+ title="Term definitions using compact and absolute IRIs">
+<!--
+{
+ "@context":
+ {
+ "foaf": "http://xmlns.com/foaf/0.1/",
+ "****foaf:age****":
+ {
+ ****"@id": "http://xmlns.com/foaf/0.1/age"****,
+ "@type": "xsd:integer"
+ },
+ "****http://xmlns.com/foaf/0.1/homepage****":
+ {
+ "@type": "@id"
+ }
+ },
+ "foaf:name": "John Smith",
+ "****foaf:age****": "41",
+ "****http://xmlns.com/foaf/0.1/homepage****":
+ [
+ "http://personal.example.org/",
+ "http://work.example.com/jsmith/"
+ ]
+}
+-->
+</pre>
+
+<p>In this case the <code>@id</code> definition in the term definition is optional.
+ If it does exist, the <tref>compact IRI</tref> or <tref>IRI</tref> representing
+ the term will always be expanded to <tref>IRI</tref> defined by the <code>@id</code>
+ key—regardless of whether a prefix is defined or not.</p>
+
+<p>Type coercion is always performed using the unexpanded value of the key. In the
+ example above, that means that type coercion is done looking for <code>foaf:age</code>
+ in the <tref>active context</tref> and not for the corresponding, expanded
+ <tref>IRI</tref> <code>http://xmlns.com/foaf/0.1/age</code>.</p>
+
+<p class="note">Keys in the context are treated as <tref title="term">terms</tref> for the purpose of
+ expansion and value coercion. At times, this may result in multiple representations for the same expanded IRI.
+ For example, one could specify that <code>dog</code> and <code>cat</code> both expanded to <code>http://example.com/vocab#animal</code>.
+ Doing this could be useful for establishing different type coercion or language specification rules. It also allows a <tref>compact IRI</tref> (or even an
+ absolute <tref>IRI</tref>) to be defined as something else entirely. For example, one could specify that
+ the <tref>term</tref> <code>http://example.org/zoo</code> should expand to
+ <code>http://example.org/river</code>, but this usage is discouraged because it would lead to a
+ great deal of confusion among developers attempting to understand the JSON-LD document.</p>
+
+
+</section>
+
+<section class="informative">
+ <h2>Embedding</h2>
+
+ <p><tdef>Embedding</tdef> is a JSON-LD feature that allows an author to
+ use <tref title="node object">node objects</tref> as
+ <tref>property</tref> values. This is a commonly used mechanism for
+ creating a parent-child relationship between two <tref title="node">nodes</tref>.</p>
+
+ <p>The example shows two nodes related by a property from the first node:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Embedding a node object as property value of another node object">
+ <!--
+ {
+ ...
+ "name": "Manu Sporny",
+ "****knows****":
+ {
+ "****@type****": "****Person****",
+ "****name****": "****Gregg Kellogg****",
+ }
+ ...
+ }
+ -->
+ </pre>
+
+ <p>
+ A <tref>node object</tref>, like the one used above, may be used in
+ any value position in the body of a JSON-LD document.</p>
+</section>
+
+<section class="informative">
+ <h2>Advanced Context Usage</h2>
+
+ <p>Section <a href="#the-context"></a> introduced the basics of what makes
+ JSON-LD work. This section expands on the basic principles of the
+ <tref>context</tref> and demonstrates how more advanced use cases can
+ be achieved using JSON-LD. </p>
+
+ <p>In general, contexts may be used at any time a
+ <tref>JSON object</tref> is defined. The only time that one cannot
+ express a context is inside a context definition itself. For example, a
+ <tref>JSON-LD document</tref> may use more than one context at different
+ points in a document:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Using multiple 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>Duplicate context <tref title="term">terms</tref> are overridden using a
+ most-recently-defined-wins 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> <tref>term</tref> 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 working with
+ legacy applications that depend on a specific structure of the
+ <tref>JSON object</tref>. If a <tref>term</tref> is redefined within a
+ context, all previous rules associated with the previous definition are
+ removed. If a <tref>term</tref> is redefined 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> are
+ referred to as <tdef title="local context">local contexts</tdef>. 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. Setting a <tref>local context</tref>
+ to <code>null</code> effectively resets the <tref>active context</tref>
+ to an empty context. 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">When possible, the <tref>context</tref> definition should be put
+ at the top of a JSON-LD document. This makes the document easier to read and
+ might make streaming parsers more efficient. Documents that do not have the
+ <tref>context</tref> at the top are still conformant JSON-LD.</p>
+
+ <p class="note">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 <tref title="keyword">keywords</tref> in future versions
+ of JSON-LD. Terms starting with an <code>@</code> character that are not
+ <tref title="keyword">JSON-LD 1.0 keywords</tref> are treated as any other term, i.e.,
+ they are ignored unless mapped to an <tref>IRI</tref>. Furthermore, the use of
+ empty <tref title="term">terms</tref> (<code>""</code>) is not allowed as
+ not all programming languages are able to handle empty property names.</p>
+</section>
+
+<section class="normative">
+ <h2>Interpreting JSON as JSON-LD</h2>
+
+ <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 documents 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="Referencing 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/",
+ "image": "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 class="informative">
+ <h2>String Internationalization</h2>
+
+ <p>At times, it is important to annotate a <tref>string</tref>
+ with its language. In JSON-LD this is possible in a variety of ways.
+ First, it is possible to define a default language for a JSON-LD document
+ by setting the <code>@language</code> key in the <tref>context</tref>:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Setting the default language of a JSON-LD document">
+ <!--
+ {
+ ****"@context":
+ {
+ ...
+ "@language": "ja"
+ }****,
+ "name": ****"花澄"****,
+ "occupation": ****"科学者"****
+ }
+ -->
+ </pre>
+
+ <p>The example above would associate the <code>ja</code> language
+ code with the two <tref title="string">strings</tref> <em>花澄</em> and <em>科学者</em>.
+ Languages codes are defined in [[!BCP47]]. The default language applies to all
+ <tref>string</tref> values that are not <a href="#type-coercion">type coerced</a>.</p>
+
+ <p>To clear the default language for a subtree, <code>@language</code> can
+ be set to <code>null</code> in a <tref>local context</tref> as follows:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Clearing default language">
+ <!--
+ {
+ "@context": {
+ ...
+ "@language": "ja"
+ },
+ "name": "花澄",
+ "details": {
+ **** "@context": {
+ "@language": null
+ }****,
+ "occupation": "Ninja"
+ }
+ }
+ -->
+ </pre>
+
+ <p>Second, it is possible to associate a language with a specific <tref>term</tref>
+ using an <tref>expanded term definition</tref>:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Expanded term definition with language">
+ <!--
+ {
+ "@context": {
+ ...
+ "ex": "http://example.com/vocab/",
+ "@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 class="note">Language associations are only applied to plain
+ <tref title="string">strings</tref>. <tref title="typed value">Typed values</tref>
+ or values that are subject to <a href="#type-coercion">type coercion</a>
+ are not language tagged.</p>
+
+ <p>Just as in the example above, systems often need to express the value of a
+ property in multiple languages. Typically, such systems also try to ensure that
+ developers have a programmatically easy way to navigate the data structures for
+ the language-specific data. In this case, <tref title="language map">language maps</tref>
+ may be utilized.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Language map expressing a property in three languages">
+ <!--
+ {
+ "@context":
+ {
+ ...
+ "occupation": { "@id": "ex:occupation", ****"@container": "@language"**** }
+ },
+ "name": "Yagyū Muneyoshi",
+ "occupation":
+ ****{
+ "ja": "忍者",
+ "en": "Ninja",
+ "cs": "Nindža"
+ }****
+ ...
+ }
+ -->
+ </pre>
+
+ <p>The example above expresses exactly the same information as the previous
+ example but consolidates all values in a single property. To access the
+ value in a specific language in a programming language supporting dot-notation
+ accessors for object properties, a developer may use the
+ <code>property.language</code> pattern. For example, to access the occupation
+ in English, a developer would use the following code snippet:
+ <code>obj.occupation.en</code>.</p>
+
+ <p>Third, it is possible to override the default language by using a
+ <tref>value object</tref>:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Overriding default language using an expanded value">
+ <!--
+ {
+ "@context": {
+ ...
+ "@language": "ja"
+ },
+ "name": "花澄",
+ "occupation": ****{
+ "@value": "Scientist",
+ "@language": "en"
+ }****
+ }
+ -->
+ </pre>
+
+ <p>This makes it possible to specify a plain string by omitting the
+ <code>@language</code> tag or setting it to <code>null</code> when expressing
+ it using a <tref>value object</tref>:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Removing language information using an expanded value">
+ <!--
+ {
+ "@context": {
+ ...
+ "@language": "ja"
+ },
+ "name": ****{
+ "@value": "Frank"
+ }****,
+ "occupation": {
+ "@value": "Ninja",
+ "@language": "en"
+ },
+ "speciality": "手裏剣"
+ }
+ -->
+ </pre>
+
+</section>
+
+<section class="informative">
+ <h2>IRI Expansion within a Context</h2>
+ <p>In general, normal IRI expansion rules apply
+ anywhere an IRI is expected (see <a class="sectionRef" href="#iris"></a>). Within
+ a <tref>context</tref> definition, this can mean that terms defined
+ within the context may also be used within that context as long as
+ there are no circular dependencies. For example, it is common to use
+ the <code>xsd</code> namespace when defining <tref>typed value</tref>s:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="IRI expansion within a context">
+<!--
+{
+ "@context":
+ {
+ ****"xsd": "http://www.w3.org/2001/XMLSchema#"****,
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "age":
+ {
+ "@id": "http://xmlns.com/foaf/0.1/age",
+ "@type": ****"xsd:integer"****
+ },
+ "homepage":
+ {
+ "@id": "http://xmlns.com/foaf/0.1/homepage",
+ "@type": "@id"
+ }
+ },
+ ...
+}
+-->
+</pre>
+
+<p>In this example, the <code>xsd</code> <tref>term</tref> is defined
+ and used as a <tref>prefix</tref> for the <code>@type</code> coercion
+ of the <code>age</code> property.</p>
+
+<p><tref title="term">Terms</tref> may also be used when defining the IRI of another
+<tref>term</tref>:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Using a term to define the IRI of another term within a context">
+<!--
+{
+ "@context":
+ {
+ ****"foaf": "http://xmlns.com/foaf/0.1/"****,
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
+ "name": ****"foaf:name"****,
+ "age":
+ {
+ "@id": ****"foaf:age"****,
+ "@type": "xsd:integer"
+ },
+ "homepage":
+ {
+ "@id": ****"foaf:homepage"****,
+ "@type": "@id"
+ }
+ },
+ ...
+}
+-->
+</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
+ <tref>term</tref> definition.</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Using a compact IRI as a term">
+<!--
+{
+ "@context":
+ {
+ ****"foaf": "http://xmlns.com/foaf/0.1/"****,
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
+ "name": "foaf:name",
+ "****foaf:age****":
+ {
+ "@type": "xsd:integer"
+ },
+ "****foaf:homepage****":
+ ****{
+ "@type": "@id"
+ }****
+ },
+ ...
+}
+-->
+</pre>
+
+<p>
+In this example, the <tref>compact IRI</tref> form is used in two different
+ways.
+In the first approach, <code>foaf:age</code> declares both the
+<tref>IRI</tref> for the <tref>term</tref> (using short-form) as well as the
+<code>@type</code> associated with the <tref>term</tref>. In the second
+approach, only the <code>@type</code> associated with the <tref>term</tref> is
+specified. The full <tref>IRI</tref> for
+<code>foaf:homepage</code> is determined by looking up the <code>foaf</code>
+<tref>prefix</tref> in the
+<tref>context</tref>.
+</p>
+
+<p>
+<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"
+ title="Associating context definitions with absolute IRIs">
+<!--
+{
+ "@context":
+ {
+ "foaf": "http://xmlns.com/foaf/0.1/",
+ "xsd": "http://www.w3.org/2001/XMLSchema#",
+ "name": "foaf:name",
+ "foaf:age":
+ {
+ "@id": "foaf:age",
+ "@type": "xsd:integer"
+ },
+ "****http://xmlns.com/foaf/0.1/homepage****":
+ {
+ "@type": "@id"
+ }
+ },
+ ...
+}
+-->
+</pre>
+
+<p>In order for the <tref>absolute IRI</tref> to match above, the <tref>absolute IRI</tref>
+ needs to be used in the <tref>JSON-LD document</tref>. Also note that <code>foaf:homepage</code>
+ will not use the <code>{ "@type": "@id" }</code> declaration because
+ <code>foaf:homepage</code> is not the same as <code>http://xmlns.com/foaf/0.1/homepage</code>.
+ That is, <tref title="term">terms</tref> are looked up in a <tref>context</tref> using
+ direct string comparison before the <tref>prefix</tref> lookup mechanism is applied.</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>The only exception for using terms in the <tref>context</tref> is that
+ circular definitions are not allowed. That is,
+ a definition of <em>term1</em> cannot depend on the
+ definition of <em>term2</em> if <em>term2</em> also depends on
+ <em>term1</em>. For example, the following <tref>context</tref> definition
+ is illegal:</p>
+<pre class="example" data-transform="updateExample"
+ title="Illegal circular definition of terms within a context">
+<!--
+{
+ "@context":
+ {
+ ****"term1": "term2:foo",
+ "term2": "term1:bar"****
+ },
+ ...
+}
+-->
+</pre>
+</section>
+
+<section class="informative">
+<h2>Sets and Lists</h2>
+
+<p>A JSON-LD author can express multiple values in a compact way by using
+ <tref title="array">arrays</tref>. Since graphs do not describe ordering for links
+ between nodes, arrays in JSON-LD do not provide an ordering of the
+ contained elements by default. This is exactly the opposite from regular JSON
+ arrays, which are ordered by default. For example, consider the following
+ simple document:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Multiple values with no inherent order">
+<!--
+{
+...
+ "@id": "http://example.org/people#joebob",
+ "nick": ****[ "joe", "bob", "JB" ]****,
+...
+}
+-->
+</pre>
+
+<p>The example shown above would result in the following data being generated,
+ each relating the node to an individual value, with no inherent order:</p>
+
+<table class="example">
+<thead>
+ <th>Subject</th>
+ <th>Property</th>
+ <th>Value</th>
+</thead>
+<tbody>
+<tr>
+ <td>http://example.org/people#joebob</td>
+ <td>http://xmlns.com/foaf/0.1/nick</td>
+ <td>joe</td>
+</tr>
+<tr>
+ <td>http://example.org/people#joebob</td>
+ <td>http://xmlns.com/foaf/0.1/nick</td>
+ <td>bob</td>
+</tr>
+<tr>
+ <td>http://example.org/people#joebob</td>
+ <td>http://xmlns.com/foaf/0.1/nick</td>
+ <td>JB</td>
+</tr>
+</tbody>
+</table>
+
+<p>Multiple values may also be expressed using the expanded form:</p>
+
+<pre class="example" data-transform="updateExample"
+ title="Using an expanded form to set multiple values">
+<!--
+{
+ "@id": "http://example.org/articles/8",
+ "dc:title": ****
+ [
+ {
+ "@value": "Das Kapital",
+ "@language": "de"
+ },
+ {
+ "@value": "Capital",
+ "@language": "en"
+ }
+ ]****
+}-->
+</pre>
+
+<p>The example shown above would generate the following data, again with
+ no inherent order:</p>
+
+<table class="example">
+<thead>
+ <th>Subject</th>
+ <th>Property</th>
+ <th>Value</th>
+ <th>Language</th>
+</thead>
+<tbody>
+<tr>
+ <td>http://example.org/articles/8</td>
+ <td>http://purl.org/dc/terms/title</td>
+ <td>Das Kapital</td>
+ <td>de</td>
+</tr>
+<tr>
+ <td>http://example.org/articles/8</td>
+ <td>http://purl.org/dc/terms/title</td>
+ <td>Capital</td>
+ <td>en</td>
+</tr>
+</tbody>
+</table>
+
+<p>As the notion of ordered collections is rather important in data
+ modeling, it is useful to have specific language support. In JSON-LD,
+ a list may be represented using the <code>@list</code> <tref>keyword</tref> as follows:</p>
+<pre class="example" data-transform="updateExample"
+ title="An ordered collection of values in JSON-LD">
+<!--
+{
+...
+ "@id": "http://example.org/people#joebob",
+ "foaf:nick":
+ ****{
+ "@list": [ "joe", "bob", "jaybee" ]
+ }****,
+...
+}
+-->
+</pre>
+
+<p>This describes the use of this <tref>array</tref> as being ordered,
+ and order is maintained when processing a document. If every use of a given multi-valued
+ property is a list, this may be abbreviated by setting <code>@container</code>
+ to <code>@list</code> in the <tref>context</tref>:</p>
+<pre class="example" data-transform="updateExample"
+ title="Specifying that a collection is ordered in the context">
+<!--
+{
+ ****"@context":
+ {
+ ...
+ "nick":
+ {
+ "@id": "http://xmlns.com/foaf/0.1/nick",
+ "@container": "@list"
+ }
+ }****,
+...
+ "@id": "http://example.org/people#joebob",
+ "nick": ****[ "joe", "bob", "jaybee" ]****,
+...
+}
+-->
+</pre>
+
+<p class="note">List of lists are not allowed in this version of JSON-LD.
+ This decision was made due to the extreme amount of added complexity when
+ processing lists of lists.</p>
+
+<p>While <code>@list</code> is used to describe <em>ordered lists</em>,
+ the <code>@set</code> keyword is used to describe <em>unordered sets</em>.
+ The use of <code>@set</code> in the body of a JSON-LD document
+ is optimized away when processing the document, as it is just syntactic
+ sugar. However, <code>@set</code> is helpful when used within the context
+ of a document.
+ Values of terms associated with a <code>@set</code> or <code>@list</code> container
+ are always represented in the form of an <tref>array</tref>,
+ even if there is just a single value that would otherwise be optimized to
+ a non-array form in compact form (see
+ <a class="sectionRef" href="#compact-document-form"></a>). This makes post-processing of
+ JSON-LD documents easier as the data is always in array form, even if the
+ array only contains a single value.</p>
+
+</section>
+
+<section class="informative">
+ <h2>Reverse Properties</h2>
+
+ <p class="issue atrisk">This feature is at risk.</p>
+
+ <p>JSON-LD serializes directed <tref title="JSON-LD graph">graphs</tref>. That means that
+ every <tref>property</tref> points from a <tref>node</tref> to another <tref>node</tref>
+ or <tref title="JSON-LD value">value</tref>. However, in some cases, it is desirable
+ to serialize in the reverse direction. Consider for example the case where a person
+ and its children should be described in a document. If the used vocabulary does not
+ provide a <em>children</em> <tref>property</tref> but just a <em>parent</em>
+ <tref>property</tref>, every <tref>node</tref> representing a child would have to
+ be expressed with a <tref>property</tref> pointing to the parent as in the following
+ example.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="A document with children linking to their parent">
+ <!--
+ [
+ {
+ ****"@id": "#homer"****,
+ "http://example.com/vocab#name": "Homer"
+ },
+ {
+ "@id": "#bart",
+ "http://example.com/vocab#name": "Bart",
+ ****"http://example.com/vocab#parent": { "@id": "#homer" }****
+ },
+ {
+ "@id": "#lisa",
+ "http://example.com/vocab#name": "Lisa",
+ ****"http://example.com/vocab#parent": { "@id": "#homer" }****
+ }
+ ]
+ -->
+ </pre>
+
+ <p>Expressing such data is much simpler by using JSON-LD's <code>@reverse</code>
+ <tref>keyword</tref>:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="A person and its children using a reverse property">
+ <!--
+ {
+ "@id": "#homer",
+ "http://example.com/vocab#name": "Homer",
+ ****"@reverse"****: {
+ ****"http://example.com/vocab#parent"****: [
+ {
+ "@id": "#bart",
+ "http://example.com/vocab#name": "Bart"
+ },
+ {
+ "@id": "#lisa",
+ "http://example.com/vocab#name": "Lisa"
+ }
+ ]
+ }
+ }
+ -->
+ </pre>
+
+ <p>The <code>@reverse</code> <tref>keyword</tref> can also be used in
+ <tref title="expanded term definition">expanded term definitions</tref>
+ to create reverse properties as shown in the following example:</p>
+
+
+ <pre class="example" data-transform="updateExample"
+ title="Using @reverse to define reverse properties">
+ <!--
+ {
+ "@context": {
+ "name": "http://example.com/vocab#name",
+ ****"children": { "@reverse": "http://example.com/vocab#parent" }****
+ },
+ "@id": "#homer",
+ "name": "Homer",
+ ****"children"****: [
+ {
+ "@id": "#bart",
+ "name": "Bart"
+ },
+ {
+ "@id": "#lisa",
+ "name": "Lisa"
+ }
+ ]
+ }
+ -->
+ </pre>
+</section>
+
+
+<section class="informative">
+ <h2>Named Graphs</h2>
+
+ <p>At times, it is necessary to make statements about a <tref>JSON-LD graph</tref>
+ itself, rather than just a single <tref>node</tref>. This can be done by
+ grouping a set of <tref title="node">nodes</tref> using the <code>@graph</code>
+ <tref>keyword</tref>. A developer may also name data expressed using the
+ <code>@graph</code> <tref>keyword</tref> by pairing it with an
+ <code>@id</code> <tref>keyword</tref> as shown in the following example:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Identifying and making statements about a graph">
+ <!--
+ {
+ "@context": {
+ "generatedAt": {
+ "@id": "http://www.w3.org/ns/prov#generatedAtTime",
+ "@type": "http://www.w3.org/2001/XMLSchema#date"
+ },
+ "Person": "http://xmlns.com/foaf/0.1/Person",
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "knows": "http://xmlns.com/foaf/0.1/knows"
+ },
+ ****"@id": "http://example.org/graphs/73",
+ "generatedAt": "2012-04-09",
+ "@graph":****
+ [
+ {
+ "@id": "http://manu.sporny.org/i/public",
+ "@type": "Person",
+ "name": "Manu Sporny",
+ "knows": "http://greggkellogg.net/foaf#me"
+ },
+ {
+ "@id": "http://greggkellogg.net/foaf#me",
+ "@type": "Person",
+ "name": "Gregg Kellogg",
+ "knows": "http://manu.sporny.org/i/public"
+ }
+ ]
+ }
+ -->
+ </pre>
+
+ <p>The example above expresses a <tref>named graph</tref> that is identified
+ by the <tref>IRI</tref> <code>http://example.org/graphs/73</code>. That
+ graph is composed of the statements about Manu and Gregg. Metadata about
+ the graph itself is expressed via the <code>generatedAt</code> property,
+ which specifies when the graph was generated. An alternative view of the
+ information above is represented in table form below:</p>
+
+ <table class="example">
+ <thead>
+ <th>Graph</th>
+ <th>Subject</th>
+ <th>Property</th>
+ <th>Value</th>
+ <th>Value Type</th>
+ </thead>
+ <tbody>
+ <tr>
+ <td> </td>
+ <td>http://example.org/graphs/73</td>
+ <td>http://www.w3.org/ns/prov#generatedAtTime</td>
+ <td>2012-04-09</td>
+ <td>http://www.w3.org/2001/XMLSchema#date</td>
+ </tr>
+ <tr>
+ <td>http://example.org/graphs/73</td>
+ <td>http://manu.sporny.org/i/public</td>
+ <td>http://www.w3.org/2001/XMLSchema#type</td>
+ <td>http://xmlns.com/foaf/0.1/Person</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>http://example.org/graphs/73</td>
+ <td>http://manu.sporny.org/i/public</td>
+ <td>http://xmlns.com/foaf/0.1/name</td>
+ <td>Manu Sporny</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>http://example.org/graphs/73</td>
+ <td>http://manu.sporny.org/i/public</td>
+ <td>http://xmlns.com/foaf/0.1/knows</td>
+ <td>http://greggkellogg.net/foaf#me</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>http://example.org/graphs/73</td>
+ <td>http://greggkellogg.net/foaf#me</td>
+ <td>http://www.w3.org/2001/XMLSchema#type</td>
+ <td>http://xmlns.com/foaf/0.1/Person</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>http://example.org/graphs/73</td>
+ <td>http://greggkellogg.net/foaf#me</td>
+ <td>http://xmlns.com/foaf/0.1/name</td>
+ <td>Gregg Kellogg</td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>http://example.org/graphs/73</td>
+ <td>http://greggkellogg.net/foaf#me</td>
+ <td>http://xmlns.com/foaf/0.1/knows</td>
+ <td>http://manu.sporny.org/i/public</td>
+ <td></td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>When a JSON-LD document's top-level structure is an
+ <tref title="JSON object">object</tref> that contains no other
+ <tref title="property">properties</tref> than <code>@graph</code> and
+ optionally <code>@context</code> (properties that are not mapped to an
+ <tref>IRI</tref> or a <tref>keyword</tref> are ignored),
+ <code>@graph</code> is considered to express the otherwise implicit
+ <tref>default graph</tref>. This mechanism can be useful when a number
+ of <tref title="node">nodes</tref> exist at the document's top level that
+ share the same <tref>context</tref>, which is, e.g., the case when a
+ document is <a href="#flattened-document-form">flattened</a>. The
+ <code>@graph</code> keyword collects such nodes in an <tref>array</tref>
+ and allows the use of a shared context.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Using @graph to explicitly express the default graph">
+ <!--
+ {
+ "@context": ...,
+ "****@graph****":
+ [
+ {
+ "@id": "http://manu.sporny.org/i/public",
+ "@type": "foaf:Person",
+ "name": "Manu Sporny",
+ "knows": "http://greggkellogg.net/foaf#me"
+ },
+ {
+ "@id": "http://greggkellogg.net/foaf#me",
+ "@type": "foaf:Person",
+ "name": "Gregg Kellogg",
+ "knows": "http://manu.sporny.org/i/public"
+ }
+ ]
+ }
+ -->
+ </pre>
+
+ <p>In this case, embedding doesn't work as each <tref>node object</tref>
+ references the other. This is equivalent to using multiple
+ <tref title="node object">node objects</tref> in array and defining
+ the <code>@context</code> within each <tref>node object</tref>:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Context needs to be duplicated if @graph is not used">
+ <!--
+ [
+ {
+ ****"@context": ...,****
+ "@id": "http://manu.sporny.org/i/public",
+ "@type": "foaf:Person",
+ "name": "Manu Sporny",
+ "knows": "http://greggkellogg.net/foaf#me"
+ },
+ {
+ ****"@context": ...,****
+ "@id": "http://greggkellogg.net/foaf#me",
+ "@type": "foaf:Person",
+ "name": "Gregg Kellogg",
+ "knows": "http://manu.sporny.org/i/public"
+ }
+ ]
+ -->
+ </pre>
+
+</section>
+
+<section class="informative">
+ <h2>Identifying Blank Nodes</h2>
+
+ <p>At times, it becomes necessary to be able to express information without
+ being able to uniquely identify the <tref>node</tref> with an <tref>IRI</tref>.
+ This type of node is called a <tref>blank node</tref>. JSON-LD does not require
+ all nodes to be identified using <code>@id</code>. However, some graph topologies
+ may require identifiers to be serializable. Graphs containing loops, e.g., cannot
+ be serialized using embedding alone, <code>@id</code> must be used to connect the nodes.
+ In these situations, one can use <tref title="blank node identifier">blank node identifiers</tref>,
+ which look like <tref title="IRI">IRIs</tref> using an underscore (<code>_</code>)
+ as scheme. This allows one to reference the node locally within the document, but
+ makes it impossible to reference the node from an external document. The
+ <tref>blank node identifier</tref> is scoped to the document in which it is used.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Specifying a local blank node identifier">
+ <!--
+ {
+ ...
+ "@id": "****_:n1****",
+ "name": "Secret Agent 1",
+ "knows":
+ {
+ "name": "Secret Agent 2",
+ "knows": { "@id": "****_:n1****" }
+ }
+ }
+ -->
+ </pre>
+
+ <p>The example above contains information about to secrete agents that cannot be identified
+ with an <tref>IRI</tref>. While expressing that <em>agent 1</em> knows <em>agent 2</em> is possible
+ without using <tref title="blank node identifier">blank node identifiers</tref>, it is
+ necessary assign <em>agent 1</em> an identifier so that it can be referenced from
+ <em>agent 2</em>.</p>
+ <p>It is worth nothing that blank node identifiers may be relabeled during processing.
+ If a developer finds that they refer to the <tref>blank node</tref> more than once,
+ they should consider naming the node using a dereferenceable <tref>IRI</tref> so that
+ it can also be referenced from other documents.</p>
+</section>
+
+<section class="informative">
+ <h2>Aliasing Keywords</h2>
+
+ <p>Each of the JSON-LD <tref title="keyword">keywords</tref>,
+ except for <code>@context</code>, may be aliased to application-specific
+ keywords. This feature allows legacy JSON content to be utilized
+ by JSON-LD by re-using JSON keys that already exist in legacy documents.
+ This feature also allows developers to design domain-specific implementations
+ using only the JSON-LD <tref>context</tref>.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Aliasing keywords">
+ <!--
+ {
+ "@context":
+ {
+ ****"url": "@id"****,
+ ****"a": "@type"****,
+ "name": "http://xmlns.com/foaf/0.1/name"
+ },
+ "****url****": "http://example.com/about#gregg",
+ "****a****": "http://xmlns.com/foaf/0.1/Person",
+ "name": "Gregg Kellogg"
+ }
+ -->
+ </pre>
+
+ <p>In the example above, the <code>@id</code> and <code>@type</code>
+ <tref title="keyword">keywords</tref> have been given the aliases
+ <strong>url</strong> and <strong>a</strong>, respectively.</p>
+
+ <p>Since keywords cannot be redefined, they can also not be aliased to
+ other keywords.</p>
+</section>
+
+<section class="informative">
+ <h2>Data Indexing</h2>
+
+ <p>Databases are typically used to make access to
+ data more efficient. Developers often extend this sort of functionality into
+ their application data to deliver similar performance gains. Often this
+ data does not have any meaning from a Linked Data standpoint, but is
+ still useful for an application.</p>
+
+ <p>JSON-LD introduces the notion of <tref title="index map">index maps</tref>
+ that can be used to structure data into a form that is
+ more efficient to access. The data indexing feature allows an author to
+ structure data using a simple key-value map where the keys do not map
+ to <tref title="IRI">IRIs</tref>. This enables direct access to data
+ instead of having to scan an array in search of a specific item.
+ In JSON-LD such data can be specified by associating the
+ <code>@index</code> <tref>keyword</tref> with a
+ <code>@container</code> declaration in the context:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Indexing data in JSON-LD">
+ <!--
+ {
+ "@context":
+ {
+ "schema": "http://schema.org/",
+ "name": "schema:name",
+ "body": "schema:articleBody",
+ "words": "schema:wordCount",
+ "post": {
+ "@id": "schema:blogPost",
+ ****"@container": "@index"****
+ }
+ },
+ "@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>index map</tref>. The <strong>en</strong>,
+ <strong>de</strong>, and <strong>ja</strong> keys will be ignored
+ semantically, but preserved syntactically, by the JSON-LD Processor.
+ This allows a developer 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 index keys do not appear in the Linked Data
+ below, but would continue to exist if the document were compacted or
+ expanded (see <a class="sectionRef" href="#compact-document-form"></a> and
+ <a class="sectionRef" href="#expanded-document-form"></a>) using a JSON-LD processor:</p>
+
+ <table class="example">
+ <thead>
+ <th>Subject</th>
+ <th>Property</th>
+ <th>Value</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 class="informative">
+ <h3>Expanded Document Form</h3>
+
+ <p>The JSON-LD Processing Algorithms and API specification [[JSON-LD-API]]
+ defines a method for <em>expanding</em> a JSON-LD document.
+ Expansion is the process of taking a JSON-LD document and applying a
+ <code>@context</code> such that all IRIs, types, and values
+ are expanded so that the <code>@context</code> is no longer necessary.</p>
+
+ <p>For example, assume the following JSON-LD input document:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Sample JSON-LD document">
+ <!--
+ {
+ "@context":
+ {
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "homepage": {
+ "@id": "http://xmlns.com/foaf/0.1/homepage",
+ "@type": "@id"
+ }
+ },
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/"
+ }
+ -->
+ </pre>
+
+ <p>Running the JSON-LD Expansion algorithm against the JSON-LD input document
+ provided above would result in the following output:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Expanded form for the previous example">
+ <!--
+ [
+ {
+ "http://xmlns.com/foaf/0.1/name": [
+ { "@value": "Manu Sporny" }
+ ],
+ "http://xmlns.com/foaf/0.1/homepage": [
+ { "@id": "http://manu.sporny.org/" }
+ ]
+ }
+ ]
+ -->
+ </pre>
+</section>
+
+<section class="informative">
+ <h3>Compact Document Form</h3>
+
+ <p>The JSON-LD Processing Algorithms and API specification [[JSON-LD-API]] defines
+ a method for <em>compacting</em> a JSON-LD document. Compaction is the process
+ of applying a developer-supplied context to shorten <tref title="IRI">IRIs</tref>
+ to <tref title="term">terms</tref> or <tref title="compact IRI">compact IRIs</tref>
+ and JSON-LD values expressed in expanded form to simple values such as
+ <tref title="string">strings</tref> or <tref title="number">numbers</tref>.
+ Often this makes it simpler to work with document as the data is expressed in
+ application-specific terms. Compacted documents are also typically easier to read
+ for humans.</p>
+
+ <p>For example, assume the following JSON-LD input document:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Sample expanded JSON-LD document">
+ <!--
+ [
+ {
+ "http://xmlns.com/foaf/0.1/name": [ "Manu Sporny" ],
+ "http://xmlns.com/foaf/0.1/homepage": [
+ {
+ "@id": "http://manu.sporny.org/"
+ }
+ ]
+ }
+ ]
+ -->
+ </pre>
+
+ <p>Additionally, assume the following developer-supplied JSON-LD context:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Sample context">
+ <!--
+ {
+ "@context": {
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "homepage": {
+ "@id": "http://xmlns.com/foaf/0.1/homepage",
+ "@type": "@id"
+ }
+ }
+ }
+ -->
+ </pre>
+
+ <p>Running the JSON-LD Compaction algorithm given the context supplied above
+ against the JSON-LD input document provided above would result in the following
+ output:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Compact form of the sample document once sample context has been applied">
+ <!--
+ {
+ "@context": {
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "homepage": {
+ "@id": "http://xmlns.com/foaf/0.1/homepage",
+ "@type": "@id"
+ }
+ },
+ "name": "Manu Sporny",
+ "homepage": "http://manu.sporny.org/"
+ }
+ -->
+ </pre>
+</section>
+
+<section class="informative">
+ <h3>Flattened Document Form</h3>
+
+ <p>The JSON-LD Processing Algorithms and API specification [[JSON-LD-API]] defines
+ a method for <em>flattening</em> a JSON-LD document. Flattening collects all
+ properties of a <tref>node</tref> in a single <tref>JSON object</tref> and labels
+ all <tref title="blank node">blank nodes</tref> with
+ <tref title="blank node identifier">blank node identifiers</tref>.
+ This ensures a shape of the data and consequently may drastically simplify the code
+ required to process JSON-LD in certain applications.</p>
+
+ <p>For example, assume the following JSON-LD input document:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Sample JSON-LD document">
+ <!--
+ {
+ "@context": {
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "knows": "http://xmlns.com/foaf/0.1/knows"
+ },
+ "@id": "http://me.markus-lanthaler.com/",
+ "name": "Markus Lanthaler",
+ "knows": [
+ {
+ "@id": "http://manu.sporny.org/",
+ "name": "Manu Sporny"
+ },
+ {
+ "name": "Dave Longley"
+ }
+ ]
+ }
+ -->
+ </pre>
+
+ <p>Running the JSON-LD Flattening algorithm against the JSON-LD input document in
+ the example above and using the same context would result in the following
+ output:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Flattened and compacted form for the previous example">
+ <!--
+ {
+ "@context": {
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "knows": "http://xmlns.com/foaf/0.1/knows"
+ },
+ "@graph": [
+ {
+ "@id": "_:b0",
+ "name": "Dave Longley"
+ },
+ {
+ "@id": "http://manu.sporny.org/",
+ "name": "Manu Sporny"
+ },
+ {
+ "@id": "http://me.markus-lanthaler.com/",
+ "name": "Markus Lanthaler",
+ "knows": [
+ { "@id": "http://manu.sporny.org/" },
+ { "@id": "_:b0" }
+ ]
+ }
+ ]
+ }
+ -->
+ </pre>
+</section>
+
+<section class="informative">
+ <h2>Embedding JSON-LD in HTML Documents</h2>
+
+ <p>HTML script tags can be used to embed blocks of data in documents.
+ This way, JSON-LD content can be easily embedded in HTML by placing
+ it in a script element with the <code>type</code> attribute set to
+ <code>application/ld+json</code>.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Embedding JSON-LD in HTML">
+ <!--
+ ****<script type="application/ld+json">****
+ {
+ "@context": "http://json-ld.org/contexts/person.jsonld",
+ "@id": "http://dbpedia.org/resource/John_Lennon",
+ "name": "John Lennon",
+ "born": "1940-10-09",
+ "spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
+ }
+ ****</script>****
+ -->
+ </pre>
+
+ <p>Depending on how the HTML document is served, certain strings may need
+ to be escaped.</p>
+
+ <p>Defining how such data may be used is beyond the scope of this specification.
+ The embedded JSON-LD document might be extracted as is or, e.g., be converted
+ to RDF.</p>
+
+ <p>If JSON-LD content is extracted as RDF [[RDF11-CONCEPTS]], it should be expanded into an
+ <tref href="http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset">RDF dataset</tref> using the
+ <cite><a href="../json-ld-api/#convert-to-rdf-algorithm">Convert to RDF Algorithm</a></cite>
+ [[JSON-LD-API]]. If multiple embedded JSON-LD documents are extracted as RDF,
+ the result is the RDF merge of the extracted datasets.</p>
+</section>
+
+</section>
+
+<section class="appendix normative">
+ <h1>Data Model</h1>
+
+ <p>JSON-LD is a serialization format for <tref>Linked Data</tref> based on JSON.
+ It is therefore important to distinguish between the syntax, which is defined
+ by JSON in [[RFC4627]], and <tdef title="JSON-LD data model">JSON-LD's data model</tdef>
+ which is defined as follows:</p>
+
+ <ul>
+ <li>A <tdef>JSON-LD document</tdef> serializes a collection of
+ <tref title="JSON-LD graph">JSON-LD graphs</tref> and comprises exactly one
+ <tdef>default graph</tdef> and zero or more <tdef title="named graph">named graphs</tdef>.</li>
+ <li>The <tref>default graph</tref> does not have a name and MAY be empty.</li>
+ <li>Each <tref>named graph</tref> is a pair consisting of an <tref>IRI</tref> or
+ <tref>blank node identifier</tref> (the <tdef>graph name</tdef>) and a <tref>JSON-LD graph</tref>.
+ Whenever possible, the <tref>graph name</tref> SHOULD be an <tref>IRI</tref>.</li>
+ <li>A <tdef>JSON-LD graph</tdef> is a labeled directed graph, i.e., a set of
+ <tref title="node">nodes</tref> connected by <tref title="edge">edges</tref>.</li>
+ <li>Every <tdef>edge</tdef> has a direction associated with it and is labeled with
+ an <tref>IRI</tref> or a <tref>blank node identifier</tref>. Within the JSON-LD syntax
+ these edge labels are called <tdef title="property">properties</tdef>. Whenever possible, an
+ <tref>edge</tref> SHOULD be labeled with an <tref>IRI</tref>.</li>
+ <li>Every <tdef>node</tdef> is an <tref>IRI</tref>, a <tref>blank node</tref>,
+ a <tref>JSON-LD value</tref>, or a <tref>list</tref>.</li>
+ <li>A <tref>node</tref> 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>,
+ 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
+ defined in [[RFC3987]]. <tref title="IRI">IRIs</tref> used within a
+ <tref>JSON-LD graph</tref> SHOULD return a <tref>Linked Data</tref> document describing
+ the resource denoted by that <tref>IRI</tref> when being dereferenced.</li>
+ <li>A <tdef>blank node</tdef> is a <tref>node</tref> which is neither an <tref>IRI</tref>,
+ nor a <tref>JSON-LD value</tref>, nor a <tref>list</tref>. A blank node MAY be identified
+ using a <tref>blank node identifier</tref>.</li>
+ <li>A <tdef>blank node identifier</tdef> is a string that can be used as an identifier
+ for a <tref>blank node</tref> within the scope of a <tref>JSON-LD document</tref>.
+ Blank node identifiers begin with <code>_:</code>.</li>
+ <li>A <tdef>JSON-LD value</tdef> is a <tref>string</tref>, a <tref>number</tref>,
+ <tref>true</tref> or <tref>false</tref>, a <tref>typed value</tref>, or a
+ <tref>language-tagged string</tref>.</li>
+ <li>A <tdef>typed value</tdef> consists of a value, which is a string, and a type, which is an
+ <tref>IRI</tref>.</li>
+ <li>A <tdef>language-tagged string</tdef> consists of a string and a non-empty language
+ tag as defined by [[BCP47]]. The language tag MUST be well-formed according to section
+ <a href="http://tools.ietf.org/html/bcp47#section-2.2.9">2.2.9</a> of [[BCP47]], and MUST
+ be lowercase.</li>
+ <li>A <tdef>list</tdef> is an ordered sequence of zero or more
+ <tref title="IRI">IRIs</tref>,
+ <tref title="blank node">blank nodes</tref>, and
+ <tref title="JSON-LD value">JSON-LD values</tref>.</li>
+ </ul>
+
+ <p class="issue atrisk" data-number="217">In contrast to the RDF data model as defined in
+ [[RDF11-CONCEPTS]], JSON-LD allows blank nodes as property labels and graph names. Thus,
+ some data that is valid JSON-LD cannot be converted to RDF. This feature may be removed
+ in the future.</p>
+
+ <p><tref title="JSON-LD document">JSON-LD documents</tref> MAY contain data that cannot be
+ represented by the <tref title="JSON-LD data model">data model</tref> defined above.
+ Unless otherwise specified, such data is ignored when a <tref>JSON-LD document</tref>
+ is being processed. This means, e.g., that properties which are not mapped to an
+ <tref>IRI</tref> or <tref>blank node</tref> will be ignored.</p>
+
+ <p style="text-align: center"><img src="linked-data-graph.png" title="An illustration of JSON-LD's data model"/></p>
+ <p style="text-align: center">Figure 1: An illustration of JSON-LD's data model.</p>
+</section>
+
+<section class="appendix normative">
+ <h1>JSON-LD Grammar</h1>
+
+ <p>This appendix restates the syntactic conventions described in the
+ previous sections more formally.</p>
+
+ <p>A <tref>JSON-LD document</tref> MUST be a valid JSON document as described
+ in [[!RFC4627]].</p>
+
+ <p>A <tref>JSON-LD document</tref> MUST be a single <tref>node object</tref>
+ or a JSON <tref>array</tref> containing a set of one or more
+ <tref title="node object">node objects</tref> at the top level.</p>
+
+ <p>In contrast to JSON, in JSON-LD the keys in <tref title="JSON object">objects</tref>
+ MUST be unique.</p>
+
+ <p class="note">JSON-LD allows <tref title="keyword">keywords</tref> to be aliased
+ (see <a class="sectionRef" href="#aliasing-keywords"></a> for details). Whenever a <tref>keyword</tref> is
+ discussed in this grammar, the statements also apply to an alias for
+ that <tref>keyword</tref>. For example, if the <tref>active context</tref>
+ defines the <tref>term</tref> <code>id</code> as an alias for <code>@id</code>,
+ that alias may be legitimately used as a substitution for <code>@id</code>.
+ Note that <tref>keyword</tref> aliases are not expanded during context
+ processing.</p>
+
+ <section class="normative">
+ <h2>Terms</h2>
+
+ <p>A <tdef>term</tdef> is a short-hand <tref>string</tref> that expands
+ to an <tref>IRI</tref> or a <tref>blank node identifier</tref>.</p>
+
+ <p>A <tref>term</tref> MUST NOT equal any of the JSON-LD
+ <tref title="keyword">keywords</tref>.</p>
+
+ <p>To avoid forward-compatibility issues, a <tref>term</tref> SHOULD NOT start
+ with an <code>@</code> character as future versions of JSON-LD may introduce
+ additional <tref title="keyword">keywords</tref>. Furthermore, the term MUST NOT
+ be an empty <tref>string</tref> (<code>""</code>) as not all programming languages
+ are able to handle empty property names.</p>
+
+ <p>See <a class="sectionRef" href="#the-context"></a> and
+ <a class="sectionRef" href="#iris"></a> for further discussion
+ on mapping <tref title="term">terms</tref> to <tref title="IRI">IRIs</tref>.</p>
+ </section>
+
+ <section class="normative">
+ <h2>Node Objects</h2>
+
+ <p>A <tdef>node object</tdef> represents zero or more properties of a
+ <tref>node</tref> in the <tref>JSON-LD graph</tref> serialized by the
+ <tref>JSON-LD document</tref>. A <tref>JSON object</tref> is a
+ <tref>node object</tref> if it exists outside of a JSON-LD
+ <tref>context</tref> and:</p>
+
+ <ul>
+ <li>it does not contain the <code>@value</code>, <code>@list</code>,
+ or <code>@set</code> keywords, and</li>
+ <li>it is not the top-most <tref>JSON object</tref> in the JSON-LD document
+ consisting of no other members than <code>@graph</code> and
+ <code>@context</code>.</li>
+ </ul>
+
+ <p>The <tref title="property">properties</tref> of a <tref>node</tref> in
+ a <tref>JSON-LD graph</tref> may be spread among different
+ <tref title="node object">node objects</tref> within a document. When
+ that happens, the keys of the different
+ <tref title="node object">node objects</tref> are merged to create the
+ properties of the resulting <tref>node</tref>.</p>
+
+ <p>A <tref>node object</tref> MUST be a <tref>JSON object</tref>. All keys
+ which are not <tref title="IRI">IRIs</tref>,
+ <tref title="compact iri">compact IRIs</tref>, <tref title="term">terms</tref>
+ valid in the <tref>active context</tref>, or one of the following
+ <tref title="keyword">keywords</tref> MUST be ignored when processed:</p>
+
+ <ul>
+ <li><code>@context</code>,</li>
+ <li><code>@id</code>,</li>
+ <li><code>@graph</code>,</li>
+ <li><code>@type</code>,</li>
+ <li><code>@reverse</code>, or</li>
+ <li><code>@index</code></li>
+ </ul>
+
+ <p>If the <tref>node object</tref> contains the <code>@context</code>
+ key, its value MUST be <tref>null</tref>, an <tref>absolute IRI</tref>,
+ a <tref>relative IRI</tref>, a <tref>context definition</tref>, or
+ an <tref>array</tref> composed of any of these.</p>
+
+ <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>).
+ See <a class="sectionRef" href="#node-identifiers"></a>,
+ <a class="sectionRef" href="#compact-iris"></a>, and
+ <a class="sectionRef" href="#identifying-blank-nodes"></a> for further discussion on
+ <code>@id</code> values.</p>
+
+ <p>If the <tref>node object</tref> contains the <code>@graph</code>
+ key, its value MUST be
+ a <tref>node object</tref> or
+ an <tref>array</tref> of zero or more <tref title="node object">node objects</tref>.
+ If the <tref>node object</tref> contains an <code>@id</code> keyword,
+ its value is used as the label of a named graph.
+ See <a class="sectionRef" href="#named-graphs"></a> for further discussion on
+ <code>@graph</code> values. As a special case, if a <tref>JSON object</tref>
+ contains no keys other than <code>@graph</code> and <code>@context</code>, and the
+ <tref>JSON object</tref> is the root of the JSON-LD document, the
+ <tref>JSON object</tref> is not treated as a <tref>node object</tref>; this
+ is used as a way of defining <tref title="node object">node
+ definitions</tref> that may not form a connected graph. This allows a
+ <tref>context</tref> to be defined which is shared by all of the constituent
+ <tref title="node object">node objects</tref>.</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>
+ (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.
+ See <a class="sectionRef" href="#specifying-the-type"></a> for further discussion on
+ <code>@type</code> values.</p>
+
+ <p>If the <tref>node object</tref> contains the <code>@reverse</code> key,
+ its value MUST be a <tref>JSON object</tref> containing members representing reverse
+ properties. Each value of such a reverse property MUST be an <tref>absolute IRI</tref>,
+ a <tref>relative IRI</tref>, a <tref>compact IRI</tref>, a <tref>blank node identifier</tref>,
+ a <tref>node object</tref> or an <tref>array</tref> containing a combination of these.</p>
+
+ <p>If the <tref>node object</tref> contains the <code>@index</code> key,
+ its value MUST be a <tref>string</tref>. See
+ <a class="sectionRef" href="#data-indexing"></a> for further discussion
+ on <code>@index</code> values.</p>
+
+ <p>Keys in a <tref>node object</tref> that are not
+ <tref title="keyword">keywords</tref> MAY expand to an <tref>absolute IRI</tref>
+ using the <tref>active context</tref>. The values associated with keys that expand
+ to an <tref>absolute IRI</tref> MUST be one 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>value object</tref>,</li>
+ <li><tref>list object</tref>,</li>
+ <li><tref>set object</tref>,</li>
+ <li>an <tref>array</tref> of zero or more of the possibilities above,</li>
+ <li>a <tref>language map</tref>, or </li>
+ <li>an <tref>index map</tref></li>
+ </ul>
+ </section>
+
+ <section class="normative">
+ <h2>Value Objects</h2>
+
+ <p>A <tdef>value object</tdef> is used to explicitly associate a type or a
+ language with a value to create a <tref>typed value</tref> or a <tref>language-tagged
+ string</tref>.</p>
+
+ <p>A <tref>value object</tref> MUST be a <tref>JSON object</tref> containing the
+ <code>@value</code> key. It MAY also contain a <code>@type</code>,
+ a <code>@language</code>, an <code>@index</code>, or an <code>@context</code> key but MUST NOT contain
+ both a <code>@type</code> and a <code>@language</code> key at the same time.
+ A <tref>value object</tref> MUST NOT contain any other keys that expand to an
+ <tref>absolute IRI</tref> or <tref>keyword</tref>.</p>
+
+ <p>The value associated with the <code>@value</code> key MUST be either a
+ <tref>string</tref>, a <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>, a <tref>relative 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>
+
+ <p>The value associated with the <code>@index</code> key MUST be a
+ <tref>string</tref>.</p>
+
+ <p>See <a class="sectionRef" href="#typed-values"></a> and
+ <a class="sectionRef" href="#string-internationalization"></a>
+ for more information on <tref title="value object">value objects</tref>.</p>
+ </section>
+
+ <section class="normative">
+ <h2>Lists and Sets</h2>
+
+ <p>A <tref>list</tref> represents an <em>ordered</em> set of values. A set
+ 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.
+ However, it is very helpful when used within the context of a document. Values
+ of terms associated with a <code>@set</code> or <code>@list</code> container
+ will always be represented in the form of an <tref>array</tref> when a document
+ is processed—even if there is just a single value that would otherwise be optimized to
+ 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 a
+ deterministic form.</p>
+
+ <p>A <tdef>list object</tdef> MUST be a <tref>JSON object</tref> that contains no
+ keys that expand to an <tref>absolute IRI</tref> or <tref>keyword</tref> other
+ than <code>@list</code>, <code>@context</code>, and <code>@index</code>.</p>
+
+ <p>A <tdef>set object</tdef> MUST be a <tref>JSON object</tref> that contains no
+ keys that expand to an <tref>absolute IRI</tref> or <tref>keyword</tref> other
+ than <code>@list</code>, <code>@context</code>, and <code>@index</code>.
+ Please note that the <code>@index</code> key will be ignored when being processed.</p>
+
+ <p>In both cases, the value associated with the keys <code>@list</code> and <code>@set</code>
+ MUST be one of the following types:</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>value object</tref>, or</li>
+ <li>an <tref>array</tref> of zero or more of the above possibilities</li>
+ </ul>
+
+ <p>See <a class="sectionRef" href="#sets-and-lists"></a> for further discussion on sets and lists.</p>
+ </section>
+
+ <section class="normative">
+ <h2>Language Maps</h2>
+
+ <p>A <tdef>language map</tdef> is used to associate a language with a value in a
+ way that allows easy programmatic access. A <tref>language map</tref> may be
+ used as a term value within a <tref>node object</tref> if the term is defined
+ with <code>@container</code> set to <code>@language</code>. The keys of a
+ <tref>language map</tref> MUST be <tref title="string">strings</tref> representing
+ [[BCP47]] language codes with and the values MUST be any of the following types:</p>
+
+ <ul>
+ <li><tref>null</tref>,</li>
+ <li><tref>string</tref>, or</li>
+ <li>an <tref>array</tref> of zero or more of the above possibilities</li>
+ </ul>
+
+ <p>See <a class="sectionRef" href="#string-internationalization"></a> for further discussion
+ on language maps.</p>
+ </section>
+
+ <section class="normative">
+ <h2>Index Maps</h2>
+
+ <p>An <tdef>index map</tdef> allows keys that have no semantic meaning,
+ but should be preserved regardless, to be used in JSON-LD documents.
+ An <tref>index map</tref> may
+ be used as a <tref>term</tref> value within a <tref>node object</tref> if the
+ term is defined with <code>@container</code> set to <code>@index</code>.
+ The values of the members of an <tref>index map</tref> MUST be one
+ of the following types:</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>value object</tref>,</li>
+ <li><tref>list object</tref>,</li>
+ <li><tref>set object</tref>,</li>
+ <li>an <tref>array</tref> of zero or more of the above possibilities</li>
+ </ul>
+
+ <p>See <a class="sectionRef" href="#data-indexing"></a> for further information on this topic.</p>
+ </section>
+
+<section class="normative">
+ <h2>Context Definitions</h2>
+
+ <p>A <tdef>context definition</tdef> defines a <tref>local context</tref> in a
+ <tref>node object</tref>.</p>
+
+ <p>A <tref>context definition</tref> MUST be a <tref>JSON object</tref> whose
+ keys MUST either be <tref title="term">terms</tref>,
+ <tref title="compact IRI">compact IRIs</tref>, <tref title="absolute IRI">absolute IRIs</tref>,
+ or the <tref title="keyword">keywords</tref> <code>@language</code>, <code>@base</code>,
+ and <code>@vocab</code>.</p>
+
+ <p>If the <tref>context definition</tref> has a <code>@language</code> key,
+ its value MUST have the lexical form described in [[!BCP47]] or be <tref>null</tref>.</p>
+
+ <p>If the <tref>context definition</tref> has a <code>@base</code> key,
+ its value MUST be an <tref>absolute IRI</tref> or <tref>null</tref>.</p>
+
+ <p class="issue atrisk" data-number="223" title="Feature at risk">This feature is
+ at risk as the fact that a document may have multiple base IRIs is potentially
+ confusing for developers. It is also being discussed whether relative IRIs
+ are allowed as values of <code>@base</code> or whether the empty string
+ should be used to explicitly specify that there isn't a base IRI, which
+ could be used to ensure that relative IRIs remain relative when expanding.</p>
+
+ <p>If the <tref>context definition</tref> has a <code>@vocab</code> key,
+ its value MUST be a <tref>absolute IRI</tref>, a <tref>compact IRI</tref>,
+ a <tref>term</tref>, or <tref>null</tref>.</p>
+
+ <p>The value of keys that are not <tref title="keyword">keywords</tref> MUST be either an
+ <tref>absolute IRI</tref>, a <tref>compact IRI</tref>, a <tref>term</tref>,
+ a <tref>blank node identifier</tref>, a <tref>keyword</tref>, <tref>null</tref>,
+ or an <tref>expanded term definition</tref>.</p>
+
+ <p>An <tref>expanded term definition</tref> is used to describe the mapping
+ between a <tref>term</tref> and its expanded identifier, as well as other
+ properties of the value associated with the <tref>term</tref> when it is
+ used as key in a <tref>node object</tref>.</p>
+
+ <p>An <tref>expanded term definition</tref> MUST be a <tref>JSON object</tref>
+ composed of zero or more keys from <code>@id</code>, <code>@reverse</code>,
+ <code>@type</code>, <code>@language</code> or <code>@container</code>. An
+ <tref>expanded term definition</tref> SHOULD NOT contain any other keys.</p>
+
+ <p>If an <tref>expanded term definition</tref> has an <code>@reverse</code> member,
+ <code>@id</code>, <code>@type</code>, and <code>@language</code> are not allowed.
+ If an <code>@container</code> member exists, its value MUST be <tref>null</tref>
+ or <code>@index</code>.</p>
+
+ <p>If the term being defined is not a <tref>compact IRI</tref> or
+ <tref>absolute IRI</tref> and the <tref>active context</tref> does not have an
+ <code>@vocab</code> mapping, the <tref>expanded term definition</tref> MUST
+ include the <code>@id</code> key.</p>
+
+ <p>If the <tref>expanded term definition</tref> contains the <code>@id</code>
+ <tref>keyword</tref>, its value MUST be <tref>null</tref>, an <tref>absolute IRI</tref>,
+ a <tref>blank node identifier</tref>, a <tref>compact IRI</tref>, or a <tref>term</tref>.</p>
+
+ <p>If the <tref>expanded term definition</tref> contains the <code>@type</code>
+ <tref>keyword</tref>, its value MUST be an <tref>absolute IRI</tref>, a
+ <tref>compact IRI</tref>, a <tref>blank node identifier</tref>, a <tref>term</tref> or
+ the <tref>active context</tref>, <tref>null</tref>, or the one of the
+ <tref title="keyword">keywords</tref> <code>@id</code> or <code>@vocab</code>.</p>
+
+ <p>If the <tref>expanded term definition</tref> contains the <code>@language</code> <tref>keyword</tref>,
+ its value MUST have the lexical form described in [[!BCP47]] or be <tref>null</tref>.</p>
+
+ <p>If the <tref>expanded term definition</tref> contains the <code>@container</code>
+ <tref>keyword</tref>, its value MUST be either <code>@list</code>, <code>@set</code>,
+ <code>@language</code>, <code>@index</code>, or be <tref>null</tref>. If the value
+ is <code>@language</code>, when the <tref>term</tref> is used outside of the
+ <code>@context</code>, the associated value MUST be a <tref>language map</tref>.
+ If the value is <code>@index</code>, when the <tref>term</tref> is used outside of
+ the <code>@context</code>, the associated value MUST be an
+ <tref>index map</tref>.</p>
+
+ <p><tref title="term">Terms</tref> MUST NOT be used in a circular manner. That is,
+ the definition of a term cannot depend on the definition of another term if that other
+ term also depends on the first term.</p>
+
+ <p>See <a class="sectionRef" href="#the-context"></a> for further discussion on contexts.</p>
+</section>
+
+</section>
+
+<section class="appendix normative">
+ <h2>Relationship to RDF</h2>
+
+ <p>The RDF data model, as outlined in [[RDF11-CONCEPTS]], is an abstract syntax for
+ representing a directed graph of information. It is a subset of
+ <tref title="JSON-LD data model">JSON-LD's data model</tref> with a few
+ additional constraints. The differences between the two data models are:</p>
+
+ <ul>
+ <li>In JSON-LD <tref title="graph name">graph names</tref> can be
+ <tref title="IRI">IRIs</tref> or <tref title="blank node">blank nodes</tref>
+ whereas in RDF graph names have to be <tref title="IRI">IRIs</tref>.</li>
+ <li>In JSON-LD <tref title="property">properties</tref> can be
+ <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 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>
+ (<tref title="typed value">typed values</tref>) or <em>language-tagged strings</em>
+ (<tref title="language-tagged string">language-tagged strings</tref>) whereas
+ JSON-LD also supports JSON's native data types, i.e., <tref title="number">number</tref>,
+ <tref title="string">strings</tref>, and the boolean values <tref>true</tref>
+ and <tref>false</tref>. The JSON-LD Processing Algorithms and API specification [[JSON-LD-API]]
+ defines the conversion rules between JSON's native data types and RDF's counterparts to
+ allow full round-tripping.</li>
+
+ </ul>
+
+ <p>Summarized these differences mean that JSON-LD is capable of serializing any RDF
+ graph or dataset and most, but not all, JSON-LD documents can be transformed to RDF.
+ A complete description of the algorithms to convert from RDF to JSON-LD and from
+ JSON-LD to RDF is included in the JSON-LD Processing Algorithms and API specification
+ [[JSON-LD-API]].</p>
+
+ <p>Even though JSON-LD serializes RDF datasets, it can also be used as a RDF graph source.
+ In that case, a consumer MUST only use the default graph and ignore all named graphs.
+ This allows servers to expose data in, e.g., both Turtle and JSON-LD using content
+ negotiation.</p>
+
+ <p class="note">Publishers supporting both dataset and graph syntaxes have to ensure that
+ the primary data is stored in the default graph to enable consumers that do not support
+ datasets to process the information.</p>
+
+ <section class="informative">
+ <h3>Transformation from JSON-LD to RDF</h3>
+
+ <p>The process of turning a JSON-LD document depends on executing the
+ algorithms defined in
+ <cite><a href="../json-ld-api/#rdf-conversion-algorithms">RDF Conversion Algorithms</a></cite>
+ in the JSON-LD Processing Algorithms and API specification [[JSON-LD-API]].
+ It is beyond the scope of this document to detail these algorithms any further,
+ but a summary of the necessary operations is provided to illustrate the process.</p>
+
+ <p>The procedure involves the following steps:</p>
+
+ <ol>
+ <li>Expand the JSON-LD document, removing any context; this ensures
+ that properties, types, and values are given their full representation
+ as <tref title="IRI">IRIs</tref> and expanded values. Expansion
+ is discussed further in <a class="sectionRef" href="#expanded-document-form"></a>.</li>
+ <li>Flatten the document, which turns the document into an array of
+ <tref title="node object">node objects</tref>. Flattening is discussed
+ further in <a class="sectionRef" href="#flattened-document-form"></a>.</li>
+ <li>Turn each <tref>node object</tref> into a series of
+ <tref href="http://www.w3.org/TR/rdf11-concepts/#dfn-rdf-triple">RDF triples</tref>.</li>
+ </ol>
+
+ <p>For example, consider the following JSON-LD document in compact form:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Sample JSON-LD document">
+ <!--
+ {
+ "@context": {
+ "name": "http://xmlns.com/foaf/0.1/name",
+ "knows": "http://xmlns.com/foaf/0.1/knows"
+ },
+ "@id": "http://me.markus-lanthaler.com/",
+ "name": "Markus Lanthaler",
+ "knows": [
+ {
+ "@id": "http://manu.sporny.org/",
+ "name": "Manu Sporny"
+ },
+ {
+ "name": "Dave Longley"
+ }
+ ]
+ }
+ -->
+ </pre>
+
+ <p>Running the JSON-LD Expansion and Flattening algorithms against the
+ JSON-LD input document in the example above would result in the
+ following output:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Flattened and expanded form for the previous example">
+ <!--
+ [
+ {
+ "@id": "_:b0",
+ "http://xmlns.com/foaf/0.1/name": "Dave Longley"
+ },
+ {
+ "@id": "http://manu.sporny.org/",
+ "http://xmlns.com/foaf/0.1/name": "Manu Sporny"
+ },
+ {
+ "@id": "http://me.markus-lanthaler.com/",
+ "http://xmlns.com/foaf/0.1/name": "Markus Lanthaler",
+ "http://xmlns.com/foaf/0.1/knows": [
+ { "@id": "http://manu.sporny.org/" },
+ { "@id": "_:b0" }
+ ]
+ }
+ ]
+ -->
+ </pre>
+
+ <p>Transforming this to RDF now is a straightforward process of turning
+ each <tref>node object</tref> into one or more RDF triples. This can be
+ expressed in Turtle as follows:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Turtle representation of expanded/flattend document">
+ <!--
+ _:b0 <http://xmlns.com/foaf/0.1/name> "Dave Longley" .
+
+ <http://manu.sporny.org/> <http://xmlns.com/foaf/0.1/name> "Manu Sporny" .
+
+ <http://me.markus-lanthaler.com/> <http://xmlns.com/foaf/0.1/name> "Markus Lanthaler" ;
+ <http://xmlns.com/foaf/0.1/knows> <http://manu.sporny.org/>, _:b0 .
+ -->
+ </pre>
+
+ <p>The process of turning RDF into JSON-LD can be thought of as the
+ inverse of this last step, creating an expanded JSON-LD document closely
+ matching the triples from RDF, using a single <tref>node object</tref>
+ for all triples having a common subject, and a single <tref>property</tref>
+ for those triples also having a common predicate.</p>
+ </section>
+</section>
+
+<section class="appendix informative">
+ <h2>Relationship to Other Linked Data Formats</h2>
+
+ <p>The JSON-LD examples below demonstrate how JSON-LD can be used to
+ express semantic data marked up in other linked data formats such as Turtle,
+ RDFa, Microformats, and Microdata. These sections are merely provided as
+ evidence that JSON-LD is very flexible in what it can express across different
+ <tref>Linked Data</tref> approaches.</p>
+
+ <section class="informative">
+ <h3>Turtle</h3>
+
+ <p>The following are examples of converting RDF expressed in Turtle [[TURTLE]]
+ into JSON-LD.</p>
+
+ <section>
+ <h4>Prefix definitions</h4>
+
+ <p>The JSON-LD context has direct equivalents for the Turtle
+ <code>@prefix</code> declaration:</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="A set of statements serialized in Turtle">
+ <!--
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+ <http://manu.sporny.org/i/public> a foaf:Person;
+ foaf:name "Manu Sporny";
+ foaf:homepage <http://manu.sporny.org/> .
+ -->
+ </pre>
+
+ <pre class="example" data-transform="updateExample"
+ title="The same set of statements serialized in JSON-LD">
+ <!--
+ {
+ "@context":
+ {
+ "foaf": "http://xmlns.com/foaf/0.1/"
+ },
+ "@id": "http://manu.sporny.org/i/public",
+ "@type": "foaf:Person",
+ "foaf:name": "Manu Sporny",
+ "foaf:homepage": { "@id": "http://manu.sporny.org/" }
+ }
+ -->
+ </pre>
+ </section>
+
+ <section>
+ <h4>Embedding</h4>
+
+ <p>Both Turtle and JSON-LD allow embedding, although Turtle only allows embedding of
+ <tref title="blank node">blank nodes</tref>.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Embedding in Turtle">
+ <!--
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+ <http://manu.sporny.org/i/public>
+ a foaf:Person;
+ foaf:name "Manu Sporny";
+ foaf:knows [ a foaf:Person; foaf:name "Gregg Kellogg" ] .
+ -->
+ </pre>
+
+ <pre class="example" data-transform="updateExample"
+ title="Same embedding example in JSON-LD">
+ <!--
+ {
+ "@context":
+ {
+ "foaf": "http://xmlns.com/foaf/0.1/"
+ },
+ "@id": "http://manu.sporny.org/i/public",
+ "@type": "foaf:Person",
+ "foaf:name": "Manu Sporny",
+ "foaf:knows":
+ {
+ "@type": "foaf:Person",
+ "foaf:name": "Gregg Kellogg"
+ }
+ }
+ -->
+ </pre>
+ </section>
+
+ <section>
+ <h4>Conversion of native data types</h4>
+
+ <p>In JSON-LD numbers and boolean values are native data types. While Turtle
+ has a shorthand syntax to express such values, RDF's abstract syntax requires
+ that numbers and boolean values are represented as typed literals. Thus,
+ to allow full round-tripping, the JSON-LD Processing Algorithms and API specification [[JSON-LD-API]]
+ defines conversion rules between JSON-LD's native data types and RDF's
+ counterparts. <tref title="number">Numbers</tref> without fractions are
+ converted to <code>xsd:integer</code>-typed literals, numbers with fractions
+ to <code>xsd:double</code>-typed literals and the two boolean values
+ <tref>true</tref> and <tref>false</tref> to a <code>xsd:boolean</code>-typed
+ literal. All typed literals are in canonical lexical form.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="JSON-LD using native data types for numbers and boolean values">
+ <!--
+ {
+ "@context":
+ {
+ "ex": "http://example.com/vocab#"
+ },
+ "@id": "http://example.com/",
+ "ex:numbers": [ 14, 2.78 ],
+ "ex:booleans": [ true, false ]
+ }
+ -->
+ </pre>
+
+ <pre class="example" data-transform="updateExample"
+ title="Same example in Turtle using typed literals">
+ <!--
+ @prefix ex: <http://example.com/vocab#> .
+ @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ <http://example.com/>
+ ex:numbers "14"^^xsd:integer, "2.78E0"^^xsd:double ;
+ ex:booleans "true"^^xsd:boolean, "false"^^xsd:boolean .
+ -->
+ </pre>
+
+ </section>
+
+ <section>
+ <h4>Lists</h4>
+ <p>Both JSON-LD and Turtle can represent sequential lists of values.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="A list of values in Turtle">
+ <!--
+ @prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+ <http://example.org/people#joebob> a foaf:Person;
+ foaf:name "Joe Bob";
+ foaf:nick ( "joe" "bob" "jaybee" ) .
+ -->
+ </pre>
+
+ <pre class="example" data-transform="updateExample"
+ title="Same example with a list of values in JSON-LD">
+ <!--
+ {
+ "@context":
+ {
+ "foaf": "http://xmlns.com/foaf/0.1/"
+ },
+ "@id": "http://example.org/people#joebob",
+ "@type": "foaf:Person",
+ "foaf:name": "Joe Bob",
+ "foaf:nick":
+ {
+ "@list": [ "joe", "bob", "jaybee" ]
+ }
+ }
+ -->
+ </pre>
+ </section>
+ </section>
+
+ <section class="informative">
+ <h3>RDFa</h3>
+
+ <p>The following example describes three people with their respective names and
+ homepages in RDFa [[RDFA-CORE]].</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="RDFa fragment that describes three people">
+ <!--
+ <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>
+ </li>
+ <li ****typeof="foaf:Person"****>
+ <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>
+ </li>
+ </ul>
+ </div>
+ -->
+ </pre>
+
+ <p>An example JSON-LD implementation using a single <tref>context</tref> is
+ described below.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Same description in JSON-LD (context shared among node objects)">
+ <!--
+ {
+ "@context":
+ {
+ "foaf": "http://xmlns.com/foaf/0.1/"
+ },
+ "@graph":
+ [
+ {
+ "@type": "foaf:Person",
+ "foaf:homepage": "http://example.com/bob/",
+ "foaf:name": "Bob"
+ },
+ {
+ "@type": "foaf:Person",
+ "foaf:homepage": "http://example.com/eve/",
+ "foaf:name": "Eve"
+ },
+ {
+ "@type": "foaf:Person",
+ "foaf:homepage": "http://example.com/manu/",
+ "foaf:name": "Manu"
+ }
+ ]
+ }
+ -->
+ </pre>
+ </section>
+
+ <section class="informative">
+ <h3>Microformats</h3>
+
+ <p>The following example uses a simple Microformats hCard example to express
+ how Microformats [[MICROFORMATS]] are represented in JSON-LD.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="HTML fragment with a simple Microformats hCard">
+ <!--
+ <div class="vcard">
+ <a class="url fn" href="http://tantek.com/">Tantek Çelik</a>
+ </div>
+ -->
+ </pre>
+
+ <p>The representation of the hCard expresses the Microformat terms in the
+ <tref>context</tref> and uses them directly for the <code>url</code> and <code>fn</code>
+ properties. Also note that the Microformat to JSON-LD processor has
+ generated the proper URL type for <code>http://tantek.com/</code>.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Same hCard representation in JSON-LD">
+ <!--
+ {
+ "@context":
+ {
+ "vcard": "http://microformats.org/profile/hcard#vcard",
+ "url":
+ {
+ "@id": "http://microformats.org/profile/hcard#url",
+ "@type": "@id"
+ },
+ "fn": "http://microformats.org/profile/hcard#fn"
+ },
+ "@type": "vcard",
+ "url": "http://tantek.com/",
+ "fn": "Tantek Çelik"
+ }
+ -->
+ </pre>
+ </section>
+
+ <section class="informative">
+ <h3>Microdata</h3>
+
+ <p>The HTML Microdata [[MICRODATA]] example below expresses book information as
+ a Microdata Work item.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="HTML fragments that describes a book using microdata">
+ <!--
+ <dl itemscope
+ itemtype="http://purl.org/vocab/frbr/core#Work"
+ itemid="http://purl.oreilly.com/works/45U8QJGZSQKDH8N">
+ <dt>Title</dt>
+ <dd><cite itemprop="http://purl.org/dc/terms/title">Just a Geek</cite></dd>
+ <dt>By</dt>
+ <dd><span itemprop="http://purl.org/dc/terms/creator">Wil Wheaton</span></dd>
+ <dt>Format</dt>
+ <dd itemprop="http://purl.org/vocab/frbr/core#realization"
+ itemscope
+ itemtype="http://purl.org/vocab/frbr/core#Expression"
+ itemid="http://purl.oreilly.com/products/9780596007683.BOOK">
+ <link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/BOOK">
+ Print
+ </dd>
+ <dd itemprop="http://purl.org/vocab/frbr/core#realization"
+ itemscope
+ itemtype="http://purl.org/vocab/frbr/core#Expression"
+ itemid="http://purl.oreilly.com/products/9780596802189.EBOOK">
+ <link itemprop="http://purl.org/dc/terms/type" href="http://purl.oreilly.com/product-types/EBOOK">
+ Ebook
+ </dd>
+ </dl>
+ -->
+ </pre>
+
+ <p>Note that the JSON-LD representation of the Microdata information stays
+ true to the desires of the Microdata community to avoid contexts and
+ instead refer to items by their full <tref>IRI</tref>.</p>
+
+ <pre class="example" data-transform="updateExample"
+ title="Same book description in JSON-LD (avoiding contexts)">
+ <!--
+ [
+ {
+ "@id": "http://purl.oreilly.com/works/45U8QJGZSQKDH8N",
+ "@type": "http://purl.org/vocab/frbr/core#Work",
+ "http://purl.org/dc/terms/title": "Just a Geek",
+ "http://purl.org/dc/terms/creator": "Whil Wheaton",
+ "http://purl.org/vocab/frbr/core#realization":
+ [
+ "http://purl.oreilly.com/products/9780596007683.BOOK",
+ "http://purl.oreilly.com/products/9780596802189.EBOOK"
+ ]
+ },
+ {
+ "@id": "http://purl.oreilly.com/products/9780596007683.BOOK",
+ "@type": "http://purl.org/vocab/frbr/core#Expression",
+ "http://purl.org/dc/terms/type": "http://purl.oreilly.com/product-types/BOOK"
+ },
+ {
+ "@id": "http://purl.oreilly.com/products/9780596802189.EBOOK",
+ "@type": "http://purl.org/vocab/frbr/core#Expression",
+ "http://purl.org/dc/terms/type": "http://purl.oreilly.com/product-types/EBOOK"
+ }
+ ]
+ -->
+ </pre>
+ </section>
+</section>
+
+<section class="appendix normative">
+ <h2>IANA Considerations</h2>
+
+ <p>This section is included for community review and will be submitted to the
+ Internet Engineering Steering Group (IESG) as part of the Last Call announcement
+ for this specification.</p>
+
+ <h3>application/ld+json</h3>
+ <dl>
+ <dt>Type name:</dt>
+ <dd>application</dd>
+ <dt>Subtype name:</dt>
+ <dd>ld+json</dd>
+ <dt>Required parameters:</dt>
+ <dd>None</dd>
+ <dt>Optional parameters:</dt>
+ <dd>
+ <dl>
+ <dt><code>profile</code></dt>
+ <dd>
+ <p>A whitespace-separated list of IRIs identifying specific constraints
+ or conventions that apply to a JSON-LD document. A profile MUST NOT change
+ the semantics of the resource representation when processed without profile
+ knowledge, so that clients both with and without knowledge of a profiled
+ resource can safely use the same representation. The <code>profile</code>
+ parameter MAY also be used by clients to express their preferences in the
+ content negotiation process. It is RECOMMENDED that profile IRIs are
+ dereferenceable and provide useful documentation at that IRI. For more
+ information and background please refer to [[RFC6906]].</p>
+ <p>This specification defines four values for the <code>profile</code> parameter.
+ To request or specify Expanded JSON-LD document form, the IRI
+ <code>http://www.w3.org/ns/json-ld#expanded</code> SHOULD be used.
+ To request or specify Expanded, Flattened JSON-LD document form, the IRI
+ <code>http://www.w3.org/ns/json-ld#expanded-flattened</code> SHOULD
+ be used. To request or specify Compacted JSON-LD document form, the IRI
+ <code>http://www.w3.org/ns/json-ld#compacted</code> SHOULD be used.
+ To request or specify Compacted, Flattened JSON-LD document form, the IRI
+ <code>http://www.w3.org/ns/json-ld#compacted-flattened</code> SHOULD be used.
+ Please note that, according [[HTTP11]], the value of the <code>profile</code>
+ parameter has to be enclosed in quotes (<code>"</code>) because it contains
+ special characters and, in some cases, whitespace.</p>
+ </dd>
+ </dl>
+ </dd>
+ <dt>Encoding considerations:</dt>
+ <dd>See RFC 6839, section 3.1.</dd>
+ <dt>Security considerations:</dt>
+ <dd>Since JSON-LD is intended to be a pure data exchange format for
+ directed graphs, the serialization SHOULD NOT be passed through a
+ code execution mechanism such as JavaScript's <code>eval()</code>
+ function to be parsed.<br/>
+ JSON-LD contexts that are loaded from the Web over non-secure connections,
+ such as HTTP, run the risk of modifying the JSON-LD
+ <tref>active context</tref> in a way that could compromise security. It
+ is advised that any application that depends on a remote context for mission
+ critical purposes vet and cache the remote context before allowing the
+ system to use it.<br />
+ Given that JSON-LD allows the substitution of long IRIs with short terms,
+ JSON-LD documents may expand considerably when processed and, in the worst case,
+ the resulting data might consume all of the recipient's resources. Applications
+ should treat any data with due skepticism.
+ </dd>
+ <dt>Interoperability considerations:</dt>
+ <dd>Not Applicable</dd>
+ <dt>Published specification:</dt>
+ <dd>http://www.w3.org/TR/json-ld</dd>
+ <dt>Applications that use this media type:</dt>
+ <dd>Any programming environment that requires the exchange of
+ directed graphs. Implementations of JSON-LD have been created for
+ JavaScript, Python, Ruby, PHP, and C++.
+ </dd>
+ <dt>Additional information:</dt>
+ <dd>
+ <dl>
+ <dt>Magic number(s):</dt>
+ <dd>Not Applicable</dd>
+ <dt>File extension(s):</dt>
+ <dd>.jsonld</dd>
+ <dt>Macintosh file type code(s):</dt>
+ <dd>TEXT</dd>
+ </dl>
+ </dd>
+ <dt>Person & email address to contact for further information:</dt>
+ <dd>Manu Sporny <msporny@digitalbazaar.com></dd>
+ <dt>Intended usage:</dt>
+ <dd>Common</dd>
+ <dt>Restrictions on usage:</dt>
+ <dd>None</dd>
+ <dt>Author(s):</dt>
+ <dd>Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Niklas Lindström</dd>
+ <dt>Change controller:</dt>
+ <dd>W3C</dd>
+ </dl>
+
+ <p>Fragment identifiers used with <a href="#application-ld-json">application/ld+json</a>
+ are treated as in RDF syntaxes, as per
+ <cite><a href="http://www.w3.org/TR/rdf11-concepts/#section-fragID">RDF 1.1 Concepts and Abstract Syntax</a></cite>
+ [[RDF11-CONCEPTS]].</p>
+</section>
+
+<section class="appendix informative">
+ <h2>Acknowledgements</h2>
+
+ <p>The authors would like to extend a deep appreciation and the most sincere
+ thanks to Mark Birbeck, who contributed foundational concepts
+ to JSON-LD via his work on RDFj. JSON-LD uses a number of core concepts
+ introduced in RDFj, such as the context as a mechanism to provide an
+ environment for interpreting JSON data. Mark had also been very involved in
+ the work on RDFa as well. RDFj built upon that work. JSON-LD exists
+ because of the work and ideas he started nearly a decade ago in 2004.</p>
+
+ <p>A large amount of thanks goes out to the JSON-LD Community Group
+ participants who worked through many of the technical issues on the mailing
+ list and the weekly telecons - of special mention are François Daoust,
+ Stéphane Corlosquet, Lin Clark, and Zdenko 'Denny' Vrandečić.</p>
+
+ <p>The work of David I. Lehn and Mike Johnson are appreciated for
+ reviewing, and performing several early implementations
+ of the specification. Thanks also to Ian Davis for this work on RDF/JSON.</p>
+
+ <p>Thanks to the following individuals, in order of their first name, for
+ their input on the specification: Adrian Walker, Alexandre Passant,
+ Andy Seaborne, Ben Adida, Blaine Cook, Bradley Allen, Brian Peterson,
+ Bryan Thompson, Conal Tuohy, Dan Brickley, Danny Ayers, Daniel Leja,
+ Dave Reynolds, David I. Lehn, David Wood, Dean Landolt, Ed Summers, elf Pavlik,
+ Eric Prud'hommeaux, Erik Wilde, Fabian Christ, Jon A. Frost, Gavin Carothers,
+ Glenn McDonald, Guus Schreiber, Henri Bergius, Jose María Alvarez Rodríguez,
+ Ivan Herman, Jack Moffitt, Josh Mandel, KANZAKI Masahide, Kingsley Idehen,
+ Kuno Woudt, Larry Garfield, Mark Baker, Mark MacGillivray, Marko Rodriguez,
+ Melvin Carvalho, Nathan Rixham, Olivier Grisel, Paolo Ciccarese, Pat Hayes,
+ Patrick Logan, Paul Kuykendall, Pelle Braendgaard, Peter Williams, Pierre-Antoine Champin,
+ Richard Cyganiak, Roy T. Fielding, Sandro Hawke, Srecko Joksimovic,
+ Stephane Fellah, Steve Harris, Ted Thibodeau Jr., Thomas Steiner, Tim Bray,
+ Tom Morris, Tristan King, Sergio Fernández, Werner Wilms, and William Waites.</p>
+</section>
+
+</body>
+</html>
Binary file spec/latest/json-ld/linked-data-graph.dia has changed
Binary file spec/latest/json-ld/linked-data-graph.png has changed
--- a/spec/latest/rdf-graph-normalization/index.html Thu Mar 28 14:29:18 2013 +0100
+++ b/spec/latest/rdf-graph-normalization/index.html Thu Mar 28 15:14:23 2013 +0100
@@ -12,7 +12,7 @@
berjon.biblio["MICRODATA"] = "Ian Hickson; et al. <a href=\"http://www.w3.org/TR/microdata/\"><cite>Microdata</cite></a> 04 March 2010. W3C Working Draft. URL: <a href=\"http://www.w3.org/TR/microdata/\">http://www.w3.org/TR/microdata/</a> ";
berjon.biblio["HTML-RDFA"] = "Manu Sporny; et al. <a href=\"http://www.w3.org/TR/rdfa-in-html/\"><cite>HTML+RDFa</cite></a> 04 March 2010. W3C Working Draft. URL: <a href=\"http://www.w3.org/TR/rdfa-in-html/\">http://www.w3.org/TR/rdfa-in-html/</a> ";
berjon.biblio["BCP47"] = "A. Phillips, M. Davis. <a href=\"http://tools.ietf.org/rfc/bcp/bcp47.txt\"><cite>Tags for Identifying Languages</cite></a> September 2009. IETF Best Current Practice. URL: <a href=\"http://tools.ietf.org/rfc/bcp/bcp47.txt\">http://tools.ietf.org/rfc/bcp/bcp47.txt</a>";
- berjon.biblio["JSON-LD"] = "Manu Sporny, Gregg Kellogg, Markus Lanthaler. <a href=\"http://json-ld.org/spec/latest/json-ld-syntax/\"><cite>The JSON-LD Syntax</cite></a> Latest. W3C Editor's Draft. URL: <a href=\"http://json-ld.org/spec/latest/json-ld-syntax/\">http://json-ld.org/spec/latest/json-ld-syntax/</a>";
+ berjon.biblio["JSON-LD"] = "Manu Sporny, Gregg Kellogg, Markus Lanthaler. <a href=\"http://json-ld.org/spec/latest/json-ld/\"><cite>The JSON-LD Syntax</cite></a> Latest. W3C Editor's Draft. URL: <a href=\"http://json-ld.org/spec/latest/json-ld/\">http://json-ld.org/spec/latest/json-ld/</a>";
berjon.biblio["RDF-API"] = "Manu Sporny, Benjamin Adrian, Nathan Rixham; et al. <a href=\"http://www.w3.org/2010/02/rdfa/sources/rdf-api/\"><cite>RDF API</cite></a> Latest. W3C Editor's Draft. URL: <a href=\"http://www.w3.org/2010/02/rdfa/sources/rdf-api/\">http://www.w3.org/2010/02/rdfa/sources/rdf-api/</a>";
berjon.biblio["RDF-INTERFACES"] = "Nathan Rixham, Manu Sporny, Benjamin Adrian; et al. <a href=\"http://www.w3.org/2010/02/rdfa/sources/rdf-interfaces/\"><cite>RDF Interfaces</cite></a> Latest. W3C Editor's Draft. URL: <a href=\"http://www.w3.org/2010/02/rdfa/sources/rdf-interfaces/\">http://www.w3.org/2010/02/rdfa/sources/rdf-interfaces/</a>";
