jsi 0.7.0 → 0.8.1

data/lib/jsi/schema.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
 module JSI
-  # JSI::Schema is a module which extends instances which represent JSON schemas.
+  # JSI::Schema is a module which extends {JSI::Base} 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.
+  # This module is included on the {Schema#jsi_schema_module JSI Schema module} of any schema
+  # that describes other schemas, i.e. is a meta-schema (a {Schema::MetaSchema}).
+  # Therefore, any JSI instance described by a schema which is a {Schema::MetaSchema} is
+  # a schema and is extended by this module.
+  #
+  # The content of an instance which is a JSI::Schema (referred to in this context as schema_content) is
+  # typically a Hash (JSON object) or a boolean.
   module Schema
     autoload :Application, 'jsi/schema/application'
     autoload :Validation, 'jsi/schema/validation'
@@ -62,7 +67,7 @@ module JSI
       # @return [Addressable::URI, nil]
       def id_without_fragment
         if id
-          id_uri = Addressable::URI.parse(id)
+          id_uri = Util.uri(id)
           if id_uri.merge(fragment: nil).empty?
             # fragment-only id is just an anchor
             # e.g. #foo
@@ -74,7 +79,7 @@ module JSI
           elsif id_uri.fragment == ''
             # empty fragment
             # e.g. http://json-schema.org/draft-07/schema#
-            id_uri.merge(fragment: nil)
+            id_uri.merge(fragment: nil).freeze
           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.
@@ -83,7 +88,7 @@ module JSI
             nil
           else
             # e.g. http://localhost:1234/bar#foo
-            id_uri.merge(fragment: nil)
+            id_uri.merge(fragment: nil).freeze
           end
         else
           nil
@@ -94,7 +99,7 @@ module JSI
       # @return [String]
       def anchor
         if id
-          id_uri = Addressable::URI.parse(id)
+          id_uri = Util.uri(id)
           if id_uri.fragment == ''
             nil
           else
@@ -128,139 +133,242 @@ module JSI
       end
     end
 
-    # 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.
+    # This module extends any JSI Schema that is a meta-schema, i.e. it describes schemas.
     #
-    # examples of a schema which describes a schema include the draft JSON Schema metaschemas and
+    # Examples of a meta-schema include the JSON Schema meta-schemas 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.
+    #
+    # Meta-schemas include {JSI::Schema} in their
+    # {Schema#jsi_schema_module JSI Schema module}, so for a schema which is an instance of
+    # JSI::Schema::MetaSchema, instances of that schema are instances of {JSI::Schema} and are schemas.
+    #
+    # A schema is indicated as describing other schemas using the {Schema#describes_schema!} method.
+    module MetaSchema
+      # @return [Set<Module>]
+      attr_reader(:schema_implementation_modules)
+
+      # Instantiates the given schema content as a JSI Schema.
+      #
+      # By default, the schema will be registered with the {JSI.schema_registry}.
+      # This can be controlled by params `register` and `schema_registry`.
+      #
+      # By default, the `schema_content` will have any Symbol keys of Hashes replaced with Strings
+      # (recursively through the document). This is controlled by the param `stringify_symbol_keys`.
+      #
+      # Schemas instantiated with `new_schema` are immutable, their content transformed using
+      # the `to_immutable` param.
       #
-      # 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.
+      # @param schema_content an object to be instantiated as a JSI Schema - typically a Hash
+      # @param uri [#to_str, Addressable::URI] The retrieval URI of the schema document.
+      #   If specified, the root schema will be identified by this URI, in addition
+      #   to any absolute URI declared with an id keyword, for resolution in the `schema_registry`.
       #
-      # the schema will be registered with the `JSI.schema_registry`.
+      #   It is rare that this needs to be specified. Most schemas, if they use absolute URIs, will
+      #   use the `$id` keyword (`id` in draft 4) to specify this. A different retrieval URI is useful
+      #   in unusual cases:
       #
