json-ld 2.1.7 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e6faa8c0a2b65b20cfeaa22ac3cba60cf98ae835
-  data.tar.gz: 9e116d70b8081c39e5b725e9053a7b40b1ecfd57
+  metadata.gz: 93516bb49f7999bcda524b639c817eb197acc412
+  data.tar.gz: 3f3a0ce771608fb40714dd05a45c9fcdec5cf21a
 SHA512:
-  metadata.gz: 4990f799a5dd3898ce3ea7b746a96f2bf84baab2fd7b90c7f08b360cd72bb8a7863bd31e56048ddfd68ca53b4a4c7510e090c9ce49aa637d4f11298020488881
-  data.tar.gz: 6c551095ca9137161f52c8f978c650a144cae1c070df62501a5dbb0323b3ffda0f13a00221cd257babbc09bd00a0c21d99056eece1895d955c64326b6ea935a5
+  metadata.gz: 80be800ae35b9906c8f289eff34b7eaa84a4d637e883f1c8d1452a4516f98daa7a63b77bddacc8791e9caf4131018ea0994f4a023557e9e9cc0587234ad85d3e
+  data.tar.gz: 2234dbcec6f4701da4adb9fd3b90bbf6cb3c2918c9be1394756a2ddfd10c28931d44a911e6f1a5a2fbbb7082bf9631e0da100119cccd7a1af8c3463bf9c5be60

data/README.md

@@ -298,6 +298,86 @@ The value of `@container` in a term definition can include `@id` or `@type`, in
       }
     }
 
+### @graph containers and maps
+A term can have `@container` set to include `@graph` optionally including `@id` or `@index` and `@set`. In the first form, with `@container` set to `@graph`, the value of a property is treated as a _simple graph object_, meaning that values treated as if they were contained in an object with `@graph`, creating _named graph_ with an anonymous name.
+
+    {
+      "@context": {
+        "@vocab": "http://example.org/",
+        "input": {"@container": "@graph"}
+      },
+      "input": {
+        "value": "x"
+      }
+    }
+
+which expands to the following:
+
+    [{
+      "http://example.org/input": [{
+        "@graph": [{
+          "http://example.org/value": [{"@value": "x"}]
+        }]
+      }]
+    }]
+
+Compaction reverses this process, optionally ensuring that a single value is contained within an array of `@container` also includes `@set`:
+
+    {
+      "@context": {
+        "@vocab": "http://example.org/",
+        "input": {"@container": ["@graph", "@set"]}
+      }
+    }
+
+A graph map uses the map form already existing for `@index`, `@language`, `@type`, and `@id` where the index is either an index value or an id.
+
+    {
+      "@context": {
+        "@vocab": "http://example.org/",
+        "input": {"@container": ["@graph", "@index"]}
+      },
+      "input": {
+        "g1": {"value": "x"}
+      }
+    }
+
+treats "g1" as an index, and expands to the following:
+
+    [{
+      "http://example.org/input": [{
+        "@index": "g1",
+        "@graph": [{
+          "http://example.org/value": [{"@value": "x"}]
+        }]
+      }]
+    }])
+
+This can also include `@set` to ensure that, when compacting, a single value of an index will be in array form.
+
+The _id_ version is similar:
+
+    {
+      "@context": {
+        "@vocab": "http://example.org/",
+        "input": {"@container": ["@graph", "@id"]}
+      },
+      "input": {
+        "http://example.com/g1": {"value": "x"}
+      }
+    }
+
+which expands to:
+
+    [{
+      "http://example.org/input": [{
+        "@id": "http://example.com/g1",
+        "@graph": [{
+          "http://example.org/value": [{"@value": "x"}]
+        }]
+      }]
+    }])
+
 ### 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:
 

data/VERSION

@@ -1 +1 @@
-2.1.7
+2.2.0

data/lib/json/ld/compact.rb

@@ -82,6 +82,7 @@ module JSON::LD
           if expanded_property == '@reverse'
             compacted_value = compact(expanded_value, property: '@reverse')
             #log_debug("@reverse") {"compacted_value: #{compacted_value.inspect}"}
+            # handle double-reversed properties
             compacted_value.each do |prop, value|
               if context.reverse?(prop)
                 value = [value] if !value.is_a?(Array) &&
@@ -112,7 +113,7 @@ module JSON::LD
             next
           end
 
