jsi 0.1.0 → 0.2.0

data/lib/jsi/json-schema-fragments.rb

@@ -43,7 +43,7 @@ module JSON
     def schema_from_fragment(base_schema, fragment)
       schema_uri = base_schema.uri
 
-      pointer = JSI::JSON::Pointer.new(:fragment, fragment)
+      pointer = JSI::JSON::Pointer.from_fragment(fragment)
 
       base_schema = JSON::Schema.new(pointer.evaluate(base_schema.schema), schema_uri, @options[:version])
 

data/lib/jsi/json/node.rb

@@ -22,52 +22,56 @@ module JSI
     # return a copy of the document with the content of the node modified.
     # the original node's document and content are untouched.
     class Node
+      include PathedNode
+
       def self.new_doc(document)
-        new_by_type(document, [])
+        new_by_type(document, JSI::JSON::Pointer.new([]))
       end
 
-      # if the content of the document at the given path is Hash-like, returns
+      # if the content of the document at the given pointer is Hash-like, returns
       # a HashNode; if Array-like, returns ArrayNode. otherwise returns a
       # regular Node, although Nodes are for the most part instantiated from
       # Hash or Array-like content.
-      def self.new_by_type(document, path)
-        node = Node.new(document, path)
-        content = node.content
+      def self.new_by_type(document, pointer)
+        content = pointer.evaluate(document)
         if content.respond_to?(:to_hash)
-          HashNode.new(document, path)
+          HashNode.new(document, pointer)
         elsif content.respond_to?(:to_ary)
-          ArrayNode.new(document, path)
+          ArrayNode.new(document, pointer)
         else
-          node
+          Node.new(document, pointer)
         end
       end
 
-      # a Node represents the content of a document at a given path.
-      def initialize(document, path)
-        unless path.respond_to?(:to_ary)
-          raise(ArgumentError, "path must be an array. got: #{path.pretty_inspect.chomp} (#{path.class})")
+      # a Node represents the content of a document at a given pointer.
+      def initialize(document, pointer)
+        unless pointer.is_a?(JSI::JSON::Pointer)
+          raise(TypeError, "pointer must be a JSI::JSON::Pointer. got: #{pointer.pretty_inspect.chomp} (#{pointer.class})")
         end
         if document.is_a?(JSI::JSON::Node)
           raise(TypeError, "document of a Node should not be another JSI::JSON::Node: #{document.inspect}")
         end
         @document = document
-        @path = path.to_ary.dup.freeze
-        @pointer = JSI::JSON::Pointer.new(:reference_tokens, path)
+        @pointer = pointer
       end
 
-      # the path of this Node within its document
-      attr_reader :path
-      # the document containing this Node at is path
+      # the document containing this Node at our pointer
       attr_reader :document
-      # JSI::JSON::Pointer representing the path to this node within its document
+
+      # JSI::JSON::Pointer pointing to this node within its document
       attr_reader :pointer
 
-      # the raw content of this Node from the underlying document at this Node's path.
-      def content
-        content = pointer.evaluate(document)
-        content
+      # @return [Array<Object>] the path of this node; an array of reference_tokens of the pointer
+      def path
+        pointer.reference_tokens
       end
 
+      alias_method :node_document, :document
+      alias_method :node_ptr, :pointer
+
+      # the raw content of this Node from the underlying document at this Node's pointer.
+      alias_method :content, :node_content
+
       # returns content at the given subscript - call this the subcontent.
       #
       # if the content cannot be subscripted, raises TypeError.
@@ -78,11 +82,13 @@ module JSI
       # if this node's content is a $ref - that is, a hash with a $ref attribute - and the subscript is
       # not a key of the hash, then the $ref is followed before returning the subcontent.
       def [](subscript)
-        node = self
-        content = node.content
+        ptr = self.pointer
+        content = self.content
         if content.respond_to?(:to_hash) && !(content.respond_to?(:key?) ? content : content.to_hash).key?(subscript)
