json-ld 0.1.5.2 → 0.1.6

data/History.markdown

@@ -1,3 +1,10 @@
+=== 0.1.6
+* Added flattening API, and updated algorithm.
+* Fixed framing issues using updated flattening.
+
+=== 0.1.5
+* Added support for @vocab.
+
 === 0.1.4.1
 * Include rdf-xsd for some specs.
 * Refactor #expand_value to deal with previous matching on RDF::Literal::Integer for sub-types.

data/VERSION

@@ -1 +1 @@
-0.1.5.2
+0.1.6

data/lib/json/ld/api.rb

@@ -1,6 +1,7 @@
 require 'open-uri'
 require 'json/ld/expand'
 require 'json/ld/compact'
+require 'json/ld/flatten'
 require 'json/ld/frame'
 require 'json/ld/to_rdf'
 require 'json/ld/from_rdf'
@@ -19,6 +20,7 @@ module JSON::LD
     include Expand
     include Compact
     include Triples
+    include Flatten
     include FromTriples
     include Frame
 
@@ -151,6 +153,77 @@ module JSON::LD
       result
     end
 
+    ##
+    # Flattens the given input according to the steps in the Flattening Algorithm. The input must be flattened and returned if there are no errors. If the flattening fails, an appropriate exception must be thrown.
+    #
+    # The resulting `Array` is returned via the provided callback.
+    #
+    # Note that for Ruby, if the callback is not provided and a block is given, it will be yielded. If there is no block, the value will be returned.
+    #
+    # @param [String, #read, Hash, Array] input
+    #   The JSON-LD object or array of JSON-LD objects to flatten or an IRI referencing the JSON-LD document to flatten.
+    # @param [String, RDF::URI] graph
+    #   The graph in the document that should be flattened. To return the default graph @default has to be passed, for the merged graph @merged and for any other graph the IRI identifying the graph has to be passed. The default value is @merged.
+    # @param [String, #read, Hash, Array] context
+    #   An optional external context to use additionally to the context embedded in input when expanding the input.
+    # @param [Proc] callback (&block)
+    #   Alternative to using block, with same parameters.
+    # @param  [Hash{Symbol => Object}] options
+    #   Other options passed to {#expand}
+    # @option options [Boolean] :embed (true)
+    #   a flag specifying that objects should be directly embedded in the output,
+    #   instead of being referred to by their IRI.
+    # @option options [Boolean] :explicit (false)
+    #   a flag specifying that for properties to be included in the output,
+    #   they must be explicitly declared in the framing context.
+    # @option options [Boolean] :omitDefault (false)
+    #   a flag specifying that properties that are missing from the JSON-LD
+    #   input should be omitted from the output.
+    # @yield jsonld
+    # @yieldparam [Hash] jsonld
+    #   The framed JSON-LD document
+    # @return [Array<Hash>]
+    #   The framed JSON-LD document
+    # @raise [InvalidFrame]
+    # @see http://json-ld.org/spec/latest/json-ld-api/#framing-algorithm
+    def self.flatten(input, graph, context, callback = nil, options = {})
+      result = nil
+      graph ||= '@merged'
+
+      # Expand input to simplify processing
+      expanded_input = API.expand(input)
+
+      # Initialize input using frame as context
+      API.new(expanded_input, nil, options) do
+        debug(".flatten") {"expanded input: #{value.to_json(JSON_STATE)}"}
+
+        # Generate _nodeMap_
+        node_map = Hash.ordered
+        self.generate_node_map(value,
+          node_map,
+          (graph.to_s == '@merged' ? '@merged' : '@default'),
+          nil,
+          BlankNodeNamer.new("t"))
+        
+        result = []
+
+        # If nodeMap has no property graph, return result, otherwise set definitions to its value.
+        definitions = node_map.fetch(graph.to_s, {})
+        
+        # Foreach property and valud of definitions
+        definitions.keys.sort.each do |prop|
+          value = definitions[prop]
+          result << value
+        end
+        
+        result
+      end
+
+      callback.call(result) if callback
+      yield result if block_given?
+      result
+    end
+
     ##
     # Frames the given input using the frame according to the steps in the Framing Algorithm. The input is used to build the
     # framed output and is returned if there are no errors. If there are no matches for the frame, null must be returned.
