json-ld 1.1.8 → 1.1.9

data/lib/json/ld/flatten.rb

@@ -5,169 +5,118 @@ module JSON::LD
     ##
     # This algorithm creates a JSON object node map holding an indexed representation of the graphs and nodes represented in the passed expanded document. All nodes that are not uniquely identified by an IRI get assigned a (new) blank node identifier. The resulting node map will have a member for every graph in the document whose value is another object with a member for every node represented in the document. The default graph is stored under the @default member, all other graphs are stored under their graph name.
     #
-    # @param [Array, Hash] element
-    #   Expanded element
-    # @param [Hash{String => Hash}] node_map
-    #   map of nodes
-    # @param [String] active_graph
+    # @param [Array, Hash] input
+    #   Expanded JSON-LD input
+    # @param [Hash] graphs A map of graph name to subjects
+    # @param [String] graph
     #   The name of the currently active graph that the processor should use when processing.
-    # @param [String] active_subject
-    #   The currently active subject that the processor should use when processing.
-    # @param [String] active_property
-    #   The currently active property or keyword that the processor should use when processing.
+    # @param [String] name
+    #   The name assigned to the current input if it is a bnode
     # @param [Array] list
-    #   List for saving list elements
-    def generate_node_map(element,
-                          node_map,
-                          active_graph    = '@default',
-                          active_subject  = nil,
-                          active_property = nil,
-                          list            = nil)
+    #   List to append to, nil for none
+    def create_node_map(input,
+                        graphs,
+                        graph = '@default',
+                        name  = nil,
+                        list  = nil)
       depth do
-        debug("node_map") {"active_graph: #{active_graph}, element: #{element.inspect}"}
-        debug("  =>") {"active_subject: #{active_subject.inspect}, active_property: #{active_property.inspect}, list: #{list.inspect}"}
-        if element.is_a?(Array)
-          # If element is an array, process each entry in element recursively by passing item for element, node map, active graph, active subject, active property, and list.
-          element.map {|o|
-            generate_node_map(o,
-                              node_map,
-                              active_graph,
-                              active_subject,
-                              active_property,
-                              list)
-          }
-        else
-          # Otherwise element is a JSON object. Reference the JSON object which is the value of the active graph member of node map using the variable graph. If the active subject is null, set node to null otherwise reference the active subject member of graph using the variable node.
-          # Spec FIXME: initializing it to an empty JSON object, if necessary
-          raise "Expected element to be a hash, was #{element.class}" unless element.is_a?(Hash)
-          graph = node_map[active_graph] ||= {}
-          node = graph[active_subject] if active_subject
-
-          # If element has an @type member, perform for each item the following steps:
-          if element.has_key?('@type')
-            types = Array(element['@type']).map do |item|
-              # If item is a blank node identifier, replace it with a newly generated blank node identifier passing item for identifier.
-              blank_node?(item) ? namer.get_name(item) : item
-            end
-
-            element['@type'] = element['@type'].is_a?(Array) ? types : types.first
-          end
-
-          # If element has an @value member, perform the following steps:
-          if value?(element)
-            unless list
-              # If no list has been passed, merge element into the active property member of the active subject in graph.
-              merge_value(node, active_property, element)
-            else
-              # Otherwise, append element to the @list member of list.
-              merge_value(list, '@list', element)
-            end
-          elsif list?(element)
-            # Otherwise, if element has an @list member, perform the following steps:
-            # Initialize a new JSON object result having a single member @list whose value is initialized to an empty array.
-            result = {'@list' => []}
-
-            # Recursively call this algorithm passing the value of element's @list member as new element and result as list.
-            generate_node_map(element['@list'],
-                              node_map,
-                              active_graph,
-                              active_subject,
-                              active_property,
-                              result)
-
-            # Append result to the the value of the active property member of node.
-            debug("node_map") {"@list: #{result.inspect}"}
-            merge_value(node, active_property, result)
+        debug("node_map") {"graph: #{graph}, input: #{input.inspect}, name: #{name}"}
+        case input
+        when Array
+          # If input is an array, process each entry in input recursively by passing item for input, node map, active graph, active subject, active property, and list.
+          input.map {|o| create_node_map(o, graphs, graph, nil, list)}
+        when Hash
+          type = input['@type']
+          if value?(input)
+            # Rename blanknode @type
+            input['@type'] = namer.get_name(type) if type && blank_node?(type)
+            list << input if list
           else
