jsi 0.2.0 → 0.6.0

data/lib/jsi/schema.rb

@@ -1,311 +1,606 @@
-require 'jsi/json/node'
+# frozen_string_literal: true
 
 module JSI
-  # JSI::Schema represents a JSON Schema. initialized from a Hash-like schema
-  # object, JSI::Schema is a relatively simple class to abstract useful methods
-  # applied to a JSON Schema.
-  class Schema
-    include Memoize
+  # JSI::Schema is a module which extends instances which represent JSON schemas.
+  #
+  # the content of an instance which is a JSI::Schema (referred to in this context as schema_content) is
+  # expected to be a Hash (JSON object) or a Boolean.
+  module Schema
+    autoload :Application, 'jsi/schema/application'
+    autoload :Validation, 'jsi/schema/validation'
+    autoload :Issue, 'jsi/schema/issue'
 
-    class << self
-      # @param schema_object [#to_hash, Boolean, JSI::Schema] an object to be instantiated as a schema.
-      #   if it's already a schema, it is returned as-is.
-      # @return [JSI::Schema]
-      def from_object(schema_object)
-        if schema_object.is_a?(Schema)
-          schema_object
+    autoload :SchemaAncestorNode, 'jsi/schema/schema_ancestor_node'
+
+    autoload :Ref, 'jsi/schema/ref'
+
+    autoload :Draft04, 'jsi/schema/draft04'
+    autoload :Draft06, 'jsi/schema/draft06'
+    autoload :Draft07, 'jsi/schema/draft07'
+
+    class Error < StandardError
+    end
+
+    # an exception raised when a thing is expected to be a JSI::Schema, but is not
+    class NotASchemaError < Error
+    end
+
+    # an exception raised when we are unable to resolve a schema reference
+    class ReferenceError < StandardError
+    end
+
+    # extends any schema which uses the keyword '$id' to identify its canonical URI
+    module BigMoneyId
+      # the contents of a $id keyword whose value is a string, or nil
+      # @return [#to_str, nil]
+      def id
+        if schema_content.respond_to?(:to_hash) && schema_content['$id'].respond_to?(:to_str)
+          schema_content['$id']
         else
-          new(schema_object)
+          nil
         end
       end
     end
 
-    # initializes a schema from a given JSI::Base, JSI::JSON::Node, or hash. Boolean schemas are
-    # instantiated as their equivalent hash ({} for true and {"not" => {}} for false).
-    #
-    # @param schema_object [JSI::Base, #to_hash, Boolean] the schema
-    def initialize(schema_object)
-      if schema_object.is_a?(JSI::Schema)
-        raise(TypeError, "will not instantiate Schema from another Schema: #{schema_object.pretty_inspect.chomp}")
-      elsif schema_object.is_a?(JSI::PathedNode)
-        @schema_node = JSI.deep_stringify_symbol_keys(schema_object.deref)
-      elsif schema_object.respond_to?(:to_hash)
-        @schema_node = JSI::JSON::Node.new_doc(JSI.deep_stringify_symbol_keys(schema_object))
-      elsif schema_object == true
-        @schema_node = JSI::JSON::Node.new_doc({})
-      elsif schema_object == false
-        @schema_node = JSI::JSON::Node.new_doc({"not" => {}})
-      else
-        raise(TypeError, "cannot instantiate Schema from: #{schema_object.pretty_inspect.chomp}")
+    # extends any schema which uses the keyword 'id' to identify its canonical URI
+    module OldId
+      # the contents of an `id` keyword whose value is a string, or nil
+      # @return [#to_str, nil]
+      def id
+        if schema_content.respond_to?(:to_hash) && schema_content['id'].respond_to?(:to_str)
+          schema_content['id']
+        else
+          nil
+        end
       end
     end
 
