jsi 0.6.0 → 0.7.0

data/lib/jsi/schema.rb

@@ -8,12 +8,12 @@ module JSI
   module Schema
     autoload :Application, 'jsi/schema/application'
     autoload :Validation, 'jsi/schema/validation'
+
     autoload :Issue, 'jsi/schema/issue'
+    autoload :Ref, 'jsi/schema/ref'
 
     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'
@@ -34,7 +34,7 @@ module JSI
       # 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)
+        if keyword?('$id') && schema_content['$id'].respond_to?(:to_str)
           schema_content['$id']
         else
           nil
@@ -47,7 +47,7 @@ module JSI
       # 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)
+        if keyword?('id') && schema_content['id'].respond_to?(:to_str)
           schema_content['id']
         else
           nil
@@ -147,8 +147,8 @@ module JSI
       # @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.
+      # @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.
       def new_schema(schema_content,
           uri: nil
       )
@@ -176,7 +176,7 @@ module JSI
       # @return [nil, #new_schema]
       def default_metaschema
         return @default_metaschema if instance_variable_defined?(:@default_metaschema)
-        return JSONSchemaOrgDraft07
+        return nil
       end
 
       # sets an application-wide default metaschema used by {JSI.new_schema}
@@ -209,8 +209,8 @@ module JSI
       # `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.
+      # will be raised. schemas which describe schemas must include JSI::Schema in their
+      # {Schema#jsi_schema_module}.
       #
       # @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.
@@ -218,7 +218,8 @@ module JSI
       # @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
+      # @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)
         default_metaschema_new_schema = -> {
           default_metaschema ||= JSI::Schema.default_metaschema
@@ -241,7 +242,10 @@ module JSI
         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)
+          if schema_object.key?('$schema')
+            unless schema_object['$schema'].respond_to?(:to_str)
+              raise(ArgumentError, "given schema_object 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")
@@ -257,12 +261,6 @@ module JSI
         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
@@ -279,10 +277,11 @@ module JSI
 
             result_schema_schemas = schema.jsi_schemas + reinstantiate_as
 
-            result_schema_class = JSI::SchemaClasses.class_for_schemas(result_schema_schemas)
+            result_schema_class = JSI::SchemaClasses.class_for_schemas(result_schema_schemas,
+              includes: SchemaClasses.includes_for(schema.jsi_node_content)
+            )
 
-            result_schema_class.new(Base::NOINSTANCE,
-              jsi_document: schema.jsi_document,
+            result_schema_class.new(schema.jsi_document,
               jsi_ptr: schema.jsi_ptr,
               jsi_root_node: schema.jsi_root_node,
               jsi_schema_base_uri: schema.jsi_schema_base_uri,
@@ -299,18 +298,25 @@ module JSI
     end
 
     # 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
+    # this is an alias for {Base#jsi_node_content}, named for clarity in the context of working with
     # a schema.
     def schema_content
       jsi_node_content
     end
 
+    # does this schema contain the given keyword?
+    # @return [Boolean]
+    def keyword?(keyword)
+      schema_content = jsi_node_content
+      schema_content.respond_to?(:to_hash) && schema_content.key?(keyword)
+    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)
+          jsi_schema_base_uri.join(id_without_fragment)
         elsif id_without_fragment.absolute?
           id_without_fragment
         else
@@ -345,10 +351,10 @@ module JSI
       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
+        resource.schema_absolute_uri
       end
 
-      anchored = self.anchor
+      anchored = respond_to?(:anchor) ? anchor : nil
       parent_schemas.each do |parent_schema|
         if anchored
           if parent_schema.jsi_anchor_subschema(anchor) == self
@@ -358,7 +364,7 @@ module JSI
           end
         end
 
-        relative_ptr = self.jsi_ptr.ptr_relative_to(parent_schema.jsi_ptr)
+        relative_ptr = jsi_ptr.relative_to(parent_schema.jsi_ptr)
         yield parent_schema.schema_absolute_uri.merge(fragment: relative_ptr.fragment)
       end
 
@@ -395,48 +401,80 @@ module JSI
       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
-    )
+    # @return [JSI::Base subclass] a JSI whose instance is the given instance and whose schemas are
+    #   inplace applicator schemas 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 }
+      jsi_schema_module <= JSI::Schema ||
+        # deprecated
+        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}
+    # @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 Set[].freeze
+      return Util::EMPTY_SET
     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)
     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.
