Merge pull request #449 from json-ld/issue-430-containers

Issue 430 containers

Author: gkellogg

spec/latest/common/terms.html

@@ -110,7 +110,14 @@ <h1>General Terminology</h1>
       <a>node object</a> or a <a>value object</a> in the input.</dd>
     <dt><dfn data-lt="graph names">graph name</dfn></dt><dd>
       The <a>IRI</a> identifying a <a>named graph</a>.</dd>
-    <dt><dfn data-lt="index maps">index map</dfn></dt><dd>
+    <dt class="changed"><dfn data-lt="id maps">id map</dfn></dt><dd class="changed">
+      An <a>id map</a> is a <a>JSON object</a> value of a <a>term</a> defined with
+      <code>@container</code> set to <code>@id</code>, who's keys are
+      interpreted as <a>IRIs</a> representing the <code>@id</code>
+      of the associated <a>node object</a>; value MUST be a <a>node object</a>.
+      If the value contains a property expanding to <code>@id</code>, it's value MUST
+      be equivalent to the referencing key.</dd>
+     <dt><dfn data-lt="index maps">index map</dfn></dt><dd>
       An <a>index map</a> is a <a>JSON object</a> value of a <a>term</a> defined with
       <code>@container</code> set to <code>@index</code>, whose values MUST be any of the following types:
         <a>string</a>,
@@ -244,6 +251,14 @@ <h1>General Terminology</h1>
       a <a>JSON object</a> as a <a>property</a>, type, or elsewhere that a string is interpreted as a vocabulary item.
       Its value is either a string, expanding to an absolute IRI, or an <a>expanded term definition</a>.
     </dd>
+    <dt class="changed"><dfn data-lt="type maps">type map</dfn></dt><dd class="changed">
+      An <a>type map</a> is a <a>JSON object</a> value of a <a>term</a> defined with
+      <code>@container</code> set to <code>@type</code>, who's keys are
+      interpreted as <a>IRIs</a> representing the <code>@type</code>
+      of the associated <a>node object</a>;
+      value MUST be a <a>node object</a>, or <a>array</a> of node objects.
+      If the value contains a property expanding to <code>@type</code>, it's values
+      are merged with the map value when expanding.</dd>
     <dt><dfn>typed literal</dfn></dt><dd>
       A <a>typed literal</a> is a <a>literal</a> with an associated <a>IRI</a>
       which indicates the literal's datatype. See <cite><a

spec/latest/json-ld-api/index.html

@@ -987,6 +987,7 @@ <h3>Algorithm</h3>
             <li>Initialize <em>container</em> to the value associated with the
               <code>@container</code> key, which must be either
               <code>@list</code>, <code>@set</code>, <code>@index</code>,
+              <span class="changed"><code>@id</code>, <code>@type</code></span>
               or <code>@language</code>. Otherwise, an
               <a data-link-for="JsonLdErrorCode">invalid container mapping</a>
               has been detected and processing is aborted.</li>
@@ -1470,9 +1471,10 @@ <h3>Algorithm</h3>
               </ol>
             </li>
             <li>Otherwise, if <em>key</em>'s <a>container mapping</a> in
-              <em class="changed">term context</em> is <code>@index</code> and
+              <em class="changed">term context</em> is <code>@index</code>,
+              <span class="changed"><code>@type</code>, or <code>@id</code></span> and
               <em>value</em> is a <a>JSON object</a> then <em>value</em>
-              is expanded from an index map as follows:
+              is expanded from an map as follows:
               <ol class="algorithm">
                 <li>Initialize <em>expanded value</em> to an empty
                   <a>array</a>.</li>
@@ -1488,11 +1490,23 @@ <h3>Algorithm</h3>
                       <em>key</em> as <a>active property</a>,
                       and <em>index value</em> as <em>element</em>.</li>
                     <li>For each <em>item</em> in <em>index value</em>:
-                      <ol class="algorithm">
-                        <li>If <em>item</em> does not have the key
+                      <ol class="algorithm changed">
+                        <li>If <a>container mapping</a> is <code>@index</code>
+                          and <em>item</em> does not have the key
                           <code>@index</code>, add the key-value pair
                           (<code>@index</code>-<em>index</em>) to
                           <em>item</em>.</li>
+                        <li>Otherwise, if <a>container mapping</a> is <code>@id</code>
+                          and <em>item</em> does not have the key
+                          <code>@id</code>, add the key-value pair
+                          (<code>@id</code>-<em>index</em>) to
+                          <em>item</em>.</li>
+                        <li>Otherwise, if <a>container mapping</a> is <code>@type</code>
+                          set <em>types</em> to the concatenation of <em>index
+                          value</em> with any existing values of
+                          <code>@type</code> in <em>item</em> and add the
+                          key-value pair (<code>@type</code>-<em>types</em>) to
+                          <em>item</em>.</li>
                         <li>Append <em>item</em> to <em>expanded value</em>.</li>
                       </ol>
                     </li>
