Implementation of Transparent Nesting (@nest) as a term definition property.

Author: gkellogg

README.md

@@ -298,6 +298,61 @@ The value of `@container` in a term definition can include `@id` or `@type`, in
       }
     }
 
+### Transparent Nesting
+Many JSON APIs separate properties from their entities using an intermediate object. For example, a set of possible labels may be grouped under a common property:
+
+    {
+      "@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"
+      }
+    }
+ 
+ In this case, the `labels` property is semantically meaningless. Defining it as equivalent to `@nest` causes it to be ignored when expanding, making it equivalent to the following:
+
+    {
+      "@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",
+      "main_label": "This is the main label for my resource",
+      "other_label": "This is the other label"
+    }
+ 
+ Similarly, properties may be marked with "@nest": "nest-term", to cause them to be nested. Note that the `@nest` keyword can also be aliased in the context.
+
+     {
+       "@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"
+       }
+     }
+
+In this way, nesting survives round-tripping through expansion, and framed output can include nested properties.
+
 ### Framing Updates
 The [JSON-LD Framing 1.1 Specification]() improves on previous un-released versions.
 

lib/json/ld.rb

@@ -53,6 +53,7 @@ module LD
       @graph
       @language
       @list
+      @nest
       @omitDefault
       @requireAll
       @reverse
@@ -111,6 +112,7 @@ class InvalidLanguageMapValue < JsonLdError; @code = "invalid language map value
       class InvalidLanguageTaggedString < JsonLdError; @code = "invalid language-tagged string"; end
       class InvalidLanguageTaggedValue < JsonLdError; @code = "invalid language-tagged value"; end
       class InvalidLocalContext < JsonLdError; @code = "invalid local context"; end
+      class InvalidNestValue < JsonLdError; @code = "invalid @nest value"; end
       class InvalidRemoteContext < JsonLdError; @code = "invalid remote context"; end
       class InvalidReverseProperty < JsonLdError; @code = "invalid reverse property"; end
       class InvalidReversePropertyMap < JsonLdError; @code = "invalid reverse property map"; end

lib/json/ld/compact.rb

@@ -52,7 +52,7 @@ def compact(element, property: nil)
         end
 
         inside_reverse = property == '@reverse'
-        result = {}
+        result, nest_result = {}, nil
 
         element.each_key do |expanded_property|
           expanded_value = element[expanded_property]
@@ -78,6 +78,7 @@ def compact(element, property: nil)
                 value = [value] if !value.is_a?(Array) &&
                   (context.container(prop) == '@set' || !@options[:compactArrays])
                 #log_debug("") {"merge #{prop} => #{value.inspect}"}
+
                 merge_compacted_value(result, prop, value)
                 compacted_value.delete(prop)
               end
@@ -112,8 +113,14 @@ def compact(element, property: nil)
                                   reverse: inside_reverse,
                                   log_depth: @options[:log_depth])
 
-            iap = result[item_active_property] ||= []
-            result[item_active_property] = [iap] unless iap.is_a?(Array)
+            if nest_prop = context.nest(item_active_property)
+              result[nest_prop] ||= {}
+              iap = result[result[nest_prop]] ||= []
+              result[nest_prop][item_active_property] = [iap] unless iap.is_a?(Array)
+            else
+              iap = result[item_active_property] ||= []
+              result[item_active_property] = [iap] unless iap.is_a?(Array)
+            end
           end
 
           # At this point, expanded value must be an array due to the Expansion algorithm.
@@ -125,6 +132,14 @@ def compact(element, property: nil)
                                   reverse: inside_reverse,
                                   log_depth: @options[:log_depth])
 
+
+            nest_result = if nest_prop = context.nest(item_active_property)
+              # FIXME??: It's possible that nest_prop will be used both for nesting, and for values of @nest
+              result[nest_prop] ||= {}
+            else
+              result
+            end
+
             container = context.container(item_active_property)
             value = list?(expanded_item) ? expanded_item['@list'] : expanded_item
             compacted_item = compact(value, property: item_active_property)
@@ -141,22 +156,20 @@ def compact(element, property: nil)
                 end
               else
                 raise JsonLdError::CompactionToListOfLists,
-                      "key cannot have more than one list value" if result.has_key?(item_active_property)
+                      "key cannot have more than one list value" if nest_result.has_key?(item_active_property)
               end
             end
 
             if %w(@language @index @id @type).include?(container)
-              map_object = result[item_active_property] ||= {}
+              map_object = nest_result[item_active_property] ||= {}
               compacted_item = case container
               when '@id'
                 id_prop = context.compact_iri('@id', vocab: true, quiet: true)
                 map_key = compacted_item[id_prop]
                 compacted_item.delete(id_prop)
                 compacted_item
               when '@index'
-                index_prop = context.compact_iri('@index', vocab: true, quiet: true)
                 map_key = expanded_item[container]
-                #compacted_item.delete(index_prop)
                 compacted_item
               when '@language'
                 map_key = expanded_item[container]
@@ -179,7 +192,7 @@ def compact(element, property: nil)
                   %w(@set @list).include?(container) ||
                   %w(@list @graph).include?(expanded_property)
                 )
-              merge_compacted_value(result, item_active_property, compacted_item)
+              merge_compacted_value(nest_result, item_active_property, compacted_item)
             end
           end
         end

lib/json/ld/context.rb

@@ -39,6 +39,9 @@ class TermDefinition
       # @return ['@index', '@language', '@index', '@set', '@type', '@id'] Container mapping
       attr_accessor :container_mapping
 