-    # @return [JSI::PathedNode] a JSI::PathedNode (JSI::JSON::Node or JSI::Base) for the schema
-    attr_reader :schema_node
-
-    alias_method :schema_object, :schema_node
-
-    # @return [JSI::Base, JSI::JSON::Node, Object] property value from the schema_object
-    # @param property_name [String, Object] property name to access from the schema_object
-    def [](property_name)
-      schema_object[property_name]
-    end
-
-    # @return [String] an absolute id for the schema, with a json pointer fragment
-    def schema_id
-      @schema_id ||= begin
-        # start from schema_node and ascend parents looking for an 'id' property.
-        # append a fragment to that id (appending to an existing fragment if there
-        # is one) consisting of the path from that parent to our schema_node.
-        node_for_id = schema_node
-        path_from_id_node = []
-        done = false
-
-        while !done
-          # TODO: track what parents are schemas. somehow.
-          # look at 'id' if node_for_id is a schema, or the document root.
-          # decide whether to look at '$id' for all parent nodes or also just schemas.
-          if node_for_id.respond_to?(:to_hash)
-            if node_for_id.node_ptr.root? || node_for_id.object_id == schema_node.object_id
-              # I'm only looking at 'id' for the document root and the schema node
-              # until I track what parents are schemas.
-              parent_id = node_for_id['$id'] || node_for_id['id']
-            else
-              # will look at '$id' everywhere since it is less likely to show up outside schemas than
-              # 'id', but it will be better to only look at parents that are schemas for this too.
-              parent_id = node_for_id['$id']
-            end
+    # extends any schema which defines an anchor as a URI fragment in the schema id
+    module IdWithAnchor
+      # a URI for the schema's id, unless the id defines an anchor in its
+      # fragment. nil if the schema defines no id.
+      # @return [Addressable::URI, nil]
+      def id_without_fragment
+        if id
+          id_uri = Addressable::URI.parse(id)
+          if id_uri.merge(fragment: nil).empty?
+            # fragment-only id is just an anchor
+            # e.g. #foo
+            nil
+          elsif id_uri.fragment == nil
+            # no fragment
+            # e.g. http://localhost:1234/bar
+            id_uri
+          elsif id_uri.fragment == ''
+            # empty fragment
+            # e.g. http://json-schema.org/draft-07/schema#
+            id_uri.merge(fragment: nil)
+          elsif jsi_schema_base_uri && jsi_schema_base_uri.join(id_uri).merge(fragment: nil) == jsi_schema_base_uri
+            # the id, resolved against the base uri, consists of the base uri plus an anchor fragment.
+            # so there's no non-fragment id.
+            # e.g. base uri is http://localhost:1234/bar
+            #        and id is http://localhost:1234/bar#foo
+            nil
+          else
+            # e.g. http://localhost:1234/bar#foo
+            id_uri.merge(fragment: nil)
           end
+        else
+          nil
+        end
+      end
 
-          if parent_id || node_for_id.node_ptr.root?
-            done = true
+      # an anchor defined by a non-empty fragment in the id uri
+      # @return [String]
+      def anchor
+        if id
+          id_uri = Addressable::URI.parse(id)
+          if id_uri.fragment == ''
+            nil
           else
-            path_from_id_node.unshift(node_for_id.node_ptr.reference_tokens.last)
-            node_for_id = node_for_id.parent_node
+            id_uri.fragment
           end
-        end
-        if parent_id
-          parent_auri = Addressable::URI.parse(parent_id)
         else
-          node_for_id = schema_node.document_root_node
-          validator = ::JSON::Validator.new(Typelike.as_json(node_for_id), nil)
-          # TODO not good instance_exec'ing into another library's ivars
-          parent_auri = validator.instance_exec { @base_schema }.uri
-        end
-        if parent_auri.fragment
-          # add onto the fragment
-          parent_id_path = JSI::JSON::Pointer.from_fragment('#' + parent_auri.fragment).reference_tokens
-          path_from_id_node = parent_id_path + path_from_id_node
-          parent_auri.fragment = nil
-        #else: no fragment so parent_id good as is
+          nil
         end
-
-        fragment = JSI::JSON::Pointer.new(path_from_id_node).fragment
-        schema_id = parent_auri.to_s + fragment
-
-        schema_id
       end
     end
 
-    # @return [Class subclassing JSI::Base] shortcut for JSI.class_for_schema(schema)
-    def jsi_schema_class
-      JSI.class_for_schema(self)
+    # @private
+    module IntegerAllows0Fraction
+      # is `value` an integer?
+      # @private
+      # @param value
+      # @return [Boolean]
+      def internal_integer?(value)
+        value.is_a?(Integer) || (value.is_a?(Numeric) && value % 1.0 == 0.0)
+      end
     end
 
-    alias_method :schema_class, :jsi_schema_class
+    # @private
+    module IntegerDisallows0Fraction
+      # is `value` an integer?
+      # @private
+      # @param value
+      # @return [Boolean]
+      def internal_integer?(value)
+        value.is_a?(Integer)
+      end
+    end
 
