jsi 0.2.0 → 0.6.0

data/lib/jsi/base.rb

@@ -1,180 +1,324 @@
-require 'json'
-require 'jsi/typelike_modules'
+# frozen_string_literal: true
 
 module JSI
-  # the base class for representing and instantiating a JSON Schema.
+  # JSI::Base is the base class of every JSI instance of a JSON schema.
   #
-  # a class inheriting from JSI::Base represents a JSON Schema. an instance of
-  # that class represents a JSON schema instance.
+  # instances are described by a set of one or more JSON schemas. JSI dynamically creates a subclass of
+  # JSI::Base for each set of JSON schemas which describe an instance that is to be instantiated.
   #
-  # as such, JSI::Base itself is not intended to be instantiated - subclasses
-  # are dynamically created for schemas using {JSI.class_for_schema}, and these
-  # are what are used to instantiate and represent JSON schema instances.
+  # a JSI instance of such a subclass represents a JSON schema instance described by that set of schemas.
+  #
+  # this subclass includes the JSI Schema Module of each schema it represents.
+  #
+  # the method {Base#jsi_schemas} is defined to indicate the schemas the class represents.
+  #
+  # the JSI::Base class itself is not intended to be instantiated.
   class Base
-    include Memoize
-    include Enumerable
     include PathedNode
+    include Schema::SchemaAncestorNode
+    include Util::Memoize
+
+    # not every JSI::Base is necessarily an Enumerable, but it's better to include Enumerable on
+    # the class than to conditionally extend the instance.
+    include Enumerable
+
+    # an exception raised when #[] is invoked on an instance which is not an array or hash
+    class CannotSubscriptError < StandardError
+    end
 
     class << self
-      # is the constant JSI::SchemaClasses::{self.schema_classes_const_name} defined?
-      # (if so, we will prefer to use something more human-readable than that ugly mess.)
-      attr_accessor :in_schema_classes
+      # @private @deprecated
+      def new_jsi(instance, **kw, &b)
+        new(instance, **kw, &b)
+      end
 
-      # @return [String] absolute schema_id of the schema this class represents.
-      #   see {Schema#schema_id}.
-      def schema_id
-        schema.schema_id
+      # @private
+      # is the constant JSI::SchemaClasses::<self.schema_classes_const_name> defined?
+      # (if so, we will prefer to use something more human-readable than that ugly mess.)
+      def in_schema_classes
+        # #name sets @in_schema_classes
+        name
+        @in_schema_classes
       end
 
-      # @return [String] a string representing the class, with schema_id
+      # a string indicating a class name if one is defined, as well as the schema module name
+      # and/or schema URI of each schema the class represents.
+      # @return [String]
       def inspect
-        name # see #name for side effects
-        if !respond_to?(:schema)
+        if !respond_to?(:jsi_class_schemas)
           super