-      # @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] a JSI which is a {JSI::Schema} whose instance is the given `schema_content`
-      #   and whose schemas are this schema's inplace applicators.
+      #     - A schema in the document uses relative URIs for `$id` or `$ref` without an absolute id in an
+      #       ancestor schema - these will be resolved relative to this URI
+      #     - Another schema refers with `$ref` to the schema being instantiated by this retrieval URI,
+      #       rather than an id declared in the schema - the schema is resolvable by this URI in the
+      #       `schema_registry`.
+      # @param register [Boolean] Whether the instantiated schema and any subschemas with absolute URIs
+      #   will be registered in the schema registry indicated by param `schema_registry`.
+      # @param schema_registry [SchemaRegistry, nil] The registry this schema will use.
+      #
+      #   - The schema and subschemas will be registered here with any declared URI,
+      #     unless the `register` param is false.
+      #   - References from within the schema (typically from `$ref` keywords) are resolved using this registry.
+      # @param stringify_symbol_keys [Boolean] Whether the schema content will have any Symbol keys of Hashes
+      #   replaced with Strings (recursively through the document).
+      #   Replacement is done on a copy; the given schema content is not modified.
+      # @param to_immutable (see SchemaSet#new_jsi)
+      # @yield If a block is given, it is evaluated in the context of the schema's JSI schema module
+      #   using [Module#module_exec](https://ruby-doc.org/core/Module.html#method-i-module_exec).
+      # @return [JSI::Base subclass + JSI::Schema] a JSI which is a {JSI::Schema} whose content comes from
+      #   the given `schema_content` and whose schemas are this schema's inplace applicators.
       def new_schema(schema_content,
-          uri: nil
+          uri: nil,
+          register: true,
+          schema_registry: JSI.schema_registry,
+          stringify_symbol_keys: true,
+          to_immutable: DEFAULT_CONTENT_TO_IMMUTABLE,
+          &block
       )
-        schema_jsi = new_jsi(Util.deep_stringify_symbol_keys(schema_content),
+        schema_jsi = new_jsi(schema_content,
           uri: uri,
+          register: register,
+          schema_registry: schema_registry,
+          stringify_symbol_keys: stringify_symbol_keys,
+          to_immutable: to_immutable,
+          mutable: false,
         )
-        JSI.schema_registry.register(schema_jsi)
+
+        schema_jsi.jsi_schema_module_exec(&block) if block
+
         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}.
+      # Instantiates the given schema content as a JSI Schema, passing all params to
+      # {Schema::MetaSchema#new_schema}, and returns its {Schema#jsi_schema_module 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
+      # @return [JSI::SchemaModule] the JSI Schema Module of the instantiated schema
+      def new_schema_module(schema_content, **kw, &block)
+        new_schema(schema_content, **kw, &block).jsi_schema_module
       end
     end
 
     class << self
-      # an application-wide default metaschema set by {default_metaschema=}, used by {JSI.new_schema}
+      def extended(o)
+        super
+        o.send(:jsi_schema_initialize)
+      end
+    end
+  end
+
+  class << self
+      # An application-wide default meta-schema set by {default_metaschema=}, used by {JSI.new_schema}
+      # to instantiate schemas that do not specify their meta-schema using a `$schema` property.
       #
-      # @return [nil, #new_schema]
+      # @return [nil, Base + Schema + Schema::MetaSchema]
       def default_metaschema
-        return @default_metaschema if instance_variable_defined?(:@default_metaschema)
-        return nil
+        @default_metaschema
       end
 
-      # sets an application-wide default metaschema used by {JSI.new_schema}
+      # Sets {default_metaschema} to a schema indicated by the given param.
+      #
+      # @param default_metaschema [Schema::MetaSchema, SchemaModule::MetaSchemaModule, #to_str, nil]
+      #   Indicates the default meta-schema.
+      #   This may be a meta-schema or a meta-schema's schema module (e.g. `JSI::JSONSchemaDraft07`),
+      #   or a URI (as would be in a `$schema` keyword).
       #