@@ -219,13 +292,20 @@ module JSON::LD
         #debug(".frame") {"expanded frame: #{expanded_frame.to_json(JSON_STATE)}"}
         #debug(".frame") {"expanded input: #{value.to_json(JSON_STATE)}"}
 
-        # Get framing subjects from expanded input, replacing Blank Node identifiers as necessary
-        @subjects = Hash.ordered
-        depth {get_framing_subjects(@subjects, value, BlankNodeNamer.new("t"))}
-        debug(".frame") {"subjects: #{@subjects.to_json(JSON_STATE)}"}
+        # Get framing nodes from expanded input, replacing Blank Node identifiers as necessary
+        all_nodes = Hash.ordered
+        depth do
+          generate_node_map(value,
+            all_nodes,
+            '@merged',
+            nil,
+            BlankNodeNamer.new("t"))
+        end
+        @node_map = all_nodes['@merged']
+        debug(".frame") {"node_map: #{@node_map.to_json(JSON_STATE)}"}
 
         result = []
-        frame(framing_state, @subjects, expanded_frame[0], result, nil)
+        frame(framing_state, @node_map, expanded_frame[0], result, nil)
         debug(".frame") {"after frame: #{result.to_json(JSON_STATE)}"}
         
         # Initalize context from frame
@@ -288,8 +368,7 @@ module JSON::LD
     # @param [Proc] callback (&block)
     #   Alternative to using block, with same parameteres.
     # @param  [Hash{Symbol => Object}] options
-    # @option options [Boolean] :useRdfType (false) use rdf:type instead of @type
-    # @option options [Boolean] :useNativeDatatypes FIXME
+    # @option options [Boolean] :notType don't use @type for rdf:type
     # @yield jsonld
     # @yieldparam [Hash] jsonld
     #   The JSON-LD document in expanded form

data/lib/json/ld/compact.rb

@@ -44,7 +44,7 @@ module JSON::LD
         
         case k
         when '@value', '@id'
-          # If element has an @value property or element is a subject reference, return the result of performing
+          # If element has an @value property or element is a node reference, return the result of performing
           # Value Compaction on element using active property.
           v = context.compact_value(property, element, :depth => @depth)
           debug("compact") {"value optimization, return as #{v.inspect}"}

data/lib/json/ld/evaluation_context.rb

@@ -13,11 +13,6 @@ module JSON::LD
     # @attr_reader [RDF::URI]
     attr_reader :base
 
-    # The base IRI of the context, if loaded remotely.
-    #
-    # @attr [RDF::URI]
-    attr :context_base, true
-
     # A list of current, in-scope mappings from term to IRI.
     #
     # @attr [Hash{String => String}]
@@ -137,26 +132,18 @@ module JSON::LD
           raise JSON::LD::InvalidContext::Syntax, "Failed to parse remote context at #{context}: #{e.message}" if @options[:validate]
           self.dup
         end
-      when nil
-        debug("parse") {"nil"}
-        # Load context document, if it is a string
-        ec = EvaluationContext.new(options)
-      when String
+      when String, nil
         debug("parse") {"remote: #{context}"}
         # Load context document, if it is a string
         ec = nil
         begin
-          url = expand_iri(context, :base => context_base || base)
-          ecdup = self.dup
-          ecdup.context_base = url  # Set context_base for recursive remote contexts
-          RDF::Util::File.open_file(url) {|f| ec = ecdup.parse(f)}
+          RDF::Util::File.open_file(context.to_s) {|f| ec = parse(f)}
           ec.provided_context = context
-          ec.context_base = url
           debug("parse") {"=> provided_context: #{context.inspect}"}
           ec
         rescue Exception => e
-          debug("parse") {"Failed to retrieve @context from remote document at #{context.inspect}: #{e.message}"}
-          raise JSON::LD::InvalidContext::LoadError, "Failed to retrieve remote context at #{context.inspect}: #{e.message}", e.backtrace if @options[:validate]
+          debug("parse") {"Failed to retrieve @context from remote document at #{context}: #{e.message}"}
+          raise JSON::LD::InvalidContext::LoadError, "Failed to parse remote context at #{context}: #{e.message}", e.backtrace if @options[:validate]
           self.dup
         end
       when Array
@@ -480,8 +467,6 @@ module JSON::LD
     # @param  [Hash{Symbol => Object}] options
     # @option options [:subject, :predicate, :object, :datatype] position
     #   Useful when determining how to serialize.
