Move "Uses of JSON Objects" before "Specifying the Type" and add some discussion of setting the type on value objects, with references to "Typed Values" and "Type Coercion".

gkellogg · gkellogg · commit 4be2d3e12b5d · 2018-11-15T10:08:54.000-08:00
diff --git a/index.html b/index.html
@@ -1238,6 +1238,86 @@ <h2>Node Identifiers</h2>
 
 </section>
 
+<section class="changed">
+  <h2>Uses of JSON Objects</h2>
+  <p>As a syntax, JSON has only a limited number of syntactic elements:</p>
+  <ul>
+    <li><a>Numbers</a>, which describe literal numeric values,</li>
+    <li><a>Strings</a>, which may describe literal string values, or be used as the keys in a <a>JSON object</a>.</li>
+    <li><a>Boolean</a> <code>true</code> and <code>false</code>, which describe literal boolean values,</li>
+    <li><code>Null</code>, which describes the absense of a value,</li>
+    <li><a>Arrays</a>, which describe an ordered set of values of any type, and</li>
+    <li><a>JSON objects</a>, which provide a set of <a>dictionary members</a>, relating keys with values.</li>
+  </ul>
+
+  <p>The JSON-LD data model allows for a richer set of resources, based on the RDF data model.
+    The data model is described more fully in <a class="sectionRef" href="#data-model"></a>.
+    JSON-LD uses JSON objects to describe various resources, along with the relationships
+    between these resources:</p>
+  <dl>
+    <dt><a>Node objects</a></dt><dd>
+      Node objects are used to define nodes in the <a>linked data graph</a>
+      which may have both incoming and outgoing edges.
+      Node objects are principle structure for defining <a>resources</a> having <a>properties</a>.
+      See <a class="sectionRef" href="#node-objects"></a> for the normative definition.
+    </dd>
+    <dt><a>Value objects</a></dt><dd>
+      Value objects are used for describing literal nodes in a <a>linked data graph</a>
+      which may have only incoming edges.
+      In JSON, some literal nodes may be described without the use of a <a>JSON object</a>
+      (e.g., <a>numbers</a>, <a>strings</a>, and <a>boolean</a> values),
+      but in the <a data-lt="expansion">expanded form</a>,
+      all literal nodes are described using <a>value objects</a>.
+      See <a class="sectionRef" href="#describing-values"></a> for more information,
+      and <a class="sectionRef" href="#value-objects"></a> for the normative definition.
+    </dd>
+    <dt><a>List Objects</a> and <a>Set objects</a></dt><dd></dd>
+    <dt>Map Objects</dt><dd>
+      JSON-LD uses various forms of <a>dictionaries</a> as ways to more easily access values of a <a>property</a>.
+      <dl>
+        <dt><a>Language Maps</a></dt><dd>
+          Allows mulitple values differing in their associated language to be
+          indexed by <a>language tag</a>.
+          See <a class="sectionRef" href="#language-indexing"></a> for more information,
+          and <a class="sectionRef" href="#language-maps"></a> for the normative definition.
+        </dd>
+        <dt><a>Index Maps</a></dt><dd>
+          Allows multiple values (<a>node objects</a> or <a>value objects</a>) to be indexed by an associated <code>@index</code>.
+          See <a class="sectionRef" href="#data-indexing"></a> for more information,
+          and <a class="sectionRef" href="#index-maps"></a> for the normative definition.
+        </dd>
+        <dt><a>Id Maps</a></dt><dd>
+          Allows multiple <a>node objects</a> to be indexed by an associated <code>@id</code>.
+          See <a class="sectionRef" href="#node-identifier-indexing"></a> for more information,
+          and <a class="sectionRef" href="#id-maps"></a> for the normative definition.
+        </dd>
+        <dt><a>Type Maps</a></dt><dd>
+          Allows multiple <a>node objects</a> to be indexed by an associated <code>@type</code>.
+          See <a class="sectionRef" href="#node-type-indexing"></a> for more information,
+          and <a class="sectionRef" href="#type-maps"></a> for the normative definition.
+        </dd>
+        <dt><a>Named Graph</a> Indexing</dt><dd>
+          Allows multiple <a>named graphs</a> to be indexed by an associated <a>graph name</a>.
+          See <a class="sectionRef" href="#named-graph-indexing"></a> for more information.
+        </dd>
+      </dl>
+    </dd>
+    <dt><a>Graph objects</a></dt><dd>
+      A Graph object is much like a <a>node object</a>, except that it defines a <a>named graph</a>.
+      See <a class="sectionRef" href="#named-graphs"></a> for more information,
+      and <a class="sectionRef" href="#graph-objects"></a> for the normative definition.
+    </dd>
+    <dt><a>Context Definitions</a></dt><dd>
+      A Context Definition uses the <a>JSON object</a> form, but is not itself data in a <a>linked data graph</a>.
+      A Context Definition also may contain expanded term definitions,
+      which are also represented using JSON objects.
+      See <a class="sectionRef" href="#the-context"></a>,
+      <a class="sectionRef" href="#advanced-context-usage"></a> for more information,
+      and <a class="sectionRef" href="#context-definitions"></a> for the normative definition.
+    </dd>
+  </dl>
+</section>
+
 <section class="informative">
   <h2>Specifying the Type</h2>
 