-          if expanded_property == '@index' && context.container(property) == '@index'
+          if expanded_property == '@index' && context.container(property) == %w(@index)
             #log_debug("@index") {"drop @index"}
             next
           end
@@ -162,13 +163,20 @@ module JSON::LD
 
             container = context.container(item_active_property)
             as_array = context.as_array?(item_active_property)
-            value = list?(expanded_item) ? expanded_item['@list'] : expanded_item
+
+            value = case
+            when list?(expanded_item) then expanded_item['@list']
+            when graph?(expanded_item) then expanded_item['@graph']
+            else expanded_item
+            end
+
             compacted_item = compact(value, property: item_active_property)
             #log_debug("") {" => compacted key: #{item_active_property.inspect} for #{compacted_item.inspect}"}
 
+            # handle @list
             if list?(expanded_item)
               compacted_item = [compacted_item] unless compacted_item.is_a?(Array)
-              unless container == '@list'
+              unless container == %w(@list)
                 al = context.compact_iri('@list', vocab: true, quiet: true)
                 compacted_item = {al => compacted_item}
                 if expanded_item.has_key?('@index')
@@ -178,25 +186,63 @@ module JSON::LD
               else
                 raise JsonLdError::CompactionToListOfLists,
                       "key cannot have more than one list value" if nest_result.has_key?(item_active_property)
+              # Falls through to add list value below
               end
             end
 
-            if container == '@language' || container == '@index' || container == '@id' || container == '@type'
+            # Graph object compaction cases:
+            if graph?(expanded_item)
+              if container.include?('@graph') && container.include?('@id')
+                # container includes @graph and @id
+                map_object = nest_result[item_active_property] ||= {}
+                map_key = expanded_item['@id']
+                # If there is no @id, create a blank node identifier to use as an index
+                map_key = map_key ? context.compact_iri(map_key, quiet: true) : namer.get_name
+                merge_compacted_value(map_object, map_key, compacted_item)
+              elsif container.include?('@graph') && container.include?('@index') && simple_graph?(expanded_item)
+                # container includes @graph and @index and value is a simple graph object
+                map_object = nest_result[item_active_property] ||= {}
+                # If there is no @index, use @none
+                map_key = expanded_item['@index'] || '@none'
+                merge_compacted_value(map_object, map_key, compacted_item)
+              elsif container.include?('@graph') && simple_graph?(expanded_item)
+                # container includes @graph but not @id or @index and value is a simple graph object
+                # Drop through, where compacted_value will be added
+                compacted_item = [compacted_item] if
+                  !compacted_item.is_a?(Array) && (!@options[:compactArrays] || as_array)
+                merge_compacted_value(nest_result, item_active_property, compacted_item)
+              else
+                # container does not include @graph or otherwise does not match one of the previous cases, redo compacted_item
+                compacted_item = [compacted_item]
+                al = context.compact_iri('@graph', vocab: true, quiet: true)
+                compacted_item = {al => compacted_item}
+                if expanded_item['@id']
+                  al = context.compact_iri('@id', vocab: true, quiet: true)
+                  compacted_item[al] = context.compact_iri(expanded_item['@id'], vocab: false, quiet: true).to_s
+                end
+                if expanded_item.has_key?('@index')
+                  key = context.compact_iri('@index', vocab: true, quiet: true)
+                  compacted_item[key] = expanded_item['@index']
+                end
+                compacted_item = [compacted_item] if !@options[:compactArrays] || as_array
+                merge_compacted_value(nest_result, item_active_property, compacted_item)
+              end
+            elsif !(container & %w(@language @index @id @type)).empty? && !container.include?('@graph')
               map_object = nest_result[item_active_property] ||= {}
               compacted_item = case container
-              when '@id'
+              when %w(@id)
                 id_prop = context.compact_iri('@id', vocab: true, quiet: true)
                 map_key = compacted_item[id_prop]
                 map_key = context.compact_iri(map_key, quiet: true)
                 compacted_item.delete(id_prop)
                 compacted_item
-              when '@index'
-                map_key = expanded_item[container]
+              when %w(@index)
+                map_key = expanded_item['@index']
                 compacted_item
-              when '@language'
-                map_key = expanded_item[container]
+              when %w(@language)
+                map_key = expanded_item['@language']
                 value?(expanded_item) ? expanded_item['@value'] : compacted_item