-    # @option options [RDF::URI] base (self.base)
-    #   Base IRI to use when expanding relative IRIs.
     #
     # @return [RDF::URI, String] IRI or String, if it's a keyword
     # @raise [RDF::ReaderError] if the iri cannot be expanded
@@ -491,7 +476,7 @@ module JSON::LD
       prefix, suffix = iri.split(':', 2)
       return mapping(iri) if mapping(iri) # If it's an exact match
       debug("expand_iri") {"prefix: #{prefix.inspect}, suffix: #{suffix.inspect}, vocab: #{vocab.inspect}"} unless options[:quiet]
-      base = options.fetch(:base, self.base) unless [:predicate, :datatype].include?(options[:position])
+      base = [:subject, :object].include?(options[:position]) ? self.base : nil
       prefix = prefix.to_s
       case
       when prefix == '_' && suffix          then bnode(suffix)
@@ -669,13 +654,13 @@ module JSON::LD
     # @param [Hash, String] value
     #   Value (literal or IRI) to be expanded
     # @param  [Hash{Symbol => Object}] options
-    # @option options [Boolean] :useNativeTypes (true) use native representations
+    # @option options [Boolean] :native (true) use native representations
     #
     # @return [Hash] Object representation of value
     # @raise [RDF::ReaderError] if the iri cannot be expanded
     # @see http://json-ld.org/spec/latest/json-ld-api/#value-expansion
     def expand_value(property, value, options = {})
-      options = {:useNativeTypes => true}.merge(options)
+      options = {:native => true}.merge(options)
       depth(options) do
         debug("expand_value") {"property: #{property.inspect}, value: #{value.inspect}, coerce: #{coerce(property).inspect}"}
         value = RDF::Literal(value) if RDF::Literal(value).has_datatype?
@@ -696,7 +681,7 @@ module JSON::LD
           when RDF::XSD.double.to_s
             {"@value" => value.to_s, "@type" => RDF::XSD.double.to_s}
           else
-            if options[:useNativeTypes]
+            if options[:native]
               # Unless there's coercion, to not modify representation
               {"@value" => (value.is_a?(RDF::Literal::Boolean) ? value.object : value)}
             else
@@ -710,7 +695,7 @@ module JSON::LD
             {"@value" => RDF::Literal::Double.new(value, :canonicalize => true).to_s, "@type" => RDF::XSD.double.to_s}
           when RDF::XSD.integer.to_s, nil
             # Unless there's coercion, to not modify representation
-            if options[:useNativeTypes]
+            if options[:native]
               {"@value" => value.is_a?(RDF::Literal::Integer) ? value.object : value}
             else
               {"@value" => value.to_s, "@type" => RDF::XSD.integer.to_s}
@@ -729,7 +714,7 @@ module JSON::LD
           when RDF::XSD.double.to_s
             {"@value" => RDF::Literal::Double.new(value, :canonicalize => true).to_s, "@type" => RDF::XSD.double.to_s}
           when nil
-            if options[:useNativeTypes]
+            if options[:native]
               # Unless there's coercion, to not modify representation
               {"@value" => value.is_a?(RDF::Literal::Double) ? value.object : value}
             else
@@ -940,7 +925,7 @@ module JSON::LD
         else
           val_lang == language(term) ? 3 : (default_term ? 1 : 0)
         end
-      else # subject definition/reference
+      else # node definition/reference
         coerce(term) == '@id' ? 3 : (default_term ? 1 : 0)
       end
       

data/lib/json/ld/expand.rb

@@ -76,17 +76,17 @@ module JSON::LD
               when Array
                 depth do
                   [value].flatten.map do |v|
-                    v = v['@id'] if subject_reference?(v)
-                    raise ProcessingError, "Object value must be a string or a subject reference: #{v.inspect}" unless v.is_a?(String)
+                    v = v['@id'] if node_reference?(v)
+                    raise ProcessingError, "Object value must be a string or a node reference: #{v.inspect}" unless v.is_a?(String)
                     context.expand_iri(v, options.merge(:position => :property, :quiet => true)).to_s
                   end
                 end
               when Hash
