Merge pull request #453 from json-ld/issue-246-nesting2

This adds a `@nest` member to term definitions used for _transparent properties_

Author: gkellogg

spec/latest/common/terms.html

@@ -180,6 +180,10 @@ <h1>General Terminology</h1>
       specified via the <code>@context</code> <a>keyword</a>.</dd>
     <dt><dfn data-lt="named graphs">named graph</dfn></dt><dd>
       A <a>linked data graph</a> that is identified by an <a>IRI</a> or <a>blank node</a>
+    <dt><dfn data-lt="nested properties">nested property</dfn></dt><dd>
+      A <a>nested property</a> is a <a>property</a> which is contained within an object referenced by
+      a semantically meaningless <em>nesting property</em>.
+    </dd>
       (the <a>graph name</a>) and a <a>graph</a>.</dd>
     <dt><dfn data-lt="nodes">node</dfn></dt><dd>
       Every <a>node</a> is an <a>IRI</a>, a <a>blank node</a>,

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

@@ -903,7 +903,7 @@ <h3>Algorithm</h3>
         </li>
         <li>If <em>value</em> contains the key <code>@reverse</code>:
           <ol class="algorithm">
-            <li>If <em>value</em> contains an <code>@id</code>, member, an
+            <li>If <em>value</em> contains <code>@id</code> or <code>@nest</code>, members, an
               <a data-link-for="JsonLdErrorCode">invalid reverse property</a>
               error has been detected and processing is aborted.</li>
             <li>If the value associated with the <code>@reverse</code> key
@@ -1020,9 +1020,18 @@ <h3>Algorithm</h3>
               of <em>definition</em> to <em>language</em>.</li>
           </ol>
         </li>
+        <li class="changed">If <em>value</em> contains the key <code>@nest</code>:
+          <ol class="algorithm">
+            <li>Initialize <em>nest</em> to the value associated with the
+              <code>@nest</code> key, which must be a <a>string</a> and
+              must not be a keyword other than <code>@nest</code>. Otherwise, an
+              <a data-link-for="JsonLdErrorCode">invalid @nest value</a>
+              error has been detected and processing is aborted.</li>
+          </ol>
+        </li>
         <li>If the value contains any key other than <code>@id</code>,
           <code>@reverse</code>, <code>@container</code>,
-          <code>@context</code>, or <code>@type</code>, an
+          <code>@context</code>, <code class="changed">@nest</code>, or <code>@type</code>, an
           <a data-link-for="JsonLdErrorCode">invalid term definition</a> error has
           been detected and processing is aborted.</li>
         <li>Set the <a>term definition</a> of <em>term</em> in
@@ -1270,7 +1279,7 @@ <h3>Algorithm</h3>
           passing <a>active context</a> and the value of the
           <code>@context</code> key as <a>local context</a>.</li>
         <li>Initialize an empty <a>JSON object</a>, <em>result</em>.</li>
-        <li>For each <em>key</em> and <em>value</em> in <em>element</em>,
+        <li id="alg-expand-each-key-value">For each <em>key</em> and <em>value</em> in <em>element</em>,
           ordered lexicographically by <em>key</em>:
           <ol class="algorithm">
             <li>If <em>key</em> is <code>@context</code>, continue to
@@ -1418,6 +1427,10 @@ <h3>Algorithm</h3>
                     <li>Continue with the next <em>key</em> from <em>element</em>.</li>
                   </ol>
                 </li>
