Clarify top-level @graph
authorMarkus Lanthaler <mark_lanthaler@gmx.net>
Mon, 11 Feb 2013 14:58:14 +0100
changeset 1208 44b840d125ce
parent 1207 6ce9f7bf07dd
child 1209 f6a73f039d75
Clarify top-level @graph

Discussion at http://lists.w3.org/Archives/Public/public-linked-json/2013Feb/0010.html
spec/latest/json-ld-syntax/index.html
--- a/spec/latest/json-ld-syntax/index.html	Mon Feb 11 13:04:21 2013 +0100
+++ b/spec/latest/json-ld-syntax/index.html	Mon Feb 11 14:58:14 2013 +0100
@@ -2134,13 +2134,17 @@
   </tbody>
   </table>
 
-  <p>When <code>@graph</code> is used in a document's top-level object which
-    has no other <tref title="property">properties</tref> that are mapped
-    to an <tref>IRI</tref> or a <tref>keyword</tref> it is considered to
-    express the otherwise implicit default graph. This mechanism can be useful
-    when a number of <tref title="node">nodes</tref> do not directly
-    relate to one another through a property or where <tref>embedding</tref>
-    is not desirable to the application. For example:</p>
+  <p>When a JSON-LD document's top-level structure is an
+    <tref title="JSON object">object</tref> that contains no other
+    <tref title="property">properties</tref> than <code>@graph</code> and
+    optionally <code>@context</code> (properties that are not mapped to an
+    <tref>IRI</tref> or a <tref>keyword</tref> are ignored),
+    <code>@graph</code> is considered to express the otherwise implicit
+    <tref>default graph</tref>. This mechanism can be useful when a number
+    of <tref title="node">nodes</tref> exist at the document's top level that
+    share the same <tref>context</tref>. The <code>@graph</code> keyword
+    collects such nodes in an <tref>array</tref> and allows the use of a
+    shared context.</p>
 
   <pre class="example" data-transform="updateExample"
     title="Using @graph to explicitly express the default graph">
@@ -2167,10 +2171,7 @@
   </pre>
 
   <p>In this case, embedding doesn't work as each <tref>node object</tref>
-    references the other. Using the <code>@graph</code> <tref>keyword</tref>
-    allows multiple <tref title="node">nodes</tref> to be defined within an
-    <tref>array</tref>, and allows the use of a shared <tref>context</tref>.
-    This is equivalent to using multiple
+    references the other. This is equivalent to using multiple
     <tref title="node object">node objects</tref> in array and defining
     the <code>@context</code> within each <tref>node object</tref>:</p>