-      # @param default_metaschema [#new_schema] the default metaschema. this may be a metaschema or a
-      #   metaschema's schema module (e.g. `JSI::JSONSchemaOrgDraft07`).
+      #   `nil` to unset.
       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
+        @default_metaschema = default_metaschema.nil? ? nil : ensure_metaschema(default_metaschema)
       end
 
-      # instantiates a given schema object as a JSI Schema.
+      # Instantiates the given schema content as a JSI Schema.
+      #
+      # The meta-schema that describes the schema must be indicated:
       #
-      # 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 `schema_registry`
+      #   param (by default {JSI.schema_registry}), and that meta-schema is used. For example:
+      #
+      #   ```ruby
+      #   JSI.new_schema({
+      #     "$schema" => "http://json-schema.org/draft-07/schema#",
+      #     "properties" => ...,
+      #   })
+      #   ```
       #
-      # - 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.
+      #   specifies it. For example:
+      #
+      #   ```ruby
+      #   JSI.new_schema({"properties" => ...}, default_metaschema: JSI::JSONSchemaDraft07)
+      #   ```
+      #
       # - 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.
+      #   {JSI.default_metaschema JSI.default_metaschema} is used,
+      #   if the application has set it. For example:
       #
-      # an ArgumentError is raised if none of these indicate a metaschema to use.
+      #   ```ruby
+      #   JSI.default_metaschema = JSI::JSONSchemaDraft07
+      #   JSI.new_schema({"properties" => ...})
+      #   ```
       #
-      # 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)`
+      # An ArgumentError is raised if none of these indicates a meta-schema to use.
       #
-      # 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 include JSI::Schema in their
-      # {Schema#jsi_schema_module}.
+      # Note that if you are instantiating a schema known to have no `$schema` property, an alternative to
+      # specifying a `default_metaschema` is to call `new_schema` on the
+      # {Schema::MetaSchema#new_schema meta-schema} or its
+      # {SchemaModule::MetaSchemaModule#new_schema schema module}, e.g.
+      # `JSI::JSONSchemaDraft07.new_schema(my_schema_content)`
       #
-      # @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::Base] a JSI which is a {JSI::Schema} whose instance is the given `schema_object`
-      #   and whose schemas are the metaschema's inplace applicators.
-      def new_schema(schema_object, default_metaschema: nil, **kw)
+      # Schemas instantiated with `new_schema` are immutable, their content transformed using
+      # the `to_immutable` param.
+      #
+      # @param schema_content (see Schema::MetaSchema#new_schema)
+      # @param default_metaschema [Schema::MetaSchema, SchemaModule::MetaSchemaModule, #to_str]
+      #   Indicates the meta-schema to use if the given `schema_content` does not have a `$schema` property.
+      #   This may be a meta-schema or a meta-schema's schema module (e.g. `JSI::JSONSchemaDraft07`),
+      #   or a URI (as would be in a `$schema` keyword).
+      # @param uri (see Schema::MetaSchema#new_schema)
+      # @param register (see Schema::MetaSchema#new_schema)
+      # @param schema_registry (see Schema::MetaSchema#new_schema)
+      # @param stringify_symbol_keys (see Schema::MetaSchema#new_schema)
+      # @param to_immutable (see Schema::DescribesSchema#new_schema)
+      # @yield (see Schema::MetaSchema#new_schema)
+      # @return [JSI::Base subclass + JSI::Schema] a JSI which is a {JSI::Schema} whose content comes from
+      #   the given `schema_content` and whose schemas are inplace applicators of the indicated meta-schema
+      def new_schema(schema_content,
+          default_metaschema: nil,
+          # params of Schema::MetaSchema#new_schema have their default values repeated here. delegating in a splat
+          # would remove repetition, but yard doesn't display delegated defaults with its (see X) directive.
+          uri: nil,
+          register: true,
+          schema_registry: JSI.schema_registry,
+          stringify_symbol_keys: true,
+          to_immutable: DEFAULT_CONTENT_TO_IMMUTABLE,
+          &block
+      )
+        new_schema_params = {
+          uri: uri,
+          register: register,
+          schema_registry: schema_registry,
+          stringify_symbol_keys: stringify_symbol_keys,
+          to_immutable: to_immutable,
+        }
         default_metaschema_new_schema = -> {
-          default_metaschema ||= JSI::Schema.default_metaschema
-          if default_metaschema.nil?
+          default_metaschema = if default_metaschema
+            Schema.ensure_metaschema(default_metaschema, name: "default_metaschema")
+          elsif self.default_metaschema
+            self.default_metaschema
+          else
             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}",