-          node = node.deref
-          content = node.content
+          pointer.deref(document) do |deref_ptr|
+            ptr = deref_ptr
+            content = ptr.evaluate(document)
+          end
         end
         unless content.respond_to?(:[])
           if content.respond_to?(:to_hash)
@@ -99,9 +105,9 @@ module JSI
           raise(e.class, e.message + "\nsubscripting with #{subscript.pretty_inspect.chomp} (#{subscript.class}) from #{content.class.inspect}. content is: #{content.pretty_inspect.chomp}", e.backtrace)
         end
         if subcontent.respond_to?(:to_hash)
-          HashNode.new(node.document, node.path + [subscript])
+          HashNode.new(document, ptr[subscript])
         elsif subcontent.respond_to?(:to_ary)
-          ArrayNode.new(node.document, node.path + [subscript])
+          ArrayNode.new(document, ptr[subscript])
         else
           subcontent
         end
@@ -120,30 +126,15 @@ module JSI
       # does not have a $ref, or if what its $ref cannot be found, this node is returned.
       #
       # currently only $refs pointing within the same document are followed.
-      def deref
-        content = self.content
-
-        if content.respond_to?(:to_hash)
-          ref = (content.respond_to?(:[]) ? content : content.to_hash)['$ref']
-        end
-        return self unless ref.is_a?(String)
-
-        if ref[/\A#/]
-          return self.class.new_by_type(document, JSI::JSON::Pointer.parse_fragment(ref)).deref
-        end
-
-        # HAX for how google does refs and ids
-        if document_node['schemas'].respond_to?(:to_hash)
-          if document_node['schemas'][ref]
-            return document_node['schemas'][ref]
-          end
-          _, deref_by_id = document_node['schemas'].detect { |_k, schema| schema['id'] == ref }
-          if deref_by_id
-            return deref_by_id
-          end
+      #
+      # @yield [Node] if a block is given (optional), this will yield a deref'd node. if this
+      #   node is not a $ref object, the block is not called. if we are a $ref which cannot be followed
+      #   (e.g. a $ref to an external document, which is not yet supported), the block is not called.
+      # @return [JSI::JSON::Node] dereferenced node, or this node
+      def deref(&block)
+        pointer.deref(document) do |deref_ptr|
+          return Node.new_by_type(document, deref_ptr).tap(&(block || Util::NOOP))
         end
-
-        #raise(NotImplementedError, "cannot dereference #{ref}") # TODO
         return self
       end
 
@@ -152,14 +143,17 @@ module JSI
         Node.new_doc(document)
       end
 
-      # the parent of this node. if this node is the document root (its path is empty), raises
+      alias_method :document_root_node, :document_node
+
+      # @return [Boolean] whether this node is the root of its document
+      def root_node?
+        pointer.root?
+      end
+
+      # the parent of this node. if this node is the document root, raises
       # JSI::JSON::Pointer::ReferenceError.
       def parent_node
-        if path.empty?
-          raise(JSI::JSON::Pointer::ReferenceError, "cannot access parent of root node: #{pretty_inspect.chomp}")
-        else
-          Node.new_by_type(document, path[0...-1])
-        end
+        Node.new_by_type(document, pointer.parent)
       end
 
       # the pointer path to this node within the document, per RFC 6901 https://tools.ietf.org/html/rfc6901
@@ -179,52 +173,12 @@ module JSI
 
       # takes a block. the block is yielded the content of this node. the block MUST return a modified
       # copy of that content (and NOT modify the object it is given).
-      def modified_copy
-        # we need to preserve the rest of the document, but modify the content at our path.
-        #
-        # this is actually a bit tricky. we can't modify the original document, obviously.
-        # we could do a deep copy, but that's expensive. instead, we make a copy of each array
-        # or hash in the path above this node. this node's content is modified by the caller, and
-        # that is recursively merged up to the document root. the recursion is done with a
-        # y combinator, for no other reason than that was a fun way to implement it.
-        modified_document = JSI::Util.ycomb do |rec|
-          proc do |subdocument, subpath|
-            if subpath == []
-              yield(subdocument)
-            else
-              car = subpath[0]
-              cdr = subpath[1..-1]
-              if subdocument.respond_to?(:to_hash)
-                subdocument_car = (subdocument.respond_to?(:[]) ? subdocument : subdocument.to_hash)[car]
-                car_object = rec.call(subdocument_car, cdr)
-                if car_object.object_id == subdocument_car.object_id
-                  subdocument
-                else
-                  (subdocument.respond_to?(:merge) ? subdocument : subdocument.to_hash).merge({car => car_object})
-                end
-              elsif subdocument.respond_to?(:to_ary)
-                if car.is_a?(String) && car =~ /\A\d+\z/
-                  car = car.to_i
-                end
-                unless car.is_a?(Integer)
-                  raise(TypeError, "bad subscript #{car.pretty_inspect.chomp} with remaining subpath: #{cdr.inspect} for array: #{subdocument.pretty_inspect.chomp}")
-                end
-                subdocument_car = (subdocument.respond_to?(:[]) ? subdocument : subdocument.to_ary)[car]
-                car_object = rec.call(subdocument_car, cdr)
-                if car_object.object_id == subdocument_car.object_id
-                  subdocument
-                else
-                  (subdocument.respond_to?(:[]=) ? subdocument : subdocument.to_ary).dup.tap do |arr|
-                    arr[car] = car_object
-                  end
-                end
-              else
-                raise(TypeError, "bad subscript: #{car.pretty_inspect.chomp} with remaining subpath: #{cdr.inspect} for content: #{subdocument.pretty_inspect.chomp}")
-              end
-            end
-          end
-        end.call(document, path)
-        Node.new_by_type(modified_document, path)
+      def modified_copy(&block)
+        Node.new_by_type(pointer.modified_document_copy(document, &block), pointer)
+      end
+
+      def dup
+        modified_copy(&:dup)
       end
 
       # meta-information about the object, outside the content. used by #inspect / #pretty_print
@@ -254,10 +208,10 @@ module JSI
 
       # fingerprint for equality (see FingerprintHash). two nodes are equal if they are both nodes
       # (regardless of type, e.g. one may be a Node and the other may be a HashNode) within equal
-      # documents at equal paths. note that this means two nodes with the same content may not be
+      # documents at equal pointers. note that this means two nodes with the same content may not be
       # considered equal.
       def fingerprint
-        {is_node: self.is_a?(JSI::JSON::Node), document: document, path: path}
+        {class: JSI::JSON::Node, document: document, pointer: pointer}
       end
       include FingerprintHash
     end
@@ -265,64 +219,25 @@ module JSI
     # a JSI::JSON::Node whose content is Array-like (responds to #to_ary)
     # and includes Array methods from Arraylike
     class ArrayNode < Node
-      # iterates over each element in the same manner as Array#each
-      def each
-        return to_enum(__method__) { (content.respond_to?(:size) ? content : content.to_ary).size } unless block_given?
-        (content.respond_to?(:each_index) ? content : content.to_ary).each_index { |i| yield self[i] }
-        self
-      end
-
-      # the content of this ArrayNode, as an Array
-      def to_ary
-        to_a
-      end
-
       include Enumerable
-      include Arraylike
+      include PathedArrayNode
 
       # returns a jsonifiable representation of this node's content
       def as_json(*opt) # needs redefined after including Enumerable
         Typelike.as_json(content, *opt)
       end
-
-      # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_a).
-      # we override these methods from Arraylike
-      SAFE_INDEX_ONLY_METHODS.each do |method_name|
-        define_method(method_name) { |*a, &b| (content.respond_to?(method_name) ? content : content.to_ary).public_send(method_name, *a, &b) }
-      end
     end
 
     # a JSI::JSON::Node whose content is Hash-like (responds to #to_hash)
     # and includes Hash methods from Hashlike
     class HashNode < Node
-      # iterates over each element in the same manner as Array#each
-      def each(&block)
-        return to_enum(__method__) { content.respond_to?(:size) ? content.size : content.to_ary.size } unless block_given?
-        if block.arity > 1
-          (content.respond_to?(:each_key) ? content : content.to_hash).each_key { |k| yield k, self[k] }
-        else
-          (content.respond_to?(:each_key) ? content : content.to_hash).each_key { |k| yield [k, self[k]] }
-        end
-        self
-      end
-
-      # the content of this HashNode, as a Hash
-      def to_hash
-        inject({}) { |h, (k, v)| h[k] = v; h }
-      end
-
       include Enumerable
-      include Hashlike
+      include PathedHashNode
 
       # returns a jsonifiable representation of this node's content
       def as_json(*opt) # needs redefined after including Enumerable
         Typelike.as_json(content, *opt)
       end
-
-      # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_hash)
-      SAFE_KEY_ONLY_METHODS.each do |method_name|
-        define_method(method_name) { |*a, &b| (content.respond_to?(method_name) ? content : content.to_hash).public_send(method_name, *a, &b) }
-      end
     end
   end
 end

data/lib/jsi/json/pointer.rb

@@ -11,66 +11,88 @@ module JSI
       class ReferenceError < Error
       end
 
-      # parse a fragment to an array of reference tokens
+      # instantiates a Pointer from any given reference tokens.
       #
-      # #/foo/bar
+      #     >> JSI::JSON::Pointer[]
+      #     => #<JSI::JSON::Pointer reference_tokens: []>
+      #     >> JSI::JSON::Pointer['a', 'b']
+      #     => #<JSI::JSON::Pointer reference_tokens: ["a", "b"]>
+      #     >> JSI::JSON::Pointer['a']['b']
+      #     => #<JSI::JSON::Pointer reference_tokens: ["a", "b"]>
       #
-      # => ['foo', 'bar']
+      # note in the last example that you can conveniently chain the class .[] method
+      # with the instance #[] method.
       #
-      # #/foo%20bar
+      # @param *reference_tokens any number of reference tokens
+      # @return [JSI::JSON::Pointer]
+      def self.[](*reference_tokens)
+        new(reference_tokens)
+      end
+
+      # parse a URI-escaped fragment and instantiate as a JSI::JSON::Pointer
+      #
+      #     ptr = JSI::JSON::Pointer.from_fragment('#/foo/bar')
+      #     => #<JSI::JSON::Pointer fragment: #/foo/bar>
+      #     ptr.reference_tokens
+      #     => ["foo", "bar"]
+      #
+      # with URI escaping:
       #
-      # => ['foo bar']
-      def self.parse_fragment(fragment)
+      #     ptr = JSI::JSON::Pointer.from_fragment('#/foo%20bar')
+      #     => #<JSI::JSON::Pointer fragment: #/foo%20bar>
+      #     ptr.reference_tokens
+      #     => ["foo bar"]
+      #
+      # @param fragment [String] a fragment containing a pointer (starting with #)
+      # @return [JSI::JSON::Pointer]
+      def self.from_fragment(fragment)
         fragment = Addressable::URI.unescape(fragment)
         match = fragment.match(/\A#/)
         if match
-          parse_pointer(match.post_match)
+          from_pointer(match.post_match, type: 'fragment')
         else
           raise(PointerSyntaxError, "Invalid fragment syntax in #{fragment.inspect}: fragment must begin with #")
         end
       end
 
-      # parse a pointer to an array of reference tokens
-      #
-      # /foo
+      # parse a pointer string and instantiate as a JSI::JSON::Pointer
       #
-      # => ['foo']
+      #     ptr1 = JSI::JSON::Pointer.from_pointer('/foo')
+      #     => #<JSI::JSON::Pointer pointer: /foo>
+      #     ptr1.reference_tokens
+      #     => ["foo"]
       #
-      # /foo~0bar/baz~1qux
+      #     ptr2 = JSI::JSON::Pointer.from_pointer('/foo~0bar/baz~1qux')
+      #     => #<JSI::JSON::Pointer pointer: /foo~0bar/baz~1qux>
+      #     ptr2.reference_tokens
+      #     => ["foo~bar", "baz/qux"]
       #
-      # => ['foo~bar', 'baz/qux']
-      def self.parse_pointer(pointer_string)
+      # @param pointer_string [String] a pointer string
+      # @param type (for internal use) indicates the original representation of the pointer
+      # @return [JSI::JSON::Pointer]
+      def self.from_pointer(pointer_string, type: 'pointer')
         tokens = pointer_string.split('/', -1).map! do |piece|
           piece.gsub('~1', '/').gsub('~0', '~')
         end
         if tokens[0] == ''
-          tokens[1..-1]
+          new(tokens[1..-1], type: type)
         elsif tokens.empty?
-          tokens
+          new(tokens, type: type)
         else
           raise(PointerSyntaxError, "Invalid pointer syntax in #{pointer_string.inspect}: pointer must begin with /")
         end
       end
 
-      # initializes a JSI::JSON::Pointer from the given representation.
-      #
-      # type may be one of:
+      # initializes a JSI::JSON::Pointer from the given reference_tokens.
       #
-      # - :fragment - the representation is a fragment containing a pointer (starting with #)
-      # - :pointer - the representation is a pointer (starting with /)
-      # - :reference_tokens - the representation is an array of tokens referencing a path in a document
-      def initialize(type, representation)
-        @type = type
-        if type == :reference_tokens
-          reference_tokens = representation
-        elsif type == :fragment
-          reference_tokens = self.class.parse_fragment(representation)
-        elsif type == :pointer
-          reference_tokens = self.class.parse_pointer(representation)
-        else
-          raise ArgumentError, "invalid initialization type: #{type.inspect} with representation #{representation.inspect}"
+      # @param reference_tokens [Array<Object>]
+      # @param type [String, Symbol] one of 'pointer' or 'fragment'
+      def initialize(reference_tokens, type: nil)
+        unless reference_tokens.respond_to?(:to_ary)
+          raise(TypeError, "reference_tokens must be an array. got: #{reference_tokens.inspect}")
         end
-        @reference_tokens = reference_tokens.map(&:freeze).freeze
+        @reference_tokens = reference_tokens.to_ary.map(&:freeze).freeze
+        @type = type.is_a?(Symbol) ? type.to_s : type
       end
 
       attr_reader :reference_tokens
@@ -106,29 +128,201 @@ module JSI
         res
       end
 
-      # the pointer string representation of this Pointer
+      # @return [String] the pointer string representation of this Pointer
       def pointer
         reference_tokens.map { |t| '/' + t.to_s.gsub('~', '~0').gsub('/', '~1') }.join('')
       end
 
-      # the fragment string representation of this Pointer
+      # @return [String] the fragment string representation of this Pointer
       def fragment
         '#' + Addressable::URI.escape(pointer)
       end
 
+      # @return [Boolean] whether this pointer points to the root (has an empty array of reference_tokens)
+      def root?
+        reference_tokens.empty?
+      end
+
+      # @return [JSI::JSON::Pointer] pointer to the parent of where this pointer points
+      # @raise [JSI::JSON::Pointer::ReferenceError] if this pointer has no parent (points to the root)
+      def parent
+        if root?
+          raise(ReferenceError, "cannot access parent of root pointer: #{pretty_inspect.chomp}")
+        else
+          Pointer.new(reference_tokens[0...-1], type: @type)
+        end
+      end
+
+      # @return [Boolean] does this pointer contain the other_ptr - that is, is this pointer an
+      #   ancestor of other_ptr, a child pointer. contains? is inclusive; a pointer does contain itself.
+      def contains?(other_ptr)
+        self.reference_tokens == other_ptr.reference_tokens[0...self.reference_tokens.size]
+      end
+
+      # @return [JSI::JSON::Pointer] returns this pointer relative to the given ancestor_ptr
+      # @raise [JSI::JSON::Pointer::ReferenceError] if the given ancestor_ptr is not an ancestor of this pointer
+      def ptr_relative_to(ancestor_ptr)
+        unless ancestor_ptr.contains?(self)
+          raise(ReferenceError, "ancestor_ptr #{ancestor_ptr.inspect} is not ancestor of #{inspect}")
+        end
+        Pointer.new(reference_tokens[ancestor_ptr.reference_tokens.size..-1], type: @type)
+      end
+
+      # @param ptr [JSI::JSON::Pointer]
+      # @return [JSI::JSON::Pointer] a pointer with the reference tokens of this one plus the given ptr's.
+      def +(ptr)
+        unless ptr.is_a?(JSI::JSON::Pointer)
+          raise(TypeError, "ptr must be a JSI::JSON::Pointer; got: #{ptr.inspect}")
+        end
+        Pointer.new(reference_tokens + ptr.reference_tokens, type: @type)
+      end
+
+      # @param n [Integer]
+      # @return [JSI::JSON::Pointer] a Pointer consisting of the first n of our reference_tokens
+      # @raise [ArgumentError] if n is not between 0 and the size of our reference_tokens
+      def take(n)
+        unless (0..reference_tokens.size).include?(n)
+          raise(ArgumentError, "n not in range (0..#{reference_tokens.size}): #{n.inspect}")
+        end
+        Pointer.new(reference_tokens.take(n), type: @type)
+      end
+
+      # appends the given token to this Pointer's reference tokens and returns the result
+      #
+      # @param token [Object]
+      # @return [JSI::JSON::Pointer] pointer to a child node of this pointer with the given token
+      def [](token)
+        Pointer.new(reference_tokens + [token], type: @type)
+      end
+
+      # takes a document and a block. the block is yielded the content of the given document at this
+      # pointer's location. the block must result a modified copy of that content (and MUST NOT modify
+      # the object it is given). this modified copy of that content is incorporated into a modified copy
+      # of the given document, which is then returned. the structure and contents of the document outside
+      # the path pointed to by this pointer is not modified.
+      #
+      # @param document [Object] the document to apply this pointer to
+      # @yield [Object] the content this pointer applies to in the given document
+      #   the block must result in the new content which will be placed in the modified document copy.
+      # @return [Object] a copy of the given document, with the content this pointer applies to
+      #   replaced by the result of the block
+      def modified_document_copy(document, &block)
+        # we need to preserve the rest of the document, but modify the content at our path.
+        #
+        # this is actually a bit tricky. we can't modify the original document, obviously.
+        # we could do a deep copy, but that's expensive. instead, we make a copy of each array
+        # or hash in the path above this node. this node's content is modified by the caller, and
+        # that is recursively merged up to the document root. the recursion is done with a
+        # y combinator, for no other reason than that was a fun way to implement it.
+        modified_document = JSI::Util.ycomb do |rec|
+          proc do |subdocument, subpath|
+            if subpath == []
+              Typelike.modified_copy(subdocument, &block)
+            else
+              car = subpath[0]
+              cdr = subpath[1..-1]
+              if subdocument.respond_to?(:to_hash)
+                subdocument_car = (subdocument.respond_to?(:[]) ? subdocument : subdocument.to_hash)[car]
+                car_object = rec.call(subdocument_car, cdr)
+                if car_object.object_id == subdocument_car.object_id
+                  subdocument
+                else
+                  (subdocument.respond_to?(:merge) ? subdocument : subdocument.to_hash).merge({car => car_object})
+                end
+              elsif subdocument.respond_to?(:to_ary)
+                if car.is_a?(String) && car =~ /\A\d+\z/
+                  car = car.to_i
+                end
+                unless car.is_a?(Integer)
+                  raise(TypeError, "bad subscript #{car.pretty_inspect.chomp} with remaining subpath: #{cdr.inspect} for array: #{subdocument.pretty_inspect.chomp}")
+                end
+                subdocument_car = (subdocument.respond_to?(:[]) ? subdocument : subdocument.to_ary)[car]
+                car_object = rec.call(subdocument_car, cdr)
+                if car_object.object_id == subdocument_car.object_id
+                  subdocument
+                else
+                  (subdocument.respond_to?(:[]=) ? subdocument : subdocument.to_ary).dup.tap do |arr|
+                    arr[car] = car_object
+                  end
+                end
+              else
+                raise(TypeError, "bad subscript: #{car.pretty_inspect.chomp} with remaining subpath: #{cdr.inspect} for content: #{subdocument.pretty_inspect.chomp}")
+              end
+            end
+          end
+        end.call(document, reference_tokens)
+        modified_document
+      end
+
+      # if this Pointer points at a $ref node within the given document, #deref attempts
+      # to follow that $ref and return a Pointer to the referenced location. otherwise,
+      # this Pointer is returned.
+      #
+      # if the content this Pointer points to in the document is not hash-like, does not
+      # have a $ref property, its $ref cannot be found, or its $ref points outside the document,
+      # this pointer is returned.
+      #
+      # @param document [Object] the document this pointer applies to
+      # @yield [Pointer] if a block is given (optional), this will yield a deref'd pointer. if this
+      #   pointer does not point to a $ref object in the given document, the block is not called.
+      #   if we point to a $ref which cannot be followed (e.g. a $ref to an external
+      #   document, which is not yet supported), the block is not called.
+      # @return [Pointer] dereferenced pointer, or this pointer
+      def deref(document, &block)
+        block ||= Util::NOOP
+        content = evaluate(document)
+
+        if content.respond_to?(:to_hash)
+          ref = (content.respond_to?(:[]) ? content : content.to_hash)['$ref']
+        end
+        return self unless ref.is_a?(String)
+
+        if ref[/\A#/]
+          return Pointer.from_fragment(ref).tap(&block)
+        end
+
+        # HAX for how google does refs and ids
+        if document['schemas'].respond_to?(:to_hash)
+          if document['schemas'][ref]
+            return Pointer.new(['schemas', ref], type: 'hax').tap(&block)
+          end
+          document['schemas'].each do |k, schema|
+            if schema['id'] == ref
+              return Pointer.new(['schemas', k], type: 'hax').tap(&block)
+            end
+          end
+        end
+
+        #raise(NotImplementedError, "cannot dereference #{ref}") # TODO
+        return self
+      end
+
+      # @return [String] string representation of this Pointer
+      def inspect
+        "#<#{self.class.inspect} #{representation_s}>"
+      end
+
+      # @return [String] string representation of this Pointer
       def to_s
-        "#<#{self.class.inspect} #{@type} = #{representation_s}>"
+        inspect
+      end
+
+      # pointers are equal if the reference_tokens are equal, regardless of @type
+      def fingerprint
+        {class: JSI::JSON::Pointer, reference_tokens: reference_tokens}
       end
+      include FingerprintHash
 
       private
 
+      # @return [String] a representation of this pointer based on @type
       def representation_s
-        if @type == :fragment
-          fragment
-        elsif @type == :pointer
-          pointer
+        if @type == 'fragment'
+          "fragment: #{fragment}"
+        elsif @type == 'pointer'
+          "pointer: #{pointer}"
         else
-          reference_tokens.inspect
+          "reference_tokens: #{reference_tokens.inspect}"
         end
       end
     end