-    # calls #new on the class for this schema with the given arguments. for parameters,
-    # see JSI::Base#initialize documentation.
+    # JSI::Schema::DescribesSchema: a schema which describes another schema. this module
+    # extends a JSI::Schema instance and indicates that JSIs which instantiate the schema
+    # are themselves also schemas.
     #
-    # @return [JSI::Base] a JSI whose schema is this schema and whose instance is the given instance
-    def new_jsi(other_instance, *a, &b)
-      jsi_schema_class.new(other_instance, *a, &b)
+    # examples of a schema which describes a schema include the draft JSON Schema metaschemas and
+    # the OpenAPI schema definition which describes "A deterministic version of a JSON Schema object."
+    module DescribesSchema
+      # instantiates the given schema content as a JSI Schema.
+      #
+      # the schema is instantiated after recursively converting any symbol hash keys in the structure
+      # to strings. note that this is in contrast to {JSI::Schema#new_jsi}, which does not alter its
+      # given instance.
+      #
+      # the schema will be registered with the `JSI.schema_registry`.
+      #
+      # @param schema_content [#to_hash, Boolean] an object to be instantiated as a schema
+      # @param uri [nil, #to_str, Addressable::URI] the URI of the schema document.
+      #   relative URIs within the document are resolved using this uri as their base.
+      #   the result schema will be registered with this URI in the {JSI.schema_registry}.
+      # @return [JSI::Base, JSI::Schema] a JSI whose instance is the given schema_content and whose schemas
+      #   are inplace applicators matched from self to the schema being instantiated.
+      def new_schema(schema_content,
+          uri: nil
+      )
+        schema_jsi = new_jsi(Util.deep_stringify_symbol_keys(schema_content),
+          uri: uri,
+        )
+        JSI.schema_registry.register(schema_jsi)
+        schema_jsi
+      end
+
+      # instantiates a given schema object as a JSI Schema and returns its JSI Schema Module.
+      #
+      # shortcut to chain {#new_schema} + {Schema#jsi_schema_module}.
+      #
+      # @param (see #new_schema)
+      # @return [Module, JSI::SchemaModule] the JSI Schema Module of the schema
+      def new_schema_module(schema_content, **kw)
+        new_schema(schema_content, **kw).jsi_schema_module
+      end
     end
 
-    # if this schema is a oneOf, allOf, anyOf schema, #match_to_instance finds
-    # one of the subschemas that matches the given instance and returns it. if
-    # there are no matching *Of schemas, this schema is returned.
-    #
-    # @param other_instance [Object] the instance to which to attempt to match *Of subschemas
-    # @return [JSI::Schema] a matched subschema, or this schema (self)
-    def match_to_instance(other_instance)
-      # matching oneOf is good here. one schema for one instance.
-      # matching anyOf is okay. there could be more than one schema matched. it's often just one. if more
-      #   than one is a match, you just get the first one.
-      %w(oneOf anyOf).select { |k| schema_node[k].respond_to?(:to_ary) }.each do |someof_key|
-        schema_node[someof_key].map(&:deref).map do |someof_node|
-          someof_schema = self.class.new(someof_node)
-          if someof_schema.validate_instance(other_instance)
-            return someof_schema.match_to_instance(other_instance)
-          end
+    class << self
+      # an application-wide default metaschema set by {default_metaschema=}, used by {JSI.new_schema}
+      #
+      # @return [nil, #new_schema]
+      def default_metaschema
+        return @default_metaschema if instance_variable_defined?(:@default_metaschema)
+        return JSONSchemaOrgDraft07
+      end
+
+      # sets an application-wide default metaschema used by {JSI.new_schema}
+      #
+      # @param default_metaschema [#new_schema] the default metaschema. this may be a metaschema or a
+      #   metaschema's schema module (e.g. `JSI::JSONSchemaOrgDraft07`).
+      def default_metaschema=(default_metaschema)
+        unless default_metaschema.respond_to?(:new_schema)
+          raise(TypeError, "given default_metaschema does not respond to #new_schema")
         end
+        @default_metaschema = default_metaschema
       end
-      return self
-    end
 
