--- a/spec/latest/json-ld-syntax/index.html Mon Nov 12 12:55:44 2012 -0500
+++ b/spec/latest/json-ld-syntax/index.html Tue Nov 13 07:40:15 2012 -0800
@@ -185,10 +185,10 @@
it introduces:</p>
<ul>
- <li>a universal identifier mechanism for <tref>JSON object</tref>s via the
- use of <tref>IRI</tref>s,</li>
+ <li>a universal identifier mechanism for <tref title="JSON object">JSON objects</tref> via the
+ use of <tref title="IRI">IRIs</tref>,</li>
<li>a way to disambiguate the keys used between multiple JSON documents
- by mapping them to <tref>IRI</tref>s via a <tref>context</tref>,</li>
+ 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 express the language associated with a <tref>string</tref></li>
@@ -297,10 +297,7 @@
</section>
<section class="normative">
-<h1>Basic Concepts</h1>
-
-<section>
-<h2>JSON-LD Data Model</h2>
+<h1>JSON-LD Data Model</h1>
<p>JSON-LD is a way of expressing <tref>Linked Data</tref> on the Web. The
JSON-LD data model encapsulates the following concepts:</p>
@@ -332,19 +329,22 @@
<p>There are a number of best practices that can ensure that developers
will generate good <tref>Linked Data</tref> for the Web. JSON-LD
formalizes those techniques by providing a mechanism to map JSON data,
- i.e., keys and values, to <tref>IRI</tref>s. This does not mean
+ i.e., keys and values, to <tref title="IRI">IRIs</tref>. This does not mean
that JSON-LD requires every key or value to be an IRI, but rather ensures that
keys and values can be mapped to IRIs if the developer desires to transform
their data into <tref>Linked Data</tref>.</p>
</section>
+<section class="normative">
+<h1>Terminology</h1>
+
<section>
- <h2>General Terminology</h3>
-
- <p>The following is an explanation of the general terminology used in this
- document. Many of the terms should be familiar to developers that have
- used JSON:</p>
+ <h2>General Terminology</h2>
+
+ <p>This document uses terms defined in JSON [[!RFC4627]] described in the
+ following list. Refer to the JSON grammar section in JSON for formal
+ definitions.</p>
<dl>
<dt><tdef>JSON object</tdef></dt><dd>
@@ -352,18 +352,17 @@
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. The keys within an object SHOULD be unique.
+ key.
</dd>
<dt><tdef>array</tdef></dt>
<dd>
+ An array structure is represented as square brackets surrounding zero
+ or more values (or elements). Elements are separated by commas.
In JSON, an array is an <em>ordered</em> sequence of zero or more values.
- An array is represented as square brackets surrounding
- zero or more values that are separated by commas.
While JSON-LD uses the same array representation as JSON,
the collection is <em>unordered</em> by default. While order is
preserved in regular JSON arrays, it is not in regular JSON-LD arrays
- unless specific markup is provided
- (see <a href="#sets-and-lists"></a>).</dd>
+ unless specific markup is provided (see <a href="#sets-and-lists"></a>).</dd>
<dt><tdef>string</tdef></dt><dd>
A string is a sequence of zero or more Unicode characters,
wrapped in double quotes, using backslash escapes (if necessary). A
@@ -376,25 +375,12 @@
<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 <code>null</code> value is processed in a special way in JSON-LD.
- Unless otherwise specified, a JSON-LD processor MUST act as if a
- key-value pair in the body of a JSON-LD document was never declared
- when the value equals <em>null</em>. If <code>@value</code>,
+ <dd>The <code>null</code> value. Unless otherwise specified, a key-value
+ pair in the body of a JSON-LD document whose value is <em>null</em>
+ 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 <em>null</em> in
expanded form, then the entire <tref>JSON object</tref> is ignored.</dd>
- <dt><tdef>node definition</tdef></dt><dd>
- A <tref>JSON object</tref> used to represent a <tref>node</tref> and
- one or more properties of that node. A <tref>JSON object</tref> is a
- node definition if it does not contain the keys <code>@value</code>,
- <code>@list</code> or <code>@set</code> and it has one or more keys other
- than <code>@id</code>. A node definition MAY be spread among different
- parts of a document or even between different documents.</dd>
- <dt><tdef>node reference</tdef></dt><dd>
- A <tref>JSON object</tref> used to refer to a node that contains a
- single key-value pair where the key is <code>@id</code>.</dd>
</dl>
-</p>
-
</section>
<section>
@@ -406,7 +392,7 @@
<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>term</tref>s and help
+ document. These short-hand names are called <tref title="term">terms</tref> and help
developers to express specific identifiers in a compact manner. The
<code>@context</code> keyword is described in detail in the section titled
<a href="#the-context"></a>.</dd>
@@ -449,20 +435,30 @@
case-sensitive.</p>
</section>
+</section>
+
+<section class="normative">
+<h1>Conformance</h1>
+
+<p>The JSON-LD Syntax specification describes the conformance criteria for JSON-LD documents (relevant to authors and authoring tool implementors).</p>
+
+<p>A <tdef>JSON-LD document</tdef> complies with this specification if it follows the normative statements for documents defined in sections <a href="#referencing-contexts-from-json-documents"></a> and <a href="#json-ld-grammar"></a>. For convenience, normative statements for documents are often phrased as statements on the properties of the document.</p>
+
+<p>The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this Recommendation have the meaning defined in [[!RFC2119]].</p>
+
+</section>
+
+<section class="normative">
+<h1>Basic Concepts</h1>
+
<section>
<h2>The Context</h2>
-<p>In JSON-LD, a <tdef>context</tdef> is used to map <tref>term</tref>s, i.e., properties with associated
- values in an JSON document, to <tref>IRI</tref>s. A <tdef>term</tdef> is a short word that expands to an
- <tref>IRI</tref>. <tref>Term</tref>s MAY be defined as any valid JSON <tref>string</tref> other
- than a JSON-LD <tref>keyword</tref>. To avoid
- forward-compatibility issues, <tref>term</tref>s starting with an <code>@</code> character SHOULD NOT be used
- as they might be used as <tref title="keyword">keywords</tref> in future versions of JSON-LD. Furthermore,
- the use of empty terms (<code>""</code>) is discouraged as not all programming languages are able to handle
- empty property names.</p>
+<p>In JSON-LD, a <tdef>context</tdef> is used to map <tref title="term">terms</tref>, i.e., properties with associated
+ values in an JSON document, to <tref title="IRI">IRIs</tref>.</p>
<p>The Web uses <tref title="IRI">IRIs</tref> for unambiguous identification. The
- idea is that these <tref>term</tref>s mean 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>term</tref>s to expand to IRIs so that
+ idea is that these <tref title="term">terms</tref> mean 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 IRIs so that
developers don't accidentally step on each other's <tdef>vocabulary</tdef> terms and other resources. Furthermore, developers, and
machines, are able to use this <tref>IRI</tref> (by plugging it directly into a web browser, for instance) to go to
the term and get a definition of what the term means. This mechanism is analogous to the way we can use
@@ -471,15 +467,16 @@
ensure that these terms are unambiguous. For example, the term <code>name</code> may
map directly to the IRI <code>http://xmlns.com/foaf/0.1/name</code>. This allows JSON-LD documents to be constructed
using the common JSON practice of simple key-value pairs while ensuring that the data is useful outside of the
- page, API or database in which it resides. The value of a term mapping
- MUST be either; 1) a simple string with the lexical form of an <tref>absolute IRI</tref> or
- 2) <tref>compact IRI</tref>, or 3) an <tref>JSON object</tref> containing an
- <code>@id</code>, <code>@type</code>, <code>@language</code>, or <code>@container</code> keyword
- (all other keywords are ignored by a JSON-LD processor).
+ page, API or database in which it resides.</p>
+
+<p>Note that, to avoid forward-compatibility issues, terms starting with an <code>@</code> character are to be avoided as they might be used as keywords in future versions of JSON-LD. Furthermore, the use of empty <tref title="term">terms</tref> (<code>""</code>)
+ is discouraged as not all programming languages are able to handle empty
+ property names.
</p>
-<p>These Linked Data <tref>term</tref>s are typically collected in a
-context document that would look something like this:</p>
+<p>In a JSON-LD document, the mapping between <tref title="term">terms</tref> and
+ <tref title="IRI">IRIs</tref> is typically collected in a <tref>context definition</tref>
+ that would look something like this:</p>
<pre class="example" data-transform="updateExample"
title="Context definition">
@@ -541,18 +538,19 @@
developers use the same IRI to describe a property, they are more than likely
expressing the same concept. This allows both developers to re-use each others'
data without having to agree to how their data will interoperate on a
-site-by-site basis. Contexts may also contain type information
-for certain <tref>term</tref>s as well as other processing instructions for
-the JSON-LD processor.</p>
-
-<p>External JSON-LD context documents MAY contain extra information
+site-by-site basis. Contexts may also contain type, language or additional information
+for certain <tref title="term">terms</tref>.</p>
+
+<p>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. When importing a
-<code>@context</code> value from an external JSON-LD context document, any extra
-information contained outside of the <code>@context</code> value MUST be discarded.</p>
-
-<p>Contexts MAY be specified in-line. This ensures that JSON-LD documents
-can be processed when a JSON-LD processor does not have access to the Web.</p>
+<tref title="term">terms</tref> declared in the document. Information contained
+outside of the <code>@context</code> value is simply discarded when the document
+is used as an external JSON-LD context document
+(see <a href="#referencing-contexts-from-json-documents"></a>).</p>
+
+<p>Contexts may also be specified in-line. This ensures that
+ <tref title="JSON-LD document">JSON-LD documents</tref> can be understood
+ even in the absence of a connection to the Web.</p>
<pre class="example" data-transform="updateExample"
title="In-line context definition">
@@ -579,12 +577,12 @@
-->
</pre>
-<p>Contexts MAY be used at any time a <tref>node definition</tref> is defined.
- A <tref>node definition</tref> MAY specify multiple contexts, using an
- <tref>array</tref>, which is processed in order. This is useful
- when an author would like to use an existing context and add
- application-specific terms to the existing context. Duplicate context
- <tref>term</tref>s MUST be overridden using a last-defined-overrides
+<p>Contexts may be used at any time a <tref>node definition</tref> is defined.
+ A <tref>node definition</tref> may specify multiple contexts, using an
+ <tref>array</tref>, processed in order.
+ This is useful when an author would like to use an existing context
+ and add application-specific terms to the existing context. Duplicate context
+ <tref title="term">terms</tref> are overridden using a last-defined-overrides
mechanism.</p>
<pre class="example" data-transform="updateExample"
@@ -615,13 +613,14 @@
legacy applications that depend on the specific structure of the
<tref>JSON object</tref>. If a <tref>term</tref> is re-defined within a
context, all previous rules associated with the previous definition are
- removed. A <tref>term</tref> defined in a previous context MUST be removed,
- if it is re-defined to <code>null</code>.</p>
+ removed. If that <tref>term</tref> is re-defined 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>The set of contexts defined within a specific <tref>node definition</tref> are
- referred to as <tdef>local context</tdef>s. Setting the context to <code>null</code>
+ referred to as <tdef title="local context">local contexts</tdef>. Setting the context to <code>null</code>
effectively resets the <tref>active context</tref> to an empty context. The
- <tdef>active context</tdef> refers to the accumulation of <tref>local context</tref>s
+ <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. The following example
specifies an external context and then layers a local context on top of the external
context:</p>
@@ -654,7 +653,7 @@
<section>
<h2>From JSON to JSON-LD</h2>
-<p>If a set of <tref>term</tref>s such as, <strong>name</strong>,
+<p>If a set of <tref title="term">terms</tref> such as, <strong>name</strong>,
<strong>homepage</strong>, and <strong>depiction</strong>,
are defined in a <tref>context</tref>, and that context is used to resolve the
names in <tref title="JSON object">JSON objects</tref>, machines are able to automatically expand the terms to
@@ -684,7 +683,7 @@
<tref>node definition</tref>. <tref title="node definition">Node definitions</tref>
do not require an <code>@id</code>.
<tref title="node definition">Node definitions</tref> that do not
- contain an <code>@id</code> are known as an <tref title="unlabeled node">unlabeled nodes</tref>.</p>
+ contain an <code>@id</code> are known as <tref title="unlabeled node">unlabeled nodes</tref>.</p>
</section>
@@ -693,13 +692,12 @@
<p><tdef title="IRI"><abbr title="Internationalized Resource Identifier">IRIs</abbr></tdef>
(Internationalized Resource Identifiers are fundamental to <tref>Linked Data</tref> as
- that is how most <tref title="node">nodes</tref>s and <tref title="property">properties</tref>
- are identified. <tref>IRI</tref>s can be expressed in a variety of different ways in JSON-LD:</p>
+ that is how most <tref title="node">nodes</tref> and <tref title="property">properties</tref>
+ are identified. <tref title="IRI">IRIs</tref> can be expressed in a variety of different ways in JSON-LD:</p>
<ol>
<li>Except within a <tref>context</tref> definition, <tref title="term">terms</tref> in the
- key position in a <tref>JSON object</tref> that have a mapping in the <tref>active context</tref>
- are expanded to an <tref>IRI</tref> by JSON-LD processors. If there's a <code>@vocab</code>
+ key position in a <tref>JSON object</tref> that have a mapping in the <tref>active context</tref> expand to an <tref>IRI</tref>. If there's a <code>@vocab</code>
mapping in the active context also <tref title="term">terms</tref> without an explicit mapping
in the active context are expanded to an <tref>IRI</tref>.</li>
<li>An <tref>IRI</tref> is generated for the <tref>string</tref> value specified using
@@ -708,12 +706,11 @@
are <tref>coercion</tref> rules in effect that identify the value as an <code>@id</code>.</li>
</ol>
-<p>IRIs may be represented as an <tref>absolute IRI</tref>, a <tref>relative IRI</tref>,
- a <tref>compact IRI</tref>, or a <tref>term</tref>.</p>
+<p>IRIs may be represented as an <tref>absolute IRI</tref> or a <tref>relative IRI</tref>.</p>
<p>An <tdef>absolute IRI</tdef> is defined in [[!RFC3987]] 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>relative IRI</tref>s are resolved relative to the
+ 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 (typically, the directory that contains the document or the document itself).</p>
<p>IRIs can be expressed directly in the key position like so:</p>
@@ -753,14 +750,14 @@
-->
</pre>
-<p><tref>Term</tref>s are case sensitive, and MUST be matched using a case-sensitive comparison.</p>
+<p><tref title="term">Terms</tref> are case sensitive.</p>
<p>JSON keys that do not expand to an absolute IRI are ignored, or removed
in some cases, by the [[JSON-LD-API]]. However, JSON keys that do not include
a mapping in the <tref>context</tref> are still considered valid expressions
in JSON-LD documents - the keys just don't expand to unambiguous identifiers.</p>
-<p><tref>Prefix</tref>es are expanded when the form of the value is a
+<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, and the prefix matches a <tref>term</tref> defined within the
<tref>active context</tref>:</p>
@@ -786,8 +783,7 @@
<p>It is often common that all types and properties come from the same vocabulary. JSON-LD's
<code>@vocab</code> keyword allows to set a common prefix to be used for all properties and types
that neither match a <tref>term</tref> nor a <tref>compact IRI</tref> or an <tref>absolute IRI</tref>
- (i.e., do not contain a colon). The <code>@vocab</code> mapping MUST have a value of a simple string with the
- lexical form of an absolute IRI.</p>
+ (i.e., do not contain a colon).</p>
<pre class="example" data-transform="updateExample"
title="Using a common vocabulary prefix">
@@ -820,7 +816,7 @@
<code>@id</code> key is used to identify that <tref>node</tref> using an
<tref>IRI</tref>. When the object has only the <code>@id</code>, it
is called a <tref>node reference</tref>.
- This facility MAY also be used to link to another
+ This facility may also be used to link to another
<tref>node definition</tref> using a mechanism called
<tref>embedding</tref>, which is covered in the section titled
<a href="#embedding"></a>.</p>
@@ -852,7 +848,7 @@
<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 processed by a JSON-LD Processor.</p>
+the value into an IRI when generating the <tref>JSON-LD graph</tref>.</p>
</section>
@@ -860,7 +856,7 @@
<h2>Node Identifiers</h2>
<p>To be able to externally reference nodes in a graph, it is important that each node has
- an unambiguous identifier. <tref>IRI</tref>s are a fundamental concept of
+ an unambiguous identifier. <tref title="IRI">IRIs</tref> are a fundamental concept of
<tref>Linked Data</tref>, and nodes should have a de-referencable
identifier used to name and locate them. For nodes to be truly linked,
de-referencing the identifier should result in a representation of that node
@@ -902,8 +898,7 @@
<tref>node definition</tref>. <tref title="node definition">Node definitions</tref>
do not require an <code>@id</code>. A <tref>node definition</tref>
that does not contain an <code>@id</code> property defines properties of an
- <tref>unlabeled node</tref>. <tref title="node definition">Node definitions</tref> MAY
- be spread among different parts of a document or even between different documents.</p>
+ <tref>unlabeled node</tref>.</p>
</section>
@@ -911,8 +906,8 @@
<h2>Specifying the Type</h2>
<p>The type of a particular node can be specified using the <code>@type</code>
- <tref>keyword</tref>. To be considered <tref>Linked Data</tref>, types MUST
- be uniquely identified by an <tref>IRI</tref>.</p>
+ <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">
@@ -969,11 +964,10 @@
</pre>
<p>The example above would associate the <code>ja</code> language
- code with the two <tref>string</tref>s <em>花澄</em> and <em>科学者</em>.
- Languages MUST be well-formed language tags according to [[!BCP47]].</p>
-
-<p>It is possible to override the default language by using the expanded
-form of a value:</p>
+ code with the two <tref title="string">strings</tref> <em>花澄</em> and <em>科学者</em>.
+ Languages codes are defined in [[!BCP47]].</p>
+
+<p>It is possible to override the default language by using an <tref>expanded value</tref>:</p>
<pre class="example" data-transform="updateExample"
title="Expanded value with language">
@@ -994,7 +988,7 @@
<p>It is also possible to override the default language or specify a plain
value by omitting the <code>@language</code> tag or setting it to
-<code>null</code> when expressing the expanded value:</p>
+<code>null</code> when expressing the <tref>expanded value</tref>:</p>
<pre class="example" data-transform="updateExample"
title="Expanded value to remove language">
@@ -1016,10 +1010,10 @@
-->
</pre>
-<p>Please note that language associations MUST only be applied to plain
- literal <tref>string</tref>s. That is, <tref>typed value</tref>s
- or values that are subject to <a href="#type-coercion"></a>
- won't be language tagged.</p>
+<p>Please note that language associations can only be applied to plain
+ literal <tref title="string">strings</tref>. That is,
+ <tref title="typed value">typed values</tref> or values that are subject
+ to <a href="#type-coercion"></a> cannot be language tagged.</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>
@@ -1044,7 +1038,7 @@
</pre>
<p class="note">JSON-LD allows one to associate language information with
- <tref>term</tref>s. See <a href="#expanded-term-definition"></a> for
+ <tref title="term">terms</tref>. See <a href="#expanded-term-definition"></a> for
more details.</p>
</section>
@@ -1052,16 +1046,15 @@
<section>
<h2>JSON-LD Syntax</h2>
- <p>A JSON-LD document is first, and foremost, a JSON document
- (as defined in [[!RFC4627]]), and any syntactically correct JSON document
- MUST be processed by a conforming JSON-LD processor. However, JSON-LD
+ <p>A <tref>JSON-LD document</tref> is first, and foremost, a JSON document
+ (as defined in [[!RFC4627]]). However, JSON-LD
describes a specific syntax to use for expressing Linked Data. This
includes the use of specific keywords, as identified in <a
href="#syntax-tokens-and-keywords"></a> for
expressing <a title="node definition">node definitions</a>, values,
and the <a>context</a>. See <a
href="#json-ld-grammar"></a> for authoring
- guidelines and a BNF description of JSON-LD.</p>
+ guidelines.</p>
</section>
</section>
@@ -1079,14 +1072,14 @@
<section>
<h2>Compact IRIs</h2>
<p>
- <tref>Term</tref>s in <tref>Linked Data</tref> documents may draw from
+ <tref title="term">Terms</tref> in <tref>Linked Data</tref> documents may draw from
a number of different <tref title="vocabulary">vocabularies</tref>.
At times, declaring every single <tref>term</tref> that a document uses can require the
developer to declare tens, if not hundreds of potential
- <tref>vocabulary</tref> <tref>term</tref>s that are used across an
+ <tref>vocabulary</tref> <tref title="term">terms</tref> that are used across an
application. This is a concern for at least two reasons: the
first is the cognitive load on the developer of remembering all of the
- <tref>term</tref>s, and the second is the serialized size of the
+ <tref title="term">terms</tref>, and the second is the serialized size of the
<tref>context</tref> if it is specified inline. In order to address these issues,
the concept of a <tref>compact IRI</tref> is introduced.</p>
<p>
@@ -1106,7 +1099,7 @@
Instead of having to remember and type out the entire IRI, the developer
can instead use the prefix in their JSON-LD markup.
</p>
- <p>Terms are interpreted as <tref>compact IRI</tref>s if they contain at least one
+ <p>Terms are interpreted as <tref title="compact IRI">compact IRIs</tref> if they contain at least one
colon and the first colon is not followed by two slashes (<code>//</code>, as in
<code>http://example.com</code>). To generate the full <tref>IRI</tref>,
the value is first split into a <em>prefix</em> and <em>suffix</em> at the first
@@ -1115,8 +1108,7 @@
prepending the mapped <em>prefix</em> to the (possibly empty) <em>suffix</em>
using textual concatenation. If no prefix mapping is defined, the value is interpreted
as an <tref>absolute IRI</tref>. If the prefix is an underscore
- (<code>_</code>), the IRI remains unchanged. This effectively means that every term
- containing a colon will be interpreted by a JSON-LD processor as an IRI.
+ (<code>_</code>), the IRI remains unchanged.
</p>
<p>Consider the following example:</p>
<pre class="example" data-transform="updateExample"
@@ -1188,7 +1180,7 @@
<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 the expanded form for specifying values.</li>
+ <li>By utilizing an <tref>expanded typed value</tref>.</li>
<li>By using a native JSON type such as <tref>number</tref>, <tref>true</tref>, or <tref>false</tref>.</li>
</ol>
@@ -1250,7 +1242,7 @@
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 an <tdef>node type</tdef> and
+ with a <tref>node</tref>. The concept of a <tdef>node type</tdef> and
a <tdef>value type</tdef> are different. This is similar to object-oriented
programming languages where both scalar and structured types use the same
class inheritance mechanism, even though scalar types and structured types are
@@ -1293,7 +1285,7 @@
<p>
A string with an associated language, also known as a
<tdef>language-tagged string</tdef>, is indicated by associating a string with
- an language code as defined in [[!BCP47]]. Language-tagged strings may be
+ a language code as defined in [[!BCP47]]. Language-tagged strings may be
expressed in JSON-LD in four ways:
</p>
@@ -1302,11 +1294,11 @@
<tref>keyword</tref> within a <code>@context</code> section.</li>
<li>By utilizing the <code>@language</code> <tref>keyword</tref> when defining
a <tref>term</tref> within a <code>@context</code> section.</li>
- <li>By utilizing the expanded form for specifying values.</li>
- <li>By utilizing the <code>@container</code> <tref>keyword</tref> with a
- value of <code>@language</code> when defining a <tref>term</tref> within
- a <code>@context</code> section. This usage pattern is called a
- <tdef>language map</tdef>.</li>
+ <li>By utilizing an <tref>expanded language-tagged string</tref>.</li>
+ <li>By utilizing a <tref>language map</tref>, provided the underlying
+ <code>term</code> is defined with a <code>@container</code>
+ <tref>keyword</tref> whose value is <code>@language</code> within
+ a <code>@context</code> section.</li>
</ol>
<p>The first example uses the <code>@language</code> keyword to associate a
@@ -1367,7 +1359,7 @@
<p>Systems that support multiple languages often need to express data values in
each language. Typically, such systems also try to ensure that developers have
a programatically easy way to navigate the datastructures for the
-language-specific data. In this case, <tref>language map</tref>s
+language-specific data. In this case, <tref title="language map">language maps</tref>
may be utilized.</p>
<pre class="example" data-transform="updateExample"
@@ -1415,7 +1407,7 @@
<p>
In order to use an external context with an ordinary JSON document, an author
-MUST specify an <tref>IRI</tref> to a valid JSON-LD document in an HTTP Link
+MUST specify an <tref>IRI</tref> to a valid <tref>JSON-LD document</tref> in an HTTP Link
Header [[!RFC5988]] using the <code>describedby</code> link relation.
The referenced document MUST have a top-level <tref>node definition</tref>. The
@@ -1452,7 +1444,8 @@
-->
</pre>
-<p>Please note that JSON-LD documents served with the <code>application/ld+json</code>
+<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>describedby</code> HTTP Link Header MUST be ignored for such documents.</p>
@@ -1461,16 +1454,16 @@
<section>
<h3>Expanded Term Definition</h3>
-<p>Within a <tref>context</tref> definition, <tref>term</tref>s MAY be
- defined using an expanded notation to allow for additional information
+<p>Within a <tref>context</tref> definition, <tref title="term">terms</tref> may be
+ defined using an <tref>expanded term definition</tref> to allow for additional information
associated with the <tref>term</tref> to be specified (see also
<a href="#type-coercion"></a> and
<a href="#sets-and-lists"></a>).</p>
-<p>Instead of using a string representation of an IRI, the IRI MAY be
-specified using a <tref>JSON object</tref> having an <code>@id</code> key.
-The value of the <code>@id</code> key MUST be either a <tref>term</tref>, a
-<tref>compact IRI</tref>, or an <tref>absolute IRI</tref>. Such
+<p>Instead of using a string representation of an IRI, the IRI may be
+specified using a <tref>JSON object</tref> having an <code>@id</code> key,
+and a <tref>term</tref>, a <tref>compact IRI</tref>, or an
+<tref>absolute IRI</tref> as value. Such
an object is called a <tref>node reference</tref>.</p>
<pre class="example" data-transform="updateExample"
@@ -1492,8 +1485,8 @@
</pre>
<p>This allows additional information to be associated with the term. This
- MAY be used for <a href="#type-coercion"></a>,
- <a href="#sets-and-lists"></a>), or to associate language
+ may be used for <a href="#type-coercion"></a>,
+ <a href="#sets-and-lists"></a>, or to associate language
information with a <tref>term</tref> as shown in the following example:</p>
<pre class="example" data-transform="updateExample"
@@ -1523,12 +1516,12 @@
<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 expanded term definition.</p>
-
-<p>Expanded terms MAY also be defined using <tref title="compact_iri">compact IRIs</tref> or
+ <tref>null</tref> in the <tref>expanded term definition</tref>.</p>
+
+<p>Expanded terms may also be defined using <tref title="compact_iri">compact IRIs</tref> or
<tref title="absolute_IRI">absolute IRIs</tref> as keys. If the definition does not include an
<code>@id</code> key, the expanded IRI is determined by performing expansion of the key
- within the current active context. This mechanism is mainly used to associate type or language
+ within the current <tref>active context</tref>. This mechanism is mainly used to associate type or language
information with a <tref>compact IRI</tref> or an <tref>absolute IRI</tref>.</p>
<p class="note">While it is possible to define a
@@ -1543,24 +1536,23 @@
<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>IRI</tref>s to
-<tref>term</tref>s. Using type coercion, value representation is preserved without requiring
+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 <a href="#expanded-term-definition"></a>
- using the <code>@type</code> key. The value of this key represents a type IRI and MUST take the form of
- a <tref>term</tref>, <tref>compact IRI</tref>, <tref>absolute IRI</tref>, or the <tref>keyword</tref> <code>@id</code>. Specifying
- <code>@id</code> indicates that within the body of a JSON-LD document, a string value of a <tref>term</tref> coerced to
+ using the <code>@type</code> key. The value of this key expands to an <tref>IRI</tref>.
+ Alternatively, the <tref>keyword</tref> <code>@id</code> may be used as value to indicate
+ that within the body of a JSON-LD document, a string value of a <tref>term</tref> coerced to
<code>@id</code> is to be interpreted as an <tref>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
+ <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 - the JSON-LD processor will be able to determine the proper expansion for
- <code>xsd:integer</code>.</p>
+ context definition.</p>
<p>The example below demonstrates how a JSON-LD author can coerce values to
-<tref>typed value</tref>s, IRIs and lists.</p>
+<tref title="typed value">typed values</tref>, IRIs and lists.</p>
<pre class="example" data-transform="updateExample"
title="Expanded term definition with types">
@@ -1675,9 +1667,8 @@
<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>
-<p>Type coercion is performed using the unexpanded value of the key,
- which MUST have an exact match for an entry in the
- <tref>active context</tref>.</p>
+<p>Type coercion is performed using the unexpanded value of the key, which has to match exactly
+ an entry in the <tref>active context</tref>.</p>
</section>
@@ -1710,8 +1701,8 @@
<p>Unfortunately, the approach above produces redundant data and would become a
publishing burden for large data sets.
In these situations, the author may use
-a <tdef>property generator</tdef> to express a <tref>term</tref> once, but have
-the JSON-LD processor expand the single statement into multiple statements.
+a <tdef>property generator</tdef> to express a <tref>term</tref> that maps to
+multiple <tref title="property">properties</tref> in the <tref>JSON-LD graph</tref>.
This method can be accomplished by using the following markup pattern:</p>
<pre class="example" data-transform="updateExample"
@@ -1731,8 +1722,7 @@
</pre>
<p>While the term above is only used once outside of the <code>@context</code>,
-a JSON-LD processor will internally transform the document above into
-the following set of statements:</p>
+the document above is equivalent to the following set of statements:</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -1755,7 +1745,7 @@
<p>In general, normal IRI expansion rules apply
anywhere an IRI is expected (see <a 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
+ 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"
@@ -1785,7 +1775,7 @@
and used as a <tref>prefix</tref> for the <code>@type</code> coercion
of the <code>age</code> property.</p>
-<p><tref>Term</tref>s MAY also be used when defining the IRI of another
+<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">
@@ -1813,7 +1803,7 @@
</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
+ 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">
@@ -1845,14 +1835,14 @@
<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 JSON-LD processor will derive the full <tref>IRI</tref> for
-<code>foaf:homepage</code> by looking up the <code>foaf</code>
+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>:
+<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">
@@ -1879,19 +1869,17 @@
</pre>
<p>
-In order for the <tref>absolute IRI</tref> to match above, the <tref>absolute IRI</tref> MUST also
-be used in the JSON-LD document. Also note that <code>foaf:homepage</code>
+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, a JSON-LD
-processor will use direct string comparison when looking up
-<tref>term</tref>s in a <tref>context</tref> before it applies the
-<tref>prefix</tref> lookup mechanism.
+<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>The only exception for using terms in the <tref>context</tref> is that
- they MUST NOT be used in a circular manner. That is,
- a definition of <em>term-1</em> MUST NOT depend on the
+ circular definitions are not allowed. That is,
+ a definition of <em>term-1</em> cannot depend on the
definition of <em>term-2</em> if <em>term-2</em> also depends on
<em>term-1</em>. For example, the following <tref>context</tref> definition
is illegal:</p>
@@ -1913,7 +1901,7 @@
<h2>Sets and Lists</h2>
<p>A JSON-LD author can express multiple values in a compact way by using
- <tref>array</tref>s. Since graphs do not describe ordering for links
+ <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
@@ -2046,13 +2034,12 @@
</pre>
<p class="note">List of lists are not allowed in this version of JSON-LD.
- If a list of lists is detected, a JSON-LD processor will throw an exception.
This decision was made due to the extreme amount of added complexity when
processing lists of lists.</p>
<p>Similarly to <code>@list</code>, there exists the <tref>keyword</tref> <code>@set</code> to
describe unordered sets. While its use in the body of a JSON-LD document
- represents just syntactic sugar that MUST be optimized away when processing
+ represents just syntactic sugar optimized away when processing
the document, 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
are always represented in the form of an <tref>array</tref> - even if there is just a
@@ -2062,8 +2049,7 @@
contains a single value.</p>
<p class="note">The use of <code>@container</code> in the body of a JSON-LD
- document, i.e., outside <code>@context</code> MUST be ignored by
- JSON-LD processors.</p>
+ document has no meaning and is not allowed by the JSON-LD grammar (see <a href="#json-ld-grammar"></a>).</p>
</section>
@@ -2073,7 +2059,7 @@
<p><tdef>Embedding</tdef> is a JSON-LD feature that allows an author to
use <tref title="node definition">node definitions</tref> as
<tref>property</tref> values. This is a commonly used mechanism for
- creating a parent-child relationship between two <tref>node</tref>s.</p>
+ 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>
@@ -2093,7 +2079,7 @@
</pre>
<p>
- A <tref>node definition</tref>, like the one used above, MAY be used in
+ A <tref>node definition</tref>, like the one used above, may be used in
any value position in the body of a JSON-LD document.</p>
</section>
@@ -2103,7 +2089,7 @@
<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
+ <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>
@@ -2307,7 +2293,7 @@
<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
+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
@@ -2473,31 +2459,22 @@
<p>This appendix restates the syntactic conventions described in the
previous sections more formally.</p>
-<p>A JSON-LD processor SHOULD attempt to process non-conforming
- JSON-LD documents. Conformance violations MUST be reported through a
- conformance violation callback mechanism defined in the [[JSON-LD-API]].</p>
-
-<p>For a JSON-LD document to be conforming, it MUST be a valid JSON document
- as described in [[!RFC4627]].</p>
-
-<p>JSON-LD introduces a number of keywords of the form '<code>@</code>'
- followed by a set of one or more lower case alphabetic characters
- (<code>@[a-z]+</code>). JSON-LD documents SHOULD NOT define terms beginning
- with '<code>@</code>'.
- (See <a href="#syntax-tokens-and-keywords"></a> for a complete definition of JSON-LD keywords).</p>
-
-<p class="note">The JSON-LD context allows <tref title="keyword">keywords</tref> to be
- aliased within the <tref>active context</tref>. Whenever a <tref>keyword</tref> is
- discussed, this is also understood to 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>
-
-<p>A JSON-LD document is either a
- a single <tref>node definition</tref>
- or a JSON <tref>array</tref> containing a set of
- one or more <tref title="node definition">node definitions</tref>.</p>
+<p class="note">The JSON-LD context allows <tref title="keyword">keywords</tref>
+ to be aliased within the <tref>active context</tref> (see
+ <a href="#aliasing-keywords"></a>). Whenever a <tref>keyword</tref> is
+ discussed in this grammar, this is also understood to 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>
+
+<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 definition</tref>
+ or a JSON <tref>array</tref> containing a set of one or more
+ <tref title="node definition">node definitions</tref>.</p>
<pre class="example" data-transform="updateExample"
title="Simple node definition">
<!--
@@ -2527,11 +2504,27 @@
<section id="grammar-node-definition">
<h3>Node Definition</h3>
-<p>A <tref>node definition</tref> is a <tref>JSON object</tref>
- containing one or more key-value pairs. Keys are <tref>IRI</tref>s,
- <tref>compact IRI</tref>s,
- <tref>term</tref>s defined within the <tref>active context</tref>, or one of the
- following keywords:</p>
+
+<p>A <tdef>node definition</tdef> represents one or more properties of a
+ <tref>node</tref> in the <tref>JSON-LD graph</tref> serialized by the
+ <tref>JSON-LD document</tref>.
+ The properties of a <tref>node</tref> in the <tref>JSON-LD graph</tref>
+ may be spread among different <tref title="node definition">node definitions</tref>
+ within a document. When that happens,
+ the keys of the different <tref title="node definition">node definitions</tref>
+ are merged to create the properties of the resulting <tref>node</tref>.</p>
+
+<p>In a JSON-LD document, a <tref>JSON object</tref> is a
+ <tref>node definition</tref> if it does not contain the keys
+ <code>@value</code>, <code>@list</code> or <code>@set</code>
+ and it has one or more keys other than <code>@id</code>.</p>
+
+<p>A <tref>node definition</tref> MUST be a <tref>JSON object</tref> that contains
+ one or more key-value pairs. Keys MUST either be
+ <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>:</p>
<ul>
<li><code>@context</code>,</li>
<li><code>@graph</code>,</li>
@@ -2541,9 +2534,8 @@
<p>If the <tref>node definition</tref> contains the <code>@context</code>
key, its value MUST be one of the following:</p>
<ul>
- <li>a <tref>string</tref> with the lexical form of <tref>IRI</tref>,</li>
- <li>a <tref>JSON object</tref> conforming the the syntax requirements stated
- in <a href="#grammar-context"></a>, or</li>
+ <li>an <tref>IRI</tref>,</li>
+ <li>a <tref>context definition</tref>, or</li>
<li>an <tref>array</tref> composed of any number of the previous two expressions.</li>
</ul>
<pre class="example" data-transform="updateExample"
@@ -2557,16 +2549,16 @@
}
-->
</pre>
-<p>See <a href="#node-identifiers"></a>, <a href="#compact-iris"></a>,
- and <a href="#identifying-unlabeled-nodes"></a> for further discussion on
- <code>@id</code> values.</p>
<p>If the <tref>node definition</tref> contains the <code>@id</code>
- key, it's value
- MUST be a <tref>string</tref> having the lexical form of <tref>IRI</tref>,
- <tref>compact IRI</tref> (including <tref>unlabeled node</tref>), or a
- <tref>term</tref> defined in the <tref>active context</tref> expanding
- into an <tref>IRI</tref> or an <tref>unlabeled node</tref>.</p>
+ key, its value MUST be
+ an <tref>IRI</tref>,
+ a <tref>compact IRI</tref> (including <tref>unlabeled node</tref> identifiers), or
+ a <tref>term</tref> defined in the <tref>active context</tref> expanding
+ into an <tref>IRI</tref> or an <tref>unlabeled node</tref> identifier.
+ See <a href="#node-identifiers"></a>, <a href="#compact-iris"></a>,
+ and <a href="#identifying-unlabeled-nodes"></a> for further discussion on
+ <code>@id</code> values.</p>
<pre class="example" data-transform="updateExample"
title="Node definition with @id">
@@ -2582,16 +2574,13 @@
</pre>
<p>If the <tref>node definition</tref> contains the <code>@type</code>
- key, it's value
- MUST be either a <tref>string</tref> having the lexical form of
- <tref>absolute IRI</tref>, <tref>compact IRI</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.</p>
-
-<p>A JSON-LD processor SHOULD process non-conforming documents
- having <code>@type</code> values including <tref>node definition</tref> or
- <tref>node reference</tref> entries but MUST
- discard everything except for the value of the <code>@id</code> key.</p>
+ key, its value MUST be either
+ an <tref>absolute IRI</tref>,
+ a <tref>compact IRI</tref> (excluding <tref>unlabeled node</tref> identifiers),
+ 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 href="#specifying-the-type"></a> for further discussion on
+ <code>@type</code> values.</p>
<pre class="example" data-transform="updateExample"
title="Node definition with @type">
@@ -2606,17 +2595,17 @@
}
-->
</pre>
-<p>See <a href="#specifying-the-type"></a> for further discussion on
- <code>@type</code> values.</p>
<p>If the <tref>node definition</tref> contains the <code>@graph</code>
- key, it's value MUST
- be a <tref>node definition</tref> or an <tref>array</tref> of zero or more
- <tref title="node definition">node definitions</tref>. If the
- <tref>node definition</tref> contains an <code>@id</code> keyword,
- its value is used as the label of a named graph.</p>
-
-<p class="note">As a special case, if the <tref>JSON object</tref> contains no
+ key, its value MUST be
+ a <tref>node definition</tref> or
+ an <tref>array</tref> of zero or more <tref title="node definition">node definitions</tref>.
+ If the <tref>node definition</tref> contains an <code>@id</code> keyword,
+ its value is used as the label of a named graph.
+ See <a href="#named-graphs"></a> for further discussion on
+ <code>@graph</code> values.</p>
+
+<p class="note">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 definition</tref>; this
@@ -2650,15 +2639,14 @@
-->
</pre>
-<p>See <a href="#named-graphs"></a> for further discussion on
- <code>@graph</code> values.</p>
-
-<p>A JSON-LD document MUST NOT contain any <tref>keyword</tref> or
+<p>A <tref>JSON-LD document</tref> MUST NOT contain any <tref>keyword</tref> or
alias that expands to another keyword.</p>
-
-<p>Other keys MUST expand to an <tref>absolute IRI</tref> using the
- <tref>active context</tref>. The values associated with these keys
- may be any of the following:</p>
+<!-- tidoust: clarify? -->
+
+<p>Keys in a <tref>node definition</tref> that are not
+ <tref title="keyword">keywords</tref> MUST expand to an <tref>absolute IRI</tref>
+ using the <tref>active context</tref>. The values associated with these keys
+ MUST be one of the following:</p>
<ul>
<li><tref>string</tref>,</li>
@@ -2668,11 +2656,10 @@
<li><tref>null</tref>,</li>
<li><tref>node reference</tref>,</li>
<li><tref>node definition</tref>,</li>
- <li><tref>typed value</tref>,</li>
- <li><tref>language-tagged string</tref>,</li>
- <li><code>@set</code> or <code>@list</code>
- definition (see <a href="#sets-and-lists"></a>),</li>
- <li>an <tref>array</tref> zero or more of these, or</li>
+ <li><tref>expanded typed value</tref>,</li>
+ <li><tref>expanded language-tagged string</tref>,</li>
+ <li><tref>list</tref> or <tref>set</tref>,</li>
+ <li>an <tref>array</tref> of zero or more of the above possibilities, or</li>
<li>a <tref>language map</tref></li>
</ul>
@@ -2680,10 +2667,24 @@
<section id="grammar-node-reference">
<h2>Node Reference</h2>
-<p>A <tref>JSON object</tref> containing only the <code>@id</code>
- (or an alias for <code>@id</code>) is a <tref>node reference</tref> and not a
- <tref>node definition</tref>.
-</p>
+
+<p>A <tdef>node reference</tdef> allows authors to reference a <tref>node</tref>
+ in the graph by its unique identifier.</p>
+
+<p>A <tref>node reference</tref> MUST be a <tref>JSON object</tref> that contains a
+ single key-value pair where the key is <code>@id</code> (or an alias for
+ <code>@id</code>, see <a href="#aliasing-keywords"></a>).</p>
+
+<p>The value of the <code>@id</code> key in a <tref>node reference</tref> MUST be
+ an <tref>IRI</tref>,
+ a <tref>compact IRI</tref> (including <tref>unlabeled node</tref> identifiers), or
+ a <tref>term</tref> defined in the <tref>active context</tref> expanding
+ into an <tref>IRI</tref> or an <tref>unlabeled node</tref> identifier.</p>
+
+<p>See <a href="#node-identifiers"></a>, <a href="#compact-iris"></a>,
+ and <a href="#identifying-unlabeled-nodes"></a> for further discussion on
+ <code>@id</code> values.</p>
+
<pre class="example" data-transform="updateExample"
title="Explicit node reference">
<!--
@@ -2712,12 +2713,31 @@
</pre>
</section>
+<section id="grammar-term-reference">
+ <h2>Term</h2>
+ <p>A <tdef>term</tdef> is a short-hand <tref>string</tref> that expands
+ to an <tref>IRI</tref> or an <tref>unlabeled node</tref> identifier.</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 use of
+ empty terms (<code>""</code>) is discouraged as not all programming languages
+ are able to handle empty property names.</p>
+</section>
+
<section id="grammar-language-map">
<h2>Language Map</h2>
+<p>A <tdef>language map</tdef> is used to associate a language with a value in a
+ way that allows easy programmatic access.</p>
+
<p>A <tref>language map</tref> may be used as a term value within a
<tref>node definition</tref> if the term is defined with
<code>@container</code> set to <code>@language</code>.</p>
-<p>The keys of a <tref>language map</tref> MUST be a [[BCP47]] string
+
+<p>The keys of a <tref>language map</tref> MUST be [[BCP47]] <tref title="string">strings</tref>
with an associated value that is any of the following types:</p>
<ul>
<li><tref>string</tref>,</li>
@@ -2727,10 +2747,8 @@
<li><tref>null</tref>,</li>
<li><tref>node reference</tref>,</li>
<li><tref>node definition</tref>,</li>
- <li><tref>typed value</tref>,</li>
- <li><tref>language-tagged string</tref>,</li>
- <li><code>@set</code> or <code>@list</code>
- definition (see <a href="#sets-and-lists"></a>), or</li>
+ <li><tref>expanded typed value</tref>,</li>
+ <li><tref>list</tref> or <tref>set</tref>, or</li>
<li>an <tref>array</tref> zero or more of these</li>
</ul>
<p class="issue" data-number="133">We are also discussing values other than strings, such as those that might represent a more reified version of a value with other properties, such as is described using <a href="http://www.w3.org/TR/skos-reference/skos-xl.html">SKOS-XL</a>.</p>
@@ -2761,97 +2779,120 @@
<section id="grammar-expanded-values">
<h2>Expanded Values</h2>
-<p>An <tdef>expanded value</tdef> is a <tref>JSON object</tref> containing the
- <code>@value</code> key, or an alias for the <code>@value</code> value key.
- It MAY
- also contain the <code>@type</code> or <code>@language</code> keys, or their
- respective keyword aliases. An <tref>expanded value</tref> MUST NOT
- contain keys other than <code>@value</code>, <code>@language</code>, and
- <code>@type</code>.
- An <tref>expanded value</tref> MUST NOT contain both the
- <code>@language</code> and <code>@type</code> keys.</p>
- <p>The value of the <code>@value</code> key, or its alias, MUST be either a
- <tref>string</tref>, <tref>number</tref>, <tref>true</tref>, or
- <tref>false</tref>.</p>
-<p>If an <tref>expanded value</tref> contains a <code>@language</code> key,
- it MUST NOT contain any other key except <code>@value</code>. The value of
- the <code>@language</code> key MUST have the lexical form described in
- [[!BCP47]], or be <tref>null</tref>.</p>
-<p>If an <tref>expanded value</tref> contains a <code>@type</code> key, it
- MUST NOT contain any other key except <code>@value</code>. The value of
- <code>@type</code> MUST be a <tref>term</tref>, <tref>compact IRI</tref>,
- <tref>absolute IRI</tref>, or <code>null</code>.</p>
+
+<p>An <tdef>expanded value</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>An <tref>expanded value</tref> MUST be a <tref>JSON object</tref> containing the
+ <code>@value</code> key. It MAY also contain a <code>@type</code> or
+ a <code>@language</code> key but MUST NOT contain both a <code>@type</code>
+ and a <code>@language</code> key. An <tref>expanded value</tref> MUST NOT
+ contain keys other than
+ <code>@value</code>,
+ <code>@language</code>, and
+ <code>@type</code>.</p>
+
+<p>An <tref>expanded value</tref> that contains a <code>@type</code> key is
+ called an <tdef>expanded typed value</tdef>. An <tref>expanded value</tref>
+ that contains a <code>@language</code> key is called an <tdef>expanded
+ language-tagged string</tdef>. An <tref>expanded value</tref> that contains
+ neither the <code>@type</code> key or the <code>@language</code> key is both
+ an <tref>expanded typed value</tref> and an <tref>expanded language-tagged
+ string</tref>.</p>
+
+<p>The value of the <code>@value</code> key MUST be either a
+ <tref>string</tref>, <tref>number</tref>, <tref>true</tref>, <tref>false</tref>
+ or <tref>null</tref>.</p>
+
+<p>The value of the <code>@language</code> key MUST have the lexical form
+ described in [[!BCP47]], or be <tref>null</tref>.</p>
+
+<p>The value of the
+ <code>@type</code> key MUST be a <tref>term</tref>, a <tref>compact IRI</tref>,
+ an <tref>absolute IRI</tref>, or <code>null</code>.</p>
+
<p>See <a href="#typed-values"></a> and <a href="#language-tagged-strings"></a>
- for a further discussion of
+ for further discussion of
<tref title="expanded value">expanded values</tref>.</p>
</section>
<section id="grammar-set-list">
<h2>List and Set Values</h2>
-<p>A <tdef>list</tdef> is a <tref>JSON object</tref> having only the <code>@list</code>
- <tref>keyword</tref>. Its value MUST be an <tref>array</tref> of any of the following:</p>
+<p>A <tdef>list</tdef> represents an <em>ordered</em> set of values.
+ A <tdef>set</tdef> represents an <em>unordered</em> set of values.
+ Unless otherwise specified (typically through the use of a <tref>list</tref>),
+ <tref title="array">arrays</tref> are unordered in JSON-LD.
+ As such, the <code>@set</code> keyword is not stricto senso necessary.
+ It is defined for symmetry with the <code>@list</code> keyword.</p>
+</p>
+
+<p>A <tref>list</tref> MUST be a <tref>JSON object</tref> that contains a single key-value pair where the key is <code>@list</code>.</p>
+
+<p>A <tref>set</tref> MUST be a <tref>JSON object</tref> that contains a single key-value pair where the key is <code>@set</code>.</p>
+
+<p>In both cases, the value associated with the key MUST be an <tref>array</tref> of any of the following:</p>
<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 reference</tref>,</li>
<li><tref>node definition</tref>,</li>
- <li><tref>typed value</tref>, or</li>
- <li><tref>language-tagged string</tref>.</li>
+ <li><tref>expanded typed value</tref>, or</li>
+ <li><tref>expanded language-tagged string</tref></li>
</ul>
-<p>A <tdef>set</tdef> is a <tref>JSON object</tref> having only the <code>@set</code>
- <tref>keyword</tref>. Its value MUST be an <tref>array</tref> of any of the following:</p>
-<ul>
- <li><tref>string</tref>,</li>
- <li><tref>node reference</tref>,</li>
- <li><tref>node definition</tref>,</li>
- <li><tref>typed value</tref>,</li>
- <li><tref>language-tagged string</tref>,</li>
- <li><code>@set</code> or <code>@list</code>
- definition (see <a href="#sets-and-lists"></a>), or</li>
- <li>an <tref>array</tref> zero or more of these.</li>
-</ul>
-<p>See <a href="#sets-and-lists"></a> for a further discussion of List and Set Values.</p>
+
+<p>See <a href="#sets-and-lists"></a> for further discussion of List and Set Values.</p>
</section>
<section id="grammar-context">
<h2>Context Definition</h2>
-<p>A <tdef>context definition</tdef> is a <tref>JSON object</tref>
- containing one or more key-value pairs. Keys are non-keyword <tref title="string">strings</tref>
- or the <code>@language</code> or <code>@vocab</code> <tref title="keyword">keywords</tref>.
- A <tref>context definition</tref>
- SHOULD NOT contain any keys having the lexical form of <tref>keyword</tref> other than
- <code>@language</code> or <code>@vocab</code>.</p>
+<p>A <tdef>context definition</tdef> defines a <tref>local context</tref> in a <tref>node definition</tref>.</p>
+
+<p>A <tref>context definition</tref> MUST be a <tref>JSON object</tref>
+ containing one or more key-value pairs. Keys MUST either be
+ <tref title="term">terms</tref> or <code>@language</code> or <code>@vocab</code> <tref title="keyword">keywords</tref>.
+
<p>If the <tref>context definition</tref> has a <code>@language</code> key,
- the value MUST have the lexical form described in [[!BCP47]] or be <tref>null</tref>.</p>
+ 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>@vocab</code> key,
- the value MUST have the lexical form of <tref>absolute IRI</tref> or be <tref>null</tref>.</p>
-<p>Other keys are <tref>term</tref> definitions. Their values MUST be either a
- <tref>string</tref>, or a <tref>JSON object</tref> having the form of an <tref>expanded term
- definition</tref> (see <a href="#expanded-term-definition"></a>).</p>
-<p>An <tdef>expanded term definition</tdef> is composed of zero or more keys from <code>@id</code>,
+ its value MUST have the lexical form of <tref>absolute IRI</tref> or be <tref>null</tref>.</p>
+
+<p><tref>Term</tref> values MUST be either a
+ <tref>string</tref>, or an <tref>expanded term definition</tref>.</p>
+
+<p>An <tdef>expanded term definition</tdef> 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 definition</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>@type</code>, <code>@language</code> or <code>@container</code>. An
- <tref>expanded term definition</tref> SHOULD NOT contain any other keys.
+ <tref>expanded term definition</tref> SHOULD NOT contain any other keys. [@@@ the previous statements contradict themselves]
All values associated with <code>@id</code> MUST expand to an <tref>absolute IRI</tref>.</p>
<p>If the <tref>term</tref> definition is not a <tref>compact IRI</tref> or <tref>absolute IRI</tref>,
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>,
- it MUST be a <tref>string</tref> having the lexical form of <tref>IRI</tref>,
- <tref>compact IRI</tref>, a <tref>term</tref> defined in the defining <tref>context
- definition</tref> or the <tref>active context</tref>, or an <tref>array</tref> composed of any of the previous allowed values.</p>
+ its value MUST be an <tref>IRI</tref>, a <tref>compact IRI</tref>, a <tref>term</tref> defined in the defining <tref>context definition</tref> or the <tref>active context</tref>, or an <tref>array</tref> composed of any of the previous allowed values.</p>
<p>If the <tref>expanded term definition</tref> contains the <code>@type</code> <tref>keyword</tref>,
- it MUST be a <tref>string</tref> having the lexical form of <tref>absolute IRI</tref>,
- <tref>compact IRI</tref>, or a <tref>term</tref> defined in the defining <tref>context
- definition</tref> or the <tref>active context</tref>.</p>
+ its value MUST be an <tref>absolute IRI</tref>, a <tref>compact IRI</tref>, a <tref>term</tref> defined in the defining <tref>context definition</tref> or the <tref>active context</tref>, or the <code>@id</code> <tref>keyword</tref>.</p>
<p>If the <tref>expanded term definition</tref> contains the <code>@language</code> <tref>keyword</tref>,
- the value MUST have the lexical form described in [[!BCP47]] or be <tref>null</tref>.</p>
+ 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>,
- the value MUST be either <code>@list</code>, <code>@set</code>, <code>@language</code>, or be <tref>null</tref>.
+ its value MUST be either <code>@list</code>, <code>@set</code>, <code>@language</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>JSON object</tref> whose keys are <tref>string</tref>s that are [[BCP47]] language identifiers.
- The values associated with each [[BCP47]] language string MUST be a <tref>string</tref> or an <tref>array</tref> of <tref>string</tref>s.</p>
+ associated value MUST be a <tref>language 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 href="#the-context"></a> and <a href="#expanded-term-definition"></a>
- for a further discussion of contexts.</p>
+ for further discussion of contexts.</p>
</section>
<pre class="example" data-transform="updateExample"
title="Context definition with simple terms, expanded term definitions and @language">