--- a/spec/latest/json-ld-syntax/index.html Wed Jun 20 13:14:08 2012 -0700
+++ b/spec/latest/json-ld-syntax/index.html Wed Jun 20 14:03:05 2012 -0700
@@ -286,6 +286,37 @@
the expectation that they could be used in a production system within the
next year.
</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">
@@ -358,43 +389,52 @@
JSON [[RFC4627]] defines several terms which are used throughout this document:
<dl>
<dt><tdef>JSON object</tdef></dt><dd>
- An object structure is represented as a pair of curly brackets surrounding zero or
- more name-value pairs. A name is a <tref>string</tref>. A single colon comes after
- each name, separating the name from the value. A single comma separates a value
- from a following name. The names within an object SHOULD be unique.
+ An object structure is represented as a pair of curly brackets
+ surrounding zero or more name-value pairs. A name is a
+ <tref>string</tref>. A single colon comes after each name, separating the
+ name from the value. A single comma separates a value from a following
+ name. The names within an object SHOULD be unique.
</dd>
<dt><tdef>array</tdef></dt>
<dd>
- In JSON, an array is an <em>ordered</em> collection of 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
+ 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">Sets and Lists</a>).
- </dd>
+ unless specific markup is provided
+ (see <a href="#sets-and-lists">Sets and Lists</a>).</dd>
<dt><tdef>string</tdef></dt><dd>
- A string is a sequence of zero or more Unicode (UTF-8) characters,
+ A string is a sequence of zero or more Unicode characters,
wrapped in double quotes, using backslash escapes (if necessary). A
- character is represented as a single character string.
- </dd>
+ character is represented as a single character string.</dd>
<dt><tdef>number</tdef></dt>
<dd>
- A number is is similar to that used in most programming languages, except that the octal and hexadecimal formats are not used and that leading zeros are not allowed.</dd>
+ A number is is similar to that used in most programming languages, except
+ that the octal and hexadecimal formats are not used and that 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>
+ Values that are used to express one of two possible boolean states.</dd>
<dt><tdef>null</tdef></dt><dd>
- 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>, <code>@list</code>, or <code>@set</code> is set to <em>null</em> in expanded form, then the entire JSON object is ignored.
- If <code>@context</code> is set to <em>null</em>, the <tref>active context</tref> is reset and when used
- within a <tref>context</tref>, it removes any definition associated with the key, unless otherwise specified.
- </dd>
+ 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>, <code>@list</code>, or <code>@set</code> is set
+ to <em>null</em> in expanded form, then the entire JSON object is
+ ignored. If <code>@context</code> is set to <em>null</em>, the
+ <tref>active context</tref> is reset and when used within a
+ <tref>context</tref>, it removes any definition associated with the key,
+ unless otherwise specified.</dd>
<dt><tdef>subject definition</tdef></dt><dd>
- A <tref>JSON object</tref> used to represent a <tref>subject</tref> and one or more properties
- of that subject. A <tref>JSON object</tref> is a subject definition if it does not contain they keys
- <code>@value</code>, <code>@list</code> or <code>@set</code> and it has one or more keys other than <code>@id</code>.</dd>
+ A <tref>JSON object</tref> used to represent a <tref>subject</tref> and
+ one or more properties of that subject. A <tref>JSON object</tref> is a
+ subject definition if it does not contain they keys <code>@value</code>,
+ <code>@list</code> or <code>@set</code> and it has one or more keys other
+ than <code>@id</code>.</dd>
<dt><tdef>subject reference</tdef></dt><dd>
- A <tref>JSON object</tref> used to reference a subject having only the <code>@id</code> key.</dd>
+ A <tref>JSON object</tref> used to reference a subject having only the
+ <code>@id</code> key.</dd>
</dl>
</p>
@@ -413,7 +453,8 @@
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">The Context</a>.</dd>
- <dt><code>@graph</code></dt><dd>Used to explicitly express a <tref>linked data graph</tref>.</dd>
+ <dt><code>@graph</code></dt><dd>Used to explicitly label a <tref>linked data graph</tref>.
+ This keyword is described in the section titled <a href="#named-graphs">Named Graphs</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 the section titled
@@ -450,40 +491,6 @@
case-sensitive.</p>
</section>
-<section>
- <h2>Contributing</h2>
-
- <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>
<section class="informative">
@@ -559,15 +566,24 @@
<li>An <tdef>object</tdef> is a node in a <tref>linked data graph</tref> with at least one incoming edge.</li>
<li>An <tref>object</tref> MAY be labeled with an <tref>IRI</tref> or a label that is not an <tref>IRI</tref> such as plain text, internationalized text, or a strictly-typed data value.</li>
<li>A node MAY be a <tref>subject</tref> and <tref>object</tref> at the same time.</li>
- <li>A <tdef>property</tdef> is an edge of the <tref>linked data graph</tref>.</li>
+ <li>A <tdef>property</tdef> is an edge of a
+ <tref>linked data graph</tref>.</li>
<li>A <tref>property</tref> SHOULD be labeled with an <tref>IRI</tref>.</li>
<li>An <tref>IRI</tref> that is a label in a <tref>linked data graph</tref> SHOULD be dereferencable to a <tref>Linked Data</tref> document describing the labeled <tref>subject</tref>, <tref>object</tref> or <tref>property</tref>.</li>
</ol>
<p class="issue">An illustration of a linked data graph would probably help here.</p>
-<p>
-Note that the definition for <tref>Linked Data</tref> above is silent on the
+<p class="issue">EricP suggests that the definitions of subject and
+object, while being practical, are at odds with [[RDF-CONCEPTS]]
+use in their roles within a triple.</p>
+
+<p class="issue">JSON-LD allows properties to be BNodes, while RDF does
+ not. When used as just JSON-LD, this is not unreasonable;
+ it only becomes an issue (and could raise an exception) when
+ transformed to RDF.</p>
+
+<p>Note that the definition for <tref>Linked Data</tref> above is silent on the
topic of unlabeled nodes. Nevertheless, this specification allows for the expression
of unlabled nodes, as most graph-based data sets on the Web contain a number
of associated nodes that are not named and thus are not directly
@@ -942,7 +958,7 @@
uniquely identify each node which may be externally referenced.
</p>
<p>A <tref>subject</tref>
- of an object in JSON is declared using the <code>@id</code> key. The subject is the
+ of a JSON object is declared using the <code>@id</code> key. The subject is the
first piece of information needed by the JSON-LD processor in order to
create the (subject, property, object) tuple, also known as a triple.</p>
@@ -968,7 +984,7 @@
<tref>unlabeled node</tref>.</p>
<p class="note">To ensure the best possible performance, it is a best practice
-to put the <code>@id</code> <tref>keyword</tref> before other key-value pairs in an object.
+to put the <code>@id</code> <tref>keyword</tref> before other key-value pairs in a <tref>JSON object</tref>.
If it isn't listed first, processors have to save each key-value pair until
<code>@id</code> is processed before they can start generating triples.
Not specifying the <code>@id</code> keyword first creates a memory and
@@ -1105,7 +1121,7 @@
<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
between nodes, arrays in JSON-LD do not provide an ordering of the
- listed objects by default. This is exactly the opposite from regular JSON
+ listed <tref title="object">objects</tref> 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">
@@ -1120,7 +1136,7 @@
</pre>
<p>The markup shown above would result in three triples being generated,
- each relating the subject to an individual object, with no inherent order:</p>
+ each relating the subject to an individual <tref>JSON object</tref>, with no inherent order:</p>
<pre class="example" data-transform="updateExample">
<!--
<http://example.org/people#joebob>
@@ -1135,7 +1151,7 @@
-->
</pre>
-<p>Multiple values may also be expressed using the expanded object form:</p>
+<p>Multiple values may also be expressed using the expanded form:</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -1542,9 +1558,9 @@
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
-object of the referencing document. If an array is at the top-level of the
-referencing document and its items are objects, the <code>@context</code>
-subtree is added to all array items. All extra information located outside
+<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.
</p>
@@ -1588,7 +1604,7 @@
<a href="#sets-and-lists">Sets and Lists</a>).</p>
<p>Instead of using a string representation of an IRI, the IRI MAY be
-specified using an object having an <code>@id</code> key.
+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>.</p>
@@ -1931,11 +1947,10 @@
<section>
<h2>Embedding</h2>
<p>
- Object <tdef>embedding</tdef> is a JSON-LD feature that allows an author to
- use the definition of JSON-LD objects as <tref>property</tref> values. This
- is a commonly used mechanism for creating a parent-child relationship
- between two <tref>subject</tref>s.
- </p>
+ Object <tdef>embedding</tdef> is a JSON-LD feature that allows an author to
+ use <tref title="subject definition">subject definitions</tref> as
+ <tref>property</tref> values. This is a commonly used mechanism for
+ creating a parent-child relationship between two <tref>subject</tref>s.</p>
<p>The example shows two subjects related by a property from the first subject:</p>
<pre class="example" data-transform="updateExample">
@@ -1954,9 +1969,8 @@
</pre>
<p>
- An object definition, like the one used above, MAY be used in any value
- position in the body of a JSON-LD document.
- </p>
+ A <tref>subject definition</tref>, like the one used above, MAY be used in
+ any value position in the body of a JSON-LD document.</p>
</section>
<section>
@@ -1989,11 +2003,13 @@
-->
</pre>
- <p>In this case, embedding doesn't work as each JSON-LD object references the other.
- Using the <code>@graph</code>
- <tref>keyword</tref> allows multiple resources to be defined within an <tref>array</tref>, and allows the use
- of a shared <tref>context</tref>. This is equivalent to using multiple <tref>JSON object</tref>
- definitions in array and defining the <code>@context</code> within each object:</p>
+ <p>In this case, embedding doesn't work as each
+ <tref>subject definition</tref> references the other. Using the
+ <code>@graph</code> <tref>keyword</tref> allows multiple resources to be
+ defined within an <tref>array</tref>, and allows the use of a shared
+ <tref>context</tref>. This is equivalent to using multiple <tref
+ title="subject definition">subject definitions</tref> in array and defining
+ the <code>@context</code> within each <tref>subject definition</tref>:</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -2022,8 +2038,8 @@
manner. A developer may name data expressed using the <code>@graph</code>
<tref>keyword</tref> by pairing it with an <code>@id</code>
<tref>keyword</tref>. This enables the developer to make statements
- about the <tref>linked data graph</tref> itself,
- rather than just a single JSON-LD object.</p>
+ about a <tref>linked data graph</tref> itself,
+ rather than just a single <tref>subject</tref>.</p>
<pre class="example" data-transform="updateExample">
<!--
@@ -2275,13 +2291,13 @@
</p>
<ol>
-<li>A JSON-LD document is composed of a single <tref>JSON object</tref> or an array of <tref>JSON object</tref>s.</li>
+<li>A JSON-LD document is composed of a single <tref>JSON object</tref> or an <tref>array</tref> of <tref title="JSON object">JSON objects</tref>.</li>
<li>The value of <code>@id</code> MUST be <code>null</code>, a <tref>term</tref>, a <tref>compact IRI</tref>, or an <tref>IRI</tref>.</li>
<li>A <code>@id</code> keyword and a <code>@language</code> keyword MUST NOT exist in the same <tref>JSON object</tref>.</li>
<li>A <code>@id</code> keyword and a <code>@container</code> keyword MUST NOT exist in the same <tref>JSON object</tref>.</li>
<li>A <tref>JSON object</tref> MAY contain a <code>@context</code> property.</li>
<li>A <code>@context</code> value MUST NOT contain an embedded <code>@context</code> definition.</li>
-<li>The value associated with the <code>@context</code> keyword MUST be an <tref>IRI</tref>, a <tref>JSON object</tref>, null, or an array containing a combination of the allowed values.</li>
+<li>The value associated with the <code>@context</code> keyword MUST be an <tref>IRI</tref>, a <tref>JSON object</tref>, null, or an <tref>array</tref> containing a combination of the allowed values.</li>
<li>The value associated with the keys used in a <code>@context</code> MUST be a <code>null</code>, an <tref>IRI</tref>, or a <tref>JSON object</tref>.</li>
<li>For each value that is a <tref>JSON object</tref> that is associated with a key in a <code>@context</code>:
<ol>
@@ -2295,14 +2311,14 @@
<li>The value of a <code>@graph</code> property MUST be null, an <tref>IRI</tref>, or a <tref>JSON object</tref>.</li>
<li>A <tref>JSON object</tref> containing a <code>@set</code> key MUST NOT have any other keys.</li>
<li>A <tref>JSON object</tref> containing a <code>@list</code> key MUST NOT have any other keys.</li>
-<li>The value of an <code>@set</code> or <code>@list</code> key can be a string, a number, a <tref>JSON object</tref>, or an array containing a combination of the allowed values.</li>
+<li>The value of an <code>@set</code> or <code>@list</code> key can be a string, a number, a <tref>JSON object</tref>, or an <tref>array</tref> containing a combination of the allowed values.</li>
<li>For each <tref>JSON object</tref> that contains a <code>@value</code> key:
<ol>
<li>It MAY have a <code>@language</code> or <code>@type</code> property and MUST NOT have any other properties.</li>
<li>It MUST NOT contain both the <code>@language</code> and <code>@type</code> keys at the same time.</li>
<li>The value of the <code>@value</code> key MUST be a string or a number.</li>
<li>The value of the <code>@language</code> key MUST be <code>null</code> or a string in [[BCP47]] format.</li>
- <li>The value of <code>@type</code> MUST be <code>null</code>, a <tref>term</tref>, a <tref>compact IRI</tref>, an <tref>IRI</tref>, a <tref>JSON object</tref>, or an array containing a combination of the allowed values.</li>
+ <li>The value of <code>@type</code> MUST be <code>null</code>, a <tref>term</tref>, a <tref>compact IRI</tref>, an <tref>IRI</tref>, a <tref>JSON object</tref>, or an <tref>array</tref> containing a combination of the allowed values.</li>
</ol>
</li>
<li>In the body of a JSON-LD document, the value of <code>@type</code> MUST NOT be <code>@id</code>. This is in contrast to the use of <code>@type</code> in the <code>@context</code>, where this is allowed.</li>