-    # @param property_name_ [String] the property for which to find a subschema
-    # @return [JSI::Schema, nil] a subschema from `properties`,
-    #   `patternProperties`, or `additionalProperties` for the given
-    #    property_name
-    def subschema_for_property(property_name_)
-      memoize(:subschema_for_property, property_name_) do |property_name|
-        if schema_object['properties'].respond_to?(:to_hash) && schema_object['properties'][property_name].respond_to?(:to_hash)
-          self.class.new(schema_object['properties'][property_name])
-        else
-          if schema_object['patternProperties'].respond_to?(:to_hash)
-            _, pattern_schema_object = schema_object['patternProperties'].detect do |pattern, _|
-              property_name.to_s =~ Regexp.new(pattern) # TODO map pattern to ruby syntax
+      # instantiates a given schema object as a JSI Schema.
+      #
+      # the metaschema to use to instantiate the schema must be indicated.
+      #
+      # - if the schema object has a `$schema` property, that URI is resolved using the {JSI.schema_registry},
+      #   and that metaschema is used.
+      # - if no `$schema` property is present, the `default_metaschema` param is used, if the caller
+      #   specifies it.
+      # - if no `default_metaschema` param is specified, the application-wide default
+      #   {JSI::Schema.default_metaschema JSI::Schema.default_metaschema} is used,
+      #   if the application has set it.
+      #
+      # an ArgumentError is raised if none of these indicate a metaschema to use.
+      #
+      # note that if you are instantiating a schema known to have no `$schema` property, an alternative to
+      # passing the `default_metaschema` param is to use `.new_schema` on the metaschema or its module, e.g.
+      # `JSI::JSONSchemaOrgDraft07.new_schema(my_schema_object)`
+      #
+      # if the given schema_object is a JSI::Base but not already a JSI::Schema, an error
+      # will be raised. schemas which describe schemas must have JSI::Schema in their
+      # Schema#jsi_schema_instance_modules.
+      #
+      # @param schema_object [#to_hash, Boolean, JSI::Schema] an object to be instantiated as a schema.
+      #   if it's already a JSI::Schema, it is returned as-is.
+      # @param uri (see DescribesSchema#new_schema)
+      # @param default_metaschema [#new_schema] the metaschema to use if the schema_object does not have
+      #   a '$schema' property. this may be a metaschema or a metaschema's schema module
+      #   (e.g. `JSI::JSONSchemaOrgDraft07`).
+      # @return [JSI::Schema] a JSI::Schema representing the given schema_object
+      def new_schema(schema_object, default_metaschema: nil, **kw)
+        default_metaschema_new_schema = -> {
+          default_metaschema ||= JSI::Schema.default_metaschema
+          if default_metaschema.nil?
+            raise(ArgumentError, [
+              "when instantiating a schema with no `$schema` property, you must specify the metaschema.",
+              "you may pass the `default_metaschema` param to this method.",
+              "JSI::Schema.default_metaschema may be set to an application-wide default metaschema.",
+              "you may alternatively use new_schema on the appropriate metaschema or its schema module.",
+              "instantiating schema_object: #{schema_object.pretty_inspect.chomp}",
+            ].join("\n"))
+          end
+          if !default_metaschema.respond_to?(:new_schema)
+            raise(TypeError, "given default_metaschema does not respond to #new_schema: #{default_metaschema.pretty_inspect.chomp}")
+          end
+          default_metaschema.new_schema(schema_object, **kw)
+        }
+        if schema_object.is_a?(Schema)
+          schema_object
+        elsif schema_object.is_a?(JSI::Base)
+          raise(NotASchemaError, "the given schema_object is a JSI::Base, but is not a JSI::Schema: #{schema_object.pretty_inspect.chomp}")
+        elsif schema_object.respond_to?(:to_hash)
+          if schema_object.key?('$schema') && schema_object['$schema'].respond_to?(:to_str)
+            metaschema = Schema::Ref.new(schema_object['$schema']).deref_schema
+            unless metaschema.describes_schema?
+              raise(Schema::ReferenceError, "given schema_object contains a $schema but the resource it identifies does not describe a schema")
             end
+            metaschema.new_schema(schema_object, **kw)
+          else
+            default_metaschema_new_schema.call
           end