+              "When instantiating a schema with no `$schema` property, you must specify its meta-schema by one of these methods:",
+              "- pass the `default_metaschema` param to this method",
+              "  e.g.: JSI.new_schema(..., default_metaschema: JSI::JSONSchemaDraft07)",
+              "- invoke `new_schema` on the appropriate meta-schema or its schema module",
+              "  e.g.: JSI::JSONSchemaDraft07.new_schema(...)",
+              "- set JSI.default_metaschema to an application-wide default meta-schema initially",
+              "  e.g.: JSI.default_metaschema = JSI::JSONSchemaDraft07",
+              "instantiating schema_content: #{schema_content.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)
+          default_metaschema.new_schema(schema_content, **new_schema_params, &block)
         }
-        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')
-            unless schema_object['$schema'].respond_to?(:to_str)
-              raise(ArgumentError, "given schema_object keyword `$schema` is not a string")
+        if schema_content.is_a?(Schema)
+          raise(TypeError, [
+            "Given schema_content is already a JSI::Schema. It cannot be instantiated as the content of a schema.",
+            "given: #{schema_content.pretty_inspect.chomp}",
+          ].join("\n"))
+        elsif schema_content.is_a?(JSI::Base)
+          raise(TypeError, [
+            "Given schema_content is a JSI::Base. It cannot be instantiated as the content of a schema.",
+            "given: #{schema_content.pretty_inspect.chomp}",
+          ].join("\n"))
+        elsif schema_content.respond_to?(:to_hash)
+          id = schema_content['$schema'] || stringify_symbol_keys && schema_content[:'$schema']
+          if id
+            unless id.respond_to?(:to_str)
+              raise(ArgumentError, "given schema_content keyword `$schema` is not a string")
             end
-            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)
+            metaschema = Schema.ensure_metaschema(id, name: '$schema', schema_registry: schema_registry)
+            metaschema.new_schema(schema_content, **new_schema_params, &block)
           else
             default_metaschema_new_schema.call
           end
-        elsif [true, false].include?(schema_object)
-          default_metaschema_new_schema.call
         else
-          raise(TypeError, "cannot instantiate Schema from: #{schema_object.pretty_inspect.chomp}")
+          default_metaschema_new_schema.call
         end
       end
+  end
 
+  self.default_metaschema = nil
+
+  module Schema
+    class << self
       # ensure the given object is a JSI Schema
       #
       # @param schema [Object] the thing the caller wishes to ensure is a Schema
@@ -272,20 +380,25 @@ module JSI
         if schema.is_a?(Schema)
           schema
         else
-          if reinstantiate_as
+          if reinstantiate_as && schema.is_a?(JSI::Base)
             # TODO warn; behavior is undefined and I hate this implementation
 
-            result_schema_schemas = schema.jsi_schemas + reinstantiate_as
+            result_schema_indicated_schemas = SchemaSet.new(schema.jsi_indicated_schemas + reinstantiate_as)
+            result_schema_applied_schemas = result_schema_indicated_schemas.inplace_applicator_schemas(schema.jsi_node_content)
 
