Support nested property expansion and compaction.

Author: gkellogg

CHANGELOG.md

@@ -53,8 +53,7 @@
 
 ### Added
 - Expansion and Compaction using scoped contexts on property and `@type` terms.
-
-### Added
+- Expansion and Compaction of nested properties.
 - Index graph containers using `@id` and `@index`, with `@set` variations.
 - Index node objects using `@id` and `@type`, with `@set` variations.
 

lib/compact.js

@@ -143,8 +143,7 @@ api.compact = ({
 
     // process element keys in order
     const keys = Object.keys(element).sort();
-    for(let ki = 0; ki < keys.length; ++ki) {
-      const expandedProperty = keys[ki];
+    for(let expandedProperty of keys) {
       const expandedValue = element[expandedProperty];
 
       // compact @id and @type(s)
@@ -161,9 +160,9 @@ api.compact = ({
         } else {
           // expanded value must be a @type array
           compactedValue = [];
-          for(let vi = 0; vi < expandedValue.length; ++vi) {
+          for(let expandedIri of expandedValue) {
             const compactedType = api.compactIri(
-              {activeCtx, iri: expandedValue[vi], relativeTo: {vocab: true}})
+              {activeCtx, iri: expandedIri, relativeTo: {vocab: true}})
 
             // Use any scoped context defined on this value
             const ctx = _getContextValue(activeCtx, compactedType, '@context');
@@ -257,14 +256,21 @@ api.compact = ({
           relativeTo: {vocab: true},
           reverse: insideReverse
         });
+        const nestProperty = (itemActiveProperty in activeCtx.mappings) ? activeCtx.mappings[itemActiveProperty]['@nest'] : null;
+        let nestResult = rval;
+        if(nestProperty) {
+          _checkNestProperty(activeCtx, nestProperty);
+          if(!_isObject(rval[nestProperty])) {
+            rval[nestProperty] = {};
+          }
+          nestResult = rval[nestProperty];
+        }
         _addValue(
-          rval, itemActiveProperty, expandedValue, {propertyIsArray: true});
+          nestResult, itemActiveProperty, expandedValue, {propertyIsArray: true});
       }
 
       // recusively process array values
-      for(let vi = 0; vi < expandedValue.length; ++vi) {
-        const expandedItem = expandedValue[vi];
-
+      for(let expandedItem of expandedValue) {
         // compact property and get container type
         const itemActiveProperty = api.compactIri({
           activeCtx,
@@ -273,6 +279,18 @@ api.compact = ({
           relativeTo: {vocab: true},
           reverse: insideReverse
         });
+
+        // if itemActiveProperty is a @nest property, add values to nestResult, otherwise rval
+        const nestProperty = (itemActiveProperty in activeCtx.mappings) ? activeCtx.mappings[itemActiveProperty]['@nest'] : null;
+        let nestResult = rval;
+        if(nestProperty) {
+          _checkNestProperty(activeCtx, nestProperty);
+          if(!_isObject(rval[nestProperty])) {
+            rval[nestProperty] = {};
+          }
+          nestResult = rval[nestProperty];
+        }
+
         const container = _getContextValue(
           activeCtx, itemActiveProperty, '@container') || [];
 
@@ -313,7 +331,7 @@ api.compact = ({
               compactedItem[api.compactIri({activeCtx, iri: '@index', relativeTo: {vocab: true}})] =
                 expandedItem['@index'];
             }
-          } else if(itemActiveProperty in rval) {
+          } else if(itemActiveProperty in nestResult) {
             // can't use @list container for more than 1 list
             throw new JsonLdError(
               'JSON-LD compact error; property has a "@list" @container ' +
@@ -330,10 +348,10 @@ api.compact = ({
             (container.includes('@id') || container.includes('@index') && _isSimpleGraph(expandedItem))) {
             // get or create the map object
             let mapObject;
-            if(itemActiveProperty in rval) {
-              mapObject = rval[itemActiveProperty];
+            if(itemActiveProperty in nestResult) {
+              mapObject = nestResult[itemActiveProperty];
             } else {
-              rval[itemActiveProperty] = mapObject = {};
+              nestResult[itemActiveProperty] = mapObject = {};
             }
 
             // index on @id or @index or alias of @none
@@ -347,7 +365,7 @@ api.compact = ({
             // container includes @graph but not @id or @index and value is a simple graph object
             // add compact value
             _addValue(
-              rval, itemActiveProperty, compactedItem,
+              nestResult, itemActiveProperty, compactedItem,
               {propertyIsArray: (!options.compactArrays || container.includes('@set'))});
           } else {
             // wrap using @graph alias
@@ -367,18 +385,18 @@ api.compact = ({
                 expandedItem['@index'];
             }
             _addValue(
-              rval, itemActiveProperty, compactedItem,
+              nestResult, itemActiveProperty, compactedItem,
               {propertyIsArray: (!options.compactArrays || container.includes('@set'))});
           }
         } else if(container.includes('@language') || container.includes('@index') ||
           container.includes('@id') || container.includes('@type')) {
           // handle language and index maps
           // get or create the map object
           let mapObject;
-          if(itemActiveProperty in rval) {
-            mapObject = rval[itemActiveProperty];
+          if(itemActiveProperty in nestResult) {
+            mapObject = nestResult[itemActiveProperty];
           } else {
-            rval[itemActiveProperty] = mapObject = {};
+            nestResult[itemActiveProperty] = mapObject = {};
           }
 
           let key;
@@ -431,7 +449,7 @@ api.compact = ({
 
           // add compact value
           _addValue(
-            rval, itemActiveProperty, compactedItem,
+            nestResult, itemActiveProperty, compactedItem,
             {propertyIsArray: isArray});
         }
       }
@@ -907,3 +925,18 @@ function _selectTerm(
 
   return null;
 }
+
+/**
+ * The value of `@nest` in the term definition must either be `@nest`, or a term
+ * which resolves to `@nest`.
+ *
+ * @param activeCtx the active context.
+ * @param nestProperty a term in the active context or `@nest`.
+ */
+function _checkNestProperty(activeCtx, nestProperty) {
+  if(_expandIri(activeCtx, nestProperty, {vocab: true}) !== '@nest') {
+    throw new JsonLdError(
+      'JSON-LD compact error; nested property must have an @nest value resolving to @nest.',
+      'jsonld.SyntaxError', {code: 'invalid @nest value'});
+  }
+}

lib/context.js

@@ -263,7 +263,7 @@ api.createTermDefinition = (activeCtx, localCtx, term, defined) => {
 
   // JSON-LD 1.1 support
   if(api.processingMode(activeCtx, 1.1)) {
-    validKeys.push('@context', '@prefix');
+    validKeys.push('@context', '@nest', '@prefix');
   }
 
   for(let kw in value) {
@@ -287,6 +287,12 @@ api.createTermDefinition = (activeCtx, localCtx, term, defined) => {
         'contain @id.', 'jsonld.SyntaxError',
         {code: 'invalid reverse property', context: localCtx});
     }
+    if('@nest' in value) {
+      throw new JsonLdError(
+        'Invalid JSON-LD syntax; a @reverse term definition must not ' +
+        'contain @nest.', 'jsonld.SyntaxError',
+        {code: 'invalid reverse property', context: localCtx});
+    }
     const reverse = value['@reverse'];
     if(!_isString(reverse)) {
       throw new JsonLdError(
@@ -502,6 +508,17 @@ api.createTermDefinition = (activeCtx, localCtx, term, defined) => {
     }
   }
 
+  if('@nest' in value) {
+    let nest = value['@nest'];
+    if(!_isString(nest) || (nest !== '@nest' && nest.indexOf('@') === 0)) {
+      throw new JsonLdError(
+        'Invalid JSON-LD syntax; @context @nest value must be ' +
+        'a string which is not a keyword other than @nest.', 'jsonld.SyntaxError',
+        {code: 'invalid @nest value', context: localCtx});
+    }
+    mapping['@nest'] = nest;
+  }
+
   // disallow aliasing @context and @preserve
   const id = mapping['@id'];
   if(id === '@context' || id === '@preserve') {
@@ -883,6 +900,7 @@ api.isKeyword = v => {
   case '@index':
   case '@language':
   case '@list':
+  case '@nest':
   case '@none':
   case '@omitDefault':
   case '@prefix':