json-ld 0.1.6.1 → 0.3.0

data/History.markdown

@@ -1,5 +1,8 @@
-=== 0.1.6.1
-* Merge relative contexts from 0.1.5.2.
+=== 0.3.0
+* Fix regression on opening self-relative contexts.
+* When generating RDF, allow @type to be a BNode. This fixes issue #2
+* Add {JSON::LD::Resource} class for simple ruby-like management of JSON-LD nodes.
+* Term Rank and IRI compaction updates.
 
 === 0.1.6
 * Added flattening API, and updated algorithm.

data/README.markdown

@@ -1,6 +1,7 @@
 # JSON-LD reader/writer
 
-[JSON-LD][] reader/writer for [RDF.rb][RDF.rb] .
+[![Build Status](https://secure.travis-ci.org/gkellogg/json-ld.png?branch=master)](http://travis-ci.org/gkellogg/json-ld)
+[JSON-LD][] reader/writer for [RDF.rb][RDF.rb] and fully conforming [JSON-LD][] processor.
 
 ## Features
 

data/VERSION

@@ -1 +1 @@
-0.1.6.1
+0.3.0

data/lib/json/ld.rb

@@ -29,6 +29,7 @@ module JSON
     autoload :EvaluationContext,  'json/ld/evaluation_context'
     autoload :Normalize,          'json/ld/normalize'
     autoload :Reader,             'json/ld/reader'
+    autoload :Resource,           'json/ld/resource'
     autoload :VERSION,            'json/ld/version'
     autoload :Writer,             'json/ld/writer'
     

data/lib/json/ld/api.rb

@@ -33,11 +33,25 @@ module JSON::LD
     # @param [String, #read, Hash, Array] input
     # @param [String, #read,, Hash, Array] context
     #   An external context to use additionally to the context embedded in input when expanding the input.
-    # @param [Hash] options
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [Boolean] :base
+    #   The Base IRI to use when expanding the document. This overrides the value of `input` if it is a _IRI_. If not specified and `input` is not an _IRI_, the base IRI defaults to the current document IRI if in a browser context, or the empty string if there is no document context.
+    # @option options [Boolean] :compactArrays (true)
+    #   If set to `true`, the JSON-LD processor replaces arrays with just one element with that element during compaction. If set to `false`, all arrays will remain arrays even if they have just one element.
+    # @option options [Proc] :conformanceCallback
+    #   The purpose of this option is to instruct the processor about whether or not it should continue processing. If the value is null, the processor should ignore any key-value pair associated with any recoverable conformance issue and continue processing. More details about this feature can be found in the ConformanceCallback section.
+    # @option options [Boolean, String, RDF::URI] :flatten
+    #   If set to a value that is not `false`, the JSON-LD processor must modify the output of the Compaction Algorithm or the Expansion Algorithm by coalescing all properties associated with each subject via the Flattening Algorithm. The value of `flatten must` be either an _IRI_ value representing the name of the graph to flatten, or `true`. If the value is `true`, then the first graph encountered in the input document is selected and flattened.
+    # @option options [Boolean] :optimize (false)
+    #   If set to `true`, the JSON-LD processor is allowed to optimize the output of the Compaction Algorithm to produce even compacter representations. The algorithm for compaction optimization is beyond the scope of this specification and thus not defined. Consequently, different implementations *MAY* implement different optimization algorithms.
+    #   (Presently, this is a noop).
+    # @option options [Boolean] :useNativeDatatypes (true)
+    # If set to `true`, the JSON-LD processor will use the expanded `rdf:type` IRI as the property instead of `@type` when converting from RDF.
+    # @option options [Boolean] :useRdfType (false) If set to `true`, the JSON-LD processor will try to convert datatyped literals to JSON native types instead of using the expanded object form when converting from RDF. `xsd:boolean` values will be converted to `true` or `false`. `xsd:integer` and `xsd:double` values will be converted to JSON numbers.
     # @yield [api]
     # @yieldparam [API]
     def initialize(input, context, options = {}, &block)
-      @options = options
+      @options = {:compactArrays => true}.merge(options)
       @value = case input
       when Array, Hash then input.dup
       when IO, StringIO then JSON.parse(input.read)
@@ -72,8 +86,7 @@ module JSON::LD
     # @param [Proc] callback (&block)
     #   Alternative to using block, with same parameters.
     # @param  [Hash{Symbol => Object}] options
-    # @option options [Boolean] :base
-    #   Base IRI to use when processing relative IRIs.
+    #   See options in {#initialize}
     # @raise [InvalidContext]
     # @yield jsonld
     # @yieldparam [Array<Hash>] jsonld
@@ -115,10 +128,8 @@ module JSON::LD
     # @param [Proc] callback (&block)
     #   Alternative to using block, with same parameters.
     # @param  [Hash{Symbol => Object}] options
+    #   See options in {#initialize}
     #   Other options passed to {#expand}
-    # @option options [Boolean] :optimize (false)
-    #   Perform further optimmization of the compacted output.
-    #   (Presently, this is a noop).
     # @yield jsonld
     # @yieldparam [Hash] jsonld
     #   The compacted JSON-LD document
@@ -169,16 +180,8 @@ module JSON::LD
     # @param [Proc] callback (&block)
     #   Alternative to using block, with same parameters.
     # @param  [Hash{Symbol => Object}] options
+    #   See options in {#initialize}
     #   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
@@ -240,6 +243,7 @@ module JSON::LD
     # @param [Proc] callback (&block)
     #   Alternative to using block, with same parameters.
     # @param  [Hash{Symbol => Object}] options
+    #   See options in {#initialize}
     #   Other options passed to {#expand}
     # @option options [Boolean] :embed (true)
     #   a flag specifying that objects should be directly embedded in the output,
@@ -338,6 +342,7 @@ module JSON::LD
     # @param [Proc] callback (&block)
     #   Alternative to using block, with same parameteres.
     # @param [{Symbol,String => Object}] options
+    #   See options in {#initialize}
     #   Options passed to {#expand}
     # @raise [InvalidContext]
     # @yield statement
@@ -368,14 +373,14 @@ 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
+    #   See options in {#initialize}
     # @yield jsonld
     # @yieldparam [Hash] jsonld
     #   The JSON-LD document in expanded form
     # @return [Array<Hash>]
     #   The JSON-LD document in expanded form
     def self.fromRDF(input, callback = nil, options = {})
+      options = {:useNativeTypes => true}.merge(options)
       result = nil
 
       API.new(nil, nil, options) do |api|

data/lib/json/ld/compact.rb

@@ -25,7 +25,7 @@ module JSON::LD
         # If element has a single member and the active property has no
         # @container mapping to @list or @set, the compacted value is that
         # member; otherwise the compacted value is element
-        if result.length == 1
+        if result.length == 1 && @options[:compactArrays]
           debug("=> extract single element: #{result.first.inspect}")
           result.first
         else
@@ -44,13 +44,17 @@ module JSON::LD
         
         case k
         when '@value', '@id'
-          # If element has an @value property or element is a node reference, return the result of performing
-          # Value Compaction on element using active property.
+          # 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}"}
           return v
         when '@list'
-          # Otherwise, if the active property has a @container mapping to @list and element has a corresponding @list property, recursively compact that property's value passing a copy of the active context and the active property ensuring that the result is an array and removing null values.
+          # Otherwise, if the active property has a @container mapping to @list and element has a corresponding @list property, recursively compact that property's value passing a copy of the active context and the active property ensuring that the result is an array with all null values removed.
+          
+          # If there already exists a value for active property in element and the full IRI of property is also coerced to @list, return an error.
+          # FIXME: check for full-iri list coercion
+
+          # Otherwise store the resulting array as value of active property if empty or property otherwise.
           compacted_key = context.compact_iri(k, :position => :predicate, :depth => @depth)
           v = depth { compact(element[k], property) }
           
@@ -66,18 +70,19 @@ module JSON::LD
           debug("compact") {"#{key}: #{value.inspect}"}
 
           if %(@id @type).include?(key)
+            position = key == '@id' ? :subject : :type
             compacted_key = context.compact_iri(key, :position => :predicate, :depth => @depth)
 
             result[compacted_key] = case value
             when String
               # If value is a string, the compacted value is the result of performing IRI Compaction on value.
               debug {" => compacted string for #{key}"}
-              context.compact_iri(value, :position => :subject, :depth => @depth)
+              context.compact_iri(value, :position => position, :depth => @depth)
             when Array
               # Otherwise, value must be an array. Perform IRI Compaction on every entry of value. If value contains just one entry, value is set to that entry
-              compacted_value = value.map {|v| context.compact_iri(v, :position => :subject, :depth => @depth)}
+              compacted_value = value.map {|v| context.compact_iri(v, :position => position, :depth => @depth)}
               debug {" => compacted value(#{key}): #{compacted_value.inspect}"}
-              compacted_value = compacted_value.first if compacted_value.length == 1
+              compacted_value = compacted_value.first if compacted_value.length == 1 && @options[:compactArrays]
               compacted_value
             end
           else

data/lib/json/ld/evaluation_context.rb

@@ -183,7 +183,7 @@ module JSON::LD
             new_ec.send(setter, v)
           elsif v
             raise InvalidContext::Syntax, "#{key.inspect} is invalid"
-            end
+          end
         end
 
         num_updates = 1
@@ -313,7 +313,7 @@ module JSON::LD
               debug {"=> coerce(#{k}) => #{coerce(k)}"}
               if coerce(k) && !NATIVE_DATATYPES.include?(coerce(k))
                 dt = coerce(k)
-                dt = compact_iri(dt, :position => :datatype) unless dt == '@id'
+                dt = compact_iri(dt, :position => :type) unless dt == '@id'
                 # Fold into existing definition
                 ctx[k]["@type"] = dt
                 debug {"=> datatype[#{k}] => #{dt}"}
@@ -478,7 +478,7 @@ module JSON::LD
     # @param [String] iri
     #   A keyword, term, prefix:suffix or possibly relative IRI
     # @param  [Hash{Symbol => Object}] options
-    # @option options [:subject, :predicate, :object, :datatype] position
+    # @option options [:subject, :predicate, :type] position
     #   Useful when determining how to serialize.
     # @option options [RDF::URI] base (self.base)
     #   Base IRI to use when expanding relative IRIs.
@@ -491,7 +491,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 = [:subject, :object].include?(options[:position]) ? options.fetch(:base, self.base) : nil
+      base = [:subject].include?(options[:position]) ? options.fetch(:base, self.base) : nil
       prefix = prefix.to_s
       case
       when prefix == '_' && suffix          then bnode(suffix)
@@ -503,7 +503,7 @@ module JSON::LD
       else
         # Otherwise, it must be an absolute IRI
         u = uri(iri)
-        u if u.absolute? || [:subject, :object].include?(options[:position])
+        u if u.absolute? || [:subject].include?(options[:position])
       end
     end
 
@@ -512,7 +512,7 @@ module JSON::LD
     #
     # @param [RDF::URI] iri
     # @param  [Hash{Symbol => Object}] options ({})
-    # @option options [:subject, :predicate, :object, :datatype] position
+    # @option options [:subject, :predicate, :type] position
     #   Useful when determining how to serialize.
     # @option options [Object] :value
     #   Value, used to select among various maps for the same IRI
@@ -528,55 +528,54 @@ module JSON::LD
         value = options.fetch(:value, nil)
 
         # Get a list of terms which map to iri
-        terms = mappings.keys.select {|t| mapping(t).to_s == iri}
+        matched_terms = mappings.keys.select {|t| mapping(t).to_s == iri}
+        debug("compact_iri", "initial terms: #{matched_terms.inspect}")
 
-        # Create an association term map for terms to their associated
-        # term rank.
-        term_map = {}
+        # Create an empty list of terms _terms_ that will be populated with terms that are ranked according to how closely they match value. Initialize highest rank to 0, and set a flag list container to false.
+        terms = {}
 
         # If value is a @list add a term rank for each
         # term mapping to iri which has @container @list.
         debug("compact_iri", "#{value.inspect} is a list? #{list?(value).inspect}")
         if list?(value)
-          list_terms = terms.select {|t| container(t) == '@list'}
+          list_terms = matched_terms.select {|t| container(t) == '@list'}
             
-          term_map = list_terms.inject({}) do |memo, t|
+          terms = list_terms.inject({}) do |memo, t|
             memo[t] = term_rank(t, value)
             memo
           end unless list_terms.empty?
-          debug("term map") {"remove zero rank terms: #{term_map.keys.select {|t| term_map[t] == 0}}"} if term_map.any? {|t,r| r == 0}
-          term_map.delete_if {|t, r| r == 0}
+          debug("term map") {"remove zero rank terms: #{terms.keys.select {|t| terms[t] == 0}}"} if terms.any? {|t,r| r == 0}
+          terms.delete_if {|t, r| r == 0}
         end
         
         # Otherwise, value is @value or a native type.
         # Add a term rank for each term mapping to iri
         # which does not have @container @list
-        if term_map.empty?
-          non_list_terms = terms.reject {|t| container(t) == '@list'}
+        if terms.empty?
+          non_list_terms = matched_terms.reject {|t| container(t) == '@list'}
 
           # If value is a @list, exclude from term map those terms
           # with @container @set
           non_list_terms.reject {|t| container(t) == '@set'} if list?(value)
 
-          term_map = non_list_terms.inject({}) do |memo, t|
+          terms = non_list_terms.inject({}) do |memo, t|
             memo[t] = term_rank(t, value)
             memo
           end unless non_list_terms.empty?
-          debug("term map") {"remove zero rank terms: #{term_map.keys.select {|t| term_map[t] == 0}}"} if term_map.any? {|t,r| r == 0}
-          term_map.delete_if {|t, r| r == 0}
+          debug("term map") {"remove zero rank terms: #{terms.keys.select {|t| terms[t] == 0}}"} if terms.any? {|t,r| r == 0}
+          terms.delete_if {|t, r| r == 0}
         end
 
         # If we don't want terms, remove anything that's not a CURIE or IRI
-        term_map.keep_if {|t, v| t.index(':') } if options.fetch(:not_term, false)
+        terms.keep_if {|t, v| t.index(':') } if options.fetch(:not_term, false)
 
         # Find terms having the greatest term match value
-        least_distance = term_map.values.max
-        terms = term_map.keys.select {|t| term_map[t] == least_distance}
+        least_distance = terms.values.max
+        terms = terms.keys.select {|t| terms[t] == least_distance}
 
-        # If terms is empty, and the active context has a @vocab which is a 
-        # prefix of iri where the resulting relative IRI is not a term in the 
-        # active context. The resulting relative IRI is the unmatched part of iri.
-        if vocab && terms.empty? && iri.to_s.index(vocab) == 0
+        # If terms is empty, and the active context has a @vocab which is a  prefix of iri where the resulting relative IRI is not a term in the  active context. The resulting relative IRI is the unmatched part of iri.
+        if vocab && terms.empty? && iri.to_s.index(vocab) == 0 &&
+           [:predicate, :type].include?(options[:position])
           terms << iri.to_s.sub(vocab, '')
           debug("vocab") {"vocab: #{vocab}, rel: #{terms.first}"}
         end
@@ -608,7 +607,7 @@ module JSON::LD
           end
 
           terms = curies.select do |curie|
-            container(curie) != '@list' &&
+            (options[:position] != :predicate || container(curie) != '@list') &&
             coerce(curie).nil? &&
             language(curie) == default_language
           end
@@ -755,7 +754,7 @@ module JSON::LD
           debug("else")
           case coerce(property)
           when '@id'
-            {'@id' => expand_iri(value, :position => :object).to_s}
+            {'@id' => expand_iri(value, :position => :subject).to_s}
           when nil
             debug("expand value") {"lang(prop): #{language(property).inspect}, def: #{default_language.inspect}"}
             language(property) ? {"@value" => value.to_s, "@language" => language(property)} : {"@value" => value.to_s}
@@ -792,22 +791,22 @@ module JSON::LD
         debug("compact_value") {"property: #{property.inspect}, value: #{value.inspect}, coerce: #{coerce(property).inspect}"}
 
         result = case
-          #when %w(boolean integer double).any? {|t| expand_iri(value['@type'], :position => :datatype) == RDF::XSD[t]}
+          #when %w(boolean integer double).any? {|t| expand_iri(value['@type'], :position => :type) == RDF::XSD[t]}
         #  # Compact native type
         #  debug {" (native)"}
-        #  l = RDF::Literal(value['@value'], :datatype => expand_iri(value['@type'], :position => :datatype))
+        #  l = RDF::Literal(value['@value'], :datatype => expand_iri(value['@type'], :position => :type))
         #  l.canonicalize.object
         when coerce(property) == '@id' && value.has_key?('@id')
           # Compact an @id coercion
           debug {" (@id & coerce)"}
-          compact_iri(value['@id'], :position => :object)
-        when value['@type'] && expand_iri(value['@type'], :position => :datatype) == coerce(property)
+          compact_iri(value['@id'], :position => :subject)
+        when value['@type'] && expand_iri(value['@type'], :position => :type) == coerce(property)
           # Compact common datatype
           debug {" (@type & coerce) == #{coerce(property)}"}
           value['@value']
         when value.has_key?('@id')
           # Compact an IRI
-          value[self.alias('@id')] = compact_iri(value['@id'], :position => :object)
+          value[self.alias('@id')] = compact_iri(value['@id'], :position => :subject)
           debug {" (#{self.alias('@id')} => #{value['@id']})"}
           value
         when value['@language'] && value['@language'] == language(property)
@@ -829,7 +828,7 @@ module JSON::LD
         when value['@type']
           # Compact datatype
           debug {" (@type)"}
-          value[self.alias('@type')] = compact_iri(value['@type'], :position => :datatype)
+          value[self.alias('@type')] = compact_iri(value['@type'], :position => :type)
           value
         else
           # Otherwise, use original value
@@ -928,7 +927,7 @@ module JSON::LD
         end
       elsif value?(value)
         val_type = value.fetch('@type', nil)
-        val_lang = value.fetch('@language', nil)
+        val_lang = value['@language'] || false if value.has_key?('@language')
         debug("term rank") {"@val_type: #{val_type.inspect}, val_lang: #{val_lang.inspect}"}
         if val_type
           coerce(term) == val_type ? 3 :  (default_term ? 1 : 0)
@@ -936,9 +935,15 @@ module JSON::LD
           default_term ? 2 : 1
         elsif val_lang.nil?
           debug("val_lang.nil") {"#{language(term).inspect} && #{coerce(term).inspect}"}
-          !language(term) && !coerce(term) ? 3 : 0
+          language(term) == false || (default_term && default_language.nil?) ? 3 : 0
         else
-          val_lang == language(term) ? 3 : (default_term ? 1 : 0)
+          if val_lang == language(term) || (default_term && default_language == val_lang)
+            3
+          elsif default_term
+            1
+          else
+            0
+          end
         end
       else # node definition/reference
         coerce(term) == '@id' ? 3 : (default_term ? 1 : 0)

data/lib/json/ld/expand.rb

@@ -181,7 +181,7 @@ module JSON::LD
         end
       else
         # Otherwise, unless the value is a number, expand the value according to the Value Expansion rules, passing active property.
-        context.expand_value(active_property, input, :position => :object, :depth => @depth) unless input.nil?
+        context.expand_value(active_property, input, :position => :subject, :depth => @depth) unless input.nil?
       end
 
       debug {" => #{result.inspect}"}

data/lib/json/ld/from_rdf.rb

@@ -71,6 +71,7 @@ module JSON::LD
           # append the string representation of object to the array value for the key @type, creating
           # an entry if necessary
           (value['@type'] ||= []) << object
+        # FIXME: 3.7) If object is a typed literal and the useNativeTypes option is set to true:
         elsif statement.object == RDF.nil
           # Otherwise, if object is http://www.w3.org/1999/02/22-rdf-syntax-ns#nil, let
           # key be the string representation of predicate. Set the value
@@ -139,7 +140,7 @@ module JSON::LD
       end
 
       # Return array as the graph representation.
-      debug("fromRdf") {array.to_json(JSON_STATE)}
+      debug("fromRDF") {array.to_json(JSON_STATE)}
       array
     end
   end

data/lib/json/ld/resource.rb

@@ -0,0 +1,243 @@
+module JSON::LD
+  # Simple Ruby reflector class to provide native
+  # access to JSON-LD objects
+  class Resource
+    # Object representation of resource
+    #
+    # @attr_reader [Hash<String => Object] attributes
+    attr_reader :attributes
+
+    # ID of this resource
+    #
+    # @attr_reader [String] id
+    attr_reader :id
+
+    # Context associated with this resource
+    #
+    # @attr_reader [JSON::LD::EvaluationContext] context
+    attr_reader :context
+
+    # Is this resource clean (i.e., saved to mongo?)
+    #
+    # @return [Boolean]
+    def clean?; @clean; end
+
+    # Is this resource dirty (i.e., not yet saved to mongo?)
+    #
+    # @return [Boolean]
+    def dirty?; !clean?; end
+    
+    # Has this resource been reconciled against a mongo ID?
+    #
+    # @return [Boolean]
+    def reconciled?; @reconciled; end
+
+    # Has this resource been resolved so that
+    # all references are to other Resources?
+    #
+    # @return [Boolean]
+    def resolved?; @resolved; end
+
+    # Anonymous resources have BNode ids or no schema:url
+    #
+    # @return [Boolean]
+    def anonymous?; @anon; end
+
+    # Is this a stub resource, which has not yet been
+    # synched or created within the DB?
+    def stub?; !!@stub; end
+
+    # Is this a new resource, which has not yet been
+    # synched or created within the DB?
+    def new?; !!@new; end
+
+    # Manage contexts used by resources.
+    #
+    # @param [String] ctx
+    # @return [JSON::LD::EvaluationContext]
+    def self.set_context(ctx)
+      (@@contexts ||= {})[ctx] = JSON::LD::EvaluationContext.new.parse(ctx)
+    end
+
+    # A new resource from the parsed graph
+    # @param [Hash{String => Object}] node_definition
+    # @param [Hash{Symbol => Object}] options
+    # @option options [String] :context
+    #   Resource context, used for finding
+    #   appropriate collection and JSON-LD context.
+    # @option options [Boolean] :clean (false)
+    # @option options [Boolean] :compact (false)
+    #   Assume `node_definition` is in expanded form
+    #   and compact using `context`.
+    # @option options [Boolean] :reconciled (!new)
+    #   node_definition is not based on Mongo IDs
+    #   and must be reconciled against Mongo, or merged
+    #   into another resource.
+    # @option options [Boolean] :new (true)
+    #   This is a new resource, not yet saved to Mongo
+    # @option options [Boolean] :stub (false)
+    #   This is a stand-in for another resource that has
+    #   not yet been retrieved (or created) from Mongo
+    def initialize(node_definition, options = {})
+      @context_name = options[:context]
+      @context = self.class.set_context(@context_name)
+      @clean = options.fetch(:clean, false)
+      @new = options.fetch(:new, true)
+      @reconciled = options.fetch(:reconciled, !@new)
+      @resolved = false
+      @attributes = if options[:compact]
+        JSON::LD::API.compact(node_definition, @context)
+      else
+        node_definition
+      end
+      @id = @attributes['@id']
+      @anon = @id.nil? || @id.to_s[0,2] == '_:'
+    end
+
+    # Return a hash of this object, suitable for use by for ETag
+    # @return [Fixnum]
+    def hash
+      self.deresolve.hash
+    end
+
+    # Reverse resolution of resource attributes.
+    # Just returns `attributes` if
+    # resource is unresolved. Otherwise, replaces `Resource`
+    # values with node references.
+    #
+    # Result is expanded and re-compacted to get to normalized
+    # representation.
+    #
+    # @return [Hash] deresolved attribute hash
+    def deresolve
+      node_definition = if resolved?
+        deresolved = attributes.keys.inject({}) do |memo, prop|
+          value = attributes[prop]
+          memo[prop] = case value
+          when Resource
+            {'id' => value.id}
+          when Array
+            value.map do |v|
+              v.is_a?(Resource) ? {'id' => v.id} : v
+            end
+          else
+            value
+          end
+          memo
+        end
+        deresolved
+      else
+        attributes
+      end
+
+      compacted = nil
+      JSON::LD::API.expand(node_definition, @context) do |expanded|
+        compacted = JSON::LD::API.compact(expanded, @context)
+      end
+      compacted.delete_if {|k, v| k == '@context'}
+    end
+
+    # Serialize to JSON-LD, minus `@context` using
+    # a deresolved version of the attributes
+    #
+    # @param [Hash] options
+    # @return [String] serizlied JSON representation of resource
+    def to_json(options = nil)
+      deresolve.to_json(options)
+    end
+
+    # Update node references using the provided map.
+    # This replaces node references with Resources,
+    # either stub or instantiated.
+    #
+    # Node references with ids not in the reference_map
+    # will cause stub resources to be added to the map.
+    #
+    # @param [Hash{String => Resource}] reference_map
+    # @return [Resource] self
+    def resolve(reference_map)
+      return if resolved?
+      def update_obj(obj, reference_map)
+        case obj
+        when Array
+          obj.map {|o| update_obj(o, reference_map)}
+        when Hash
+          if obj.node_ref?
+            reference_map[obj['id']] ||= Resource.new(obj,
+              :context => @context_name,
+              :clean => false,
+              :stub => true
+              )
+          else
+            obj.keys.each do |k|
+              obj[k] = update_obj(obj[k], reference_map)
+            end
+            obj
+          end
+        else
+          obj
+        end
+      end
+
+      #$logger.debug "resolve(0): #{attributes.inspect}"
+      @attributes.each do |k, v|
+        next if %w(id type).include?(k)
+        @attributes[k] = update_obj(@attributes[k], reference_map)
+      end
+      #$logger.debug "resolve(1): #{attributes.inspect}"
+      @resolved = true
+      self
+    end
+
+    # Merge resources
+    # FIXME: If unreconciled or unresolved resources are merged
+    # against reconciled/resolved resources, they will appear
+    # to not match, even if they are really the same thing.
+    #
+    # @param [Resource] resource
+    # @return [Resource] self
+    def merge(resource)
+      if attributes.neq?(resource.attributes)
+        resource.attributes.each do |p, v|
+          next if p == 'id'
+          if v.nil? or (v.is_a?(Array) and v.empty?)
+            attributes.delete(p)
+          else
+            attributes[p] = v
+          end
+        end
+        @resolved = @clean = false
+      end
+      self
+    end
+
+    #
+    # Override this method to implement save using
+    # an appropriate storage mechanism.
+    #
+    # Save the object to the Mongo collection
+    # use Upsert to create things that don't exist.
+    # First makes sure that the resource is valid.
+    #
+    # @return [Boolean] true or false if resource not saved
+    def save
+      raise NotImplemented
+    end
+
+    # Access individual fields, from subject definition
+    def property(prop_name); @attributes.fetch(prop_name, nil); end
+
+    # Access individual fields, from subject definition
+    def method_missing(method, *args)
+      property(method.to_s)
+    end
+
+    def inspect
+      "<Resource" +
+      attributes.map do |k, v|
+        "\n  #{k}: #{v.inspect}"
+      end.join(" ") +
+      ">"
+    end
+  end
+end