-          if pattern_schema_object
-            self.class.new(pattern_schema_object)
+        elsif [true, false].include?(schema_object)
+          default_metaschema_new_schema.call
+        else
+          raise(TypeError, "cannot instantiate Schema from: #{schema_object.pretty_inspect.chomp}")
+        end
+      end
+
+      # @deprecated
+      alias_method :new, :new_schema
+
+      # @deprecated
+      alias_method :from_object, :new_schema
+
+      # ensure the given object is a JSI Schema
+      #
+      # @param schema [Object] the thing the caller wishes to ensure is a Schema
+      # @param msg [#to_s, #to_ary] lines of the error message preceding the pretty-printed schema param
+      #   if the schema param is not a schema
+      # @raise [NotASchemaError] if the schema param is not a schema
+      # @return [Schema] the given schema
+      def ensure_schema(schema, msg: "indicated object is not a schema:", reinstantiate_as: nil)
+        if schema.is_a?(Schema)
+          schema
+        else
+          if reinstantiate_as
+            # TODO warn; behavior is undefined and I hate this implementation
+
+            result_schema_schemas = schema.jsi_schemas + reinstantiate_as
+
+            result_schema_class = JSI::SchemaClasses.class_for_schemas(result_schema_schemas)
+
+            result_schema_class.new(Base::NOINSTANCE,
+              jsi_document: schema.jsi_document,
+              jsi_ptr: schema.jsi_ptr,
+              jsi_root_node: schema.jsi_root_node,
+              jsi_schema_base_uri: schema.jsi_schema_base_uri,
+              jsi_schema_resource_ancestors: schema.jsi_schema_resource_ancestors,
+            )
           else
-            if schema_object['additionalProperties'].respond_to?(:to_hash)
-              self.class.new(schema_object['additionalProperties'])
-            else
-              nil
-            end
+            raise(NotASchemaError, [
+              *msg,
+              schema.pretty_inspect.chomp,
+            ].join("\n"))
           end
         end
       end
     end
 
-    # @param index_ [Integer] the index for which to find a subschema
-    # @return [JSI::Schema, nil] a subschema from `items` or
-    #   `additionalItems` for the given index
-    def subschema_for_index(index_)
-      memoize(:subschema_for_index, index_) do |index|
-        if schema_object['items'].respond_to?(:to_ary)
-          if index < schema_object['items'].size
-            self.class.new(schema_object['items'][index])
-          elsif schema_object['additionalItems'].respond_to?(:to_hash)
-            self.class.new(schema_object['additionalItems'])
-          end
-        elsif schema_object['items'].respond_to?(:to_hash)
-          self.class.new(schema_object['items'])
+    # the underlying JSON data used to instantiate this JSI::Schema.
+    # this is an alias for PathedNode#jsi_node_content, named for clarity in the context of working with
+    # a schema.
+    def schema_content
+      jsi_node_content
+    end
+
+    # the URI of this schema, calculated from our `#id`, resolved against our `#jsi_schema_base_uri`
+    # @return [Addressable::URI, nil]
+    def schema_absolute_uri
+      if respond_to?(:id_without_fragment) && id_without_fragment
+        if jsi_schema_base_uri
+          Addressable::URI.parse(jsi_schema_base_uri).join(id_without_fragment)
+        elsif id_without_fragment.absolute?
+          id_without_fragment
         else
+          # TODO warn / schema_error
           nil
         end
       end
     end
 
-    # @return [Set] any object property names this schema indicates may be
-    #   present on its instances. this includes, if present: keys of this
-    #   schema's "properties" object; entries of this schema's array of
-    #   "required" property keys. if this schema has oneOf/allOf/anyOf
-    #   subschemas, those schemas are checked (recursively) for their
-    #   described object property names.
-    def described_object_property_names
-      memoize(:described_object_property_names) do
-        Set.new.tap do |property_names|
-          if schema_node['properties'].respond_to?(:to_hash)
-            property_names.merge(schema_node['properties'].keys)
-          end
-          if schema_node['required'].respond_to?(:to_ary)
-            property_names.merge(schema_node['required'].to_ary)
-          end
-          # we _could_ look at the properties of 'default' and each 'enum' but ... nah.
-          # we should look at dependencies (TODO).
-          %w(oneOf allOf anyOf).select { |k| schema_node[k].respond_to?(:to_ary) }.each do |schemas_key|
-            schema_node[schemas_key].map(&:deref).map do |someof_node|
-              property_names.merge(self.class.new(someof_node).described_object_property_names)
-            end
+    # a nonrelative URI which refers to this schema.
+    # nil if no parent of this schema defines an id.
+    # see {#schema_uris} for all URIs known to refer to this schema.
+    # @return [Addressable::URI, nil]
+    def schema_uri
+      schema_uris.first
+    end
+
+    # nonrelative URIs (that is, absolute, but possibly with a fragment) which refer to this schema
+    # @return [Array<Addressable::URI>]
+    def schema_uris
+      jsi_memoize(:schema_uris) do
+        each_schema_uri.to_a
+      end
+    end
+
+    # see {#schema_uris}
+    # @yield [Addressable::URI]
+    # @return [Enumerator, nil]
+    def each_schema_uri
+      return to_enum(__method__) unless block_given?
+
+      yield schema_absolute_uri if schema_absolute_uri
+
+      parent_schemas = jsi_subschema_resource_ancestors.reverse_each.select do |resource|
+        resource.is_a?(Schema) && resource.schema_absolute_uri
+      end
+
+      anchored = self.anchor
+      parent_schemas.each do |parent_schema|
+        if anchored
+          if parent_schema.jsi_anchor_subschema(anchor) == self
+            yield parent_schema.schema_absolute_uri.merge(fragment: anchor)
+          else
+            anchored = false
           end
         end
