Update API to describe an algorithm to turn serialized N-Triples into a JSON-LD as part of normalization.
authorGregg Kellogg <gregg@kellogg-assoc.com>
Wed, 11 Jan 2012 16:14:23 -0800
changeset 329 5458bd10c815
parent 328 69fe37f6ec42
child 330 9d135c7b8307
Update API to describe an algorithm to turn serialized N-Triples into a JSON-LD as part of normalization.
spec/latest/json-ld-api/index.html
--- a/spec/latest/json-ld-api/index.html	Wed Jan 11 11:25:05 2012 -0800
+++ b/spec/latest/json-ld-api/index.html	Wed Jan 11 16:14:23 2012 -0800
@@ -571,6 +571,9 @@
         no errors. If the compaction fails, <code>null</code> MUST be returned.
         The output is the serialized representation returned from the
         <a href="#normalization-algorithm">Normalization Algorithm</a>.
+        <span class="issue">It's still an open question if the result is a DOMString
+          representing the serialized graph in JSON-LD, or an <tref>array</tref> representation
+          which is in normalized form.</span>
         <dl class="parameters">
           <dt>object input</dt>
           <dd>The JSON-LD object to perform normalization upon.</dd>
@@ -1323,10 +1326,6 @@
   <tref>JSON-LD output</tref>. The following series of steps is the recursive
   portion of the framing algorithm:</p>
 
-<p class="issue">Doubtful that the Framing Algorithm requires the
-  <a href="#normalization-algorithm">Normalization Algorithm</a>
-  any longer, perhaps needs to be a <em>Flattening Algorithm</em> instead.</p>
-
 <ol class="algorithm">
   <li>Initialize the <tref>framing context</tref> by setting the
     <tref>object embed flag</tref>, clearing the
@@ -1466,10 +1465,7 @@
 
 <p>Normalization is the process of taking <tref>JSON-LD input</tref> and
   performing a deterministic transformation on that input that results in
-  a normalized and serialized RDF representation.
-  The normalized output is generated in such a way
-  that any conforming JSON-LD (or other RDF) processor will generate identical serialized output
-  given the same input.</p>
+  a normalized and serialized JSON-LD representation.</p>
 
 <p>Normalization is achieved by transforming <tref>JSON-LD input</tref> to RDF,
   as described in <a href="#rdf-conversion">RDF Conversion</a>, invoking the normalization procedure
@@ -1513,25 +1509,93 @@
 
 <p>The example below is the normalized form of the JSON-LD document above:</p>
 
+<p class="note">Whitespace is used below to aid readability. The normalization
+  algorithm for JSON-LD removes all unnecessary whitespace in the fully
+  normalized form.</p>
+<p class="issue">Not clear that whitespace must be normalized, as the JSON-LD
+  representation can't be used directly to create a signature, but would be based
+  on the serialized result of [[!RDF-NORMALIZATION]].</p>
+
 <pre class="example" data-transform="updateExample">
 <!--
-_:c14n0 <http://xmlns.com/foaf/0.1/homepage> <http://manu.sporny.org/> .
-_:c14n0 <http://xmlns.com/foaf/0.1/name> "Manu Sporny" .
+[{
+  "@id": "_:c14n0",
+  "http://xmlns.com/foaf/0.1/homepage": {
+    "@id": "http://manu.sporny.org/"
+  },
+  "http://xmlns.com/foaf/0.1/name": "Manu Sporny"
+}]
 -->
 </pre>
 
+<p>Notice how all of the <tref>term</tref>s have been expanded and sorted in
+  alphabetical order. Also, notice how the <tref>subject</tref> has been labeled with a
+  named <tref>blank node</tref>. Normalization ensures that any arbitrary graph
+  containing exactly the same information would be normalized to exactly the same form
+  shown above.</p>
 <section>
 <h3>Normalization Algorithm</h3>
 
 <p>The normalization algorithm transforms the <tref>JSON-LD input</tref>