@@ -1250,7 +1330,7 @@ <h2>Specifying the Type</h2>
     type is a <em>Person</em>; making this explicit with <code>@type</code> helps
     to clarify the association.</p>
   
-  <p>The type of a particular node can be specified using the <code>@type</code>
+  <p>The type of a particular <a>node</a> can be specified using the <code>@type</code>
     <a>keyword</a>. In Linked Data, types are uniquely
     identified with an <a>IRI</a>.</p>
 
@@ -1373,7 +1453,7 @@ <h2>Specifying the Type</h2>
     </pre>
   </aside>
 
-  <p>The value of an <code>@type</code> key may also be a <a>term</a> defined in the <a>active context</a>:</p>
+  <p>The value of a <code>@type</code> key may also be a <a>term</a> defined in the <a>active context</a>:</p>
 
   <aside class="example ds-selector-tabs"
          title="Using a term to specify the type">
@@ -1428,6 +1508,22 @@ <h2>Specifying the Type</h2>
     </pre>
   </aside>
 
+  <p class="changed">In addition to setting the type of nodes,
+    <code>@type</code> can also be used to set the type of a value
+    to create a <a>typed value</a>.
+    This use of <code>@type</code> is similar to that used to define the type of a <a>node object</a>,
+    but value objects are restricted to having just a single type.
+    The use of @type to create typed values is discussed more fully in <a class="sectionRef" href="#typed-values"></a>.</p>
+
+  <p class="changed">Typed values can also be defined implicitly, by specifying
+    @type in an expanded term definition.
+    This is covered more fully in <a class="sectionRef" href="#type-coercion"></a>.</p>
+
+  <p class="note">The ability coerce a value using a <a>term definition</a> is distinct
+    from setting one or more types on a <a>node object</a>, as the former does not result in
+    new data being added to the graph, while the later manages node types
+    through adding additional relationships to the graph.</p>
+
   <p class="note">This section only covers the most basic features associated with
     types in JSON-LD. It is worth noting that the <code>@type</code>
     <a>keyword</a> is not only used to specify the type of a
@@ -1440,86 +1536,6 @@ <h2>Specifying the Type</h2>
     <a class="sectionRef" href="#typed-values"></a>.</p>
 
 </section>