-            result_schema_class = JSI::SchemaClasses.class_for_schemas(result_schema_schemas,
-              includes: SchemaClasses.includes_for(schema.jsi_node_content)
+            result_schema_class = JSI::SchemaClasses.class_for_schemas(result_schema_applied_schemas,
+              includes: SchemaClasses.includes_for(schema.jsi_node_content),
+              mutable: schema.jsi_mutable?,
             )
 
             result_schema_class.new(schema.jsi_document,
               jsi_ptr: schema.jsi_ptr,
-              jsi_root_node: schema.jsi_root_node,
+              jsi_indicated_schemas: result_schema_indicated_schemas,
               jsi_schema_base_uri: schema.jsi_schema_base_uri,
               jsi_schema_resource_ancestors: schema.jsi_schema_resource_ancestors,
+              jsi_schema_registry: schema.jsi_schema_registry,
+              jsi_content_to_immutable: schema.jsi_content_to_immutable,
+              jsi_root_node: schema.jsi_ptr.root? ? nil : schema.jsi_root_node, # bad
             )
           else
             raise(NotASchemaError, [
@@ -295,6 +408,40 @@ module JSI
           end
         end
       end
+
+      # Ensures the given param identifies a meta-schema and returns that meta-schema.
+      #
+      # @api private
+      # @param metaschema [Schema::MetaSchema, SchemaModule::MetaSchemaModule, #to_str]
+      # @raise [TypeError] if the param does not indicate a meta-schema
+      # @return [Base + Schema + Schema::MetaSchema]
+      def ensure_metaschema(metaschema, name: nil, schema_registry: JSI.schema_registry)
+        if metaschema.respond_to?(:to_str)
+          schema = Schema::Ref.new(metaschema, schema_registry: schema_registry).deref_schema
+          if !schema.describes_schema?
+            raise(TypeError, [name, "URI indicates a schema that is not a meta-schema: #{metaschema.pretty_inspect.chomp}"].compact.join(" "))
+          end
+          schema
+        elsif metaschema.is_a?(SchemaModule::MetaSchemaModule)
+          metaschema.schema
+        elsif metaschema.is_a?(Schema::MetaSchema)
+          metaschema
+        else
+          raise(TypeError, "#{name || "param"} does not indicate a meta-schema: #{metaschema.pretty_inspect.chomp}")
+        end
+      end
+    end
+
+    if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+      def initialize(*)
+        super
+        jsi_schema_initialize
+      end
+    else
+      def initialize(*, **)
+        super
+        jsi_schema_initialize
+      end
     end
 
     # the underlying JSON data used to instantiate this JSI::Schema.
@@ -316,7 +463,7 @@ module JSI
     def schema_absolute_uri
       if respond_to?(:id_without_fragment) && id_without_fragment
         if jsi_schema_base_uri
-          jsi_schema_base_uri.join(id_without_fragment)
+          jsi_schema_base_uri.join(id_without_fragment).freeze
         elsif id_without_fragment.absolute?
           id_without_fragment
         else
@@ -327,7 +474,7 @@ module JSI
     end
 
     # a nonrelative URI which refers to this schema.
-    # nil if no parent of this schema defines an id.
+    # `nil` if no ancestor 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
@@ -337,9 +484,11 @@ module JSI
     # 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
+      @schema_uris_map[]
+    end
+
+    private def schema_uris_compute(**_) # TODO remove **_ eventually (keyword argument compatibility)
         each_schema_uri.to_a
-      end
     end
 
     # see {#schema_uris}
@@ -350,22 +499,22 @@ module JSI
 
       yield schema_absolute_uri if schema_absolute_uri
 
-      parent_schemas = jsi_subschema_resource_ancestors.reverse_each.select do |resource|
+      ancestor_schemas = jsi_subschema_resource_ancestors.reverse_each.select do |resource|
         resource.schema_absolute_uri
       end
 
       anchored = respond_to?(:anchor) ? anchor : nil
-      parent_schemas.each do |parent_schema|
+      ancestor_schemas.each do |ancestor_schema|
         if anchored
-          if parent_schema.jsi_anchor_subschema(anchor) == self
-            yield parent_schema.schema_absolute_uri.merge(fragment: anchor)
+          if ancestor_schema.jsi_anchor_subschema(anchor) == self
+            yield(ancestor_schema.schema_absolute_uri.merge(fragment: anchor).freeze)
           else
             anchored = false
           end
         end
 
-        relative_ptr = jsi_ptr.relative_to(parent_schema.jsi_ptr)
-        yield parent_schema.schema_absolute_uri.merge(fragment: relative_ptr.fragment)
+        relative_ptr = jsi_ptr.relative_to(ancestor_schema.jsi_ptr)
+        yield(ancestor_schema.schema_absolute_uri.merge(fragment: relative_ptr.fragment).freeze)
       end
 
       nil
@@ -374,9 +523,6 @@ module JSI
     # 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
@@ -386,7 +532,7 @@ module JSI
     #   as `schema.items.jsi_schema_module`.
     # - method .schema which returns this schema.
     #
-    # @return [Module]
+    # @return [SchemaModule]
     def jsi_schema_module
       JSI::SchemaClasses.module_for_schema(self)
     end
@@ -401,57 +547,47 @@ module JSI
       jsi_schema_module.module_exec(*a, **kw, &block)
     end
 
-    # instantiates the given instance as a JSI::Base class for schemas matched from this schema to the
-    # instance.
+    # Instantiates a new JSI whose content comes from the given `instance` param.
+    # This schema indicates the schemas of the JSI - its schemas are inplace
+    # applicators of this schema which apply to the given 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
-    #   inplace applicator schemas matched from this schema.
+    # @param (see SchemaSet#new_jsi)
+    # @return [JSI::Base subclass] a JSI whose content comes from the given instance and whose schemas are
+    #   inplace applicators of 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_module <= JSI::Schema ||
-        # deprecated
-        jsi_schema_instance_modules.any? { |m| m <= JSI::Schema }
+    # @param keyword schema keyword e.g. "$ref", "$schema"
+    # @return [Schema::Ref]
+    def schema_ref(keyword = "$ref")
+      raise(ArgumentError, "keyword not present: #{keyword}") unless keyword?(keyword)
+      @schema_ref_map[keyword: keyword, value: schema_content[keyword]]
     end
 
-    # modules to apply to instances described by this schema. these modules are included
-    # on this schema's {#jsi_schema_module}
-    # @deprecated reopen the jsi_schema_module to include such modules instead, or use describes_schema! if this schema describes a schema
-    # @return [Set<Module>]
-    def jsi_schema_instance_modules
-      return @jsi_schema_instance_modules if instance_variable_defined?(:@jsi_schema_instance_modules)
-      return Util::EMPTY_SET
+    # Does this schema itself describe a schema? I.e. is this schema a meta-schema?
+    # @return [Boolean]
+    def describes_schema?
+      jsi_schema_module <= JSI::Schema || false
     end
 
-    # see {#jsi_schema_instance_modules}
-    #
-    # @deprecated
-    # @return [void]
-    def jsi_schema_instance_modules=(jsi_schema_instance_modules)
-      @jsi_schema_instance_modules = Util.ensure_module_set(jsi_schema_instance_modules)
+    # Is this a JSI Schema?
+    # @return [Boolean]
+    def jsi_is_schema?
+      true
     end
 
-    # indicates that this schema describes a schema.
-    # this schema is extended with {DescribesSchema} and its {#jsi_schema_module} is extended
-    # with {DescribesSchemaModule}, and the JSI Schema Module will include the given modules.
+    # Indicates that this schema describes schemas, i.e. it is a meta-schema.
+    # this schema is extended with {Schema::MetaSchema} and its {#jsi_schema_module} is extended
+    # with {SchemaModule::MetaSchemaModule}, and the JSI Schema Module will include
+    # JSI::Schema and the given modules.
     #
     # @param schema_implementation_modules [Enumerable<Module>] modules which implement the functionality of
     #   the schema to extend schemas described by this schema.
-    #   this must include JSI::Schema (usually indirectly).
     # @return [void]
     def describes_schema!(schema_implementation_modules)
       schema_implementation_modules = Util.ensure_module_set(schema_implementation_modules)
 
-      unless schema_implementation_modules.any? { |mod| mod <= Schema }
-        raise(ArgumentError, "schema_implementation_modules for a schema must include #{Schema}")
-      end
-
       if describes_schema?
         # this schema, or one equal to it, has already had describes_schema! called on it.
         # this is to be avoided, but is not particularly a problem.
@@ -460,29 +596,30 @@ module JSI
           raise(ArgumentError, "this schema already describes a schema with different schema_implementation_modules")
         end
       else
+        jsi_schema_module.include(Schema)
         schema_implementation_modules.each do |mod|
           jsi_schema_module.include(mod)
         end
-        jsi_schema_module.extend(DescribesSchemaModule)
-        jsi_schema_module.instance_variable_set(:@schema_implementation_modules, schema_implementation_modules)
+        jsi_schema_module.extend(SchemaModule::MetaSchemaModule)
       end
 
-      extend(DescribesSchema)
+      @schema_implementation_modules = schema_implementation_modules
+      extend(Schema::MetaSchema)
 
       nil
     end
 
     # a resource containing this schema.
     #
-    # if any parent, or this schema itself, is a schema with an absolute uri (see {#schema_absolute_uri}),
+    # If any ancestor, 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.
+    # If no ancestor schema has an absolute uri, the schema_resource_root is the {Base#jsi_root_node document's 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
+      jsi_subschema_resource_ancestors.last || jsi_root_node
     end
 
     # is this schema the root of a schema resource?
@@ -496,71 +633,89 @@ module JSI
     # @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[subptr: 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
+          subptr = Ptr.ary_ptr(subptr)
           Schema.ensure_schema(jsi_descendent_node(subptr), msg: [
             "subschema is not a schema at pointer: #{subptr.pointer}"
           ])
-        end
-      end
     end
 
-    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: Ptr.ary_ptr(ptr)]
-    end
-
-    private
-
-    def resource_root_subschema_map
-      jsi_memomap(:resource_root_subschema_map) do |ptr: |
-        if 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.
-          self.class.new(
-            jsi_document,
-            jsi_ptr: ptr,
-            jsi_schema_base_uri: nil,
-          )
-        else
+          ptr = Ptr.ary_ptr(ptr)
           Schema.ensure_schema(schema_resource_root.jsi_descendent_node(ptr),
-            msg: [
-              "subschema is not a schema at pointer: #{ptr.pointer}"
-            ],
             reinstantiate_as: jsi_schemas.select(&:describes_schema?)
           )
-        end
+    end
+
+    # a set of inplace applicator schemas of this schema (from $ref, allOf, etc.) which apply to the
+    # given instance.
+    #
+    # the returned set will contain this schema itself, unless this schema contains a $ref keyword.
+    #
+    # @param instance [Object] the instance to check any applicators against
+    # @return [JSI::SchemaSet] matched applicator schemas
+    def inplace_applicator_schemas(instance)
+      SchemaSet.new(each_inplace_applicator_schema(instance))
+    end
+
+    # yields each inplace applicator schema which applies to the given instance.
+    #
+    # @param instance (see #inplace_applicator_schemas)
+    # @param visited_refs [Enumerable<JSI::Schema::Ref>]
+    # @yield [JSI::Schema]
+    # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
+    def each_inplace_applicator_schema(
+        instance,
+        visited_refs: Util::EMPTY_ARY,
+        &block
+    )
+      return to_enum(__method__, instance, visited_refs: visited_refs) unless block
+
+      catch(:jsi_application_done) do
+        internal_inplace_applicate_keywords(instance, visited_refs, &block)
       end
+
+      nil
     end
 
-    public
+    # a set of child applicator subschemas of this schema which apply to the child of the given instance
+    # on the given token.
+    #
+    # @param token [Object] the array index or object property name for the child instance
+    # @param instance [Object] the instance to check any child applicators against
+    # @return [JSI::SchemaSet] child applicator subschemas of this schema for the given token
+    #   of the instance
+    def child_applicator_schemas(token, instance)
+      SchemaSet.new(each_child_applicator_schema(token, instance))
+    end
+
+    # yields each child applicator subschema (from properties, items, etc.) which applies to the child of
+    # the given instance on the given token.
+    #
+    # @param (see #child_applicator_schemas)
+    # @yield [JSI::Schema]
+    # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
+    def each_child_applicator_schema(token, instance, &block)
+      return to_enum(__method__, token, instance) unless block
+
+      internal_child_applicate_keywords(token, instance, &block)
+
+      nil
+    end
 
     # 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
+      @described_object_property_names_map[]
+    end
+
+    private def described_object_property_names_compute(**_) # TODO remove **_ eventually (keyword argument compatibility)
         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)
@@ -569,7 +724,6 @@ module JSI
             property_names.merge(schema_content['required'].to_ary)
           end
         end.freeze
-      end
     end
 
     # validates the given instance against this schema
@@ -577,7 +731,7 @@ module JSI
     # @param instance [Object] the instance to validate against this schema
     # @return [JSI::Validation::Result]
     def instance_validate(instance)
-      if instance.is_a?(Base)
+      if instance.is_a?(SchemaAncestorNode)
         instance_ptr = instance.jsi_ptr
         instance_document = instance.jsi_document
       else
@@ -591,12 +745,58 @@ module JSI
     # @param instance [Object] the instance to validate against this schema
     # @return [Boolean]
     def instance_valid?(instance)
-      if instance.is_a?(Base)
+      if instance.is_a?(SchemaAncestorNode)
         instance = instance.jsi_node_content
       end
       internal_validate_instance(Ptr[], instance, validate_only: true).valid?
     end
 
+    # validates the given instance against this schema
+    #
+    # @private
+    # @param instance_ptr [JSI::Ptr] a pointer to the instance to validate against the schema, in the instance_document
+    # @param instance_document [#to_hash, #to_ary, Object] document containing the instance instance_ptr pointer points to
+    # @param validate_only [Boolean] whether to return a full schema validation result or a simple, validation-only result
+    # @param visited_refs [Enumerable<JSI::Schema::Ref>]
+    # @return [JSI::Validation::Result]
+    def internal_validate_instance(
+        instance_ptr,
+        instance_document,
+        visited_refs: Util::EMPTY_ARY,
+        validate_only: false
+    )
+      if validate_only
+        result = JSI::Validation::VALID
+      else
+        result = JSI::Validation::FullResult.new
+      end
+      result_builder = result.class::Builder.new(
+        result: result,
+        schema: self,
+        instance_ptr: instance_ptr,
+        instance_document: instance_document,
+        validate_only: validate_only,
+        visited_refs: visited_refs,
+      )
+
+      catch(:jsi_validation_result) do
+        # note: true/false are not valid as schemas in draft 4; they are only values of
+        # additionalProperties / additionalItems. since their behavior is undefined, though,
+        # it's fine for them to behave the same as boolean schemas in later drafts.
+        # I don't care about draft 4 to implement a different structuring for that.
+        if schema_content == true
+          # noop
+        elsif schema_content == false
+          result_builder.validate(false, 'instance is not valid against `false` schema')
+        elsif schema_content.respond_to?(:to_hash)
+          internal_validate_keywords(result_builder)
+        else
+          result_builder.schema_error('schema is not a boolean or a JSON object')
+        end
+        result
+      end.freeze
+    end
+
     # schema resources which are ancestors of any subschemas below this schema.
     # this may include this schema if this is a schema resource root.
     # @api private
@@ -608,5 +808,15 @@ module JSI
         jsi_schema_resource_ancestors
       end
     end
+
+    private
+
+    def jsi_schema_initialize
+      @schema_ref_map = jsi_memomap(key_by: proc { |i| i[:keyword] }) do |keyword: , value: |
+        Schema::Ref.new(value, ref_schema: self)
+      end
+      @schema_uris_map = jsi_memomap(&method(:schema_uris_compute))
+      @described_object_property_names_map = jsi_memomap(&method(:described_object_property_names_compute))
+    end
   end
 end