+      # @return [String] Term used for nest properties
+      attr_accessor :nest
+
       # Language mapping of term, `false` is used if there is explicitly no language mapping for this term.
       # @return [String] Language mapping
       attr_accessor :language_mapping
@@ -66,6 +69,7 @@ def simple?; simple; end
       # @param [String] language_mapping
       #   Language mapping of term, `false` is used if there is explicitly no language mapping for this term
       # @param [Boolean] reverse_property
+      # @param [String] nest term used for nest properties
       # @param [Boolean] simple
       #   This is a simple term definition, not an expanded term definition
       def initialize(term,
@@ -74,6 +78,7 @@ def initialize(term,
                     container_mapping: nil,
                     language_mapping: nil,
                     reverse_property: false,
+                    nest: nil,
                     simple: false,
                     context: nil)
         @term               = term
@@ -82,6 +87,7 @@ def initialize(term,
         @container_mapping  = container_mapping if container_mapping
         @language_mapping   = language_mapping  if language_mapping
         @reverse_property   = reverse_property  if reverse_property
+        @nest               = nest              if nest
         @simple             = simple            if simple
         @context            = context           if context
       end
@@ -105,7 +111,8 @@ def to_context_definition(context)
            container_mapping.nil? &&
            type_mapping.nil? &&
            reverse_property.nil? &&
-           self.context.nil?
+           self.context.nil? &&
+           nest.nil?
 
            cid.to_s unless cid == term && context.vocab
         else
@@ -122,6 +129,7 @@ def to_context_definition(context)
           # Language set as false to be output as null
           defn['@language'] = (language_mapping ? language_mapping : nil) unless language_mapping.nil?
           defn['@context'] = self.context unless self.context.nil?
+          defn['@nest'] = selfnest unless self.nest.nil?
           defn
         end
       end
@@ -132,7 +140,7 @@ def to_context_definition(context)
       # @return [String]
       def to_rb
         defn = [%(TermDefinition.new\(#{term.inspect})]
-        %w(id type_mapping container_mapping language_mapping reverse_property simple context).each do |acc|
+        %w(id type_mapping container_mapping language_mapping reverse_property nest simple context).each do |acc|
           v = instance_variable_get("@#{acc}".to_sym)
           v = v.to_s if v.is_a?(RDF::Term)
           defn << "#{acc}: #{v.inspect}" if v
@@ -148,6 +156,7 @@ def inspect
         v << "container=#{container_mapping}" if container_mapping
         v << "lang=#{language_mapping.inspect}" unless language_mapping.nil?
         v << "type=#{type_mapping}" unless type_mapping.nil?
+        v << "nest=#{nest.inspect}" unless nest.nil?
         v << "has-context" unless context.nil?
         v.join(" ") + "]"
       end
@@ -524,7 +533,7 @@ def create_term_definition(local_context, term, defined)
 
         expected_keys = case @options[:processingMode]
         when "json-ld-1.0" then %w(@id @reverse @type @container @language)
-        else  %w(@id @reverse @type @container @language @context)
+        else  %w(@id @reverse @type @container @language @context @nest)
         end
 
         extra_keys = value.keys - expected_keys
@@ -556,7 +565,7 @@ def create_term_definition(local_context, term, defined)
 
         if value.has_key?('@reverse')
           raise JsonLdError::InvalidReverseProperty, "unexpected key in #{value.inspect} on term #{term.inspect}" if
-            value.keys.any? {|k| %w(@id).include?(k)}
+            value.keys.any? {|k| %w(@id @nest).include?(k)}
           raise JsonLdError::InvalidIRIMapping, "expected value of @reverse to be a string: #{value['@reverse'].inspect} on term #{term.inspect}" unless
             value['@reverse'].is_a?(String)
 
@@ -637,6 +646,14 @@ def create_term_definition(local_context, term, defined)
           definition.language_mapping = language || false
         end
 
+        if value.has_key?('@nest')
+          nest = value['@nest']
+          raise JsonLdError::InvalidNestValue, "nest must be a string, was #{nest.inspect}} on term #{term.inspect}" unless nest.is_a?(String)
+          raise JsonLdError::InvalidNestValue, "nest must not be a keyword other than @nest, was #{nest.inspect}} on term #{term.inspect}" if nest.start_with?('@') && nest != '@nest'
+          #log_debug("") {"nest: #{nest.inspect}"}
+          definition.nest = nest
+        end
+
         term_definitions[term] = definition
         defined[term] = true
       else
@@ -813,6 +830,27 @@ def content(term)
       term && term.content
     end
 
+    ##
+    # Retrieve nest of a term.
+    # value of nest must be @nest or a term that resolves to @nest
+    #
+    # @param [Term, #to_s] term in unexpanded form
+    # @return [String] Nesting term
+    # @raise JsonLdError::InvalidNestValue if nesting term exists and is not a term resolving to `@nest` in the current context.
+    def nest(term)
+      term = find_definition(term)
+      if term
+        case term.nest
+        when '@nest', nil
+          term.nest
+        else
+          nest_term = find_definition(term.nest)
+          raise JsonLdError::InvalidNestValue, "nest must a term resolving to @nest" unless nest_term && nest_term.simple? && nest_term.id == '@nest'
+          term.nest
+        end
+      end
+    end
+
     ##
     # Retrieve the language associated with a term, or the default language otherwise
     # @param [Term, #to_s] term in unexpanded form