-                # Empty object used for @type wildcard or subject reference
-                if subject_reference?(value)
+                # Empty object used for @type wildcard or node reference
+                if node_reference?(value)
                   context.expand_iri(value['@id'], options.merge(:position => :property, :quiet => true)).to_s
                 elsif !value.empty?
-                  raise ProcessingError, "Object value of @type must be empty or a subject reference: #{value.inspect}"
+                  raise ProcessingError, "Object value of @type must be empty or a node reference: #{value.inspect}"
                 else
                   value
                 end

data/lib/json/ld/flatten.rb

@@ -0,0 +1,109 @@
+module JSON::LD
+  module Flatten
+    include Utils
+
+    ##
+    # Build hash of nodes used for framing. Also returns flattened representation of input.
+    #
+    # @param [Array, Hash] element
+    #   Expanded element
+    # @param [Hash{String => Hash}] node_map
+    #   map of nodes
+    # @param [String] graph
+    #   Graph name for results
+    # @param [Array] list
+    #   List for saving list elements
+    # @param [BlankNodeNamer] namer
+    # @param [String] id
+    #   Identifier already associated with element
+    def generate_node_map(element, node_map, graph, list, namer, id = nil)
+      depth do
+        debug("nodeMap") {"element: #{element.inspect}, graph: #{graph}"}
+        if element.is_a?(Array)
+          element.map {|o| generate_node_map(o, node_map, graph, list, namer)}
+        elsif !element.is_a?(Hash) || value?(element)
+          list << element if list
+        else
+          # If the @id property exists and is an IRI, set id to its value, otherwise set it to a blank node identifier created by the Generate Blank Node Identifier algorithm.
+          # FIXME: (spec) id passed when it is allocated, so it is not re-allocated here.
+          id ||= blank_node?(element) ? namer.get_name(element.fetch('@id', nil)) : element['@id']
+          
+          # If list is not nil, append a new node reference to list using id at the value for @id.
+          list << {'@id' => id} if list
+
+          # Let nodes be the value in nodeMap where the key is graph; if no such value exists, insert a new JSON object for the key graph.
+          debug("nodeMap") {"new graph: #{graph}"} unless node_map.has_key?(graph)
+          nodes = (node_map[graph] ||= Hash.ordered)
+
+          # If id is not in nodes, create a new JSON object node with id as the value for @id. Let node be the value of id in nodes.
+          debug("nodeMap") {"new node: #{id}"} unless nodes.has_key?(id)
+          node = (nodes[id] ||= Hash.ordered)
+          node['@id'] ||= id
+
+          # For each property that is not @id and each value in element ordered by property:
+          element.each do |prop, value|
+            case prop
+            when '@id'
+              # Skip @id, already assigned
+            when '@graph'
+              # If property is @graph, recursively call this algorithm passing value for element, nodeMap, nil for list and if graph is @merged use graph, otherwise use id for graph and then continue.
+              graph = graph == '@merged' ? '@merged' : id
+              generate_node_map(value, node_map, graph, nil, namer)
+            when /^@(?!type)/
+              # If property is not @type and is a keyword, merge property and value into node and then continue.
+              debug("nodeMap") {"merge keyword#{prop}: #{value.inspect}"}
+              node[prop] = value
+            else
+              raise InvalidFrame::Syntax,
+                "unexpected value: #{value.inspect}, expected array" unless
+                value.is_a?(Array)
+              
+              # For each value v in the array value:
+              value.each do |v|
+                if node?(v) || node_reference?(v)
+                  debug("nodeMap") {"node value #{prop}: #{v.inspect}"}
+                  # If v is a node definition or node reference:
+                  # If the property @id is not an IRI or it does not exist, map v to a new blank node identifier to avoid collisions.
+                  name = blank_node?(v) ?
+                    namer.get_name(v.fetch('@id', nil)) :
+                    v['@id']
+
+                  # If one does not already exist, add a node reference for v into node for property.
+                  node[prop] ||= []
+                  node[prop] << {'@id' => name} unless node[prop].any? {|n|
+                    node_reference?(n) && n['@id'] == name
+                  }
+
+                  # Recursively call this algorithm passing v for value, nodeMap, graph, and nil for list.
+                  generate_node_map(v, node_map, graph, nil, namer, name)
+                elsif list?(v)
+                  # Otherwise if v has the property @list then recursively call this algorithm with the value of @list as element, nodeMap, graph, and a new array flattenedList as list.
+                  debug("nodeMap") {"list value #{prop}: #{v.inspect}"}
+                  flattened_list = []
+                  generate_node_map(v['@list'],
+                    node_map,
+                    graph,
+                    flattened_list,
+                    namer)
+                  # Create a new JSON object with the property @list set to flattenedList and add it to node for property.
+                  (node[prop] ||= []) << {'@list' => flattened_list}
+                elsif prop == '@type'
+                  # Otherwise, if property is @type and v is not an IRI, generate a new blank node identifier and add it to node for property.
+                  # FIXME: @type shouldn't really be a BNode, and not clear how we even get here from expansion
+                  name = blank_node?({'@id' => v}) ? namer.get_name(v) : v
+                  (node[prop] ||= []) << name
+                else
+                  debug("nodeMap") {"value #{prop}: #{v.inspect}"}
+                  # Otherwise, add v to node for property.
+                  (node[prop] ||= []) << v
+                end
+              end
+            end
+          end
+        end
+
+        debug("nodeMap") {node_map.to_json(JSON_STATE)}
+      end
+    end
+  end
+end