@@ -1994,20 +2008,39 @@ <h3>Algorithm</h3>
                   </ol>
                 </li>
                 <li>
-                  If <em>container</em> is <code>@language</code> or
-                  <code>@index</code>:
+                  If <em>container</em> is <code>@language</code>,
+                  <code>@index</code>, <span class="changed"><code>@id</code>,
+                    or <code>@type</code></span>:
                   <ol class="algorithm">
                     <li>If <em>item active property</em> is not a key in
                       <em>result</em>, initialize it to an empty <a>JSON object</a>.
                       Initialize <em>map object</em> to the value of <em>item active property</em>
                       in <em>result</em>.</li>
+                    <li>Set <em>compacted container</em> to the result of calling the 
+                      <a href="#iri-compaction">IRI Compaction algorithm</a>
+                      passing <a>active context</a>,
+                      <em>container</em> as <em>iri</em>, and <code>true</code>
+                      for <em>vocab</em>.</li>
                     <li>If <em>container</em> is <code>@language</code> and
                       <em>compacted item</em> contains the key
                       <code>@value</code>, then set <em>compacted item</em>
                       to the value associated with its <code>@value</code> key.</li>
-                    <li>Initialize <em>map key</em> to the value associated with
+                    <li>If <em>container</em> is <code>@index</code>,
+                      set <em>map key</em> to the value associated with
                       with the key that equals <em>container</em> in
                       <em>expanded item</em>.</li>
+                    <li class="changed">If <em>container</em> is <code>@id</code>, set
+                      <em>map key</em> to the value associated with the key that equals
+                      <em>compacted container</em> in <em>compacted item</em>
+                      and remove that key-value pair from <em>compacted item</em>.</li>
+                    <li class="changed">If <em>container</em> is <code>@type</code>,
+                      set <em>map key</em> to the first value associated with
+                      the key that equals <em>container</em> in <em>expanded
+                      item</em>. If there are remaining values in <em>compacted
+                      item</em> for <em>compacted container</em>, set the value
+                      of <em>compacted container</em> in <em>compacted
+                      value</em> to those remaining values. Otherwise, remove
+                      that key-value pair from <em>compacted item</em>.</li>
                     <li>If <em>map key</em> is not a key in <em>map object</em>,
                       then set this key's value in <em>map object</em>
                       to <em>compacted item</em>. Otherwise, if the value
@@ -2284,9 +2317,10 @@ <h3>Algorithm</h3>
               variables will keep track of the preferred
               <a>type mapping</a> or <a>language mapping</a> for
               a <a>term</a>, based on what is compatible with <em>value</em>.</li>
-            <li>If <em>value</em> is a <a>JSON object</a> that contains the
-              key <code>@index</code>, then append the value <code>@index</code>
-              to <em>containers</em>.</li>
+            <li>If <em>value</em> is a <a>JSON object</a>,
+              <span class="changed">then for the keywords <code>@index</code>,
+              <code>@id</code>, and <code>@type</code>, if <em>value</em>
+              contains that <a>keyword</a>, append it to <em>containers</em>.</span></li>
             <li>If <em>reverse</em> is <code>true</code>, set <em>type/language</em>
               to <code>@type</code>, <em>type/language value</em> to
               <code>@reverse</code>, and append <code>@set</code> to <em>containers</em>.</li>
@@ -4208,6 +4242,8 @@ <h2>Changes since 1.0 Recommendation of 16 January 2014</h2>
     <li>A new <a href="#merge-node-maps" class="sectionRef"></a> is required
       for framing, to create a single graph from the <a data-lt="default graph">default</a>
       and <a>named graphs</a>.</li>
+    <li><code>@container</code> values within an <a>expanded term definition</a> may now
+      include <code>@id</code> and <code>@type</code>, corresponding to <a>id maps</a> and <a>type maps</a>.</li>
   </ul>
 </section>
 

spec/latest/json-ld/index.html

@@ -2583,6 +2583,107 @@ <h2>Data Indexing</h2>
   </table>
 </section>
 