-            # Otherwise element is a node object, perform the following steps:
-
-            # If element has an @id member, set id to its value and remove the member from element. If id is a blank node identifier, replace it with a newly generated blank node identifier passing id for identifier.
-            # Otherwise, set id to the result of the Generate Blank Node Identifier algorithm passing null for identifier.
-            id = element.delete('@id')
-            id = namer.get_name(id) if blank_node?(id)
-            debug("node_map") {"id: #{id.inspect}"}
+            # Input is a node definition
 
-            # If graph does not contain a member id, create one and initialize it to a JSON object consisting of a single member @id whose value is set to id.
-            graph[id] ||= {'@id' => id}
+            # spec requires @type to be named first, so assign names early
+            Array(type).each {|t| namer.get_name(t) if blank_node?(t)}
 
-            # If active property is not null, perform the following steps:
-            if node?(active_subject) || node_reference?(active_subject)
-              debug("node_map") {"active_subject is an object, merge into #{id}"}
-              merge_value(graph[id], active_property, active_subject)
-            elsif active_property
-              # Create a new JSON object reference consisting of a single member @id whose value is id.
-              reference = {'@id' => id}
-
-              # If list is null:
-              unless list
-                merge_value(node, active_property, reference)
-              else
-                merge_value(list, '@list', reference)
-              end
+            # get name for subject
+            if name.nil?
+              name ||= input['@id']
+              name = namer.get_name(name) if blank_node?(name)
             end
 
-            # Reference the value of the id member of graph using the variable node.
-            node = graph[id]
-
-            # If element has an @type key, append each item of its associated array to the array associated with the @type key of node unless it is already in that array. Finally remove the @type member from element.
-            if element.has_key?('@type')
-              Array(element.delete('@type')).each do |t|
-                merge_value(node, '@type', t)
-              end
-            end
-
-            # If element has an @index member, set the @index member of node to its value. If node has already an @index member with a different value, a conflicting indexes error has been detected and processing is aborted. Otherwise, continue by removing the @index member from element.
-            if element.has_key?('@index')
-              raise JsonLdError::ConflictingIndexes,
-                    "Element already has index #{node['@index']} dfferent from #{element['@index']}" if
-                    node['@index'] && node['@index'] != element['@index']
-              node['@index'] = element.delete('@index')
-            end
-
-            # If element has an @reverse member:
-            if element.has_key?('@reverse')
-              element.delete('@reverse').each do |property, values|
-                values.each do |value|
-                  debug("node_map") {"@reverse(#{id}): #{value.inspect}"}
-                  # Recursively invoke this algorithm passing value for element, node map, and active graph.
-                  generate_node_map(value,
-                                    node_map,
-                                    active_graph,
-                                    {'@id' => id},
-                                    property)
+            # add subject reference to list
+            list << {'@id' => name} if list
+
+            # create new subject or merge into existing one
+            subject = (graphs[graph] ||= {})[name] ||= {'@id' => name}
+
+            input.keys.kw_sort.each do |property|
+              objects = input[property]
+              case property
+              when '@id'
+                # Skip
+              when '@reverse'
+                # handle reverse properties
+                referenced_node, reverse_map = {'@id' => name}, objects
+                reverse_map.each do |reverse_property, items|
+                  items.each do |item|
+                    item_name = item['@id']
+                    item_name = namer.get_name(item_name) if blank_node?(item_name)
+                    create_node_map(item, graphs, graph, item_name)
+                    add_value(graphs[graph][item_name],
+                              reverse_property,
+                              referenced_node,
+                              property_is_array: true,
+                              allow_duplicate: false)
+                  end
+                end
+              when '@graph'
+                graphs[name] ||= {}
+                g = graph == '@merged' ? graph : name
+                create_node_map(objects, graphs, g)
+              when /^@(?!type)/
+                # copy non-@type keywords
+                if property == '@index' && subject['@index']
+                  raise JsonLdError::ConflictingIndexes,
+                        "Element already has index #{subject['@index']} dfferent from #{input['@index']}" if
+                        subject['@index'] != input['@index']
+                  subject['@index'] = input.delete('@index')
+                end
+                subject[property] = objects
+              else
+                # if property is a bnode, assign it a new id
+                property = namer.get_name(property) if blank_node?(property)
+
+                add_value(subject, property, [], property_is_array: true) if objects.empty?
+
+                objects.each do |o|
+                  o = namer.get_name(o) if property == '@type' && blank_node?(o)
+
+                  case
+                  when node?(o) || node_reference?(o)
+                    id = o['@id']
+                    id = namer.get_name(id) if blank_node?(id)
+
+                    # add reference and recurse
+                    add_value(subject, property, {'@id' => id}, property_is_array: true, allow_duplicate: false)
+                    create_node_map(o, graphs, graph, id)
+                  when list?(o)
+                    olist = []
+                    create_node_map(o['@list'], graphs, graph, name, olist)
+                    o = {'@list' => olist}
+                    add_value(subject, property, o, property_is_array: true, allow_duplicate: true)
+                  else
+                    # handle @value
+                    create_node_map(o, graphs, graph, name)
+                    add_value(subject, property, o, property_is_array: true, allow_duplicate: false)
+                  end
                 end
               end
             end
