Make ordering optional, and test suite tests using both ordered: true and ordered; false (the default).

When ordered is false, compare JSON results ignoring array ordering, except for array values of `@list`. If results are compacted, also test by expanding each.

Author: gkellogg

lib/json/ld/api.rb

@@ -82,12 +82,15 @@ class API
     #   Use unique bnode identifiers, defaults to using the identifier which the node was originally initialized with (if any).
     # @option options [Symbol] :adapter used with MultiJson
     # @option options [Boolean] :validate Validate input, if a string or readable object.
+    # @option options [Boolean] :ordered (true)
+    #   Order traversal of dictionary members by key when performing algorithms.
     # @yield [api]
     # @yieldparam [API]
     # @raise [JsonLdError]
     def initialize(input, context, rename_bnodes: true, unique_bnodes: false, **options, &block)
       @options = {
         compactArrays:      true,
+        ordered:            false,
         documentLoader:     self.class.method(:documentLoader)
       }.merge(options)
       @namer = unique_bnodes ? BlankNodeUniqer.new : (rename_bnodes ? BlankNodeNamer.new("b") : BlankNodeMapper.new)
@@ -163,11 +166,11 @@ def initialize(input, context, rename_bnodes: true, unique_bnodes: false, **opti
     # @return [Object, Array<Hash>]
     #   If a block is given, the result of evaluating the block is returned, otherwise, the expanded JSON-LD document
     # @see http://json-ld.org/spec/latest/json-ld-api/#expansion-algorithm
-    def self.expand(input, ordered: true, framing: false, **options, &block)
+    def self.expand(input, framing: false, **options, &block)
       result, doc_base = nil
       API.new(input, options[:expandContext], options) do
         result = self.expand(self.value, nil, self.context,
-          ordered: ordered,
+          ordered: @options[:ordered],
           framing: framing)
         doc_base = @options[:base]
       end
@@ -218,14 +221,14 @@ def self.compact(input, context, expanded: false, **options)
 
       # 1) Perform the Expansion Algorithm on the JSON-LD input.
       #    This removes any existing context to allow the given context to be cleanly applied.
-      expanded_input = expanded ? input : API.expand(input, options) do |res, base_iri|
+      expanded_input = expanded ? input : API.expand(input, options.merge(ordered: false)) do |res, base_iri|
         options[:base] ||= base_iri if options[:compactToRelative]
         res
       end
 
       API.new(expanded_input, context, no_default_base: true, **options) do
         log_debug(".compact") {"expanded input: #{expanded_input.to_json(JSON_STATE) rescue 'malformed json'}"}
-        result = compact(value)
+        result = compact(value, ordered: @options[:ordered])
 
         # xxx) Add the given context to the output
         ctx = self.context.serialize
@@ -276,23 +279,23 @@ def self.flatten(input, context, expanded: false, **options)
         create_node_map(value, graph_maps)
 
         default_graph = graph_maps['@default']
-        graph_maps.keys.sort.each do |graph_name|
+        graph_maps.keys.opt_sort(ordered: @options[:ordered]).each do |graph_name|
           next if graph_name == '@default'
 
           graph = graph_maps[graph_name]
           entry = default_graph[graph_name] ||= {'@id' => graph_name}
           nodes = entry['@graph'] ||= []
-          graph.keys.sort.each do |id|
+          graph.keys.opt_sort(ordered: @options[:ordered]).each do |id|
             nodes << graph[id] unless node_reference?(graph[id])
           end
         end
-        default_graph.keys.sort.each do |id|
+        default_graph.keys.opt_sort(ordered: @options[:ordered]).each do |id|
           flattened << default_graph[id] unless node_reference?(default_graph[id])
         end
 
         if context && !flattened.empty?
           # Otherwise, return the result of compacting flattened according the Compaction algorithm passing context ensuring that the compaction result uses the @graph keyword (or its alias) at the top-level, even if the context is empty or if there is only one element to put in the @graph array. This ensures that the returned document has a deterministic structure.
-          compacted = as_array(compact(flattened))
+          compacted = as_array(compact(flattened, ordered: @options[:ordered]))
           kwgraph = self.context.compact_iri('@graph', quiet: true)
           flattened = self.context.serialize.merge(kwgraph => compacted)
         end
@@ -397,7 +400,7 @@ def self.frame(input, frame, expanded: false, **options)
         framing_state[:subjects] = framing_state[:graphMap][framing_state[:graph]]
 
         result = []
-        frame(framing_state, framing_state[:subjects].keys.sort, (expanded_frame.first || {}), parent: result, **options)
+        frame(framing_state, framing_state[:subjects].keys.opt_sort(ordered: @options[:ordered]), (expanded_frame.first || {}), parent: result, **options)
 
         # Count blank node identifiers used in the document, if pruning
         unless @options[:processingMode] == 'json-ld-1.0'
@@ -408,7 +411,7 @@ def self.frame(input, frame, expanded: false, **options)
         # Initalize context from frame
         @context = @context.parse(frame['@context'])
         # Compact result
-        compacted = compact(result)
+        compacted = compact(result, ordered: @options[:ordered])
         compacted = [compacted] unless options[:omitGraph] || compacted.is_a?(Array)
 
         # Add the given context to the output
@@ -493,8 +496,11 @@ def self.toRdf(input, expanded: false, **options, &block)
     def self.fromRdf(input, useRdfType: false, useNativeTypes: false, **options, &block)
       result = nil
 
-      API.new(nil, nil, options) do |api|
-        result = api.from_statements(input, useRdfType: useRdfType, useNativeTypes: useNativeTypes)
+      API.new(nil, nil, options) do
+        result = from_statements(input,
+          useRdfType: useRdfType,
+          useNativeTypes: useNativeTypes,
+          ordered: @options[:ordered])
       end
 
       block_given? ? yield(result) : result

lib/json/ld/compact.rb

@@ -9,8 +9,10 @@ module Compact
     #
     # @param [Array, Hash] element
     # @param [String] property (nil)
+    # @param [Boolean] ordered (true)
+    #   Ensure output objects have keys ordered properly
     # @return [Array, Hash]
-    def compact(element, property: nil)
+    def compact(element, property: nil, ordered: false)
       #if property.nil?
       #  log_debug("compact") {"element: #{element.inspect}, ec: #{context.inspect}"}
       #else
@@ -25,7 +27,7 @@ def compact(element, property: nil)
       case element
       when Array
         #log_debug("") {"Array #{element.inspect}"}
-        result = element.map {|item| compact(item, property: property)}.compact
+        result = element.map {|item| compact(item, property: property, ordered: ordered)}.compact
 
         # If element has a single member and the active property has no
         # @container mapping to @list or @set, the compacted value is that
@@ -54,7 +56,7 @@ def compact(element, property: nil)
 
         # If expanded property is @list and we're contained within a list container, recursively compact this item to an array
         if list?(element) && context.container(property) == %w(@list)
-          return compact(element['@list'], property: property)
+          return compact(element['@list'], property: property, ordered: ordered)
         end
 
 
@@ -71,7 +73,7 @@ def compact(element, property: nil)
           self.context = context.parse(term_context) if term_context
         end
 
-        element.keys.sort.each do |expanded_property|
+        element.keys.opt_sort(ordered: ordered).each do |expanded_property|
           expanded_value = element[expanded_property]
           #log_debug("") {"#{expanded_property}: #{expanded_value.inspect}"}
 
@@ -89,7 +91,7 @@ def compact(element, property: nil)
           end
 
           if expanded_property == '@reverse'
-            compacted_value = compact(expanded_value, property: '@reverse')
+            compacted_value = compact(expanded_value, property: '@reverse', ordered: ordered)
             #log_debug("@reverse") {"compacted_value: #{compacted_value.inspect}"}
             # handle double-reversed properties
             compacted_value.each do |prop, value|
@@ -110,7 +112,7 @@ def compact(element, property: nil)
 
           if expanded_property == '@preserve'
             # Compact using `property`
-            compacted_value = compact(expanded_value, property: property)
+            compacted_value = compact(expanded_value, property: property, ordered: ordered)
             #log_debug("@preserve") {"compacted_value: #{compacted_value.inspect}"}
 
             unless compacted_value.is_a?(Array) && compacted_value.empty?
@@ -176,7 +178,7 @@ def compact(element, property: nil)
             else expanded_item
             end
 
-            compacted_item = compact(value, property: item_active_property)
+            compacted_item = compact(value, property: item_active_property, ordered: ordered)
             #log_debug("") {" => compacted key: #{item_active_property.inspect} for #{compacted_item.inspect}"}
 
             # handle @list
@@ -267,8 +269,7 @@ def compact(element, property: nil)
           end
         end
 
-        # Re-order result keys
-        result.keys.sort.each_with_object({}) {|kk, memo| memo[kk] = result[kk]}
+        result
       else
         # For other types, the compacted value is the element value
         #log_debug("compact") {element.class.to_s}

lib/json/ld/context.rb

@@ -750,7 +750,7 @@ def serialize(**options)
         ctx['@vocab'] = vocab.to_s if vocab
 
         # Term Definitions
-        term_definitions.keys.sort.each do |term|
+        term_definitions.keys.each do |term|
           defn = term_definitions[term].to_context_definition(self)
           ctx[term] = defn if defn
         end
@@ -1201,7 +1201,7 @@ def compact_iri(iri, value: nil, vocab: nil, reverse: false, quiet: false, **opt
         candidates << ciri unless value && term_definitions.has_key?(ciri)
       end
 
-      return candidates.term_sort.first if !candidates.empty?
+      return candidates.sort.first if !candidates.empty?
 
       # If we still don't have any terms and we're using standard_prefixes,
       # try those, and add to mapping
@@ -1214,7 +1214,7 @@ def compact_iri(iri, value: nil, vocab: nil, reverse: false, quiet: false, **opt
             iri.sub(v.to_uri.to_s, "#{prefix}:").sub(/:$/, '')
           end
 
-        return candidates.term_sort.first if !candidates.empty?
+        return candidates.sort.first if !candidates.empty?
       end
 
       if !vocab

lib/json/ld/expand.rb

@@ -19,7 +19,7 @@ module Expand
     # @param [Boolean] framing (false)
     #   Special rules for expanding a frame
     # @return [Array<Hash{String => Object}>]
-    def expand(input, active_property, context, ordered: true, framing: false)
+    def expand(input, active_property, context, ordered: false, framing: false)
       #log_debug("expand") {"input: #{input.inspect}, active_property: #{active_property.inspect}, context: #{context.inspect}"}
       framing = false if active_property == '@default'
       result = case input

lib/json/ld/extensions.rb

@@ -43,11 +43,11 @@ def valid_extended?
 end
 
 class Array
-  # Order terms, length first, then lexographically
-  def term_sort
-    self.sort do |a, b|
-      len_diff = a.length <=> b.length
-      len_diff == 0 ? a <=> b : len_diff
-    end
+  # Optionally order items
+  #
+  # @param [Boolean] ordered
+  # @return [Array]
+  def opt_sort(ordered: false)
+    ordered ? self.sort : self
   end
 end

lib/json/ld/flatten.rb

@@ -18,6 +18,8 @@ module Flatten
     #   Property within current node
     # @param [Array] list (nil)
     #   Used when property value is a list
+    # @param [Boolean] ordered (true)
+    #   Ensure output objects have keys ordered properly
     def create_node_map(element, graph_map,
                         active_graph: '@default',
                         active_subject: nil,
@@ -110,7 +112,7 @@ def create_node_map(element, graph_map,
                             active_graph: id)
           end
 
-          element.keys.sort.each do |property|
+          element.keys.each do |property|
             value = element[property]
 
             property = namer.get_name(property) if blank_node?(property)

lib/json/ld/frame.rb

@@ -14,13 +14,15 @@ module Frame
     # @param [Array<String>] subjects
     #   The subjects to filter
     # @param [Hash{String => Object}] frame
-    # @param [Hash{Symbol => Object}] options ({})
-    # @option options [Hash{String => Object}] :parent (nil)
-    #   Parent subject or top-level array
-    # @option options [String] :property (nil)
+    # @param [String] property (nil)
     #   The parent property.
+    # @param [Hash{String => Object}] parent (nil)
+    #   Parent subject or top-level array
+    # @param [Boolean] ordered (true)
+    #   Ensure output objects have keys ordered properly
+    # @param [Hash{Symbol => Object}] options ({})
     # @raise [JSON::LD::InvalidFrame]
-    def frame(state, subjects, frame, parent: nil, property: nil, **options)
+    def frame(state, subjects, frame, parent: nil, property: nil, ordered: false, **options)
       #log_depth do
       #log_debug("frame") {"subjects: #{subjects.inspect}"}
       #log_debug("frame") {"frame: #{frame.to_json(JSON_STATE)}"}
@@ -45,7 +47,7 @@ def frame(state, subjects, frame, parent: nil, property: nil, **options)
       matches = filter_subjects(state, subjects, frame, flags)
 
       # For each id and node from the set of matched subjects ordered by id
-      matches.keys.sort.each do |id|
+      matches.keys.opt_sort(ordered: ordered).each do |id|
         subject = matches[id]
 
         # Note: In order to treat each top-level match as a compartmentalized result, clear the unique embedded subjects map when the property is nil, which only occurs at the top-level.
@@ -110,7 +112,7 @@ def frame(state, subjects, frame, parent: nil, property: nil, **options)
         end
 
         # iterate over subject properties in order
-        subject.keys.sort.each do |prop|
+        subject.keys.opt_sort(ordered: ordered).each do |prop|
           objects = subject[prop]
 
           # copy keywords to output
@@ -153,7 +155,7 @@ def frame(state, subjects, frame, parent: nil, property: nil, **options)
         end
 
         # handle defaults in order
-        frame.keys.sort.each do |prop|
+        frame.keys.opt_sort(ordered: ordered).each do |prop|
           next if prop.start_with?('@')
 
           # if omit default is off, then include default values for properties that appear in the next frame but are not in the matching subject

lib/json/ld/from_rdf.rb

@@ -14,8 +14,10 @@ module FromRDF
     # @param [Boolean] useRdfType (false)
     #   If set to `true`, the JSON-LD processor will treat `rdf:type` like a normal property instead of using `@type`.
     # @param [Boolean] useNativeTypes (false) use native representations
+    # @param [Boolean] ordered (true)
+    #   Ensure output objects have keys ordered properly
     # @return [Array<Hash>] the JSON-LD document in normalized form
-    def from_statements(dataset, useRdfType: false, useNativeTypes: false)
+    def from_statements(dataset, useRdfType: false, useNativeTypes: false, ordered: false)
       default_graph = {}
       graph_map = {'@default' => default_graph}
       referenced_once = {}
@@ -118,11 +120,11 @@ def from_statements(dataset, useRdfType: false, useNativeTypes: false)
       end
 
       result = []
-      default_graph.keys.sort.each do |subject|
+      default_graph.keys.opt_sort(ordered: ordered).each do |subject|
         node = default_graph[subject]
         if graph_map.has_key?(subject)
           node['@graph'] = []
-          graph_map[subject].keys.sort.each do |s|
+          graph_map[subject].keys.opt_sort(ordered: ordered).each do |s|
             n = graph_map[subject][s]
             n.delete(:usages)
             node['@graph'] << n unless node_reference?(n)

spec/api_spec.rb

@@ -81,17 +81,17 @@
               options = {logger: logger, adapter: adapter}
               options[:expandContext] = File.open(context) if context
               jld = described_class.expand(File.open(filename), options)
-              expect(jld).to produce(JSON.load(File.open(expanded)), logger)
+              expect(jld).to produce_jsonld(JSON.load(File.open(expanded)), logger)
             end if File.exist?(expanded)
 
             it "compacts" do
               jld = described_class.compact(File.open(filename), File.open(context), adapter: adapter, logger: logger)
-              expect(jld).to produce(JSON.load(File.open(compacted)), logger)
+              expect(jld).to produce_jsonld(JSON.load(File.open(compacted)), logger)
             end if File.exist?(compacted) && File.exist?(context)
 
             it "frame" do
               jld = described_class.frame(File.open(filename), File.open(frame), adapter: adapter, logger: logger)
-              expect(jld).to produce(JSON.load(File.open(framed)), logger)
+              expect(jld).to produce_jsonld(JSON.load(File.open(framed)), logger)
             end if File.exist?(framed) && File.exist?(frame)
 
             it "toRdf" do

spec/compact_spec.rb

@@ -501,7 +501,7 @@
         })
         allow(JSON::LD::API).to receive(:documentLoader).with("http://example.com/context", anything).and_yield(remote_doc)
         jld = JSON::LD::API.compact(input, "http://example.com/context", logger: logger, validate: true)
-        expect(jld).to produce(expected, logger)
+        expect(jld).to produce_jsonld(expected, logger)
       end
     end
 
@@ -2237,7 +2237,12 @@ def run_compact(params)
       expect {JSON::LD::API.compact(input, context, params.merge(logger: logger))}.to raise_error(params[:exception])
     else
       jld = JSON::LD::API.compact(input, context, params.merge(logger: logger))
-      expect(jld).to produce(output, logger)
+      expect(jld).to produce_jsonld(output, logger)
+
+      # Compare expanded jld/output too to make sure list values remain ordered
+      exp_jld = JSON::LD::API.expand(jld, processingMode: 'json-ld-1.1')
+      exp_output = JSON::LD::API.expand(output, processingMode: 'json-ld-1.1')
+      expect(exp_jld).to produce_jsonld(exp_output, logger)
     end
   end
 end