Updated syntax based on EricP's feedback in issue #136.
authorGregg Kellogg <gregg@kellogg-assoc.com>
Wed, 20 Jun 2012 14:03:05 -0700
changeset 729 e746b3f08db1
parent 728 1aea42d32f85
child 730 7b45a8345074
Updated syntax based on EricP's feedback in issue #136.
spec/latest/json-ld-syntax/index.html
--- 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>