-
-            # If element has an @graph member, recursively invoke this algorithm passing the value of the @graph member for element, node map, and id for active graph before removing the @graph member from element.
-            if element.has_key?('@graph')
-              generate_node_map(element.delete('@graph'),
-                                node_map,
-                                id)
-            end
-
-            # Finally, for each key-value pair property-value in element ordered by property perform the following steps:
-            # Note: Not ordering doesn't seem to affect results and is more performant
-            element.keys.each do |property|
-              value = element[property]
-
-              # If property is a blank node identifier, replace it with a newly generated blank node identifier passing property for identifier.
-              property = namer.get_name(property) if blank_node?(property)
-
-              # If node does not have a property member, create one and initialize its value to an empty array.
-              node[property] ||= []
-
-              # Recursively invoke this algorithm passing value as new element, id as new active subject, and property as new active property.
-              generate_node_map(value,
-                                node_map,
-                                active_graph,
-                                id,
-                                property)
-            end
           end
+        else
+          # add non-object to list
+          list << input if list
         end
-
-        debug("node_map") {node_map.to_json(JSON_STATE) rescue 'malformed json'}
       end
     end
   end

data/lib/json/ld/format.rb

@@ -39,7 +39,9 @@ module JSON::LD
     # @param [String] sample Beginning several bytes (~ 1K) of input.
     # @return [Boolean]
     def self.detect(sample)