+    #
+    # @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.
+        # it is a bug if it was called different times with different schema_implementation_modules, though.
+        unless jsi_schema_module.schema_implementation_modules == schema_implementation_modules
+          raise(ArgumentError, "this schema already describes a schema with different schema_implementation_modules")
+        end
+      else
+        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)
+      end
+
+      extend(DescribesSchema)
+
+      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 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
@@ -458,13 +496,13 @@ 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[Ptr.ary_ptr(subptr)]
+      subschema_map[subptr: Ptr.ary_ptr(subptr)]
     end
 
     private
 
     def subschema_map
-      jsi_memomap(:subschema) do |subptr|
+      jsi_memomap(:subschema) do |subptr: |
         if is_a?(MetaschemaNode::BootstrapSchema)
           self.class.new(
             jsi_document,
@@ -472,7 +510,7 @@ module JSI
             jsi_schema_base_uri: jsi_resource_ancestor_uri,
           )
         else
-          Schema.ensure_schema(subptr.evaluate(self, as_jsi: true), msg: [
+          Schema.ensure_schema(jsi_descendent_node(subptr), msg: [
             "subschema is not a schema at pointer: #{subptr.pointer}"
           ])
         end
@@ -481,37 +519,35 @@ module JSI
 
     public
 
-    # a schema in the same schema resource as this one (see #schema_resource_root) at the given
+    # 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)]
+      resource_root_subschema_map[ptr: Ptr.ary_ptr(ptr)]
     end
 
     private
 
     def resource_root_subschema_map
-      jsi_memomap(:resource_root_subschema_map) do |ptr|
-        schema = self
-        if schema.is_a?(MetaschemaNode::BootstrapSchema)
+      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.
-          schema.class.new(
-            schema.jsi_document,
+          self.class.new(
+            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),
+          Schema.ensure_schema(schema_resource_root.jsi_descendent_node(ptr),
             msg: [
               "subschema is not a schema at pointer: #{ptr.pointer}"
             ],
-            reinstantiate_as: schema.jsi_schemas.select(&:describes_schema?)
+            reinstantiate_as: jsi_schemas.select(&:describes_schema?)
           )
         end
       end
@@ -541,7 +577,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?(JSI::PathedNode)
+      if instance.is_a?(Base)
         instance_ptr = instance.jsi_ptr
         instance_document = instance.jsi_document
       else
@@ -555,49 +591,19 @@ module JSI
     # @param instance [Object] the instance to validate against this schema
     # @return [Boolean]
     def instance_valid?(instance)
-      if instance.is_a?(JSI::PathedNode)
+      if instance.is_a?(Base)
         instance = instance.jsi_node_content
       end
       internal_validate_instance(Ptr[], instance, validate_only: true).valid?
     end
 
-    # @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
-
-    # @private
-    def validate_instance(other_instance)
-      raise(NotImplementedError, "Schema#validate_instance renamed: see Schema#instance_valid?")
-    end
-
-    # @private
-    def validate_instance!(other_instance)
-      raise(NotImplementedError, "Schema#validate_instance! removed")
-    end
-
-    # @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
-
-    # @private
-    def validate_schema
-      raise(NotImplementedError, "Schema#validate_schema removed: use validation interface Base#jsi_valid? on the schema")
-    end
-
-    # @private
-    def validate_schema!
-      raise(NotImplementedError, "Schema#validate_schema! removed")
-    end
-
     # schema resources which are ancestors of any subschemas below this schema.
     # this may include this schema if this is a schema resource root.
-    # @private
+    # @api private
     # @return [Array<JSI::Schema>]
     def jsi_subschema_resource_ancestors
       if schema_resource_root?
-        jsi_schema_resource_ancestors + [self]
+        jsi_schema_resource_ancestors.dup.push(self).freeze
       else
         jsi_schema_resource_ancestors
       end

data/lib/jsi/schema_classes.rb

@@ -24,12 +24,14 @@ module JSI
       end
     end
 
+    alias_method :to_s, :inspect
+
     # invokes {JSI::Schema#new_jsi} on this module's schema, passing the given instance.
     #
     # @param (see JSI::Schema#new_jsi)
     # @return [JSI::Base] a JSI whose instance is the given instance
-    def new_jsi(instance, **kw, &b)
-      schema.new_jsi(instance, **kw, &b)
+    def new_jsi(instance, **kw)
+      schema.new_jsi(instance, **kw)
     end
   end
 
@@ -55,6 +57,9 @@ module JSI
     def new_schema_module(schema_content, **kw)
       schema.new_schema(schema_content, **kw).jsi_schema_module
     end
+
+    # @return [Set<Module>]
+    attr_reader :schema_implementation_modules
   end
 
   # this module is a namespace for building schema classes and schema modules.
@@ -62,18 +67,30 @@ module JSI
     extend Util::Memoize
 
     class << self
+      # @api private
+      # @return [Set<Module>]
+      def includes_for(instance)
+        includes = Set[]
+        includes << Base::ArrayNode if instance.respond_to?(:to_ary)
+        includes << Base::HashNode if instance.respond_to?(:to_hash)
+        includes.freeze
+      end
+
       # a JSI Schema Class which represents the given schemas.
       # an instance of the class is a JSON Schema instance described by all of the given schemas.
-      # @private
+      # @api private
       # @param schemas [Enumerable<JSI::Schema>] schemas which the class will represent
+      # @param includes [Enumerable<Module>] modules which will be included on the class
       # @return [Class subclassing JSI::Base]
-      def class_for_schemas(schemas)
+      def class_for_schemas(schemas, includes: )
         schemas = SchemaSet.ensure_schema_set(schemas)
+        includes = Util.ensure_module_set(includes)
 
-        jsi_memoize(:class_for_schemas, schemas) do |schemas|
-          Class.new(Base).instance_exec(schemas) do |schemas|
+        jsi_memoize(:class_for_schemas, schemas: schemas, includes: includes) do |schemas: , includes: |
+          Class.new(Base).instance_exec(schemas: schemas, includes: includes) do |schemas: , includes: |
             define_singleton_method(:jsi_class_schemas) { schemas }
             define_method(:jsi_schemas) { schemas }
+            includes.each { |m| include(m) }
             schemas.each { |schema| include(schema.jsi_schema_module) }
             jsi_class = self
             define_method(:jsi_class) { jsi_class }
@@ -83,16 +100,16 @@ module JSI
         end
       end
 
-      # @private
       # a subclass of MetaschemaNode::BootstrapSchema with the given modules included
-      # @param modules [Set<Module>] metaschema instance modules
+      # @api private
+      # @param modules [Set<Module>] schema implementation modules
       # @return [Class]
       def bootstrap_schema_class(modules)
         modules = Util.ensure_module_set(modules)
-        jsi_memoize(__method__, modules) do |modules|
-          Class.new(MetaschemaNode::BootstrapSchema).instance_exec(modules) do |modules|
-            define_singleton_method(:metaschema_instance_modules) { modules }
-            define_method(:metaschema_instance_modules) { modules }
+        jsi_memoize(__method__, modules: modules) do |modules: |
+          Class.new(MetaschemaNode::BootstrapSchema) do
+            define_singleton_method(:schema_implementation_modules) { modules }
+            define_method(:schema_implementation_modules) { modules }
             modules.each { |mod| include(mod) }
 
             self
@@ -105,9 +122,9 @@ module JSI
       # @return [Module]
       def module_for_schema(schema)
         Schema.ensure_schema(schema)
-        jsi_memoize(:module_for_schema, schema) do |schema|
-          Module.new.tap do |m|
-            m.module_eval do
+        jsi_memoize(:module_for_schema, schema: schema) do |schema: |
+          Module.new do
+            begin
               define_singleton_method(:schema) { schema }
 
               extend SchemaModule
@@ -117,17 +134,13 @@ module JSI
               end
 
               accessor_module = JSI::SchemaClasses.accessor_module_for_schema(schema,
-                conflicting_modules: Set[JSI::Base, JSI::PathedArrayNode, JSI::PathedHashNode] +
+                conflicting_modules: Set[JSI::Base, JSI::Base::ArrayNode, JSI::Base::HashNode] +
                   schema.jsi_schema_instance_modules,
               )
               include accessor_module
 
               define_singleton_method(:jsi_property_accessors) { accessor_module.jsi_property_accessors }
 
-              if schema.describes_schema?
-                extend DescribesSchemaModule
-              end
-
               @possibly_schema_node = schema
               extend(SchemaModulePossibly)
               schema.jsi_schemas.each do |schema_schema|
@@ -143,6 +156,8 @@ module JSI
 
       # a module of accessors for described property names of the given schema.
       # getters are always defined. setters are defined by default.
+      #
+      # @api private
       # @param schema [JSI::Schema] a schema for which to define accessors for any described property names
       # @param conflicting_modules [Enumerable<Module>] an array of modules (or classes) which
       #   may be used alongside the accessor module. methods defined by any conflicting_module
@@ -151,10 +166,12 @@ module JSI
       # @return [Module]
       def accessor_module_for_schema(schema, conflicting_modules: , setters: true)
         Schema.ensure_schema(schema)
-        jsi_memoize(:accessor_module_for_schema, schema, conflicting_modules, setters) do |schema, conflicting_modules, setters|
-          Module.new.tap do |m|
-            m.module_eval do
-              conflicting_instance_methods = (conflicting_modules + [m]).map do |mod|
+        jsi_memoize(:accessor_module_for_schema, schema: schema, conflicting_modules: conflicting_modules, setters: setters) do |schema: , conflicting_modules: , setters: |
+          Module.new do
+            begin
+              define_singleton_method(:inspect) { '(JSI Schema Accessor Module)' }
+
+              conflicting_instance_methods = conflicting_modules.map do |mod|
                 mod.instance_methods + mod.private_instance_methods
               end.inject(Set.new, &:|)
 
@@ -166,8 +183,8 @@ module JSI
               define_singleton_method(:jsi_property_accessors) { accessors_to_define }
 
               accessors_to_define.each do |property_name|
-                define_method(property_name) do |*a|
-                  self[property_name, *a]
+                define_method(property_name) do |**kw|
+                  self[property_name, **kw]
                 end
                 if setters
                   define_method("#{property_name}=") do |value|
@@ -190,45 +207,55 @@ module JSI
     # a name relative to a named schema module of an ancestor schema.
     # for example, if `Foos = JSI::JSONSchemaOrgDraft07.new_schema_module({'items' => {}})`
     # then the module `Foos.items` will have a name_from_ancestor of `"Foos.items"`
+    # @api private
     # @return [String, nil]
     def name_from_ancestor
-      schema_ancestors = [possibly_schema_node] + possibly_schema_node.jsi_parent_nodes
-      named_parent_schema = schema_ancestors.detect { |jsi| jsi.is_a?(JSI::Schema) && jsi.jsi_schema_module.name }
-
-      return nil unless named_parent_schema
+      named_ancestor_schema, tokens = named_ancestor_schema_tokens
+      return nil unless named_ancestor_schema
 
-      tokens = possibly_schema_node.jsi_ptr.ptr_relative_to(named_parent_schema.jsi_ptr).tokens
-      name = named_parent_schema.jsi_schema_module.name
-      parent = named_parent_schema
+      name = named_ancestor_schema.jsi_schema_module.name
+      ancestor = named_ancestor_schema
       tokens.each do |token|
-        if parent.jsi_schemas.any? { |s| s.jsi_schema_module.jsi_property_accessors.include?(token) }
+        if ancestor.jsi_schemas.any? { |s| s.jsi_schema_module.jsi_property_accessors.include?(token) }
           name += ".#{token}"
         elsif [String, Numeric, TrueClass, FalseClass, NilClass].any? { |m| token.is_a?(m) }
           name += "[#{token.inspect}]"
         else
           return nil
         end
-        parent = parent[token]
+        ancestor = ancestor[token]
       end
       name
     end
 
     # subscripting a JSI schema module or a NotASchemaModule will subscript the node, and
-    # if the result is a JSI::Schema, return the JSI Schema module of that schema; if it is a PathedNode,
+    # if the result is a JSI::Schema, return the JSI Schema module of that schema; if it is a JSI::Base,
     # return a NotASchemaModule; or if it is another value (a basic type), return that value.
     #
     # @param token [Object]
     # @return [Module, NotASchemaModule, Object]
-    def [](token)
+    def [](token, **kw)
+      raise(ArgumentError) unless kw.empty? # TODO remove eventually (keyword argument compatibility)
       sub = @possibly_schema_node[token]
       if sub.is_a?(JSI::Schema)
         sub.jsi_schema_module
-      elsif sub.is_a?(JSI::PathedNode)
+      elsif sub.is_a?(JSI::Base)
         NotASchemaModule.new(sub)
       else
         sub
       end
     end
+
+    private
+
+    # @return [Array<JSI::Schema, Array>, nil]
+    def named_ancestor_schema_tokens
+      schema_ancestors = possibly_schema_node.jsi_ancestor_nodes
+      named_ancestor_schema = schema_ancestors.detect { |jsi| jsi.is_a?(JSI::Schema) && jsi.jsi_schema_module.name }
+      return nil unless named_ancestor_schema
+      tokens = possibly_schema_node.jsi_ptr.relative_to(named_ancestor_schema.jsi_ptr).tokens
+      [named_ancestor_schema, tokens]
+    end
   end
 
   # a JSI Schema Module is a module which represents a schema. a NotASchemaModule represents
@@ -245,14 +272,10 @@ module JSI
   # is another node, a NotASchemaModule for that node is returned. otherwise - when the
   # value is a basic type - that value itself is returned.
   class NotASchemaModule
-    # @param node [JSI::PathedNode]
+    # @param node [JSI::Base]
     def initialize(node)
-      unless node.is_a?(JSI::PathedNode)
-        raise(TypeError, "not JSI::PathedNode: #{node.pretty_inspect.chomp}")
-      end
-      if node.is_a?(JSI::Schema)
-        raise(TypeError, "cannot instantiate NotASchemaModule for a JSI::Schema node: #{node.pretty_inspect.chomp}")
-      end
+      raise(Bug, "node must be JSI::Base: #{node.pretty_inspect.chomp}") unless node.is_a?(JSI::Base)
+      raise(Bug, "node must not be JSI::Schema: #{node.pretty_inspect.chomp}") if node.is_a?(JSI::Schema)
       @possibly_schema_node = node
       node.jsi_schemas.each do |schema|
         extend(JSI::SchemaClasses.accessor_module_for_schema(schema, conflicting_modules: [NotASchemaModule, SchemaModulePossibly], setters: false))
@@ -269,5 +292,7 @@ module JSI
         "(JSI wrapper for Schema Module: #{@possibly_schema_node.jsi_ptr.uri})"
       end
     end
+
+    alias_method :to_s, :inspect
   end
 end

data/lib/jsi/schema_registry.rb

@@ -24,8 +24,8 @@ module JSI
 
     # registers the given resource and/or schema resources it contains in the registry.
     #
-    # each child of the resource (including the resource itself) is registered if it is a schema that
-    # has an absolute URI (generally defined by the '$id' keyword).
+    # each descendent node of the resource (including the resource itself) is registered if it is a schema
+    # that has an absolute URI (generally defined by the '$id' keyword).
     #
     # the given resource itself will be registered, whether or not it is a schema, if it is the root
     # of its document and was instantiated with the option `uri` specified.
@@ -48,7 +48,7 @@ module JSI
         register_single(resource.jsi_schema_base_uri, resource)
       end
 
-      resource.jsi_each_child_node do |node|
+      resource.jsi_each_descendent_node do |node|
         if node.is_a?(JSI::Schema) && node.schema_absolute_uri
           register_single(node.schema_absolute_uri, node)
         end
@@ -89,11 +89,21 @@ module JSI
       uri = Addressable::URI.parse(uri)
       ensure_uri_absolute(uri)
       if @autoload_uris.key?(uri) && !@resources.key?(uri)
-        register(@autoload_uris[uri].call)
+        autoloaded = @autoload_uris[uri].call
+        register(autoloaded)
       end
       registered_uris = @resources.keys
       if !registered_uris.include?(uri)
-        raise(ResourceNotFound, "URI #{uri} is not registered. registered URIs:\n#{registered_uris.join("\n")}")
+        if @autoload_uris.key?(uri)
+          msg = [
+            "URI #{uri} was registered with autoload_uri but the result did not contain a resource with that URI.",
+            "the resource resulting from autoload_uri was:",
+            autoloaded.pretty_inspect.chomp,
+          ]
+        else
+          msg = ["URI #{uri} is not registered. registered URIs:", *registered_uris]
+        end
+        raise(ResourceNotFound, msg.join("\n"))
       end
       @resources[uri]
     end