Support JSON Literals.

Gemfile.lock

@@ -1,9 +1,10 @@
 GIT
   remote: git://github.com/ruby-rdf/json-ld.git
-  revision: d88f81b143a602a6174b8b9da79c2fc6c04d127b
+  revision: 6f4b20de173ef27ff3959f5206b9a7cb813ecde7
   branch: develop
   specs:
     json-ld (3.0.2)
+      json-canonicalization (~> 0.1)
       link_header (~> 0.0, >= 0.0.8)
       multi_json (~> 1.13)
       rack (>= 1.6, < 3.0)
@@ -33,6 +34,7 @@ GEM
     htmlentities (4.3.4)
     i18n (1.6.0)
       concurrent-ruby (~> 1.0)
+    json-canonicalization (0.1.0)
     json-ld-preloaded (3.0.2)
       json-ld (~> 3.0)
       multi_json (~> 1.12)

common/extract-examples.rb

@@ -17,6 +17,11 @@
 require 'yaml'
 require 'cgi'
 
+# FIXME: This is here until the rdf:JSON is added in RDF.rb
+unless RDF::RDFV.properties.include?( RDF.to_uri + 'JSON')
+  RDF::RDFV.property :JSON, label: "JSON", comment: "JSON datatype"
+end
+
 PREFIXES = {
   dc:     "http://purl.org/dc/terms/",
   cred:   "https://w3id.org/credentials#",

common/jsonld.js

@@ -18,7 +18,7 @@ const jsonld = {
     },
     "JCS": {
       title: "JSON Canonicalization Scheme (JCS)",
-      href: 'https://tools.ietf.org/html/draft-rundgren-json-canonicalization-scheme-05#page-6',
+      href: 'https://tools.ietf.org/html/draft-rundgren-json-canonicalization-scheme-05',
       authors: ['A. Rundgren', 'B. Jordan', 'S. Erdtman'],
       publisher: 'Network Working Group',
       status: 'Internet-Draft',

common/terms.html

@@ -338,7 +338,7 @@
   <dt><dfn>JSON literal</dfn></dt><dd>
     A <a>JSON literal</a> is a <a>typed literal</a> where the associated <a>IRI</a> is <code>rdf:JSON</code>.
     In the <a>value object</a> representation, the value of <code>@type</code> is <code>@json</code>.
-    JSON literals represent values which are valid [[JSON]].
+    JSON literals represent values which are valid JSON [[RFC8259]].
     See <dfn data-cite="JSON-LD11#dfn-json-datatype" class="preserve">JSON datatype</dfn> in [[JSON-LD11]].
   </dd>
   <dt><dfn>typed literal</dfn></dt><dd>

index.html

@@ -1247,7 +1247,7 @@ <h3>Algorithm</h3>
               <code>true</code> for <var>vocab</var>,
               <var>local context</var>, and <var>defined</var>. If the expanded <var>type</var> is
               neither <code>@id</code>, nor <code>@vocab</code>,
-              <span class="changed">nor, if <a>processing mode</a> is <code>json-ld-1.1</code>, <code>@none</code>,</span>
+              <span class="changed">nor, if <a>processing mode</a> is <code>json-ld-1.1</code>, <code>@json</code> nor <code>@none</code>,</span>
               nor an <a>absolute IRI</a>, an
               <a data-link-for="JsonLdErrorCode">invalid type mapping</a>
               error has been detected and processing is aborted.</li>
@@ -1715,7 +1715,12 @@ <h3>Algorithm</h3>
           </ol>
         </li>
         <li>Initialize an empty <a class="changed">dictionary</a>, <var>result</var>.</li>
-        <li id="alg-expand-each-key-value">For each <var>key</var> and <var>value</var> in <var>element</var>,
+        <li id="alg-expand-each-key-value">
+          <span class="changed">
+            Initialize an empty <a>dictionary</a>, <var>nests</var>, and
+            <var>input type</var> to the last value of any <a>member</a> expanding to <code>@type</code>.
+          </span>
+          For each <var>key</var> and <var>value</var> in <var>element</var>,
           ordered lexicographically by <var>key</var> <span class="changed">if <a data-link-for="JsonLdOptions">ordered</a> is <code>true</code></span>:
           <ol>
             <li>If <var>key</var> is <code>@context</code>, continue to
@@ -1778,7 +1783,11 @@ <h3>Algorithm</h3>
                     and <a data-link-for="JsonLdOptions">ordered</a> flags</span>,
                   <span class="changed">
                     ensuring that <var>expanded value</var> is an <a>array</a> of one or more <a>dictionaries</a></span>.</li>
-                <li>If <var>expanded property</var> is <code>@value</code> and
+                <li>Otherwise, if <var>expanded property</var> is <code>@value</code>,
+                  <span class="changed"><a>processing mode</a> is <code>json-ld-1.1</code>, and
+                    <var>input type</var> is <code>@json</code>,
+                    set <var>expanded value</var> to <var>value</var>.
+                    Otherwise, if</span>
                   <var>value</var> is not a <a>scalar</a> or <code>null</code>, an
                   <a data-link-for="JsonLdErrorCode">invalid value object value</a>
                   error has been detected and processing is aborted. Otherwise,
@@ -1903,7 +1912,11 @@ <h3>Algorithm</h3>
               set <var>term context</var> to <var>active context</var>.</li>
             <li>Set <var>container mapping</var> to <var>key</var>'s <a>container mapping</a> in
               <var class="changed">term context</var>.</li>
-            <li>If <var>container mapping</var> <span class="changed">includes</span> <code>@language</code> and
+            <li class="changed">If <var>key</var>'s <a>term definition</a> in <var>active context</var>
+              has a <a>type mapping</a> of <code>@json</code>,
+              set <var>expanded value</var> to a new <a>dictionary</a>, set the <a>member</a>
+              <code>@value</code> to <var>value</var>, and set the member <code>@type</code> to <code>@json</code>.</li>
+            <li>Otherwise, if <var>container mapping</var> <span class="changed">includes</span> <code>@language</code> and
               <var>value</var> is a <a class="changed">dictionary</a> then <var>value</var>
               is expanded from a <a>language map</a>
               as follows:
@@ -2077,7 +2090,7 @@ <h3>Algorithm</h3>
                       <var>nested value</var> expands to <code>@value</code>, an
                       <a data-link-for="JsonLdErrorCode">invalid @nest value</a> error
                       has been detected and processing is aborted.</li>
-                    <li>Recursively repeat <a href="#alg-expand-each-key-value">step 7</a>
+                    <li>Recursively repeat <a href="#alg-expand-each-key-value">step 9</a>
                       using <var>nested value</var> for <var>element</var>.</li>
                   </ol>
                 </li>
@@ -2096,6 +2109,9 @@ <h3>Algorithm</h3>
               error has been detected and processing is aborted.</li>
             <li>If the value of <var>result</var>'s <code>@value</code> <a>member</a> is
               <code>null</code>, then set <var>result</var> to <code>null</code>.</li>
+            <li class="changed">Otherwise, if the <var>result</var>'s <code>@type</code> <a>member</a>
+              is <code>@json</code>, then the <code>@value</code> <a>member</a> may
+              contain any value, and is treated as a <a>JSON literal</a>.</li>
             <li>Otherwise, if the value of <var>result</var>'s <code>@value</code> <a>member</a>
               is not a <a>string</a> and <var>result</var> contains the <a>member</a>
               <code>@language</code>, an
@@ -2220,7 +2236,7 @@ <h3>Algorithm</h3>
           <var>value</var>.</li>
         <li>If <var>active property</var> has a <a>type mapping</a> in
           <var>active context</var>,
-          <span class="changed">other than <code>@id</code> or <code>@vocab</code>, or <code>@none</code>,</span>
+          <span class="changed">other than <code>@id</code>, <code>@vocab</code>, or <code>@none</code>,</span>
           add an <code>@type</code> <a>member</a> to
           <var>result</var> and set its value to the value associated with the
           <a>type mapping</a>.</li>
@@ -2372,7 +2388,10 @@ <h3>Algorithm</h3>
           <a href="#value-compaction">Value Compaction algorithm</a>,
           passing <var>active context</var>, <var>inverse context</var>,
           <var>active property</var>,and <var>element</var> as <var>value</var> is
-          a <a>scalar</a>, return that result.</li>
+          a <a>scalar</a>,
+          <span class="changed">or the <a>term definition</a> for <var>active property</var>
+            has a <a>type mapping</a> of <code>@json</code>,</span>
+          return that result.</li>
         <li class="changed">If <var>element</var> is a
           <a>list object</a>, and the <a>container mapping</a> for
           <var>active property</var> in <var>active context</var> is <code>@list</code>,
@@ -2938,7 +2957,7 @@ <h3>Algorithm</h3>
               </ol>
             </li>
             <li class="changed">Otherwise, if <a>term definition</a> has a
-              <a>type mapping</a> which is <code>@none</code>:</li>
+              <a>type mapping</a> which is <code>@none</code>:
               <ol>
                 <li>Reference the value associated with the <code>@language</code>
                   <a>member</a> in <var>type/language map</var> using the variable
@@ -2953,6 +2972,7 @@ <h3>Algorithm</h3>
                   <a>member</a>, create one and set its value to the <a>term</a>
                   being processed.</li>
               </ol>
+            </li>
             <li>Otherwise, if <a>term definition</a> has a
               <a>type mapping</a>:
               <ol>
@@ -4235,6 +4255,18 @@ <h3>Algorithm</h3>
         <li class="changed">If <var>datatype</var> is not <a>well-formed</a>, return <code>null</code>.</li>
         <li class="changed">If <var>item</var> has a <code>@language</code>
           <a>member</a> which is not <a>well-formed</a>, return <code>null</code>.</li>
+        <li class="changed">If <var>datatype</var> is <code>@json</code>,
+          convert <var>value</var> to the <a>canonical lexical form</a>
+          using the result of transforming the <a>internal representation</a> of <var>value</var>
+          to JSON and set <var>datatype</var> to <code>rdf:JSON</code>.
+          <div class="issue atrisk">The JSON Canonicalization Scheme [[?JCS]]
+            is an emerging standard for JSON canonicalization
+            not yet ready to be referenced.
+            When a JSON canonicalization standard becomes available,
+            this specification will likely be updated to require such a canonical representation.
+            Users are cautioned from depending on the
+            <a>JSON literal</a> lexical representation as an <a>RDF literal</a>,
+            as the specifics of serialization may change in a future revison of this document.</div></li>
         <li>If <var>value</var> is <code>true</code> or
           <code>false</code>, set <var>value</var> to the <a>string</a>
           <code>true</code> or <code>false</code> which is the
@@ -4552,6 +4584,11 @@ <h3>Overview</h3>
         <a>value objects</a> whereas <a>IRIs</a> and
         <a>blank node identifiers</a> are
         transformed to <a>node objects</a>.
+        <span class="changed">Literals with datatype <code>rdf:JSON</code>
+          are transformed into a value object using the internal representation
+          based on the lexical-to-value mapping defined in
+          <a data-cite="JSON-LD11#dfn-json-datatype" class="externalDfn">JSON datatype</a> in [[JSON-LD11]],
+          and <code>@type</code> of <code>@json</code>.</span>
         If the <a data-link-for="JsonLdOptions">useNativeTypes</a> flag is set to <code>true</code>,
         <a>RDF literals</a> with a
         <a>datatype IRI</a>
@@ -4610,6 +4647,11 @@ <h3>Algorithm</h3>
                   to a JSON <a>number</a>.</li>
               </ol>
             </li>
+            <li class="changed">Otherwise, if <a>processing mode</a> is <code>json-ld-1.1</code>,
+              and <var>value</var> is a <a>JSON literal</a>,
+              set the <code>@value</code> <a>member</a> to the result of
+              turning the lexical value of <var>value</var>
+              into the <a>JSON-LD internal representation</a>, and set <var>type</var> to <code>@json</code>.</li>
             <li>Otherwise, if <var>value</var> is a
               <a>language-tagged string</a>
               add a <a>member</a> <code>@language</code> to <var>result</var> and set its value to the
@@ -4638,7 +4680,7 @@ <h2>Data Round Tripping</h2>
       or not (the result of a modulo&#8209;1 operation), the boolean values
       <code>true</code> and <code>false</code> are coerced to <code>xsd:boolean</code>,
       and <a>strings</a> are coerced to <code>xsd:string</code>.
-      The numeric or boolean values themselves are converted to
+      The <span class="changed">JSON</span>, numeric, or boolean values themselves are converted to
       <dfn>canonical lexical form</dfn>, i.e., a deterministic string
       representation as defined in [[XMLSCHEMA11-2]].</p>
 
@@ -4692,6 +4734,74 @@ <h2>Data Round Tripping</h2>
       values <code>true</code> and <code>false</code> are the strings
       <code>true</code> and <code>false</code>.</p>
 
+    <p class="changed">The <a>canonical lexical form</a> of a <a>JSON literal</a>
+      value is non-normative, as a normative recommendation for
+      JSON canonicalization is not yet defined. Implementations
+      SHOULD use the following guidelines when creating the lexical
+      representation of a <a>JSON literal</a>:</p>
+    <ul class="changed">
+      <li>Serialize JSON using no unnecessary whitespace,</li>
+      <li>Keys in objects SHOULD be ordered lexicographically,</li>
+      <li>Native Numeric values SHOULD be serialized according to
+        <a data-cite="?ECMASCRIPT#sec-tostring-applied-to-the-number-type">Section 7.1.12.1</a> of [[?ECMASCRIPT]],</li>
+      <li>Strings SHOULD be serialized with Unicode codepoints from <code>U+0000</code> through <code>U+001F</code>
+        using lowercase hexaddecimal Unicode notation (<code>\uhhhh</code>) unless in the set
+        of predefined JSON control characters <code>U+0008</code>, <code>U+0009</code>,
+        <code>U+000A</code>, <code>U+000C</code> or <code>U+000D</code>
+        which SHOULD be serialized as <code>\b</code>, <code>\t</code>, <code>\n</code>, <code>\f</code> and <code>\r</code> respectively.
+        All other Unicode characters SHOULD be serialized "as is", other than
+        <code>U+005C</code> (<code>\</code>) and <code>U+0022</code> (<code>"</code>)
+        which SHOULD be serialized as <code>\\</code> and <code>\"</code> respectively.</li>
+    </ul>
+
+    <p class="issue atrisk changed">The JSON Canonicalization Scheme [[?JCS]]
+      is an emerging standard for JSON canonicalization
+      not yet ready to be referenced.
+      When a JSON canonicalization standard becomes available,
+      this specification will likely be updated to require such a canonical representation.
+      Users are cautioned from depending on the
+      <a>JSON literal</a> lexical representation as an <a>RDF literal</a>,
+      as the specifics of serialization may change in a future revison of this document.</p>
+
+    <aside class="example changed" data-ignore
+           title="Canonicalized JSON literal">
+      <pre class="original" data-transform="updateExample">
+      <!--
+      {
+        "@context": {
+          "@version": 1.1,
+          "e": {"@id": "http://example.org/vocab#json", ****"@type": "@json"****}
+        },
+        "e": ****[
+          56.0,
+          {
+            "d": true,
+            "10": null,
+            "1": [ ]
+          }
+        ]****
+      }
+      -->
+      </pre>
+
+      <p>The example shows the value of "e" as a native JSON array including
+        unnecessary whitespace, a number and an object. The result
+        eliminates the whitespace, uses a canonical number representation,
+        and reorders the object members lexicographically:</p>
+
+      <pre class="turtle"
+           data-content-type="text/turtle"
+           data-result-for="Canonicalized JSON literal-original"
+           data-transform="updateExample"
+           data-to-rdf>
+      <!--
+      @prefix ex: <http://example.org/vocab#> .
+      @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+      [ex:json ****"""[56,{"1":[],"10":null,"d":true}]"""^^rdf:JSON****] .
+      -->
+      </pre>
+    </aside>
+
     <p>When JSON-native <a>numbers</a> are deserialized
       to RDF, lossless data round-tripping cannot be guaranteed, as rounding
       errors might occur. When
@@ -5731,6 +5841,7 @@ <h2>Changes since JSON-LD Community Group Final Report</h2>
     <li>Because scoped contexts can lead to contexts being reloaded, replace the
       <strong>recursive context inclusion</strong> error with a <a data-link-for="JsonLdErrorCode">context overflow</a> error.</li>
     <li>Added support for <code>"@type": "@none"</code> in a <a>term definition</a> to prevent value compaction.</li>
+    <li>Added support for <a>JSON literals</a>.</li>
   </ul>
 </section>