+<section class="informative changed">
+  <h2>Node Identifier Indexing</h2>
+
+  <p>In addition to <a>index maps</a>, JSON-LD introduces the notion of <a>id maps</a>
+    for structuring data. The id indexing feature allows an author to
+    structure data using a simple key-value map where the keys map
+    to <a>IRIs</a>. This enables direct access to associated <a>node objects</a>
+    instead of having to scan an array in search of a specific item.
+    In JSON-LD such data can be specified by associating the
+    <code>@id</code> <a>keyword</a> with a
+    <code>@container</code> declaration in the context:</p>
+
+  <pre class="example" data-transform="updateExample"
+       title="Indexing data in JSON-LD by node identifiers">
+  <!--
+  {
+    "@context":
+    {
+       "schema": "http://schema.org/",
+       "name": "schema:name",
+       "body": "schema:articleBody",
+       "words": "schema:wordCount",
+       "post": {
+         "@id": "schema:blogPost",
+         ****"@container": "@id"****
+       }
+    },
+    "@id": "http://example.com/",
+    "@type": "schema:Blog",
+    "name": "World Financial News",
+    ****"post": {
+       "http://example.com/posts/1/en": {
+         "body": "World commodities were up today with heavy trading of crude oil...",
+         "words": 1539
+       },
+       "http://example.com/posts/1/de": {
+         "body": "Die Werte an Warenbörsen stiegen im Sog eines starken Handels von Rohöl...",
+         "words": 1204
+       }****
+    }
+  }
+  -->
+  </pre>
+
+  <p>In the example above, the <code>post</code> <a>term</a> has
+    been marked as an <a>id map</a>. The <code>http://example.com/posts/1/en</code> and
+    <code>http://example.com/posts/1/de</code> keys will be interpreted
+    as the <code>@id</code> property of the <a>node object</a> value.</p>
+
+  <p>The interpretation of the data above is exactly the same
+    as that in <a class="sectionRef" href="#data-indexing"></a>
+    using a JSON-LD processor.</p>
+</section>
+
+<section class="informative changed">
+  <h2>Node Type Indexing</h2>
+
+  <p>In addition to <a data-lt="id map">id</a> and <a>index maps</a>, JSON-LD introduces the notion of <a>type maps</a>
+    for structuring data. The type indexing feature allows an author to
+    structure data using a simple key-value map where the keys map
+    to <a>IRIs</a>. This enables data to be structured based on the <code>@type</code>
+    of specific <a>node objects</a>.
+    In JSON-LD such data can be specified by associating the
+    <code>@type</code> <a>keyword</a> with a
+    <code>@container</code> declaration in the context:</p>
+
+  <pre class="example" data-transform="updateExample"
+       title="Indexing data in JSON-LD by node identifiers">
+  <!--
+  {
+    "@context":
+    {
+       "schema": "http://schema.org/",
+       "name": "schema:name",
+       "affiliation": {
+         "@id": "schema:affiliation",
+         ****"@container": "@type"****
+       }
+    },
+    "name": "Manu Sporny",
+    "affiliation": {
+      ****"schema:Corporpation"****: {
+        "@id": "http://digitalbazaar.com/",
+        "name": "Digital Bazaar"
+      },
+      ****"schema:ProfessionalService"****: {
+        "@id": "https://spec-ops.io",
+        "name": "Spec-Ops"
+      }
+      
+    }
+  }
+  -->
+  </pre>
+
+  <p>In the example above, the <code>affiliation</code> <a>term</a> has
+    been marked as an <a>type map</a>. The <code>schema:Corporpation</code> and
+    <code>schema:ProfessionalService</code> keys will be interpreted
+    as the <code>@type</code> property of the <a>node object</a> value.</p>
+</section>
+
 <section class="informative">
   <h3>Expanded Document Form</h3>
 
@@ -3186,6 +3287,34 @@ <h2>Index Maps</h2>
     <p>See <a class="sectionRef" href="#data-indexing"></a> for further information on this topic.</p>
   </section>
 
+  <section class="changed">
+    <h2>Id Maps</h2>
+
+    <p>An <a>id map</a> is used to associate an <a>IRI</a> with a value that allows easy
+      programatic access. An <a>id map</a> may be used as a term value within a <a>node object</a> if the <a>term</a>
+      is defined with <code>@container</code> set to <code>@id</code>. The keys of an <a>id map</a> MUST be <a>IRIs</a>
+      (<a>relative IRI</a>, <a>compact IRI</a> (including <a>blank node identifiers</a>), or <a>absolute IRI</a>)
+      and the values MUST be <a>node objects</a>.</p>
+
+    <p>If the value contains a property expanding to <code>@id</code>, it's value MUST
+      be equivalent to the referencing key. Otherwise, the property from the value is used as
+      the <code>@id</code> of the <a>node object</a> value when expanding.</p>
+  </section>
+
+  <section class="changed">
+    <h2>Type Maps</h2>
+
+    <p>An <a>type map</a> is used to associate an <a>IRI</a> with a value that allows easy
+      programatic access. An <a>id map</a> may be used as a term value within a <a>node object</a> if the <a>term</a>
+      is defined with <code>@container</code> set to <code>@id</code>. The keys of an <a>id map</a> MUST be <a>IRIs</a>
+      (<a>relative IRI</a>, <a>compact IRI</a> (including <a>blank node identifiers</a>), or <a>absolute IRI</a>)
+      and the values MUST be <a>node objects</a>.</p>
+
+    <p>If the value contains a property expanding to <code>@id</code>, it's value MUST
+      be equivalent to the referencing key. Otherwise, the property from the value is used as
+      the <code>@id</code> of the <a>node object</a> value when expanding.</p>
+  </section>
+
 <section class="normative">
   <h2>Context Definitions</h2>
 