data/lib/json/ld/frame.rb

@@ -7,28 +7,27 @@ module JSON::LD
     #
     # @param [Hash{Symbol => Object}] state
     #   Current framing state
-    # @param [Hash{String => Hash}] subjects
-    #   Map of flattened subjects
+    # @param [Hash{String => Hash}] nodes
+    #   Map of flattened nodes
     # @param [Hash{String => Object}] frame
     # @param [Hash{String => Object}] parent
-    #   Parent subject or top-level array
+    #   Parent node or top-level array
     # @param [String] property
     #   Property referencing this frame, or null for array.
     # @raise [JSON::LD::InvalidFrame]
-    def frame(state, subjects, frame, parent, property)
-      raise ProcessingError, "why isn't @subjects a hash?: #{@subjects.inspect}" unless @subjects.is_a?(Hash)
+    def frame(state, nodes, frame, parent, property)
       depth do
         debug("frame") {"state: #{state.inspect}"}
-        debug("frame") {"subjects: #{subjects.keys.inspect}"}
+        debug("frame") {"nodes: #{nodes.keys.inspect}"}
         debug("frame") {"frame: #{frame.to_json(JSON_STATE)}"}
         debug("frame") {"parent: #{parent.to_json(JSON_STATE)}"}
         debug("frame") {"property: #{property.inspect}"}
         # Validate the frame
         validate_frame(state, frame)
 
-        # Create a set of matched subjects by filtering subjects by checking the map of flattened subjects against frame
+        # Create a set of matched nodes by filtering nodes by checking the map of flattened nodes against frame
         # This gives us a hash of objects indexed by @id
-        matches = filter_subjects(state, subjects, frame)
+        matches = filter_nodes(state, nodes, frame)
         debug("frame") {"matches: #{matches.keys.inspect}"}
 
         # Get values for embedOn and explicitOn
@@ -36,7 +35,7 @@ module JSON::LD
         explicit = get_frame_flag(state, frame, 'explicit');
         debug("frame") {"embed: #{embed.inspect}, explicit: #{explicit.inspect}"}
       
-        # For each id and subject from the set of matched subjects ordered by id
+        # For each id and node from the set of matched nodes ordered by id
         matches.keys.sort.each do |id|
           element = matches[id]
           # If the active property is null, set the map of embeds in state to an empty map
@@ -45,7 +44,7 @@ module JSON::LD
           output = {'@id' => id}
         
           # prepare embed meta info
-          embedded_subject = {:parent => parent, :property => property}
+          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))
@@ -58,7 +57,7 @@ module JSON::LD
               # 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 subject definition. Set embedOn to true if any of the items in parent property is a subject definition or subject reference for id because the embed can be overwritten
+              # 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
@@ -74,14 +73,14 @@ module JSON::LD
             add_frame_output(state, parent, property, output)
           else
             # Add embed to map of embeds for id
-            state[:embeds][id] = embedded_subject
-            debug("frame") {"add embedded_subject: #{embedded_subject.inspect}"}
+            state[:embeds][id] = embedded_node
+            debug("frame") {"add embedded_node: #{embedded_node.inspect}"}
         