-              when '@type'
+              when %w(@type)
                 type_prop = context.compact_iri('@type', vocab: true, quiet: true)
                 map_key, *types = Array(compacted_item[type_prop])
                 map_key = context.compact_iri(map_key, vocab: true, quiet: true)

data/lib/json/ld/context.rb

@@ -38,13 +38,9 @@ module JSON::LD
       attr_accessor :type_mapping
 
       # Base container mapping, without @set
-      # @return ['@index', '@language', '@index', '@type', '@id'] Container mapping
+      # @return Array<'@index', '@language', '@index', '@set', '@type', '@id', '@graph'> Container mapping
       attr_reader :container_mapping
 
-      # If container mapping was defined along with @set
-      # @return [Boolean]
-      attr_reader :as_set
-
       # @return [String] Term used for nest properties
       attr_accessor :nest
 
@@ -78,7 +74,7 @@ module JSON::LD
       # @param [String] term
       # @param [String] id
       # @param [String] type_mapping Type mapping
-      # @param ['@index', '@language', '@index', '@set', '@type', '@id'] container_mapping
+      # @param [Array<'@index', '@language', '@index', '@set', '@type', '@id', '@graph'>] container_mapping
       # @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
@@ -100,7 +96,7 @@ module JSON::LD
         @term                   = term
         @id                     = id.to_s           unless id.nil?
         @type_mapping           = type_mapping.to_s unless type_mapping.nil?
-        self.container_mapping  = container_mapping unless container_mapping.nil?
+        self.container_mapping  = container_mapping
         @language_mapping       = language_mapping  unless language_mapping.nil?
         @reverse_property       = reverse_property
         @nest                   = nest              unless nest.nil?
@@ -116,7 +112,7 @@ module JSON::LD
           mapping = mapping.dup
           mapping.delete('@set')
         end
-        @container_mapping = mapping.first
+        @container_mapping = mapping.sort
       end
 
       ##
@@ -147,7 +143,7 @@ module JSON::LD
             end
           end
 
-          cm = [container_mapping, ('@set' if as_set)].compact
+          cm = (Array(container_mapping) + (as_set? ? %w(@set) : [])).compact
           cm = cm.first if cm.length == 1
           defn['@container'] = cm unless cm.empty?
           # Language set as false to be output as null
@@ -168,21 +164,26 @@ module JSON::LD
         %w(id type_mapping container_mapping language_mapping reverse_property nest simple prefix context).each do |acc|
           v = instance_variable_get("@#{acc}".to_sym)
           v = v.to_s if v.is_a?(RDF::Term)
-          if acc == 'container_mapping' && as_set
-            v = v ? [v, '@set'] : '@set'
+          if acc == 'container_mapping'
+            v.concat(%w(@set)) if as_set?
+            v = v.first if v.length <= 1
           end
           defn << "#{acc}: #{v.inspect}" if v
         end
         defn.join(', ') + ")"
       end
 