@@ -3451,17 +3580,16 @@ <h2>Changes since 1.0 Recommendation of 16 January 2014</h2>
     <li>An <a>expanded term definition</a> can now have an
       <code>@context</code> property, which defines a <a>context</a> used for values of
       a <a>property</a> identified with such a <a>term</a>.</li>
+    <li><code>@container</code> values within an <a>expanded term definition</a> may now
+      include <code>@id</code> and <code>@type</code>, corresponding to <a>id maps</a> and <a>type maps</a>.</li>
   </ul>
 </section>
 
 <section class="appendix informative">
   <h4>Open Issues</h4>
   <p>The following is a list of open issues being worked on for the next release.</p>
-  <p class="issue" data-number="12"></p>
   <p class="issue" data-number="195"></p>
   <p class="issue" data-number="246"></p>
-  <p class="issue" data-number="247"></p>
-  <p class="issue" data-number="262"></p>
   <p class="issue" data-number="269"></p>
   <p class="issue" data-number="271"></p>
   <p class="issue" data-number="272"></p>

test-suite/README.md

@@ -23,6 +23,7 @@ Tests are defined into _compact_, _expand_, _flatten_, _frame_, _normalize_, and
   contained within the _sparql_ document using a SPARQL endpoint. The end result is a
   yes/no on whether the expected triples were extracted by the JSON-LD processor.
 
+Unless `processingMode` is set explicitly in a test entry, `processingMode` is compatible with both `json-ld-1.0` and `json-ld-1.1`. Otherwise, a JSON-LD 1.0 processor should not run tests marked `json-ld-1.1` and a JSON-LD 1.1 processor should not run tests marked `json-ld-1.0`.
 
 Contributing
 ------------

test-suite/index.html

@@ -166,6 +166,11 @@ <h2 id="design" class="span12" style="text-align: center;">Running the test suit
           <p>To run the tests, create a test runner which will run through each test manifest
             and execute the tests defined within the manifest using the rules associated with
             each <code>@type</code> defined for the test case as defined in <a href="vocab">the test vocabulary</a>.</p>
+          <p>Unless <code>processingMode</code> is set explicitly in a test entry,
+            <code>processingMode</code> is compatible with both <code>json-ld-1.0</code> and
+            <code>json-ld-1.1</code>. Otherwise, a JSON-LD 1.0 processor should not run
+            tests marked <code>json-ld-1.1</code> and a JSON-LD 1.1 processor should not run
+            tests marked <code>json-ld-1.0</code>. </p>
           <p>Note that property values are typed, and those which are typed as <code>@id</code> must
             be treated as IRIs relative to the manifest test base. In particular, this means that
             <em>input</em>, </em>context</em>, <em>frame</em>, and <em>expandContext</em> are to be

test-suite/tests/compact-m001-context.jsonld

@@ -0,0 +1,6 @@
+{
+  "@context": {
+    "@vocab": "http://example/",
+    "idmap": {"@container": "@id"}
+  }
+}

test-suite/tests/compact-m001-in.jsonld

@@ -0,0 +1,6 @@
+[{
+  "http://example/idmap": [
+    {"http://example/label": [{"@value": "Object with @id _:bar"}], "@id": "_:bar"},
+    {"http://example/label": [{"@value": "Object with @id <foo>"}], "@id": "http://example.org/foo"}
+  ]
+}]

test-suite/tests/compact-m001-out.jsonld

@@ -0,0 +1,10 @@
+{
+  "@context": {
+    "@vocab": "http://example/",
+    "idmap": {"@container": "@id"}
+  },
+  "idmap": {
+    "http://example.org/foo": {"label": "Object with @id <foo>"},
+    "_:bar": {"label": "Object with @id _:bar"}
+  }
+}

test-suite/tests/compact-m002-context.jsonld

@@ -0,0 +1,6 @@
+{
+  "@context": {
+    "@vocab": "http://example/",
+    "idmap": {"@container": "@id"}
+  }
+}

test-suite/tests/compact-m002-in.jsonld

@@ -0,0 +1,6 @@
+[{
+  "http://example/idmap": [
+    {"@id": "_:foo", "http://example/label": [{"@value": "Object with @id _:bar"}]},
+    {"@id": "http://example.org/bar", "http://example/label": [{"@value": "Object with @id <foo>"}]}
+  ]
+}]