+
+        relative_ptr = self.jsi_ptr.ptr_relative_to(parent_schema.jsi_ptr)
+        yield parent_schema.schema_absolute_uri.merge(fragment: relative_ptr.fragment)
       end
+
+      nil
+    end
+
+    # a module which extends all instances of this schema. this may be opened by the application to add
+    # methods to schema instances.
+    #
+    # this module includes accessor methods for object property names this schema
+    # describes (see {#described_object_property_names}). these accessors wrap {Base#[]} and {Base#[]=}.
+    #
+    # some functionality is also defined on the module itself (its singleton class, not for its instances):
+    #
+    # - the module is extended with {JSI::SchemaModule}, which defines .new_jsi to instantiate instances
+    #   of this schema (see {#new_jsi}).
+    # - properties described by this schema's metaschema are defined as methods to get subschemas' schema
+    #   modules, so for example `schema.jsi_schema_module.items` returns the same module
+    #   as `schema.items.jsi_schema_module`.
+    # - method .schema which returns this schema.
+    #
+    # @return [Module]
+    def jsi_schema_module
+      JSI::SchemaClasses.module_for_schema(self)
+    end
+
+    # Evaluates the given block in the context of this schema's JSI schema module.
+    # Any arguments passed to this method will be passed to the block.
+    # shortcut to invoke [Module#module_exec](https://ruby-doc.org/core/Module.html#method-i-module_exec)
+    # on our {#jsi_schema_module}.
+    #
+    # @return the result of evaluating the block
+    def jsi_schema_module_exec(*a, **kw, &block)
+      jsi_schema_module.module_exec(*a, **kw, &block)
+    end
+
+    # @private @deprecated
+    def jsi_schema_class
+      JSI::SchemaClasses.class_for_schemas(SchemaSet[self])
+    end
+
+    # instantiates the given instance as a JSI::Base class for schemas matched from this schema to the
+    # instance.
+    #
+    # @param instance [Object] the JSON Schema instance to be represented as a JSI
+    # @param uri (see SchemaSet#new_jsi)
+    # @return [JSI::Base subclass] a JSI whose instance is the given instance and whose schemas are matched
+    #   from this schema.
+    def new_jsi(instance,
+        **kw
+    )
+      SchemaSet[self].new_jsi(instance, **kw)
+    end
+
+    # does this schema itself describe a schema?
+    # @return [Boolean]
+    def describes_schema?
+      jsi_schema_instance_modules.any? { |m| m <= JSI::Schema }
+    end
+
+    # modules to apply to instances described by this schema. these modules are included
+    # on this schema's {#jsi_schema_module}
+    # @return [Set<Module>]
+    def jsi_schema_instance_modules
+      return @jsi_schema_instance_modules if instance_variable_defined?(:@jsi_schema_instance_modules)
+      return Set[].freeze
+    end
+
+    # see {#jsi_schema_instance_modules}
+    #
+    # @return [void]
+    def jsi_schema_instance_modules=(jsi_schema_instance_modules)
+      @jsi_schema_instance_modules = Util.ensure_module_set(jsi_schema_instance_modules)
+    end
+
+    # a resource containing this schema.
+    #
+    # if any parent, or this schema itself, is a schema with an absolute uri (see #schema_absolute_uri),
+    # the resource root is the closest schema with an absolute uri.
+    #
+    # if no parent schema has an absolute uri, the schema_resource_root is the root of the document
+    # (our #jsi_root_node). in this case, the resource root may or may not be a schema itself.
+    #
+    # @return [JSI::Base] resource containing this schema
+    def schema_resource_root
+      jsi_subschema_resource_ancestors.reverse_each.detect(&:schema_resource_root?) || jsi_root_node
     end
 