-        elsif in_schema_classes
-          %Q(#{SchemaClasses.inspect}[#{schema_id.inspect}])
-        elsif !name
-          %Q(#<Class for Schema: #{schema_id}>)
         else
-          %Q(#{name} (#{schema_id}))
-        end
-      end
+          schema_names = jsi_class_schemas.map do |schema|
+            mod = schema.jsi_schema_module
+            if mod.name && schema.schema_uri
+              "#{mod.name} (#{schema.schema_uri})"
+            elsif mod.name
+              mod.name
+            elsif schema.schema_uri
+              schema.schema_uri.to_s
+            else
+              schema.jsi_ptr.uri.to_s
+            end
+          end
 
-      # @return [String] a string representing the class - a class name if one
-      #   was explicitly defined, otherwise a reference to JSI::SchemaClasses
-      def to_s
-        if !respond_to?(:schema)
-          super
-        elsif !name || name =~ /\AJSI::SchemaClasses::/
-          %Q(#{SchemaClasses.inspect}[#{schema_id.inspect}])
-        else
-          name
+          if name && !in_schema_classes
+            if jsi_class_schemas.empty?
+              "#{name} (0 schemas)"
+            else
+              "#{name} (#{schema_names.join(', ')})"
+            end
+          else
+            if schema_names.empty?
+              "(JSI Schema Class for 0 schemas)"
+            else
+              "(JSI Schema Class: #{schema_names.join(', ')})"
+            end
+          end
         end
       end
 
-      # @return [String] a name for a constant for this class, generated from the
-      #   schema_id. only used if the class is not assigned to another constant.
+      alias_method :to_s, :inspect
+
+      # @private
+      # see {.name}
       def schema_classes_const_name
-        name = schema.schema_id.gsub(/[^\w]/, '_')
-        name = 'X' + name unless name[/\A[a-zA-Z]/]
-        name = name[0].upcase + name[1..-1]
-        name
+        if respond_to?(:jsi_class_schemas)
+          schema_names = jsi_class_schemas.map do |schema|
+            if schema.jsi_schema_module.name
+              schema.jsi_schema_module.name
+            elsif schema.schema_uri
+              schema.schema_uri.to_s
+            else
+              nil
+            end
+          end
+          if !schema_names.any?(&:nil?) && !schema_names.empty?
+            schema_names.sort.map { |n| 'X' + n.to_s.gsub(/[^\w]/, '_') }.join('')
+          end
+        end
       end
 
-      # @return [String] a constant name of this class
+      # a constant name of this class. this is generated from the schema module name or URI of each schema
+      # this class represents. nil if any represented schema has no schema module name or schema URI.
+      #
+      # this generated name is not too pretty but can be more helpful than an anonymous class, especially
+      # in error messages.
+      #
+      # @return [String]
       def name
-        unless super || SchemaClasses.const_defined?(schema_classes_const_name)
-          SchemaClasses.const_set(schema_classes_const_name, self)
-          self.in_schema_classes = true
+        unless instance_variable_defined?(:@in_schema_classes)
+          const_name = schema_classes_const_name
+          if super || !const_name || SchemaClasses.const_defined?(const_name)
+            @in_schema_classes = false
+          else
+            SchemaClasses.const_set(const_name, self)
+            @in_schema_classes = true
+          end
         end
         super
       end
     end
 
     # NOINSTANCE is a magic value passed to #initialize when instantiating a JSI
-    # from a document and JSON Pointer.
-    NOINSTANCE = Object.new.tap { |o| [:inspect, :to_s].each(&(-> (s, m) { o.define_singleton_method(m) { s } }.curry.([JSI::Base.name, 'NOINSTANCE'].join('::')))) }
+    # from a document and pointer.
+    #
+    # @private
+    NOINSTANCE = Object.new
+    [:inspect, :to_s].each(&(-> (s, m) { NOINSTANCE.define_singleton_method(m) { s } }.curry.("#{JSI::Base}::NOINSTANCE")))
+    NOINSTANCE.freeze
 
     # initializes this JSI from the given instance - instance is most commonly
     # a parsed JSON document consisting of Hash, Array, or sometimes a basic
     # type, but this is in no way enforced and a JSI may wrap any object.
     #
-    # @param instance [Object] the JSON Schema instance being represented
+    # @param instance [Object] the JSON Schema instance to be represented as a JSI
     # @param jsi_document [Object] for internal use. the instance may be specified as a
     #   node in the `jsi_document` param, pointed to by `jsi_ptr`. the param `instance`
     #   MUST be `NOINSTANCE` to use the jsi_document + jsi_ptr form. `jsi_document` MUST
     #   NOT be passed if `instance` is anything other than `NOINSTANCE`.
-    # @param jsi_ptr [JSI::JSON::Pointer] for internal use. a JSON pointer specifying
+    # @param jsi_ptr [JSI::Ptr] for internal use. a pointer specifying
     #   the path of this instance in the `jsi_document` param. `jsi_ptr` must be passed
     #   iff `jsi_document` is passed, i.e. when `instance` is `NOINSTANCE`
-    # @param ancestor_jsi [JSI::Base] for internal use, specifies an ancestor_jsi
-    #   from which this JSI originated to calculate #parents
-    def initialize(instance, jsi_document: nil, jsi_ptr: nil, ancestor_jsi: nil)
-      unless respond_to?(:schema)
-        raise(TypeError, "cannot instantiate #{self.class.inspect} which has no method #schema. please use JSI.class_for_schema")
+    # @param jsi_root_node [JSI::Base] for internal use, specifies the JSI at the root of the document
+    # @param jsi_schema_base_uri [Addressable::URI] see {SchemaSet#new_jsi} param uri
+    # @param jsi_schema_resource_ancestors [Array<JSI::Base>]
+    def initialize(instance,
+        jsi_document: nil,
+        jsi_ptr: nil,
+        jsi_root_node: nil,
+        jsi_schema_base_uri: nil,
+        jsi_schema_resource_ancestors: []
+    )
+      unless respond_to?(:jsi_schemas)
+        raise(TypeError, "cannot instantiate #{self.class.inspect} which has no method #jsi_schemas. it is recommended to instantiate JSIs from a schema using JSI::Schema#new_jsi.")
       end
 
-      if instance.is_a?(JSI::Base)
-        raise(TypeError, "assigning another JSI::Base instance to #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
-      elsif instance.is_a?(JSI::Schema)
-        raise(TypeError, "assigning a schema to #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
+      if instance.is_a?(JSI::Schema)
+        raise(TypeError, "assigning a schema to a #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
+      elsif instance.is_a?(JSI::Base)
+        raise(TypeError, "assigning another JSI::Base instance to a #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
       end
 
+      jsi_initialize_memos
+
       if instance == NOINSTANCE
-        @jsi_document = jsi_document
-        unless jsi_ptr.is_a?(JSI::JSON::Pointer)
-          raise(TypeError, "jsi_ptr must be a JSI::JSON::Pointer; got: #{jsi_ptr.inspect}")
-        end
-        @jsi_ptr = jsi_ptr
-      else
-        raise(Bug, 'incorrect usage') if jsi_document || jsi_ptr || ancestor_jsi
-        if instance.is_a?(PathedNode)
-          @jsi_document = instance.document_root_node
-          # this can result in the unusual situation where ancestor_jsi is nil, though jsi_ptr is not root.
-          # #document_root_node will then return a JSI::JSON::Pointer instead of a root JSI.
-          @jsi_ptr = instance.node_ptr
+        self.jsi_document = jsi_document
+        self.jsi_ptr = jsi_ptr
+        if @jsi_ptr.root?
+          raise(Bug, "jsi_root_node cannot be specified for root JSI") if jsi_root_node
+          @jsi_root_node = self
         else
-          @jsi_document = instance
-          @jsi_ptr = JSI::JSON::Pointer.new([])
-        end
-      end
-      if ancestor_jsi
-        if !ancestor_jsi.is_a?(JSI::Base)
-          raise(TypeError, "ancestor_jsi must be a JSI::Base; got: #{ancestor_jsi.inspect}")
-        end
-        if !ancestor_jsi.jsi_ptr.contains?(@jsi_ptr)
-          raise(Bug, "ancestor_jsi ptr #{ancestor_jsi.jsi_ptr.inspect} is not ancestor of #{@jsi_ptr.inspect}")
+          if !jsi_root_node.is_a?(JSI::Base)
+            raise(TypeError, "jsi_root_node must be a JSI::Base; got: #{jsi_root_node.inspect}")
+          end
+          if !jsi_root_node.jsi_ptr.root?
+            raise(Bug, "jsi_root_node ptr #{jsi_root_node.jsi_ptr.inspect} is not root")
+          end
+          @jsi_root_node = jsi_root_node
         end
+      else
+        raise(Bug, 'incorrect usage') if jsi_document || jsi_ptr || jsi_root_node
+        @jsi_document = instance
+        @jsi_ptr = Ptr[]
+        @jsi_root_node = self
       end
-      @ancestor_jsi = ancestor_jsi
+
+      self.jsi_schema_base_uri = jsi_schema_base_uri
+      self.jsi_schema_resource_ancestors = jsi_schema_resource_ancestors
 
       if self.jsi_instance.respond_to?(:to_hash)
-        extend BaseHash
-      elsif self.jsi_instance.respond_to?(:to_ary)
-        extend BaseArray
+        extend PathedHashNode
+      end
+      if self.jsi_instance.respond_to?(:to_ary)
+        extend PathedArrayNode
       end
     end
 
-    # document containing the instance of this JSI
+    # @!method jsi_schemas
+    #   the set of schemas which describe this instance
+    #   @return [JSI::SchemaSet]
+    # note: defined on subclasses by JSI::SchemaClasses.class_for_schemas
+
+
+    # document containing the instance of this JSI at our {#jsi_ptr}
     attr_reader :jsi_document
 
-    # JSI::JSON::Pointer pointing to this JSI's instance within the jsi_document
+    # {JSI::Ptr} pointing to this JSI's instance within our {#jsi_document}
+    # @return [JSI::Ptr]
     attr_reader :jsi_ptr
 
-    # a JSI which is an ancestor_jsi of this
-    attr_reader :ancestor_jsi
+    # the JSI at the root of this JSI's document
+    # @return [JSI::Base]
+    attr_reader :jsi_root_node
 
-    alias_method :node_document, :jsi_document
-    alias_method :node_ptr, :jsi_ptr
+    # the JSON schema instance this JSI represents - the underlying JSON data used to instantiate this JSI
+    alias_method :jsi_instance, :jsi_node_content
 
-    # the instance of the json-schema
-    alias_method :jsi_instance, :node_content
-    alias_method :instance, :node_content
+    # each is overridden by PathedHashNode or PathedArrayNode when appropriate. the base #each
+    # is not actually implemented, along with all the methods of Enumerable.
+    def each(*_)
+      raise NoMethodError, "Enumerable methods and #each not implemented for instance that is not like a hash or array: #{jsi_instance.pretty_inspect.chomp}"
+    end
 
-    # each is overridden by BaseHash or BaseArray when appropriate. the base
-    # #each is not actually implemented, along with all the methods of Enumerable.
-    def each
-      raise NoMethodError, "Enumerable methods and #each not implemented for instance that is not like a hash or array: #{instance.pretty_inspect.chomp}"
+    # yields a JSI of each node at or below this one in this JSI's document.
+    #
+    # returns an Enumerator if no block is given.
+    #
+    # @yield [JSI::Base] each node in the document, starting with self
+    # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
+    def jsi_each_child_node(&block)
+      return to_enum(__method__) unless block
+
+      yield self
+      if respond_to?(:to_hash)
+        each_key do |k|
+          self[k, as_jsi: true].jsi_each_child_node(&block)
+        end
+      elsif respond_to?(:to_ary)
+        each_index do |i|
+          self[i, as_jsi: true].jsi_each_child_node(&block)
+        end
+      end
+      nil
     end
 
-    # an array of JSI instances above this one in the document. empty if this
-    # JSI does not have a known ancestor.
+    # recursively selects child nodes of this JSI, returning a modified copy of self containing only
+    # child nodes for which the given block had a true-ish result.
     #
-    # @return [Array<JSI::Base>]
-    def parent_jsis
-      ancestor_jsi = @ancestor_jsi || self
-      parent = ancestor_jsi
-
-      (ancestor_jsi.jsi_ptr.reference_tokens.size...self.jsi_ptr.reference_tokens.size).map do |i|
-        current = parent
-        parent = parent[self.jsi_ptr.reference_tokens[i]]
-        if current.is_a?(JSI::Base)
-          current
+    # this method yields a node before recursively descending to its child nodes, so leaf nodes are yielded
+    # last, after their parents. if a node is not selected, its children are never recursed.
+    #
+    # @yield [JSI::Base] each child node below self
+    # @return [JSI::Base] modified copy of self containing only the selected nodes
+    def jsi_select_children_node_first(&block)
+      jsi_modified_copy do |instance|
+        if respond_to?(:to_hash)
+          res = instance.class.new
+          each_key do |k|
+            v = self[k, as_jsi: true]
+            if yield(v)
+              res[k] = v.jsi_select_children_node_first(&block).jsi_node_content
+            end
+          end
+          res
+        elsif respond_to?(:to_ary)
+          res = instance.class.new
+          each_index do |i|
+            e = self[i, as_jsi: true]
+            if yield(e)
+              res << e.jsi_select_children_node_first(&block).jsi_node_content
+            end
+          end
+          res
+        else
+          instance
+        end
+      end
+    end
+
+    # recursively selects child nodes of this JSI, returning a modified copy of self containing only
+    # child nodes for which the given block had a true-ish result.
+    #
+    # this method recursively descends child nodes before yielding each node, so leaf nodes are yielded
+    # before their parents.
+    #
+    # @yield [JSI::Base] each child node below self
+    # @return [JSI::Base] modified copy of self containing only the selected nodes
+    def jsi_select_children_leaf_first(&block)
+      jsi_modified_copy do |instance|
+        if respond_to?(:to_hash)
+          res = instance.class.new
+          each_key do |k|
+            v = self[k, as_jsi: true].jsi_select_children_leaf_first(&block)
+            if yield(v)
+              res[k] = v.jsi_node_content
+            end
+          end
+          res
+        elsif respond_to?(:to_ary)
+          res = instance.class.new
+          each_index do |i|
+            e = self[i, as_jsi: true].jsi_select_children_leaf_first(&block)
+            if yield(e)
+              res << e.jsi_node_content
+            end
+          end
+          res
         else
-          # sometimes after a deref, we may end up with parents whose schema we do not know.
-          # TODO this is kinda crap; hopefully we can remove it along with deref instantiating
-          # a deref ptr as the same JSI class it is
-          SimpleWrap.new(NOINSTANCE, jsi_document: jsi_document, jsi_ptr: jsi_ptr.take(i), ancestor_jsi: @ancestor_jsi)
+          instance
+        end
+      end
+    end
+
+    # an array of JSI instances above this one in the document.
+    #
+    # @return [Array<JSI::Base>]
+    def jsi_parent_nodes
+      parent = jsi_root_node
+
+      jsi_ptr.tokens.map do |token|
+        parent.tap do
+          parent = parent[token, as_jsi: true]
         end
       end.reverse
     end
@@ -182,291 +326,294 @@ module JSI
     # the immediate parent of this JSI. nil if there is no parent.
     #
     # @return [JSI::Base, nil]
-    def parent_jsi
-      parent_jsis.first
-    end
-
-    # @return [JSI::PathedNode] a pathed node at the root of the document. this is generally a JSI::Base
-    #   but may be a JSI::JSON::Node in unusual circumstances.
-    def document_root_node
-      if @jsi_ptr.root?
-        self
-      elsif @ancestor_jsi
-        @ancestor_jsi.document_root_node
-      elsif instance.is_a?(PathedNode)
-        instance.document_root_node
-      else
-        JSI::JSON::Node.new_doc(@jsi_document)
-      end
+    def jsi_parent_node
+      jsi_parent_nodes.first
     end
 
-    # @return [JSI::PathedNode]
-    def parent_node
-      if @jsi_ptr.root?
-        nil
-      elsif @ancestor_jsi
-        parent_jsis.first.tap do |parent_node|
-          raise(Bug, 'is @ancestor_jsi == self? it should not be') if parent_node.nil?
-          raise(Bug, "parent_node not PathedNode: #{parent_node.pretty_inspect.chomp}") unless parent_node.is_a?(JSI::PathedNode)
-        end
-      elsif instance.is_a?(PathedNode)
-        instance.parent_node
+    # subscripts to return a child value identified by the given token.
+    #
+    # @param token [String, Integer, Object] an array index or hash key (JSON object property name)
+    #   of the instance identifying the child value
+    # @param as_jsi [:auto, true, false] whether to return the result value as a JSI. one of:
+    #
+    #   - :auto (default): by default a JSI will be returned when either:
+    #
+    #     - the result is a complex value (responds to #to_ary or #to_hash) and is described by some schemas
+    #     - the result is a schema (including true/false schemas)
+    #
+    #     a plain value is returned when no schemas are known to describe the instance, or when the value is a
+    #     simple type (anything unresponsive to #to_ary / #to_hash).
+    #
+    #   - true: the result value will always be returned as a JSI. the #jsi_schemas of the result may be empty
+    #     if no schemas describe the instance.
+    #   - false: the result value will always be the plain instance.
+    #
+    #   note that nil is returned (regardless of as_jsi) when there is no value to return because the token
+    #   is not a hash key or array index of the instance and no default value applies.
+    #   (one exception is when this JSI's instance is a Hash with a default or default_proc, which has
+    #   unspecified behavior.)
+    # @param use_default [true, false] whether to return a schema default value when the token is not in
+    #   range. if the token is not an array index or hash key of the instance, and one schema for the child
+    #   instance specifies a default value, that default is returned.
+    #
+    #   if the result with the default value is a JSI (per the `as_jsi` param), that JSI is not a child of
+    #   this JSI - this JSI is not modified to fill in the default value. the result is a JSI within a new
+    #   document containing the filled-in default.
+    #
+    #   if the child instance's schemas do not indicate a single default value (that is, if zero or multiple
+    #   defaults are specified across those schemas), nil is returned.
+    #   (one exception is when this JSI's instance is a Hash with a default or default_proc, which has
+    #   unspecified behavior.)
+    # @return [JSI::Base, Object] the child value identified by the subscript token
+    def [](token, as_jsi: :auto, use_default: true)
+      if respond_to?(:to_hash)
+        token_in_range = jsi_node_content_hash_pubsend(:key?, token)
+        value = jsi_node_content_hash_pubsend(:[], token)
+      elsif respond_to?(:to_ary)
+        token_in_range = jsi_node_content_ary_pubsend(:each_index).include?(token)
+        value = jsi_node_content_ary_pubsend(:[], token)
       else
-        JSI::JSON::Node.new_by_type(@jsi_document, @jsi_ptr.parent)
+        raise(CannotSubscriptError, "cannot subscript (using token: #{token.inspect}) from instance: #{jsi_instance.pretty_inspect.chomp}")
       end
-    end
 
-    # @deprecated
-    alias_method :parents, :parent_jsis
-    # @deprecated
-    alias_method :parent, :parent_jsi
+      begin
+        subinstance_schemas = jsi_subinstance_schemas_memos[token: token, instance: jsi_node_content, subinstance: value]
 
-    # if this JSI is a $ref then the $ref is followed. otherwise this JSI
-    # is returned.
-    #
-    # @yield [JSI::Base] if a block is given (optional), this will yield a deref'd JSI. if this
-    #   JSI 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::Base, self]
-    def deref(&block)
-      node_ptr_deref do |deref_ptr|
-        jsi_from_root = deref_ptr.evaluate(document_root_node)
-        if jsi_from_root.is_a?(JSI::Base)
-          return jsi_from_root.tap(&(block || Util::NOOP))
+        if token_in_range
+          jsi_subinstance_as_jsi(value, subinstance_schemas, as_jsi) do
+            jsi_subinstance_memos[token: token, subinstance_schemas: subinstance_schemas]
+          end
         else
-          # TODO I want to get rid of this ... just return jsi_from_root whatever it is
-          # NOTE when I get rid of this, simplify #parent_jsis too
-          if @ancestor_jsi && @ancestor_jsi.jsi_ptr.contains?(deref_ptr)
-            derefed = self.class.new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: deref_ptr, ancestor_jsi: @ancestor_jsi)
+          if use_default
+            defaults = Set.new
+            subinstance_schemas.each do |subinstance_schema|
+              if subinstance_schema.respond_to?(:to_hash) && subinstance_schema.key?('default')
+                defaults << subinstance_schema['default']
+              end
+            end
+          end
+
+          if use_default && defaults.size == 1
+            # use the default value
+            # we are using #dup so that we get a modified copy of self, in which we set dup[token]=default.
+            dup.tap { |o| o[token] = defaults.first }[token, as_jsi: as_jsi]
           else
-            derefed = self.class.new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: deref_ptr)
+            # I kind of want to just return nil here. the preferred mechanism for
+            # a JSI's default value should be its schema. but returning nil ignores
+            # any value returned by Hash#default/#default_proc. there's no compelling
+            # reason not to support both, so I'll return that.
+            value
           end
-          return derefed.tap(&(block || Util::NOOP))
         end
       end
-      return self
     end
 
-    # yields the content of the underlying instance. the block must result in
-    # a modified copy of that (not destructively modifying the yielded content)
-    # which will be used to instantiate a new instance of this JSI class with
-    # the modified content.
-    # @yield [Object] the content of the instance. the block should result
-    #   in a (nondestructively) modified copy of this.
-    # @return [JSI::Base subclass the same as self] the modified copy of self
-    def modified_copy(&block)
-      if @ancestor_jsi
-        raise(Bug, 'bad @ancestor_jsi') if @ancestor_jsi.object_id == self.object_id
-
-        modified_ancestor = @ancestor_jsi.modified_copy do |anc|
-          mod_anc = @jsi_ptr.ptr_relative_to(@ancestor_jsi.jsi_ptr).modified_document_copy(anc, &block)
-          mod_anc
-        end
-        self.class.new(Base::NOINSTANCE, jsi_document: modified_ancestor.jsi_document, jsi_ptr: @jsi_ptr, ancestor_jsi: modified_ancestor)
+    # assigns the subscript of the instance identified by the given token to the given value.
+    # if the value is a JSI, its instance is assigned instead of the JSI value itself.
+    #
+    # @param token [String, Integer, Object] token identifying the subscript to assign
+    # @param value [JSI::Base, Object] the value to be assigned
+    def []=(token, value)
+      unless respond_to?(:to_hash) || respond_to?(:to_ary)
+        raise(NoMethodError, "cannot assign subscript (using token: #{token.inspect}) to instance: #{jsi_instance.pretty_inspect.chomp}")
+      end
+      if value.is_a?(Base)
+        self[token] = value.jsi_instance
       else
+        jsi_instance[token] = value
+      end
+    end
+
+    # the set of JSI schema modules corresponding to the schemas that describe this JSI
+    # @return [Set<Module>]
+    def jsi_schema_modules
+      jsi_schemas.map(&:jsi_schema_module).to_set.freeze
+    end
+
+    # yields the content of this JSI's instance. the block must result in
+    # a modified copy of the yielded instance (not destructively modifying it)
+    # which will be used to instantiate a new JSI with the modified content.
+    #
+    # the result may have different schemas which describe it than this JSI's schemas,
+    # if conditional applicator schemas apply differently to the modified instance.
+    #
+    # @yield [Object] this JSI's instance. the block should result
+    #   in a nondestructively modified copy of this.
+    # @return [JSI::Base subclass] the modified copy of self
+    def jsi_modified_copy(&block)
+      if @jsi_ptr.root?
         modified_document = @jsi_ptr.modified_document_copy(@jsi_document, &block)
-        self.class.new(Base::NOINSTANCE, jsi_document: modified_document, jsi_ptr: @jsi_ptr)
+        self.class.new(Base::NOINSTANCE,
+          jsi_document: modified_document,
+          jsi_ptr: @jsi_ptr,
+          jsi_schema_base_uri: @jsi_schema_base_uri,
+          jsi_schema_resource_ancestors: @jsi_schema_resource_ancestors, # this can only be empty but included for consistency
+        )
+      else
+        modified_jsi_root_node = @jsi_root_node.jsi_modified_copy do |root|
+          @jsi_ptr.modified_document_copy(root, &block)
+        end
+        @jsi_ptr.evaluate(modified_jsi_root_node, as_jsi: true)
       end
     end
 
-    # @return [String] the fragment representation of a pointer to this JSI's instance within its document
-    def fragment
-      @jsi_ptr.fragment
+    # validates this JSI's instance against its schemas
+    #
+    # @return [JSI::Validation::FullResult]
+    def jsi_validate
+      jsi_schemas.instance_validate(self)
     end
 
-    # @return [Array<String>] array of schema validation error messages for this instance
-    def fully_validate
-      schema.fully_validate_instance(instance)
+    # whether this JSI's instance is valid against all of its schemas
+    # @return [Boolean]
+    def jsi_valid?
+      jsi_schemas.instance_valid?(self)
     end
 
-    # @return [true, false] whether the instance validates against its schema
+    # @private
+    def fully_validate(errors_as_objects: false)
+      raise(NotImplementedError, "Base#fully_validate removed: see new validation interface Base#jsi_validate")
+    end
+
+    # @private
     def validate
-      schema.validate_instance(instance)
+      raise(NotImplementedError, "Base#validate renamed: see Base#jsi_valid?")
     end
 
-    # @return [true] if this method does not raise, it returns true to
-    #   indicate a valid instance.
-    # @raise [::JSON::Schema::ValidationError] raises if the instance has
-    #   validation errors
+    # @private
     def validate!
-      schema.validate_instance!(instance)
+      raise(NotImplementedError, "Base#validate! removed")
     end
 
     def dup
-      modified_copy(&:dup)
+      jsi_modified_copy(&:dup)
     end
 
-    # @return [String] a string representing this JSI, indicating its class
-    #   and inspecting its instance
+    # a string representing this JSI, indicating any named schemas and inspecting its instance
+    # @return [String]
     def inspect
-      "\#<#{self.class.to_s} #{instance.inspect}>"
+      "\#<#{jsi_object_group_text.join(' ')} #{jsi_instance.inspect}>"
     end
 
-    # pretty-prints a representation this JSI to the given printer
+    # pretty-prints a representation of this JSI to the given printer
     # @return [void]
     def pretty_print(q)
-      q.instance_exec(self) do |obj|
-        text "\#<#{obj.class.to_s}"
-        group_sub {
-          nest(2) {
-            breakable ' '
-            pp obj.instance
-          }
+      q.text '#<'
+      q.text jsi_object_group_text.join(' ')
+      q.group_sub {
+        q.nest(2) {
+          q.breakable ' '
+          q.pp jsi_instance
         }
-        breakable ''
-        text '>'
-      end
-    end
-
-    # @return [String] the instance's object_group_text
-    def object_group_text
-      instance.respond_to?(:object_group_text) ? instance.object_group_text : instance.class.inspect
-    end
-
-    # @return [Object] a jsonifiable representation of the instance
-    def as_json(*opt)
-      Typelike.as_json(instance, *opt)
-    end
-
-    # @return [Object] an opaque fingerprint of this JSI for FingerprintHash. JSIs are equal
-    #   if their instances are equal, and if the JSIs are of the same JSI class or subclass.
-    def fingerprint
-      {class: jsi_class, jsi_document: jsi_document, jsi_ptr: jsi_ptr}
+      }
+      q.breakable ''
+      q.text '>'
     end
-    include FingerprintHash
 
-    private
-
-    # assigns a subscript, unwrapping a JSI if given.
-    # @param subscript [Object] the bit between the [ and ]
-    # @param value [JSI::Base, Object] the value to be assigned
-    def subscript_assign(subscript, value)
-      clear_memo(:[])
-      if value.is_a?(Base)
-        instance[subscript] = value.instance
-      else
-        instance[subscript] = value
-      end
-    end
-
-    # this is an instance method in order to allow subclasses of JSI classes to
-    # override it to point to other subclasses corresponding to other schemas.
-    def class_for_schema(schema)
-      JSI.class_for_schema(schema)
-    end
-  end
-
-  # module extending a {JSI::Base} object when its instance is Hash-like (responds to #to_hash)
-  module BaseHash
-    include PathedHashNode
-
-    alias_method :jsi_instance_hash_pubsend, :node_content_hash_pubsend
-
-    # @param property_name [String, Object] the property name to subscript
-    # @return [JSI::Base, Object] the instance's subscript value at the given
-    #   key property_name_. if there is a subschema defined for that property
-    #   on this JSI's schema, returns the instance's subscript as a JSI
-    #   instiation of that subschema.
-    def [](property_name)
-      instance_property_key_ = jsi_instance_hash_pubsend(:key?, property_name)
-      if !instance_property_key_
-        deref do |deref_jsi|
-          return deref_jsi[property_name]
+    # @private
+    # @return [Array<String>]
+    def jsi_object_group_text
+      class_name = self.class.name unless self.class.in_schema_classes
+      class_txt = begin
+        if class_name
+          # ignore ID
+          schema_module_names = jsi_schemas.map { |schema| schema.jsi_schema_module.name }.compact
+          if schema_module_names.empty?
+            class_name
+          else
+            "#{class_name} (#{schema_module_names.join(', ')})"
+          end
+        else
+          schema_names = jsi_schemas.map { |schema| schema.jsi_schema_module.name_from_ancestor || schema.schema_uri }.compact
+          if schema_names.empty?
+            "JSI"
+          else
+            "JSI (#{schema_names.join(', ')})"
+          end
         end
       end
-      instance_property_value_ = jsi_instance_sub(property_name)
-      memoize(:[], property_name, instance_property_value_, instance_property_key_) do |property_name_, instance_property_value, instance_property_key|
-        begin
-          property_schema = schema.subschema_for_property(property_name_)
-          property_schema = property_schema && property_schema.match_to_instance(instance_property_value)
 
-          if !instance_property_key && property_schema && property_schema.schema_object.key?('default')
-            # use the default value
-            default = property_schema.schema_object['default']
-            if default.respond_to?(:to_hash) || default.respond_to?(:to_ary)
-              # we are using #dup so that we get a modified copy of self, in which we set dup[property_name_]=default.
-              # this avoids duplication of code with #modified_copy and below in #[] to handle pathing and such.
-              dup.tap { |o| o[property_name_] = default }[property_name_]
-            else
-              default
-            end
-          elsif property_schema && (instance_property_value.respond_to?(:to_hash) || instance_property_value.respond_to?(:to_ary))
-            class_for_schema(property_schema).new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: @jsi_ptr[property_name_], ancestor_jsi: @ancestor_jsi || self)
-          else
-            instance_property_value
-          end
+      if (is_a?(PathedArrayNode) || is_a?(PathedHashNode)) && ![Array, Hash].include?(jsi_node_content.class)
+        if jsi_node_content.respond_to?(:jsi_object_group_text)
+          content_txt = jsi_node_content.jsi_object_group_text
+        else
+          content_txt = [jsi_node_content.class.to_s]
         end
+      else
+        content_txt = []
       end
-    end
 
-    # assigns the given property name of the instance to the given value.
-    # if the value is a JSI, its instance is assigned.
-    # @param property_name [Object] this should generally be a String, but JSI
-    #   does not enforce any constraint on it.
-    # @param value [Object] the value to be assigned to the given subscript
-    #   property_name
-    def []=(property_name, value)
-      subscript_assign(property_name, value)
+      [
+        class_txt,
+        is_a?(Metaschema) ? "Metaschema" : is_a?(Schema) ? "Schema" : nil,
+        *content_txt,
+      ].compact
     end
 
-    private
-
-    # @param token [String, Object]
+    # a jsonifiable representation of the instance
     # @return [Object]
-    def jsi_instance_sub(token)
-      jsi_instance_hash_pubsend(:[], token)
+    def as_json(*opt)
+      Typelike.as_json(jsi_instance, *opt)
     end
-  end
-
-  # module extending a {JSI::Base} object when its instance is Array-like (responds to #to_ary)
-  module BaseArray
-    include PathedArrayNode
 
-    alias_method :jsi_instance_ary_pubsend, :node_content_ary_pubsend
+    # an opaque fingerprint of this JSI for {Util::FingerprintHash}.
+    def jsi_fingerprint
+      {
+        class: jsi_class,
+        jsi_document: jsi_document,
+        jsi_ptr: jsi_ptr,
+        # for instances in documents with schemas:
+        jsi_resource_ancestor_uri: jsi_resource_ancestor_uri,
+        # only defined for JSI::Schema instances:
+        jsi_schema_instance_modules: is_a?(Schema) ? jsi_schema_instance_modules : nil,
+      }
+    end
+    include Util::FingerprintHash
 
-    # @param i [Integer] the array index to subscript
-    # @return [JSI::Base, Object] the instance's subscript value at the given index
-    #   i. if there is a subschema defined for that index on this JSI's schema,
-    #   returns the instance's subscript as a JSI instiation of that subschema.
-    def [](i)
-      memoize(:[], i, jsi_instance_sub(i), jsi_instance_ary_pubsend(:each_index).to_a.include?(i)) do |i_, instance_idx_value, i_in_range|
-        begin
-          index_schema = schema.subschema_for_index(i_)
-          index_schema = index_schema && index_schema.match_to_instance(instance_idx_value)
+    private
 
-          if !i_in_range && index_schema && index_schema.schema_object.key?('default')
-            # use the default value
-            default = index_schema.schema_object['default']
-            if default.respond_to?(:to_hash) || default.respond_to?(:to_ary)
-              # we are using #dup so that we get a modified copy of self, in which we set dup[i]=default.
-              # this avoids duplication of code with #modified_copy and below in #[] to handle pathing and such.
-              dup.tap { |o| o[i_] = default }[i_]
-            else
-              default
+    def jsi_subinstance_schemas_memos
+      jsi_memomap(:subinstance_schemas, key_by: -> (i) { i[:token] }) do |token: , instance: , subinstance: |
+        SchemaSet.build do |schemas|
+          jsi_schemas.each do |schema|
+            schema.each_child_applicator_schema(token, instance) do |child_app_schema|
+              child_app_schema.each_inplace_applicator_schema(subinstance) do |child_inpl_app_schema|
+                schemas << child_inpl_app_schema
+              end
             end
-          elsif index_schema && (instance_idx_value.respond_to?(:to_hash) || instance_idx_value.respond_to?(:to_ary))
-            class_for_schema(index_schema).new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: @jsi_ptr[i_], ancestor_jsi: @ancestor_jsi || self)
-          else
-            instance_idx_value
           end
         end
       end
     end
 
-    # assigns the given index of the instance to the given value.
-    # if the value is a JSI, its instance is assigned.
-    # @param i [Object] the array index to assign
-    # @param value [Object] the value to be assigned to the given subscript i
-    def []=(i, value)
-      subscript_assign(i, value)
+    def jsi_subinstance_memos
+      jsi_memomap(:subinstance, key_by: -> (i) { i[:token] }) do |token: , subinstance_schemas: |
+        JSI::SchemaClasses.class_for_schemas(subinstance_schemas).new(Base::NOINSTANCE,
+          jsi_document: @jsi_document,
+          jsi_ptr: @jsi_ptr[token],
+          jsi_root_node: @jsi_root_node,
+          jsi_schema_base_uri: jsi_resource_ancestor_uri,
+          jsi_schema_resource_ancestors: is_a?(Schema) ? jsi_subschema_resource_ancestors : jsi_schema_resource_ancestors,
+        )
+      end
     end
 
-    private
+    def jsi_subinstance_as_jsi(value, subinstance_schemas, as_jsi)
+      value_as_jsi = if [true, false].include?(as_jsi)
+        as_jsi
+      elsif as_jsi == :auto
+        complex_value = subinstance_schemas.any? && (value.respond_to?(:to_hash) || value.respond_to?(:to_ary))
+        schema_value = subinstance_schemas.any? { |subinstance_schema| subinstance_schema.describes_schema? }
+        complex_value || schema_value
+      else
+        raise(ArgumentError, "as_jsi must be one of: :auto, true, false")
+      end
 
-    # @param token [Integer]
-    # @return [Object]
-    def jsi_instance_sub(token)
-      jsi_instance_ary_pubsend(:[], token)
+      if value_as_jsi
+        yield
+      else
+        value
+      end
     end
   end
 end