-            # Process each property and value in the matched subject as follows
+            # Process each property and value in the matched node as follows
             element.keys.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 subject
+                # 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
@@ -89,7 +88,7 @@ module JSON::LD
               # If property is not in frame:
               unless frame.has_key?(prop)
                 debug("frame") {"non-framed property #{prop}"}
-                # If explicitOn is false, Embed values from subject in output using subject as element and property as active property
+                # 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
@@ -110,29 +109,29 @@ module JSON::LD
                   
                   # Process each listitem in the @list array as follows
                   item['@list'].each do |listitem|
-                    if subject_reference?(listitem)
+                    if node_reference?(listitem)
                       itemid = listitem['@id']
                       debug("frame") {"list item of #{prop} recurse for #{itemid.inspect}"}
 
-                      # If listitem is a subject reference process listitem recursively using this algorithm passing a new map of subjects that contains the @id of listitem as the key and the subject 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 => @subjects[itemid]}, frame[prop].first, list, '@list')
+                      # 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, list, '@list')
                     else
                       # Otherwise, append a copy of listitem to @list in list.
-                      debug("frame") {"list item of #{prop} non-subject ref #{listitem.inspect}"}
+                      debug("frame") {"list item of #{prop} non-node ref #{listitem.inspect}"}
                       add_frame_output(state, list, '@list', listitem)
                     end
                   end
-                elsif subject_reference?(item)
-                  # If item is a subject reference process item recursively
+                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 subjects that contains the @id of item as the key and the subject 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 => @subjects[itemid]}, frame[prop].first, output, prop)
+                  # 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, output, prop)
                 else
                   # Otherwise, append a copy of item to active property in output.
-                  debug("frame") {"value property #{prop} non-subject ref #{item.inspect}"}
+                  debug("frame") {"value property #{prop} non-node ref #{item.inspect}"}
                   add_frame_output(state, output, prop, item)
                 end
               end
@@ -164,89 +163,6 @@ module JSON::LD
       end
     end
 
-    ##
-    # Build hash of subjects used for framing. Also returns flattened representation
-    # of input.
-    #
-    # @param [Hash{String => Hash}] subjects
-    #   destination for mapped subjects and their Object representations
-    # @param [Array, Hash] input
-    #   JSON-LD in expanded form
-    # @param [BlankNodeNamer] namer
-    # @return
-    #   input with subject definitions changed to references
-    def get_framing_subjects(subjects, input, namer)
-      depth do
-        debug("framing subjects") {"input: #{input.inspect}"}
-        case input
-        when Array
-          input.map {|o| get_framing_subjects(subjects, o, namer)}
-        when Hash
-          case
-          when subject?(input) || subject_reference?(input)
-            # Get name for subject, mapping old blank node identifiers to new
-            name = blank_node?(input) ? namer.get_name(input.fetch('@id', nil)) : input['@id']
-            debug("framing subjects") {"new subject: #{name.inspect}"} unless subjects.has_key?(name)
-            subject = subjects[name] ||= {'@id' => name}
-
-            # In property order
-            input.keys.sort.each do |prop|
-              value = input[prop]
-              case prop
-              when '@id'
-                # Skip @id, already assigned
-              when /^@/
-                # Copy other keywords
-                subject[prop] = value
-              else
-                case value
-                when Hash
-                  # Special case @list, which is not in expanded form
-                  raise InvalidFrame::Syntax, "Unexpected hash value: #{value.inspect}" unless value.has_key?('@list')
-                
-                  # Map entries replacing subjects with subject references
-                  subject[prop] = {"@list" =>
-                    value['@list'].map {|o| get_framing_subjects(subjects, o, namer)}
-                  }
-                when Array
-                  # Map array entries
-                  subject[prop] = get_framing_subjects(subjects, value, namer)
-                else
-                  raise InvalidFrame::Syntax, "unexpected value: #{value.inspect}"
-                end
-              end
-            end
-            
-            # Return as subject reference
-            {"@id" => name}
-          else
-            # At this point, it's not a subject or a reference, just return input
-            input
-          end
-        else
-          # Returns equivalent representation
-          input
-        end
-      end
-    end
-
-    ##
-    # Flatten input, used in framing.
-    #
-    # This algorithm works by transforming input to statements, and then back to JSON-LD
-    #
-    # @return [Array{Hash}]
-    def flatten
-      debug("flatten")
-      expanded = depth {self.expand(self.value, nil, context)}
-      statements = []
-      depth {self.statements("", expanded, nil, nil, nil ) {|s| statements << s}}
-      debug("flatten") {"statements: #{statements.map(&:to_nquads).join("\n")}"}
-
-      # Transform back to JSON-LD, not flattened
-      depth {self.from_statements(statements)}
-    end
-
     ##
     # Replace @preserve keys with the values, also replace @null with null
     #