-    def default_value
-      if schema_node.key?('default')
-        if schema_node['default'].respond_to?(:to_ary) || schema_node['default'].respond_to?(:to_hash)
-          schema_class.new(schema_node['default'])
+    # is this schema the root of a schema resource?
+    # @return [Boolean]
+    def schema_resource_root?
+      jsi_ptr.root? || !!schema_absolute_uri
+    end
+
+    # a subschema of this Schema
+    #
+    # @param subptr [JSI::Ptr, #to_ary] a relative pointer, or array of tokens, pointing to the subschema
+    # @return [JSI::Schema] the subschema at the location indicated by subptr. self if subptr is empty.
+    def subschema(subptr)
+      subschema_map[Ptr.ary_ptr(subptr)]
+    end
+
+    private
+
+    def subschema_map
+      jsi_memomap(:subschema) do |subptr|
+        if is_a?(MetaschemaNode::BootstrapSchema)
+          self.class.new(
+            jsi_document,
+            jsi_ptr: jsi_ptr + subptr,
+            jsi_schema_base_uri: jsi_resource_ancestor_uri,
+          )
         else
-          schema_node['default']
+          Schema.ensure_schema(subptr.evaluate(self, as_jsi: true), msg: [
+            "subschema is not a schema at pointer: #{subptr.pointer}"
+          ])
         end
-      else
-        nil
       end
     end
 
-    def default_value?
-      schema_node.key?('default')
+    public
+
+    # a schema in the same schema resource as this one (see #schema_resource_root) at the given
+    # pointer relative to the root of the schema resource.
+    #
+    # @param ptr [JSI::Ptr, #to_ary] a pointer to a schema from our schema resource root
+    # @return [JSI::Schema] the schema pointed to by ptr
+    def resource_root_subschema(ptr)
+      resource_root_subschema_map[Ptr.ary_ptr(ptr)]
     end
 
-    # @return [Array<String>] array of schema validation error messages for
-    #   the given instance against this schema
-    def fully_validate_instance(other_instance)
-      ::JSON::Validator.fully_validate(JSI::Typelike.as_json(schema_node.node_document), JSI::Typelike.as_json(other_instance), fragment: schema_node.node_ptr.fragment)
+    private
+
+    def resource_root_subschema_map
+      jsi_memomap(:resource_root_subschema_map) do |ptr|
+        schema = self
+        if schema.is_a?(MetaschemaNode::BootstrapSchema)
+          # BootstrapSchema does not track jsi_schema_resource_ancestors used by #schema_resource_root;
+          # resource_root_subschema is always relative to the document root.
+          # BootstrapSchema also does not implement jsi_root_node or #[]. we instantiate the ptr directly
+          # rather than as a subschema from the root.
+          schema.class.new(
+            schema.jsi_document,
+            jsi_ptr: ptr,
+            jsi_schema_base_uri: nil,
+          )
+        else
+          resource_root = schema.schema_resource_root
+          Schema.ensure_schema(ptr.evaluate(resource_root, as_jsi: true),
+            msg: [
+              "subschema is not a schema at pointer: #{ptr.pointer}"
+            ],
+            reinstantiate_as: schema.jsi_schemas.select(&:describes_schema?)
+          )
+        end
+      end
     end
 
-    # @return [true, false] whether the given instance validates against this schema
-    def validate_instance(other_instance)
-      ::JSON::Validator.validate(JSI::Typelike.as_json(schema_node.node_document), JSI::Typelike.as_json(other_instance), fragment: schema_node.node_ptr.fragment)
+    public
+
+    # any object property names this schema indicates may be present on its instances.
+    # this includes any keys of this schema's "properties" object and any entries of this schema's
+    # array of "required" property keys.
+    # @return [Set]
+    def described_object_property_names
+      jsi_memoize(:described_object_property_names) do
+        Set.new.tap do |property_names|
+          if schema_content.respond_to?(:to_hash) && schema_content['properties'].respond_to?(:to_hash)
+            property_names.merge(schema_content['properties'].keys)
+          end
+          if schema_content.respond_to?(:to_hash) && schema_content['required'].respond_to?(:to_ary)
+            property_names.merge(schema_content['required'].to_ary)
+          end
+        end.freeze
+      end
     end
 