+                <li class="changed">If <em>expanded property</em> is <code>@nest</code>,
+                  add <em>key</em> to <em>nests</em>, initializing it to an empty <a>array</a>,
+                  if necessary.
+                  Continue with the next <em>key</em> from <em>element</em>.</li>
                 <li class="changed">When the <code>frame expansion</code> flag is set,
                   if <em>expanded property</em> is any other
                   framing keyword (<code>@explicit</code>, <code>@default</code>,
@@ -1559,6 +1572,22 @@ <h3>Algorithm</h3>
                   member of <em>result</em>.</li>
               </ol>
             </li>
+            <li class="changed">For each key <em>nesting-key</em> in <em>nests</em>
+              <ol class="algorithm">
+                <li>Set <em>nested values</em> to the value of <em>nesting-key</em>
+                  in <em>element</em>, ensuring that it is an <a>array</a>.</li>
+                <li>For each <em>nested value</em> in <em>nested values</em>:
+                  <ol class="algorithm">
+                    <li>If <em>nested value</em> is not a <a>JSON object</a>, or any key within
+                      <em>nested value</em> 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>
+                      using <em>nested value</em> for <em>element</em>.</li>
+                  </ol>
+                </li>
+              </ol>
+            </li>
           </ol>
         </li>
         <li>If <em>result</em> contains the key <code>@value</code>:
@@ -1942,7 +1971,22 @@ <h3>Algorithm</h3>
                   <em>expanded value</em> for <em>value</em>,
                   <code>true</code> for <em>vocab</em>, and
                   <em>inside reverse</em>.</li>
-                <li>If <em>result</em> does not have the key that equals
+                <li class="changed">If the <a>term definition</a> for <em>item active property</em>
+                  in the <em>active context</em> has a <code>@nest</code>
+                  member, that value (<em>nest term</em>) must be
+                  <code>@nest</code>, or a <a>term definition</a> in the
+                  <em>active context</em> that expands to <code>@nest</code>,
+                  otherwise an <a data-link-for="JsonLdErrorCode">invalid @nest
+                  value</a> error has been detected, and processing is aborted.
+                  If <em>result</em> does not have the key that equals <em>nest
+                  term</em>, initialize it to an empty JSON object (<em>nest
+                  object</em>). If <em>nest object</em> does not have the key
+                  that equals <em>item active property</em>, set this key's
+                  value in <em>nest object</em> to an empty
+                  <a>array</a>.Otherwise, if the key's value is not an
+                  <a>array</a>, then set it to one containing only the
+                  value.</li>
+                <li>Otherwise, if <em>result</em> does not have the key that equals
                   <em>item active property</em>, set this key's value in
                   <em>result</em> to an empty <a>array</a>. Otherwise, if
                   the key's value is not an <a>array</a>, then set it
@@ -1962,6 +2006,16 @@ <h3>Algorithm</h3>
                   <em>expanded item</em> for <em>value</em>,
                   <code>true</code> for <em>vocab</em>, and
                   <em>inside reverse</em>.</li>
+                <li class="changed">If the <a>term definition</a> for <em>item active property</em>
+                  in the <em>active context</em> has a <code>@nest</code>
+                  member, that value (<em>nest term</em>) must be
+                  <code>@nest</code>, or a <a>term definition</a> in the
+                  <em>active context</em> that expands to <code>@nest</code>,
+                  otherwise an <a data-link-for="JsonLdErrorCode">invalid @nest
+                  value</a> error has been detected, and processing is aborted.
+                  Set <em>nest result</em> to the value of <em>nest term</em> in <em>result</em>,
+                  initializing it to a new <a>JSON object</a>, if necessary; otherwise
+                  set <em>nest result</em> to <em>result</em>.</li>
                 <li>Initialize <em>container</em> to <code>null</code>. If there
                   is a <a>container mapping</a> for
                   <em>item active property</em> in <a>active context</a>,
@@ -1999,7 +2053,7 @@ <h3>Algorithm</h3>
                       </ol>
                     </li>
                     <li>Otherwise, <em>item active property</em> must not be a key
-                      in <em>result</em> because there cannot be two
+                      in <em class="changed">nest result</em> because there cannot be two
                       <a>list objects</a> associated
                       with an <a>active property</a> that has a
                       <a>container mapping</a>; a
@@ -2013,14 +2067,17 @@ <h3>Algorithm</h3>
                     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>.
+                      <em class="changed">nest 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>
+                      in <em class="changed">nest 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>Initialize <em>map key</em> to the value associated with
+                      with the key that equals <em>container</em> in
+                      <em>expanded item</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>
@@ -2063,9 +2120,9 @@ <h3>Algorithm</h3>
                     <li>If <em>item active property</em> is not a key in
                       <em>result</em> then add the key-value pair,
                       (<em>item active property</em>-<em>compacted item</em>),
-                      to <em>result</em>.</li>
+                      to <em class="changed">nest result</em>.</li>
                     <li>Otherwise, if the value associated with the key that
-                      equals <em>item active property</em> in <em>result</em>
+                      equals <em>item active property</em> in <em class="changed">nest result</em>
                       is not an <a>array</a>, set it to a new
                       <a>array</a> containing only the value. Then
                       append <em>compacted item</em> to the value if
@@ -4082,6 +4139,7 @@ <h4>JsonLdErrorCode</h4>
             "cyclic IRI mapping",
             "invalid @id value",
             "invalid @index value",
+            "invalid @nest value",
             "invalid @reverse value",
             "invalid base IRI",
             "invalid container mapping",
@@ -4133,6 +4191,8 @@ <h4>JsonLdErrorCode</h4>
         <dt><dfn>invalid @index value</dfn></dt>
         <dd>An <code>@index</code> member was encountered whose value was
           not a <a>string</a>.</dd>
+        <dt class="changed"><dfn>invalid @nest value</dfn></dt>
+        <dd class="changed">An invalid value for <code>@nest</code> has been found.</dd>
         <dt><dfn>invalid @reverse value</dfn></dt>
         <dd>An invalid value for an <code>@reverse</code> member has been detected,
           i.e., the value was not a <a>JSON object</a>.</dd>
@@ -4242,6 +4302,12 @@ <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>An <a>expanded term definition</a> can now have an
+      <code>@nest</code> property, which identifies a term expanding to
+      <code>@nest</code> which is used for containing properties using the same
+      <code>@nest</code> mapping. When expanding, the values of a property
+      expanding to <code>@nest</code> are treated as if they were contained
+      within the enclosing <a>node object</a> directly.</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>

spec/latest/json-ld/index.html

@@ -395,6 +395,8 @@ <h2>Syntax Tokens and Keywords</h2>
         <a>IRI</a>. This keyword is described in <a class="sectionRef" href="#default-vocabulary"></a>.</dd>
       <dt><code>@graph</code></dt><dd>Used to express a <a>graph</a>.
         This keyword is described in <a class="sectionRef" href="#named-graphs"></a>.</dd>
+      <dt class="changed"><code>@nest</code></dt><dd class="changed">Collects a set of <a>nested properties</a> within
+        a <a>node object</a>.</dd>
       <dt><code>:</code></dt>
       <dd>The separator for JSON keys and values that use
         <a>compact IRIs</a>.</dd>
@@ -2684,6 +2686,85 @@ <h2>Node Type Indexing</h2>
     as the <code>@type</code> property of the <a>node object</a> value.</p>
 </section>
 
+<section class="informative changed">
+  <h2>Nested Properties</h2>
+
+  <p>Many JSON APIs separate properties from their entities using an
+    intermediate object; in JSON-LD these are called <a>nested properties</a>.
+    For example, a set of possible labels may be grouped
+    under a common property:</p>
+  <pre class="example" data-transform="updateExample"
+       title="Nested properties">
+  <!--
+  {
+    "@context": {
+      "skos": "http://www.w3.org/2004/02/skos/core#",
+      ****"labels": "@nest"****,
+      "main_label": {"@id": "skos:prefLabel"},
+      "other_label": {"@id": "skos:altLabel"},
+      "homepage": {"@id": "http://schema.org/description", "@type": "@id"}
+    },
+    "@id": "http://example.org/myresource",
+    "homepage": "http://example.org",
+    "labels": {
+       "main_label": "This is the main label for my resource",
+       "other_label": "This is the other label"
+    }
+  }
+  -->
+  </pre>
+
+  <p>By defining <em>labels</em> using the <a>keyword</a> <code>@nest</code>,
+    a <a>JSON-LD processor</a> will ignore the nesting created by using the
+    <em>labels</em> property and process the contents as if it were declared
+    directly within containing object. In this case, the <em>labels</em>
+    property is semantically meaningless. Defining it as equivalent to
+    <code>@nest</code> causes it to be ignored when expanding, making it
+    equivalent to the following:</p>
+
+  <pre class="example" data-transform="updateExample"
+       title="Nested properties folded into containing object">
+  <!--
+  {
+    "@context": {
+      "skos": "http://www.w3.org/2004/02/skos/core#",
+      "main_label": {"@id": "skos:prefLabel"},
+      "other_label": {"@id": "skos:altLabel"},
+      "homepage": {"@id": "http://schema.org/description", "@type": "@id"}
+    },
+    "@id": "http://example.org/myresource",
+    "homepage": "http://example.org",
+    ****"main_label": "This is the main label for my resource",
+    "other_label": "This is the other label"****
+  }
+  -->
+  </pre>
+
+  <p>Similarly, node definitions may contain a <code>@nest</code> property to
+    reference a term aliased to <code>@nest</code> which causes such
+    values to be nested under that aliased term.</p>
+  <pre class="example" data-transform="updateExample"
+       title="Defining property nesting">
+  <!--
+ {
+   "@context": {
+     "skos": "http://www.w3.org/2004/02/skos/core#",
+     ****"labels": "@nest"****,
+     "main_label": {"@id": "skos:prefLabel", ****"@nest": "labels"****},
+     "other_label": {"@id": "skos:altLabel", ****"@nest": "labels"****},
+     "homepage": {"@id": "http://schema.org/description", "@type": "@id"}
+   },
+   "@id": "http://example.org/myresource",
+   "homepage": "http://example.org",
+   "labels": {
+      "main_label": "This is the main label for my resource",
+      "other_label": "This is the other label"
+   }
+ }
+  -->
+  </pre>
+</section>
+
 <section class="informative">
   <h3>Expanded Document Form</h3>
 
@@ -3090,6 +3171,7 @@ <h2>Node Objects</h2>
       <li><code>@context</code>,</li>
       <li><code>@id</code>,</li>
       <li><code>@graph</code>,</li>
+      <li class="changed"><code>@nest</code>,</li>
       <li><code>@type</code>,</li>
       <li><code>@reverse</code>, or</li>
       <li><code>@index</code></li>
@@ -3145,6 +3227,12 @@ <h2>Node Objects</h2>
       <a class="sectionRef" href="#data-indexing"></a> for further discussion
       on <code>@index</code> values.</p>
 
+    <p class="changed">If the <a>node object</a> contains the <code>@nest</code> key,
+      its value MUST be an <a>JSON object</a> or an <a>array</a> of <a>JSON objects</a>
+      which MUST NOT include a <a>value object</a>. See
+      <a class="sectionRef" href="#property-nesting"></a> for further discussion
+      on <code>@nest</code> values.</p>
+
     <p>Keys in a <a>node object</a> that are not
       <a>keyword</a> MAY expand to an <a>absolute IRI</a>
       using the <a>active context</a>. The values associated with keys that expand
@@ -3315,6 +3403,19 @@ <h2>Type Maps</h2>
       the <code>@id</code> of the <a>node object</a> value when expanding.</p>
   </section>
 
+  <section class="changed">
+    <h2>Property Nesting</h2>
+
+    <p>A <a>nested property</a> is used to gather <a>properties</a> of a <a>node object</a> in a separate
+      <a>JSON object</a>, or <a>array</a> of <a>JSON objects</a> which are not
+      <a>value objects</a>. It is semantically transparent and is removed
+      during the process of expansion. Property nesting is recursive, and
+      collections of nested properties may contain further nesting.</p>
+
+    <p>Semantically, nesting is treated as if the properties and values were declared directly
+      within the containing <a>node object</a>.</p>
+  </section>
+
 <section class="normative">
   <h2>Context Definitions</h2>
 
@@ -3354,7 +3455,7 @@ <h2>Context Definitions</h2>
     <a>expanded term definition</a> SHOULD NOT contain any other keys.</p>
 
   <p>If an <a>expanded term definition</a> has an <code>@reverse</code> member,
-    it MUST NOT have an <code>@id</code> member at the same time. If an
+    it MUST NOT have <code>@id</code> or <code>@nest</code> members at the same time. If an
     <code>@container</code> member exists, its value MUST be <a>null</a>,
     <code>@set</code>, or <code>@index</code>.</p>
 
@@ -3392,6 +3493,10 @@ <h2>Context Definitions</h2>
     the definition of a term cannot depend on the definition of another term if that other
     term also depends on the first term.</p>
 
+  <p>If the <a>expanded term definition</a> contains the <code>@nest</code>
+    <a>keyword</a>, its value MUST be either <code>@nest</code>, or a term
+    which expands to <code>@nest</code>.</p>
+
   <p>See <a class="sectionRef" href="#the-context"></a> for further discussion on contexts.</p>
 </section>
 
@@ -3582,6 +3687,12 @@ <h2>Changes since 1.0 Recommendation of 16 January 2014</h2>
       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>
+    <li>An <a>expanded term definition</a> can now have an
+      <code>@nest</code> property, which identifies a term expanding to
+      <code>@nest</code> which is used for containing properties using the same
+      <code>@nest</code> mapping. When expanding, the values of a property
+      expanding to <code>@nest</code> are treated as if they were contained
+      within the enclosing <a>node object</a> directly.</li>
   </ul>
 </section>