@@ -289,50 +205,51 @@ module JSON::LD
     private
     
     ##
-    # Returns a map of all of the subjects that match a parsed frame.
+    # Returns a map of all of the nodes that match a parsed frame.
     # 
     # @param state the current framing state.
-    # @param subjects the set of subjects to filter.
+    # @param nodes the set of nodes to filter.
     # @param frame the parsed frame.
     # 
-    # @return all of the matched subjects.
-    def filter_subjects(state, subjects, frame)
-      subjects.dup.keep_if {|id, element| filter_subject(state, element, 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)}
     end
 
     ##
-    # Returns true if the given subject matches the given frame.
+    # Returns true if the given node matches the given frame.
     #
-    # Matches either based on explicit type inclusion where the subject
+    # Matches either based on explicit type inclusion where the node
     # has any type listed in the frame. If the frame has empty types defined
-    # matches subjects not having a @type. If the frame has a type of {} defined
-    # matches subjects having any type defined.
+    # matches nodes not having a @type. If the frame has a type of {} defined
+    # matches nodes having any type defined.
     #
-    # Otherwise, does duck typing, where the subject must have all of the properties
+    # 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}] subject the subject to check.
+    # @param [Hash{String => Object}] node the node to check.
     # @param [Hash{String => Object}] frame the frame to check.
     # 
-    # @return true if the subject matches, false if not.
-    def filter_subject(state, subject, frame)
+    # @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)
-        subject_types = subject.fetch('@type', [])
+        node_types = node.fetch('@type', [])
         raise InvalidFrame::Syntax, "frame @type must be an array: #{types.inspect}" unless types.is_a?(Array)
-        raise InvalidFrame::Syntax, "subject @type must be an array: #{subject_types.inspect}" unless subject_types.is_a?(Array)
-        # If frame has an @type, use it for selecting appropriate subjects.
-        debug("frame") {"filter subject: #{subject_types.inspect} has any of #{types.inspect}"}
+        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}"}
 
         # Check for type wild-card, or intersection
-        types == [{}] ? !subject_types.empty? : subject_types.any? {|t| types.include?(t)}
+        types == [{}] ? !node_types.empty? : node_types.any? {|t| types.include?(t)}
       else
-        # Duck typing, for subjects not having a type, but having @id
+        # 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] == '@'}
-        subject_keys = subject.keys.reject {|k| k[0,1] == '@'}
-        (frame_keys & subject_keys) == frame_keys
+        node_keys = node.keys.reject {|k| k[0,1] == '@'}
+        (frame_keys & node_keys) == frame_keys
       end
     end
 
@@ -361,13 +278,13 @@ module JSON::LD
       property = embed[:property];
 
       # create reference to replace embed
-      subject = {}
-      subject['@id'] = id
+      node = {}
+      node['@id'] = id
       ref = {'@id' => id}
       
       # remove existing embed
-      if subject?(parent)
-        # replace subject with reference
+      if node?(parent)
+        # replace node with reference
         parent[property].map! do |v|
           v.is_a?(Hash) && v.fetch('@id', nil) == id ? ref : v
         end
@@ -418,7 +335,7 @@ module JSON::LD
     def embed_values(state, element, property, output)
       element[property].each do |o|
         # Get element @id, if this is an object
-        sid = o['@id'] if subject_reference?(o)
+        sid = o['@id'] if node_reference?(o)
         if sid
           unless state[:embeds].has_key?(sid)
             debug("frame") {"embed element #{sid.inspect}"}
@@ -427,7 +344,7 @@ module JSON::LD
             state[:embeds][sid] = embed
           
             # Recurse into element
-            s = @subjects.fetch(sid, {'@id' => sid})
+            s = @node_map.fetch(sid, {'@id' => sid})
             o = {}
             s.each do |prop, value|
               if prop[0,1] == '@'