-      !!sample.match(/\{\s*"@(id|context|type)"/m)
+      !!sample.match(/\{\s*"@(id|context|type)"/m) &&
+        # Exclude CSVW metadata
+        !sample.include?("http://www.w3.org/ns/csvw")
     end
     
     ##

data/lib/json/ld/frame.rb

@@ -7,158 +7,140 @@ module JSON::LD
     #
     # @param [Hash{Symbol => Object}] state
     #   Current framing state
-    # @param [Hash{String => Hash}] nodes
-    #   Map of flattened nodes
+    # @param [Array<String>] subjects
+    #   The subjects to filter
     # @param [Hash{String => Object}] frame
     # @param [Hash{Symbol => Object}] options ({})
-    # @option options [Hash{String => Object}] :parent
-    #   Parent node or top-level array
-    # @option options [String] :property
-    #   Property referencing this frame, or null for array.
+    # @option options [Hash{String => Object}] :parent (nil)
+    #   Parent subject or top-level array
+    # @option options [String] :property (nil)
+    #   The parent property.
     # @raise [JSON::LD::InvalidFrame]
-    def frame(state, nodes, frame, options = {})
+    def frame(state, subjects, frame, options = {})
       depth do
         parent, property = options[:parent], options[:property]
-        debug("frame") {"state: #{state.inspect}"}
-        debug("frame") {"nodes: #{nodes.keys.inspect}"}
-        debug("frame") {"frame: #{frame.to_json(JSON_STATE) rescue 'malformed json'}"}
-        debug("frame") {"parent: #{parent.to_json(JSON_STATE) rescue 'malformed json'}"}
-        debug("frame") {"property: #{property.inspect}"}
         # Validate the frame
         validate_frame(state, frame)
+        frame = frame.first if frame.is_a?(Array)
 
-        # Create a set of matched nodes by filtering nodes by checking the map of flattened nodes against frame
+        # Get values for embedOn and explicitOn
+        flags = {
+          embed: get_frame_flag(frame, options, :embed),
+          explicit: get_frame_flag(frame, options, :explicit),
+          requireAll: get_frame_flag(frame, options, :requireAll),
+        }
+
+        # Create a set of matched subjects by filtering subjects by checking the map of flattened subjects against frame
         # This gives us a hash of objects indexed by @id
-        matches = filter_nodes(state, nodes, frame)
-        debug("frame") {"matches: #{matches.keys.inspect}"}
+        matches = filter_subjects(state, subjects, frame, flags)
 
-        # Get values for embedOn and explicitOn
-        embed = get_frame_flag(state, frame, 'embed');
-        explicit = get_frame_flag(state, frame, 'explicit');
-        debug("frame") {"embed: #{embed.inspect}, explicit: #{explicit.inspect}"}
-      
-        # For each id and node from the set of matched nodes ordered by id
+        # For each id and node from the set of matched subjects ordered by id
         matches.keys.kw_sort.each do |id|
-          element = matches[id]
-          # If the active property is null, set the map of embeds in state to an empty map
-          state = state.merge(embeds: {}) if property.nil?
+          subject = matches[id]
+
+          if flags[:embed] == '@link' && state[:link].has_key?(id)
+            # TODO: may want to also match an existing linked subject
+            # against the current frame ... so different frames could
+            # produce different subjects that are only shared in-memory
+            # when the frames are the same
+
+            # add existing linked subject
+            add_frame_output(parent, property, state[:link][id])
+            next
+          end
+
+          # Note: In order to treat each top-level match as a
+          # compartmentalized result, clear the unique embedded subjects map
+          # when the property is None, which only occurs at the top-level.
+          state = state.merge(uniqueEmbeds: {}) if property.nil?
 
           output = {'@id' => id}
-        
-          # prepare embed meta info
-          embedded_node = {parent: parent, property: property}
-        
-          # If embedOn is true, and id is in map of embeds from state
-          if embed && (existing = state[:embeds].fetch(id, nil))
-            # only overwrite an existing embed if it has already been added to its parent -- otherwise its parent is somewhere up the tree from this embed and the embed would occur twice once the tree is added
-            embed = false
-          
-            embed = if existing[:parent].is_a?(Array)
-              # If existing has a parent which is an array containing a JSON object with @id equal to id, element has already been embedded and can be overwritten, so set embedOn to true
-              existing[:parent].detect {|p| p['@id'] == id}
-            else
-              # Otherwise, existing has a parent which is a node definition. Set embedOn to true if any of the items in parent property is a node definition or node reference for id because the embed can be overwritten
-              existing[:parent].fetch(existing[:property], []).any? do |v|
-                v.is_a?(Hash) && v.fetch('@id', nil) == id
-              end
-            end
-            debug("frame") {"embed now: #{embed.inspect}"}
+          state[:link][id] = output
 
-            # If embedOn is true, existing is already embedded but can be overwritten
-            remove_embed(state, id) if embed
+          # if embed is @never or if a circular reference would be created
+          # by an embed, the subject cannot be embedded, just add the
+          # reference; note that a circular reference won't occur when the
+          # embed flag is `@link` as the above check will short-circuit
+          # before reaching this point
+          if flags[:embed] == '@never' || creates_circular_reference(subject, state[:subjectStack])
+            add_frame_output(parent, property, output)
+            next
           end
 
-          unless embed
-            # not embedding, add output without any other properties
-            add_frame_output(state, parent, property, output)
-          else
-            # Add embed to map of embeds for id
-            state[:embeds][id] = embedded_node
-            debug("frame") {"add embedded_node: #{embedded_node.inspect}"}
-        
-            # Process each property and value in the matched node as follows
-            element.keys.kw_sort.each do |prop|
-              value = element[prop]
-              if prop[0,1] == '@'
-                # If property is a keyword, add property and a copy of value to output and continue with the next property from node
-                output[prop] = value.dup
-                next
-              end
+          # if only the last match should be embedded
+          if flags[:embed] == '@last'
+            # remove any existing embed
+            remove_embed(state, id) if state[:uniqueEmbeds].include?(id)
+            state[:uniqueEmbeds][id] = {
+              parent: parent,
+              property: property
+            }
+          end
 
-              # If property is not in frame:
-              unless frame.has_key?(prop)
-                debug("frame") {"non-framed property #{prop}"}
-                # If explicitOn is false, Embed values from node in output using node as element and property as active property
-                embed_values(state, element, prop, output) unless explicit
-                
-                # Continue to next property
-                next
-              end
-          
-              # Process each item from value as follows
-              value.each do |item|
-                debug("frame") {"value property #{prop.inspect} == #{item.inspect}"}
-                
-                # FIXME: If item is a JSON object with the key @list
-                if list?(item)
-                  # create a JSON object named list with the key @list and the value of an empty array
-                  list = {'@list' => []}
-                  
-                  # Append list to property in output
-                  add_frame_output(state, output, prop, list)
-                  
-                  # Process each listitem in the @list array as follows
-                  item['@list'].each do |listitem|
-                    if node_reference?(listitem)
-                      itemid = listitem['@id']
-                      debug("frame") {"list item of #{prop} recurse for #{itemid.inspect}"}
-
-                      # If listitem is a node reference process listitem recursively using this algorithm passing a new map of nodes that contains the @id of listitem as the key and the node reference as the value. Pass the first value from frame for property as frame, list as parent, and @list as active property.
-                      frame(state, {itemid => @node_map[itemid]}, frame[prop].first, parent: list, property: '@list')
-                    else
-                      # Otherwise, append a copy of listitem to @list in list.
-                      debug("frame") {"list item of #{prop} non-node ref #{listitem.inspect}"}
-                      add_frame_output(state, list, '@list', listitem)
-                    end
-                  end
-                elsif node_reference?(item)
-                  # If item is a node reference process item recursively
-                  # Recurse into sub-objects
-                  itemid = item['@id']
-                  debug("frame") {"value property #{prop} recurse for #{itemid.inspect}"}
-                  
-                  # passing a new map as nodes that contains the @id of item as the key and the node reference as the value. Pass the first value from frame for property as frame, output as parent, and property as active property
-                  frame(state, {itemid => @node_map[itemid]}, frame[prop].first, parent: output, property: prop)
-                else
-                  # Otherwise, append a copy of item to active property in output.
-                  debug("frame") {"value property #{prop} non-node ref #{item.inspect}"}
-                  add_frame_output(state, output, prop, item)
-                end
-              end
+          # push matching subject onto stack to enable circular embed checks
+          state[:subjectStack] << subject
+
+          # iterate over subject properties in order
+          subject.keys.kw_sort.each do |prop|
+            objects = subject[prop]
+
+            # copy keywords to output
+            if prop.start_with?('@')
+              output[prop] = objects.dup
+              next
             end
 
-            # Process each property and value in frame in lexographical order, where property is not a keyword, as follows:
-            frame.keys.kw_sort.each do |prop|
-              next if prop[0,1] == '@' || output.has_key?(prop)
-              property_frame = frame[prop]
-              debug("frame") {"frame prop: #{prop.inspect}. property_frame: #{property_frame.inspect}"}
+            # explicit is on and property isn't in frame, skip processing
+            next if flags[:explicit] && !frame.has_key?(prop)
 
-              # Set property frame to the first item in value or a newly created JSON object if value is empty.
-              property_frame = property_frame.first || {}
+            # add objects
+            objects.each do |o|
+              case
+              when list?(o)
+                # add empty list
+                list = {'@list' => []}
+                add_frame_output(output, prop, list)
 
-              # Skip to the next property in frame if property is in output or if property frame contains @omitDefault which is true or if it does not contain @omitDefault but the value of omit default flag true.
-              next if output.has_key?(prop) || get_frame_flag(state, property_frame, 'omitDefault')
+                src = o['@list']
+                src.each do |oo|
+                  if node_reference?(oo)
+                    subframe = frame[prop].first['@list'] if frame[prop].is_a?(Array) && frame[prop].first.is_a?(Hash)
+                    subframe ||= create_implicit_frame(flags)
+                    frame(state, [oo['@id']], subframe, options.merge(parent: list, property: '@list'))
+                  else
+                    add_frame_output(list, '@list', oo.dup)
+                  end
+                end
+              when node_reference?(o)
+                # recurse into subject reference
+                subframe = frame[prop] || create_implicit_frame(flags)
+                frame(state, [o['@id']], subframe, options.merge(parent: output, property: prop))
+              else
+                # include other values automatically
+                add_frame_output(output, prop, o.dup)
+              end
+            end
+          end
 
-              # Set the value of property in output to a new JSON object with a property @preserve and a value that is a copy of the value of @default in frame if it exists, or the string @null otherwise
-              default = property_frame.fetch('@default', '@null').dup
-              default = [default] unless default.is_a?(Array)
-              output[prop] = [{"@preserve" => default.compact}]
-              debug("=>") {"add default #{output[prop].inspect}"}
+          # handle defaults in order
+          frame.keys.kw_sort.reject {|p| p.start_with?('@')}.each do |prop|
+            # if omit default is off, then include default values for
+            # properties that appear in the next frame but are not in
+            # the matching subject
+            n = frame[prop].first || {}
+            omit_default_on = get_frame_flag(n, options, :omitDefault)
+            if !omit_default_on && !output[prop]
+              preserve = n.fetch('@default', '@null').dup
+              preserve = [preserve] unless preserve.is_a?(Array)
+              output[prop] = [{'@preserve' => preserve}]
             end
-          
-            # Add output to parent
-            add_frame_output(state, parent, property, output)
           end
+
+          # add output to parent
+          add_frame_output(parent, property, output)
+
+          # pop matching subject from circular ref-checking stack
+          state[:subjectStack].pop()
         end
       end
     end
@@ -170,10 +152,9 @@ module JSON::LD
     # @return [Array, Hash]
     def cleanup_preserve(input)
       depth do
-        #debug("cleanup preserve") {input.inspect}
         result = case input
         when Array
-          # If, after replacement, an array contains only the value null remove the value, leaving an empty array. 
+          # If, after replacement, an array contains only the value null remove the value, leaving an empty array.
           input.map {|o| cleanup_preserve(o)}.compact
         when Hash
           output = Hash.new(input.size)
@@ -183,7 +164,7 @@ module JSON::LD
               output = cleanup_preserve(value)
             else
               v = cleanup_preserve(value)
-              
+
               # Because we may have added a null value to an array, we need to clean that up, if we possible
               v = v.first if v.is_a?(Array) && v.length == 1 &&
                 context.expand_iri(key) != "@graph" && context.container(key).nil?
@@ -197,23 +178,29 @@ module JSON::LD
         else
           input
         end
-        #debug(" => ") {result.inspect}
         result
       end
     end
 
     private
-    
+
     ##
-    # Returns a map of all of the nodes that match a parsed frame.
-    # 
-    # @param state the current framing state.
-    # @param nodes the set of nodes to filter.
-    # @param frame the parsed frame.
-    # 
-    # @return all of the matched nodes.
-    def filter_nodes(state, nodes, frame)
-      nodes.dup.keep_if {|id, element| element && filter_node(state, element, frame)}
+    # Returns a map of all of the subjects that match a parsed frame.
+    #
+    # @param [Hash{Symbol => Object}] state
+    #   Current framing state
+    # @param [Hash{String => Hash}] subjects
+    #   The subjects to filter
+    # @param [Hash{String => Object}] frame
+    # @param [Hash{Symbol => String}] flags the frame flags.
+    #
+    # @return all of the matched subjects.
+    def filter_subjects(state, subjects, frame, flags)
+      subjects.inject({}) do |memo, id|
+        subject = state[:subjects][id]
+        memo[id] = subject if filter_subject(subject, frame, flags)
+        memo
+      end
     end
 
     ##
@@ -226,42 +213,95 @@ module JSON::LD
     #
     # Otherwise, does duck typing, where the node must have all of the properties
     # defined in the frame.
-    # 
-    # @param [Hash{Symbol => Object}] state the current frame state.
-    # @param [Hash{String => Object}] node the node to check.
+    #
+    # @param [Hash{String => Object}] subject the subject to check.
     # @param [Hash{String => Object}] frame the frame to check.
-    # 
-    # @return true if the node matches, false if not.
-    def filter_node(state, node, frame)
-      debug("frame") {"filter node: #{node.inspect}"}
-      if types = frame.fetch('@type', nil)
-        node_types = node.fetch('@type', [])
-        raise InvalidFrame::Syntax, "frame @type must be an array: #{types.inspect}" unless types.is_a?(Array)
-        raise InvalidFrame::Syntax, "node @type must be an array: #{node_types.inspect}" unless node_types.is_a?(Array)
-        # If frame has an @type, use it for selecting appropriate nodes.
-        debug("frame") {"filter node: #{node_types.inspect} has any of #{types.inspect}"}
+    # @param [Hash{Symbol => Object}] flags the frame flags.
+    #
+    # @return [Boolean] true if the node matches, false if not.
+    def filter_subject(subject, frame, flags)
+      types = frame.fetch('@type', [])
+      raise InvalidFrame::Syntax, "frame @type must be an array: #{types.inspect}" unless types.is_a?(Array)
+      subject_types = subject.fetch('@type', [])
+      raise InvalidFrame::Syntax, "node @type must be an array: #{node_types.inspect}" unless subject_types.is_a?(Array)
 
-        # Check for type wild-card, or intersection
-        types == [{}] ? !node_types.empty? : node_types.any? {|t| types.include?(t)}
+      # check @type (object value means 'any' type, fall through to ducktyping)
+      if !types.empty? &&
+         !(types.length == 1 && types.first.is_a?(Hash))
+        # If frame has an @type, use it for selecting appropriate nodes.
+        return types.any? {|t| subject_types.include?(t)}
       else
         # Duck typing, for nodes not having a type, but having @id
-        
-        # Subject matches if it has all the properties in the frame
-        frame_keys = frame.keys.reject {|k| k[0,1] == '@'}
-        node_keys = node.keys.reject {|k| k[0,1] == '@'}
-        (frame_keys & node_keys) == frame_keys
+        wildcard, matches_some = true, false
+
+        frame.each do |k, v|
+          case k
+          when '@id'
+            return false if v.is_a?(String) && subject['@id'] != v
+            wildcard, matches_some = true, true
+          when '@type'
+            wildcard, matches_some = true, true
+          when /^@/
+          else
+            wildcard = false
+
+            # v == [] means do not match if property is present
+            if subject.has_key?(k)
+              return false if v == []
+              matches_some = true
+              next
+            end
+
+            # all properties must match to be a duck unless a @default is
+            # specified
+            has_default = v.is_a?(Array) && v.length == 1 && v.first.is_a?(Hash) && v.first.has_key?('@default')
+            return false if flags[:requireAll] && !has_default
+          end
+        end
+
+        # return true if wildcard or subject matches some properties
+        wildcard || matches_some
       end
     end
 
     def validate_frame(state, frame)
       raise InvalidFrame::Syntax,
-            "Invalid JSON-LD syntax; a JSON-LD frame must be an object: #{frame.inspect}" unless frame.is_a?(Hash)
+            "Invalid JSON-LD syntax; a JSON-LD frame must be an object: #{frame.inspect}" unless
+        frame.is_a?(Hash) || (frame.is_a?(Array) && frame.first.is_a?(Hash) && frame.length == 1)
     end
-    
-    # Return value of @name in frame, or default from state if it doesn't exist
-    def get_frame_flag(state, frame, name)
-      value = frame.fetch("@#{name}", [state[name.to_sym]]).first
-      !!(value?(value) ? value['@value'] : value)
+
+    # Checks the current subject stack to see if embedding the given subject
+    # would cause a circular reference.
+    # 
+    # @param subject_to_embed the subject to embed.
+    # @param subject_stack the current stack of subjects.
+    # 
+    # @return true if a circular reference would be created, false if not.
+    def creates_circular_reference(subject_to_embed, subject_stack)
+      subject_stack[0..-2].any? do |subject|
+        subject['@id'] == subject_to_embed['@id']
+      end
+    end
+
+    # Gets the frame flag value for the given flag name.
+    # 
+    # @param frame the frame.
+    # @param options the framing options.
+    # @param name the flag name.
+    # 
+    # @return the flag value.
+    def get_frame_flag(frame, options, name)
+      rval = frame.fetch("@#{name}", [options[name]]).first
+      rval = rval.values.first if value?(rval)
+      if name == :embed
+        rval = case rval
+        when true then '@last'
+        when false then '@never'
+        when '@always', '@never', '@link' then rval
+        else '@last'
+        end
+      end
+      rval
     end
 
     ##
@@ -270,29 +310,32 @@ module JSON::LD
     # @param state the current framing state.
     # @param id the @id of the embed to remove.
     def remove_embed(state, id)
-      debug("frame") {"remove embed #{id.inspect}"}
       # get existing embed
-      embeds = state[:embeds];
+      embeds = state[:uniqueEmbeds];
       embed = embeds[id];
-      parent = embed[:parent];
       property = embed[:property];
 
       # create reference to replace embed
-      node = {}
-      node['@id'] = id
-      ref = {'@id' => id}
-      
-      # remove existing embed
-      if node?(parent)
+      subject = {'@id' => id}
+
+      if embed[:parent].is_a?(Array)
+        # replace subject with reference
+        embed[:parent].map! do |parent|
+          compare_values(parent, subject) ? subject : parent
+        end
+      else
+        parent = embed[:parent]
         # replace node with reference
-        parent[property].map! do |v|
-          v.is_a?(Hash) && v.fetch('@id', nil) == id ? ref : v
+        if parent[property].is_a?(Array)
+          parent[property].reject! {|v| compare_values(v, subject)}
+          parent[property] << subject
+        elsif compare_values(parent[property], subject)
+          parent[property] = subject
         end
       end
 
       # recursively remove dependent dangling embeds
       def remove_dependents(id, embeds)
-        debug("frame") {"remove dependents for #{id}"}
 
         depth do
           # get embed keys as a separate array to enable deleting keys in map
@@ -301,70 +344,40 @@ module JSON::LD
             next unless p.is_a?(Hash)
             pid = p.fetch('@id', nil)
             if pid == id
-              debug("frame") {"remove #{id_dep} from embeds"}
               embeds.delete(id_dep)
               remove_dependents(id_dep, embeds)
             end
           end
         end
       end
-      
+
       remove_dependents(id, embeds)
     end
 
     ##
     # Adds framing output to the given parent.
     #
-    # @param state the current framing state.
     # @param parent the parent to add to.
     # @param property the parent property, null for an array parent.
     # @param output the output to add.
-    def add_frame_output(state, parent, property, output)
+    def add_frame_output(parent, property, output)
       if parent.is_a?(Hash)
-        debug("frame") { "add for property #{property.inspect}: #{output.inspect}"}
         parent[property] ||= []
         parent[property] << output
       else
-        debug("frame") { "add top-level: #{output.inspect}"}
         parent << output
       end
     end
-    
-    ##
-    # Embeds values for the given element and property into output.
-    def embed_values(state, element, property, output)
-      element[property].each do |o|
-        # Get element @id, if this is an object
-        sid = o['@id'] if node_reference?(o)
-        if sid
-          unless state[:embeds].has_key?(sid)
-            debug("frame") {"embed element #{sid.inspect}"}
-            # Embed full element, if it isn't already embedded
-            embed = {parent: output, property: property}
-            state[:embeds][sid] = embed
-          
-            # Recurse into element
-            s = @node_map.fetch(sid, {'@id' => sid})
-            o = {}
-            s.each do |prop, value|
-              if prop[0,1] == '@'
-                # Copy keywords
-                o[prop] = s[prop].dup
-              else
-                depth do
-                  debug("frame") {"embed property #{prop.inspect} value #{value.inspect}"}
-                  embed_values(state, s, prop, o)
-                end
-              end
-            end
-          else
-            debug("frame") {"don't embed element #{sid.inspect}"}
-          end
-        else
-          debug("frame") {"embed property #{property.inspect}, value #{o.inspect}"}
-        end
-        add_frame_output(state, output, property, o.dup)
-      end
+
+    # Creates an implicit frame when recursing through subject matches. If
+    # a frame doesn't have an explicit frame for a particular property, then
+    # a wildcard child frame will be created that uses the same flags that
+    # the parent frame used.
+    #
+    # @param [Hash] flags the current framing flags.
+    # @return [Array<Hash>] the implicit frame.
+    def create_implicit_frame(flags)
+      [flags.keys.inject({}) {|memo, key| memo["@#{key}"] = [flags[key]]; memo}]
     end
   end
 end