-    # @return [true] if this method does not raise, it returns true to
-    #   indicate the instance is valid against this schema
-    # @raise [::JSON::Schema::ValidationError] raises if the instance has
-    #   validation errors against this schema
-    def validate_instance!(other_instance)
-      ::JSON::Validator.validate!(JSI::Typelike.as_json(schema_node.node_document), JSI::Typelike.as_json(other_instance), fragment: schema_node.node_ptr.fragment)
+    # validates the given instance against this schema
+    #
+    # @param instance [Object] the instance to validate against this schema
+    # @return [JSI::Validation::Result]
+    def instance_validate(instance)
+      if instance.is_a?(JSI::PathedNode)
+        instance_ptr = instance.jsi_ptr
+        instance_document = instance.jsi_document
+      else
+        instance_ptr = Ptr[]
+        instance_document = instance
+      end
+      internal_validate_instance(instance_ptr, instance_document)
     end
 
-    # @return [Array<String>] array of schema validation error messages for
-    #   this schema, validated against its metaschema. a default metaschema
-    #   is assumed if the schema does not specify a $schema.
-    def fully_validate_schema
-      ::JSON::Validator.fully_validate(JSI::Typelike.as_json(schema_node.node_document), [], fragment: schema_node.node_ptr.fragment, validate_schema: true, list: true)
+    # whether the given instance is valid against this schema
+    # @param instance [Object] the instance to validate against this schema
+    # @return [Boolean]
+    def instance_valid?(instance)
+      if instance.is_a?(JSI::PathedNode)
+        instance = instance.jsi_node_content
+      end
+      internal_validate_instance(Ptr[], instance, validate_only: true).valid?
     end
 
-    # @return [true, false] whether this schema validates against its metaschema
-    def validate_schema
-      ::JSON::Validator.validate(JSI::Typelike.as_json(schema_node.node_document), [], fragment: schema_node.node_ptr.fragment, validate_schema: true, list: true)
+    # @private
+    def fully_validate_instance(other_instance, errors_as_objects: false)
+      raise(NotImplementedError, "Schema#fully_validate_instance removed: see new validation interface Schema#instance_validate")
     end
 
-    # @return [true] if this method does not raise, it returns true to
-    #   indicate this schema is valid against its metaschema
-    # @raise [::JSON::Schema::ValidationError] raises if this schema has
-    #   validation errors against its metaschema
-    def validate_schema!
-      ::JSON::Validator.validate!(JSI::Typelike.as_json(schema_node.node_document), [], fragment: schema_node.node_ptr.fragment, validate_schema: true, list: true)
+    # @private
+    def validate_instance(other_instance)
+      raise(NotImplementedError, "Schema#validate_instance renamed: see Schema#instance_valid?")
     end
 
-    # @return [String] a string for #instance and #pretty_print including the schema_id
-    def object_group_text
-      "schema_id=#{schema_id}"
+    # @private
+    def validate_instance!(other_instance)
+      raise(NotImplementedError, "Schema#validate_instance! removed")
     end
 
-    # @return [String] a string representing this Schema
-    def inspect
-      "\#<#{self.class.inspect} #{object_group_text} #{schema_object.inspect}>"
+    # @private
+    def fully_validate_schema(errors_as_objects: false)
+      raise(NotImplementedError, "Schema#fully_validate_schema removed: use validation interface Base#jsi_validate on the schema")
     end
-    alias_method :to_s, :inspect
 
-    # pretty-prints a representation this Schema to the given printer
-    # @return [void]
-    def pretty_print(q)
-      q.instance_exec(self) do |obj|
-        text "\#<#{obj.class.inspect} #{obj.object_group_text}"
-        group_sub {
-          nest(2) {
-            breakable ' '
-            pp obj.schema_object
-          }
-        }
-        breakable ''
-        text '>'
-      end
+    # @private
+    def validate_schema
+      raise(NotImplementedError, "Schema#validate_schema removed: use validation interface Base#jsi_valid? on the schema")
     end
 
-    # @return [Object] returns a jsonifiable representation of this schema
-    def as_json(*opt)
-      Typelike.as_json(schema_object, *opt)
+    # @private
+    def validate_schema!
+      raise(NotImplementedError, "Schema#validate_schema! removed")
     end
 
-    # @return [Object] an opaque fingerprint of this Schema for FingerprintHash
-    def fingerprint
-      {class: self.class, schema_ptr: schema_node.node_ptr, schema_document: JSI::Typelike.as_json(schema_node.node_document)}
+    # schema resources which are ancestors of any subschemas below this schema.
+    # this may include this schema if this is a schema resource root.
+    # @private
+    # @return [Array<JSI::Schema>]
+    def jsi_subschema_resource_ancestors
+      if schema_resource_root?
+        jsi_schema_resource_ancestors + [self]
+      else
+        jsi_schema_resource_ancestors
+      end
     end
-    include FingerprintHash
   end
 end