-  into RDF, normalizes it according to [[!RDF-NORMALIZATION]]. The result
-  is a serialized representation that represents a deterministically
-  RDF graph.</p>
+  into RDF, normalizes it according to [[!RDF-NORMALIZATION]] and then
+  transforms back to JSON-LD. The result is an object representation that
+  deterministically represents a RDF graph.</p>
 
 <ol class="algorithm">
   <li>Transform the <tref>JSON-LD input</tref> to RDF according to the steps in
     the <a href="#rdf-conversion-algorithm">RDF Conversion Algorithm</a>.</li>
-  <li>Return the result of [[!RDF-NORMALIZATION]] on that RDF.</li>
+  <li>Perform [[!RDF-NORMALIZATION]] of that RDF to create a serialized N-Triples
+    representation of the RDF graph.</li>
+  <li>Construct a JSON <tref>array</tref> <em>array</em> to serve as the output object.</li>
+  <li>For each triple in the N-Triples document having <em>subject</em>, <em>predicate</em>,
+    and <em>object</em>:
+    <ol class="algorithm">
+      <li>If <em>predicate</em> is <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#first</code>,
+        let <em>object representation</em> be <em>object</em> represented in expanded
+        form as described in <a href="#value-expansion">Value Expansion</a>.
+        <ol class="algorithm">
+          <li>Set <em>value</em> as the last entry in <em>array</em>.</li>
+          <li>If the last entry in <em>value</em> is <em>subject</em>, replace it with
+            the a <tref>JSON object</tref> having a key/value pair of <code>@list</code> and an
+            <tref>array</tref> containing <em>object representation</em>.</li>
+          <li>Otherwise, the last key/value entry in <em>value</em> MUST be a <tref>JSON object</tref>
+            having a single key of <em>@list</em> with a value that is an <tref>array</tref>.
+            Append <em>object representation</em>.</li>
+        </ol>
+      </li>
+      <li>Otherwise, if <em>predicate</em> is
+        <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#rest</code>, ignore this triple.</li>
+      <li>Otherwise, if the last entry in <em>array</em> is not a <tref>JSON Object</tref> with an
+        <code>@id</code> having a value of <em>subject</em>:
+        <ol class="algorithm">
+          <li>Create a new <tref>JSON Object</tref> with key/value pair of <code>@id</code> and
+            a string representation of <em>subject</em> and use as <em>value</em>.</li>
+          <li>Otherwise, set <em>value</em> to that value.</li>
+        </ol>
+      </li>
+      <li>If <code>predicate</code> is <code>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</code>:
+        <ol class="algorithm">
+          <li>If <em>value</em> has an key/value pair of <code>@type</code> and an <tref>array</tref>,
+            append the string representation of <tref>object</tref> to that array.</li>
+          <li>Otherwise, if <em>value</em> has an key of <code>@type</code>, replace that value
+            with a new array containing the existing value and a string representation of
+            <em>object</em>.</li>
+          <li>Otherwise, create a new entry in value with a key of <code>@type</code> and value being a
+            string representation of <em>object</em>.</li>
+        </ol>
+      </li>
+      <li>Otherwise, let <em>key</em> by the string representation of <em>predicate</em> and
+        let <em>object representation</em> be <em>object</em> represented in expanded
+        form as described in <a href="#value-expansion">Value Expansion</a>.</li>
+      <li>If <em>value</em> has an key/value pair of <em>key</em> and an <tref>array</tref>,
+        append <em>object representation</em> to that array.</li>
+      <li>Otherwise, if <em>value</em> has an key of <em>key</em>, replace that value
+        with a new array containing the existing value and <em>object representation</em>.</li>
+      <li>Otherwise, create a new entry in value with a key of <em>key</em> and
+        <em>object representation</em>.</li>
+    </ol>
+  </li>
+  <li>Return <em>array</em> as the normalized graph representation.</li>
 </ol>
 </section>