+      # If container mapping was defined along with @set
+      # @return [Boolean]
+      def as_set?; @as_set || false; end
+
       def inspect
         v = %w([TD)
         v << "id=#{@id}"
         v << "term=#{@term}"
         v << "rev" if reverse_property
         v << "container=#{container_mapping}" if container_mapping
-        v << "as_set=#{as_set.inspect}"
+        v << "as_set=#{as_set?.inspect}"
         v << "lang=#{language_mapping.inspect}" unless language_mapping.nil?
         v << "type=#{type_mapping}" unless type_mapping.nil?
         v << "nest=#{nest.inspect}" unless nest.nil?
@@ -874,23 +875,22 @@ module JSON::LD
     # Retrieve container mapping, add it if `value` is provided
     #
     # @param [Term, #to_s] term in unexpanded form
-    # @return [String]
+    # @return [Array<'@index', '@language', '@index', '@set', '@type', '@id', '@graph'>]
     def container(term)
-      return '@set' if term == '@graph'
-      return term if KEYWORDS.include?(term)
+      return [term] if KEYWORDS.include?(term)
       term = find_definition(term)
-      term && term.container_mapping
+      term ? term.container_mapping : []
     end
 
     ##
-    # Should values be represented as a set?
+    # Should values be represented using an array?
     #
     # @param [Term, #to_s] term in unexpanded form
     # @return [Boolean]
     def as_array?(term)
-      return true if term == '@graph' || term == '@list'
+      return true if CONTEXT_CONTAINER_ARRAY_TERMS.include?(term)
       term = find_definition(term)
-      term && (term.as_set || term.container_mapping == '@list')
+      term && (term.as_set? || term.container_mapping.include?('@list'))
     end
 
     ##
@@ -1122,6 +1122,11 @@ module JSON::LD
             tl_value = common_language
           end
           #log_debug("") {"list: containers: #{containers.inspect}, type/language: #{tl.inspect}, type/language value: #{tl_value.inspect}"} unless quiet
+        elsif graph?(value)
+          # TODO: support `@graphId`?
+          # TODO: "@graph@set"?
+          containers << '@graph'
+          containers << '@set'
         else
           if value?(value)
             if value.has_key?('@language') && !index?(value)
@@ -1228,14 +1233,16 @@ module JSON::LD
     def expand_value(property, value, useNativeTypes: false, **options)
       #log_debug("expand_value") {"property: #{property.inspect}, value: #{value.inspect}"}
 
+      td = term_definitions.fetch(property, TermDefinition.new(property))
+
       # If the active property has a type mapping in active context that is @id, return a new JSON object containing a single key-value pair where the key is @id and the value is the result of using the IRI Expansion algorithm, passing active context, value, and true for document relative.
-      if (td = term_definitions.fetch(property, TermDefinition.new(property))) && td.type_mapping == '@id'
+      if value.is_a?(String) && td.type_mapping == '@id'
         #log_debug("") {"as relative IRI: #{value.inspect}"}
         return {'@id' => expand_iri(value, documentRelative: true).to_s}
       end
 
       # If active property has a type mapping in active context that is @vocab, return a new JSON object containing a single key-value pair where the key is @id and the value is the result of using the IRI Expansion algorithm, passing active context, value, true for vocab, and true for document relative.
-      if td.type_mapping == '@vocab'
+      if value.is_a?(String) && td.type_mapping == '@vocab'
         #log_debug("") {"as vocab IRI: #{value.inspect}"}
         return {'@id' => expand_iri(value, vocab: true, documentRelative: true).to_s}
       end
@@ -1271,15 +1278,14 @@ module JSON::LD
         # Otherwise, initialize result to a JSON object with an @value member whose value is set to value.
         res = {'@value' => value}
 
-        if td.type_mapping
+        if td.type_mapping && !%w(@id @vocab).include?(td.type_mapping.to_s)
           res['@type'] = td.type_mapping.to_s
-        elsif value.is_a?(String)
-          if td.language_mapping
-            res['@language'] = td.language_mapping
-          elsif default_language && td.language_mapping.nil?
-            res['@language'] = default_language
-          end
+        elsif value.is_a?(String) && td.language_mapping
+          res['@language'] = td.language_mapping
+        elsif value.is_a?(String) && default_language && td.language_mapping.nil?
+          res['@language'] = default_language
         end
+
         res
       end
 
@@ -1305,7 +1311,7 @@ module JSON::LD
 
       num_members = value.length
 
-      num_members -= 1 if index?(value) && container(property) == '@index'
+      num_members -= 1 if index?(value) && container(property).include?('@index')
       if num_members > 2
         #log_debug("") {"can't compact value with # members > 2"}
         return value
@@ -1442,6 +1448,10 @@ module JSON::LD
 
   private
 
+    CONTEXT_CONTAINER_ARRAY_TERMS = %w(@set @list @graph).freeze
+    CONTEXT_CONTAINER_ID_GRAPH = %w(@id @graph).freeze
+    CONTEXT_CONTAINER_INDEX_GRAPH = %w(@index @graph).freeze
+
     def uri(value)
       case value.to_s
       when /^_:(.*)$/
@@ -1482,7 +1492,26 @@ module JSON::LD
     #
     # To make use of an inverse context, a list of preferred container mappings and the type mapping or language mapping are gathered for a particular value associated with an IRI. These parameters are then fed to the Term Selection algorithm, which will find the term that most appropriately matches the value's mappings.
     #
+    # @example Basic structure of resulting inverse context
+    #     {
+    #       "http://example.com/term": {
+    #         "@language": {
+    #           "@null": "term",
+    #           "@none": "term",
+    #           "en": "term"
+    #         },
+    #         "@type": {
+    #           "@reverse": "term",
+    #           "@none": "term",
+    #           "http://datatype": "term"
+    #         },
+    #         "@any": {
+    #           "@none": "term",
+    #         }
+    #       }
+    #     }
     # @return [Hash{String => Hash{String => String}}]
+    # @todo May want to include @set along with container to allow selecting terms using @set over those without @set. May require adding some notion of value cardinality to compact_iri
     def inverse_context
       @inverse_context ||= begin
         result = {}
@@ -1491,7 +1520,15 @@ module JSON::LD
           a.length == b.length ? (a <=> b) : (a.length <=> b.length)
         end.each do |term|
           next unless td = term_definitions[term]
-          container = td.container_mapping || (td.as_set ? '@set' : '@none')
+
+          container = Array(td.container_mapping).sort.first
+          container ||= td.as_set? ? %(@set) : %(@none)
+          # FIXME: Alternative to consider
+          ## Creates "@language", "@language@set", "@set", or "@none"
+          ## for each of "@language", "@index", "@type", "@id", "@list", and "@graph"
+          #container = td.container_mapping.to_s
+          #container += '@set' if td.as_set?
+          #container = '@none' if container.empty?
           container_map = result[td.id.to_s] ||= {}
           tl_map = container_map[container] ||= {'@language' => {}, '@type' => {}, '@any' => {}}
           type_map = tl_map['@type']
@@ -1620,20 +1657,45 @@ module JSON::LD
       val = Array(container).dup
       val.delete('@set') if has_set = val.include?('@set')
 
-      raise JsonLdError::InvalidContainerMapping,
-        "'@container' has more than one value other than @set" if val.length > 1
-
-      case val.first
-      when '@list'
+      if val.include?('@list')
         raise JsonLdError::InvalidContainerMapping,
-          "'@container' on term #{term.inspect} cannot be both @list and @set" if has_set
+          "'@container' on term #{term.inspect} using @list cannot have any other values" unless
+          !has_set && val.length == 1
         # Okay
-      when '@language', '@index', nil
+      elsif val.include?('@language')
+        raise JsonLdError::InvalidContainerMapping,
+              "unknown mapping for '@container' to #{container.inspect} on term #{term.inspect}" if
+               has_set && (processingMode || 'json-ld-1.0') < 'json-ld-1.1'
+        raise JsonLdError::InvalidContainerMapping,
+          "'@container' on term #{term.inspect} using @language cannot have any values other than @set, found  #{container.inspect}" unless
+          val.length == 1
+        # Okay
+      elsif val.include?('@index')
+        raise JsonLdError::InvalidContainerMapping,
+              "unknown mapping for '@container' to #{container.inspect} on term #{term.inspect}" if
+               has_set && (processingMode || 'json-ld-1.0') < 'json-ld-1.1'
+        raise JsonLdError::InvalidContainerMapping,
+          "'@container' on term #{term.inspect} using @index cannot have any values other than @set and/or @graph, found  #{container.inspect}" unless
+          (val - CONTEXT_CONTAINER_INDEX_GRAPH).empty?
+        # Okay
+      elsif val.include?('@id')
+        raise JsonLdError::InvalidContainerMapping,
+              "unknown mapping for '@container' to #{container.inspect} on term #{term.inspect}" if
+               (processingMode || 'json-ld-1.0') < 'json-ld-1.1'
+        raise JsonLdError::InvalidContainerMapping,
+          "'@container' on term #{term.inspect} using @id cannot have any values other than @set and/or @graph, found  #{container.inspect}" unless
+          (val - CONTEXT_CONTAINER_ID_GRAPH).empty?
         # Okay
-      when '@type', '@id', nil
+      elsif val.include?('@type') || val.include?('@graph')
         raise JsonLdError::InvalidContainerMapping,
               "unknown mapping for '@container' to #{container.inspect} on term #{term.inspect}" if
                (processingMode || 'json-ld-1.0') < 'json-ld-1.1'
+        raise JsonLdError::InvalidContainerMapping,
+          "'@container' on term #{term.inspect} using @language cannot have any values other than @set, found  #{container.inspect}" unless
+          val.length == 1
+        # Okay
+      elsif val.empty?
+        # Okay
       else
         raise JsonLdError::InvalidContainerMapping,
               "unknown mapping for '@container' to #{container.inspect} on term #{term.inspect}"