-
-<section class="changed">
-  <h2>Uses of JSON Objects</h2>
-  <p>As a syntax, JSON has only a limited number of syntactic elements:</p>
-  <ul>
-    <li><a>Numbers</a>, which describe literal numeric values,</li>
-    <li><a>Strings</a>, which may describe literal string values, or be used as the keys in a <a>JSON object</a>.</li>
-    <li><a>Boolean</a> <code>true</code> and <code>false</code>, which describe literal boolean values,</li>
-    <li><code>Null</code>, which describes the absense of a value,</li>
-    <li><a>Arrays</a>, which describe an ordered set of values of any type, and</li>
-    <li><a>JSON objects</a>, which provide a set of <a>dictionary members</a>, relating keys with values.</li>
-  </ul>
-
-  <p>The JSON-LD data model allows for a richer set of resources, based on the RDF data model.
-    The data model is described more fully in <a class="sectionRef" href="#data-model"></a>.
-    JSON-LD uses JSON objects to describe various resources, along with the relationships
-    between these resources:</p>
-  <dl>
-    <dt><a>Node objects</a></dt><dd>
-      Node objects are used to define nodes in the <a>linked data graph</a>
-      which may have both incoming and outgoing edges.
-      Node objects are principle structure for defining <a>resources</a> having <a>properties</a>.
-      See <a class="sectionRef" href="#node-objects"></a> for the normative definition.
-    </dd>
-    <dt><a>Value objects</a></dt><dd>
-      Value objects are used for describing literal nodes in a <a>linked data graph</a>
-      which may have only incoming edges.
-      In JSON, some literal nodes may be described without the use of a <a>JSON object</a>
-      (e.g., <a>numbers</a>, <a>strings</a>, and <a>boolean</a> values),
-      but in the <a data-lt="expansion">expanded form</a>,
-      all literal nodes are described using <a>value objects</a>.
-      See <a class="sectionRef" href="#describing-values"></a> for more information,
-      and <a class="sectionRef" href="#value-objects"></a> for the normative definition.
-    </dd>
-    <dt><a>List Objects</a> and <a>Set objects</a></dt><dd></dd>
-    <dt>Map Objects</dt><dd>
-      JSON-LD uses various forms of <a>dictionaries</a> as ways to more easily access values of a <a>property</a>.
-      <dl>
-        <dt><a>Language Maps</a></dt><dd>
-          Allows mulitple values differing in their associated language to be
-          indexed by <a>language tag</a>.
-          See <a class="sectionRef" href="#language-indexing"></a> for more information,
-          and <a class="sectionRef" href="#language-maps"></a> for the normative definition.
-        </dd>
-        <dt><a>Index Maps</a></dt><dd>
-          Allows multiple values (<a>node objects</a> or <a>value objects</a>) to be indexed by an associated <code>@index</code>.
-          See <a class="sectionRef" href="#data-indexing"></a> for more information,
-          and <a class="sectionRef" href="#index-maps"></a> for the normative definition.
-        </dd>
-        <dt><a>Id Maps</a></dt><dd>
-          Allows multiple <a>node objects</a> to be indexed by an associated <code>@id</code>.
-          See <a class="sectionRef" href="#node-identifier-indexing"></a> for more information,
-          and <a class="sectionRef" href="#id-maps"></a> for the normative definition.
-        </dd>
-        <dt><a>Type Maps</a></dt><dd>
-          Allows multiple <a>node objects</a> to be indexed by an associated <code>@type</code>.
-          See <a class="sectionRef" href="#node-type-indexing"></a> for more information,
-          and <a class="sectionRef" href="#type-maps"></a> for the normative definition.
-        </dd>
-        <dt><a>Named Graph</a> Indexing</dt><dd>
-          Allows multiple <a>named graphs</a> to be indexed by an associated <a>graph name</a>.
-          See <a class="sectionRef" href="#named-graph-indexing"></a> for more information.
-        </dd>
-      </dl>
-    </dd>
-    <dt><a>Graph objects</a></dt><dd>
-      A Graph object is much like a <a>node object</a>, except that it defines a <a>named graph</a>.
-      See <a class="sectionRef" href="#named-graphs"></a> for more information,
-      and <a class="sectionRef" href="#graph-objects"></a> for the normative definition.
-    </dd>
-    <dt><a>Context Definitions</a></dt><dd>
-      A Context Definition uses the <a>JSON object</a> form, but is not itself data in a <a>linked data graph</a>.
-      A Context Definition also may contain expanded term definitions,
-      which are also represented using JSON objects.
-      See <a class="sectionRef" href="#the-context"></a>,
-      <a class="sectionRef" href="#advanced-context-usage"></a> for more information,
-      and <a class="sectionRef" href="#context-definitions"></a> for the normative definition.
-    </dd>
-  </dl>
-</section>
 </section>
 
 <section class="normative">
