jsi 0.2.1 → 0.3.0

data/README.md

@@ -3,11 +3,11 @@
 [![Build Status](https://travis-ci.org/notEthan/jsi.svg?branch=master)](https://travis-ci.org/notEthan/jsi)
 [![Coverage Status](https://coveralls.io/repos/github/notEthan/jsi/badge.svg)](https://coveralls.io/github/notEthan/jsi)
 
-JSI offers an Object-Oriented representation for JSON data using JSON Schemas. Given your JSON Schemas, JSI constructs Ruby classes which are used to instantiate your JSON data. These classes let you use JSON with all the niceties of OOP such as property accessors and application-defined instance methods.
+JSI offers an Object-Oriented representation for JSON data using JSON Schemas. Given your JSON Schemas, JSI constructs Ruby modules and classes which are used to instantiate your JSON data. These modules let you use JSON with all the niceties of OOP such as property accessors and application-defined instance methods.
 
 To learn more about JSON Schema see [https://json-schema.org/]().
 
-A JSI class aims to be a fairly unobtrusive wrapper around its instance - "instance" here meaning the JSON data which instantiate the JSON Schema. The instance is usually a Hash or an Array but may be basic types, or in fact any object. A JSI class adds accessors for property names described by its schema, schema validation, and other nice things. Mostly though, you use a JSI as you would use its underlying data, calling the same methods (e.g. `#[]`, `#map`, `#repeated_permutation`) and passing it to anything that duck-types expecting #to_ary or #to_hash.
+A JSI class aims to be a fairly unobtrusive wrapper around its instance - "instance" here meaning the JSON data, usually a Hash or Array, which instantiate the JSON Schema. JSI schema modules and classes add accessors for property names described by its schema, schema validation, and other nice things. Mostly though, you use a JSI as you would use its underlying data, calling the same methods (e.g. `#[]`, `#map`, `#repeated_permutation`) and passing it to anything that duck-types expecting `#to_ary` or `#to_hash`.
 
 ## Example
 
@@ -21,20 +21,27 @@ properties:
   phone:
     type: "array"
     items:
+      description: "A phone number"
       type: "object"
       properties:
         location: {type: "string"}
         number: {type: "string"}
 ```
 
-And here's how you'd normally instantiate the class for that schema using JSI:
+Using that schema, we instantiate a JSI::Schema to represent it:
 
 ```ruby
 # this would usually use a YAML.load/JSON.parse/whatever; it's inlined for copypastability.
-Contact = JSI.class_for_schema({"description" => "A Contact", "type" => "object", "properties" => {"name" => {"type" => "string"}, "phone" => {"type" => "array", "items" => {"type" => "object", "properties" => {"location" => {"type" => "string"}, "number" => {"type" => "string"}}}}}})
+contact_schema = JSI::Schema.new({"description" => "A Contact", "type" => "object", "properties" => {"name" => {"type" => "string"}, "phone" => {"type" => "array", "items" => {"type" => "object", "properties" => {"location" => {"type" => "string"}, "number" => {"type" => "string"}}}}}})
 ```
 
-This definition gives you not just the Contact class, but classes for the whole nested structure. To instantiate it, we need some JSON data (expressed here as YAML)
+We name the module that JSI will use when instantiating a contact. Named modules are better to work with, and JSI will indicate the names of schema modules in its `#inspect` output.
+
+```ruby
+Contact = contact_schema.jsi_schema_module
+```
+
+To instantiate the schema, we need some JSON data (expressed here as YAML)
 
 ```yaml
 name: bill
@@ -48,11 +55,14 @@ So, if we construct an instance like:
 
 ```ruby
 # this would usually use a YAML.load/JSON.parse/whatever; it's inlined for copypastability.
-bill = Contact.new({"name" => "bill", "phone" => [{"location" => "home", "number" => "555"}], "nickname" => "big b"})
-# => #{<Contact Hash>
+bill = Contact.new_jsi({"name" => "bill", "phone" => [{"location" => "home", "number" => "555"}], "nickname" => "big b"})
+# => #{<JSI (Contact)>
 #   "name" => "bill",
-#   "phone" => #[<JSI::SchemaClasses["23d8#/properties/phone"] Array>
-#     #{<JSI::SchemaClasses["23d8#/properties/phone/items"] Hash> "location" => "home", "number" => "555"}
+#   "phone" => #[<JSI>
+#     #{<JSI>
+#       "location" => "home",
+#       "number" => "555"
+#     }
 #   ],
 #   "nickname" => "big b"
 # }
@@ -60,8 +70,6 @@ bill = Contact.new({"name" => "bill", "phone" => [{"location" => "home", "number
 
 Note that the keys are strings. JSI, being designed with JSON in mind, is geared toward string keys. Symbol keys will not match to schema properties, and so act the same as any other key not recognized from the schema.
 
-The nested classes can be seen in the #inspect output as `JSI::SchemaClasses[schema_id]` where schema_id is a generated value.
-
 We get accessors for the Contact:
 
 ```ruby
@@ -86,23 +94,25 @@ bill.validate
 ... and validations on the nested schema instances (#phone here), showing in this example validation failure:
 
 ```ruby
-bad = Contact.new('phone' => [{'number' => [5, 5, 5]}])
-# => #{<Contact Hash>
-#   "phone" => #[<JSI::SchemaClasses["23d8#/properties/phone"] Array>
-#     #{<JSI::SchemaClasses["23d8#/properties/phone/items"] Hash>
-#       "number" => #[<JSI::SchemaClasses["23d8#/properties/phone/items/properties/number"] Array> 5, 5, 5]
+bad = Contact.new_jsi({'phone' => [{'number' => [5, 5, 5]}]})
+# => #{<JSI (Contact)>
+#   "phone" => #[<JSI>
+#     #{<JSI>
+#       "number" => #[<JSI> 5, 5, 5]
 #     }
 #   ]
 # }
 bad.phone.fully_validate
-# => ["The property '#/0/number' of type array did not match the following type: string in schema 23d8"]
+# => ["The property '#/0/number' of type array did not match the following type: string in schema 594126e3"]
 ```
 
 These validations are done by the [`json-schema` gem](https://github.com/ruby-json-schema/json-schema) - JSI does not do validations on its own.
 
-Since the underlying instance is a ruby hash (json object), we can use it like a hash with #[] or, say, #transform_values:
+Since the underlying instance is a ruby hash (json object), we can use it like a hash with `#[]` or, say, `#transform_values`:
 
 ```ruby
+# note that #size here is actually referring to multiple different methods; for name and nickname
+# it is String#size but for phone it is Array#size.
 bill.transform_values(&:size)
 # => {"name" => 4, "phone" => 1, "nickname" => 5}
 bill['nickname']
@@ -115,19 +125,20 @@ There's plenty more JSI has to offer, but this should give you a pretty good ide
 
 - `JSI::Base` is the base class for each JSI class representing a JSON Schema.
 - a "JSI class" is a subclass of `JSI::Base` representing a JSON schema.
+- a "JSI schema module" is a module representing a schema, included on a JSI class.
 - "instance" is a term that is significantly overloaded in this space, so documentation will attempt to be clear what kind of instance is meant:
   - a schema instance refers broadly to a data structure that is described by a JSON schema.
-  - a JSI instance (or just "a JSI") is a ruby object instantiating a JSI class. it has a method #instance which contains the underlying data.
-- a schema refers to a JSON schema. a `JSI::Schema` represents such a schema. a JSI class allows instantiation of a schema as a JSI instance.
+  - a JSI instance (or just "a JSI") is a ruby object instantiating a JSI class. it has a method `#jsi_instance` which contains the underlying data.
+- a schema refers to a JSON schema. `JSI::Schema` is a module which extends schemas. A schema is usually a `JSI::Base` instance, and that schema JSI's schema is a metaschema (see the sections on Metaschemas below).
 
-## JSI classes
+## JSI and Object Oriented Programming
 
-A JSI class (that is, subclass of JSI::Base) is a starting point but obviously you want your own methods, so you reopen the class as you would any other. referring back to the Example section above, we reopen the Contact class:
+Instantiating your schema is a starting point. But, since the major point of object-oriented programming is applying methods to your objects, of course you want to be able to define your own methods. To do this we reopen the JSI module we defined. Referring back to the Example section above, we reopen the `Contact` module:
 
 ```ruby
-class Contact
-  def full_address
-    address.values.join(", ")
+module Contact
+  def phone_numbers
+    phone.map(&:number)
   end
   def name
     super + ' esq.'
@@ -143,15 +154,17 @@ bill.name = 'rob esq.'
 # => "rob esq."
 bill['name']
 # => "rob"
+bill.phone_numbers
+# => ["555"]
 ```
 
-Note the use of `super` - you can call to accessors defined by JSI and make your accessors act as wrappers (these accessor methods are defined on an included module instead of the JSI class for this reason). You can also use [] and []=, of course, with the same effect.
+Note the use of `super` - you can call to accessors defined by JSI and make your accessors act as wrappers. You can alternatively use `[]` and `[]=` with the same effect.
 
-If you want to add methods to a subschema, get the class_for_schema for that schema and open up that class. You can leave the class anonymous, as in this example:
+You can also add methods to a subschema using the same method `#jsi_schema_module` which we used to define the `Contact` module above.
 
 ```ruby
-phone_schema = Contact.schema['properties']['phone']['items']
-JSI.class_for_schema(phone_schema).class_eval do
+phone_schema = Contact.schema.properties['phone'].items
+phone_schema.jsi_schema_module.module_eval do
   def number_with_dashes
     number.split(//).join('-')
   end
@@ -160,11 +173,11 @@ bill.phone.first.number_with_dashes
 # => "5-5-5"
 ```
 
-If you want to name the class, this works:
+If you want to name the module, this works:
 
 ```ruby
-Phone = JSI.class_for_schema(Contact.schema['properties']['phone']['items'])
-class Phone
+ContactPhone = Contact.schema.properties['phone'].items.jsi_schema_module
+module ContactPhone
   def number_with_dashes
     number.split(//).join('-')
   end
@@ -173,15 +186,23 @@ end
 
 Either syntax is slightly cumbersome and a better syntax is in the works.
 
+## Metaschemas
+
+A metaschema is a schema which describes schemas. Likewise, a schema is an instance of a metaschema.
+
+In JSI, a schema is generally a JSI::Base instance whose schema is a metaschema.
+
+A self-descriptive metaschema - most commonly one of the JSON schema draft metaschemas - is an object whose schema is itself. This is instantiated in JSI as a JSI::MetaschemaNode (not a JSI::Base).
+
 ## ActiveRecord serialization
 
 A really excellent place to use JSI is when dealing with serialized columns in ActiveRecord.
 
-Let's say you're sticking to json types in the database - you have to do so if you're using json columns, or json serialization, and if you have dealt with arbitrary yaml- or marshal-serialized objects in ruby, you have probably found that approach has its shortcomings when the implementation of your classes changes.
+Let's say you're sticking to JSON types in the database - you have to do so if you're using JSON columns, or JSON serialization, and if you have dealt with arbitrary yaml- or marshal-serialized objects in ruby, you have probably found that approach has its shortcomings when the implementation of your classes changes.
 
-But if your database contains json, then your deserialized objects in ruby are likewise Hash / Array / basic types. You have to use subscripts instead of accessors, and you don't have any way to add methods to your data types.
+But if your database contains JSON, then your deserialized objects in ruby are likewise Hash / Array / basic types. You have to use subscripts instead of accessors, and you don't have any way to add methods to your data types.
 
-JSI gives you the best of both with JSICoder. This coder dumps objects which are simple json types, and loads instances of a specified JSI class. Here's an example:
+JSI gives you the best of both with JSICoder. This coder dumps objects which are simple JSON types, and loads instances of a specified JSI schema. Here's an example:
 
 ```ruby
 class User < ActiveRecord::Base
@@ -189,7 +210,7 @@ class User < ActiveRecord::Base
 end
 ```
 
-Now `user.contacts` will return an array of Contact instances, from the json type in the database, with Contact's accessors, validations, and user-defined instance methods.
+Now `user.contacts` will return an array of Contact instances, from the JSON type in the database, with Contact's accessors, validations, and user-defined instance methods.
 
 See the gem [`arms`](https://github.com/notEthan/arms) if you wish to serialize the dumped JSON-compatible objects further as text.
 
@@ -203,4 +224,8 @@ Issues and pull requests are welcome on GitHub at https://github.com/notEthan/js
 
 ## License
 
-JSI is open source software available under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+[<img align="right" src="https://github.com/notEthan/jsi/raw/master/resources/icons/AGPL-3.0.png">](https://www.gnu.org/licenses/agpl-3.0.html)
+
+JSI is Open Source Software licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
+
+Unlike the MIT or BSD licenses more commonly used with Ruby gems, this license requires that if you modify JSI and propagate your changes, e.g. by including it in a web application, your modified version must be publicly available. The common path of forking on Github should satisfy this requirement.

data/jsi.gemspec

@@ -6,26 +6,22 @@ Gem::Specification.new do |spec|
   spec.name    = "jsi"
   spec.version = JSI::VERSION
   spec.authors = ["Ethan"]
-  spec.email   = ["ethan@unth.net"]
+  spec.email   = ["ethan.jsi@unth.net"]
 
   spec.summary     = "JSI: JSON Schema Instantiation"
   spec.description = "JSI offers an Object-Oriented representation for JSON data using JSON Schemas"
   spec.homepage    = "https://github.com/notEthan/jsi"
-  spec.license     = "MIT"
-  ignore_files = %w(.gitignore .travis.yml Gemfile test)
-  ignore_files_re = %r{\A(#{ignore_files.map { |f| Regexp.escape(f) }.join('|')})(/|\z)}
-  Dir.chdir(File.expand_path('..', __FILE__)) do
-    spec.files      = `git ls-files -z`.split("\x0").reject { |f| f.match(ignore_files_re) }
-    spec.test_files = `git ls-files -z test`.split("\x0")
-  end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.license     = "AGPL-3.0"
+  ignore_files     = %w(.gitignore .travis.yml Gemfile test)
+  ignore_files_re  = %r{\A(#{ignore_files.map { |f| Regexp.escape(f) }.join('|')})(/|\z)}
+  spec.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(ignore_files_re) }
+  spec.test_files   = `git ls-files -z test`.split("\x0")
   spec.require_paths = ["lib"]
 
   # we are monkey patching json-schema with a fix that has not been merged in a timely fashion.
   spec.add_dependency "json-schema", "~> 2.8"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "minitest"
   spec.add_development_dependency "minitest-around"
   spec.add_development_dependency "minitest-reporters"
   spec.add_development_dependency "scorpio"

data/lib/jsi.rb

@@ -1,6 +1,9 @@
+# frozen_string_literal: true
+
 require "jsi/version"
 require "pp"
 require "set"
+require "pathname"
 require "jsi/json-schema-fragments"
 require "jsi/util"
 
@@ -10,6 +13,9 @@ module JSI
   class Bug < NotImplementedError
   end
 
+  ROOT_PATH = Pathname.new(__FILE__).dirname.parent.expand_path
+  RESOURCES_PATH = ROOT_PATH.join('resources')
+
   autoload :JSON, 'jsi/json'
   autoload :PathedNode, 'jsi/pathed_node'
   autoload :Typelike, 'jsi/typelike_modules'
@@ -19,9 +25,14 @@ module JSI
   autoload :Base, 'jsi/base'
   autoload :BaseArray, 'jsi/base'
   autoload :BaseHash, 'jsi/base'
+  autoload :Metaschema, 'jsi/metaschema'
+  autoload :MetaschemaNode, 'jsi/metaschema_node'
   autoload :SchemaClasses, 'jsi/schema_classes'
   autoload :JSICoder, 'jsi/jsi_coder'
 
+  autoload :JSONSchemaOrgDraft04, 'schemas/json-schema.org/draft-04/schema'
+  autoload :JSONSchemaOrgDraft06, 'schemas/json-schema.org/draft-06/schema'
+
   autoload :SimpleWrap, 'jsi/simple_wrap'
 
   # @return [Class subclassing JSI::Base] a JSI class which represents the

data/lib/jsi/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'jsi/typelike_modules'
 
@@ -16,9 +18,20 @@ module JSI
     include PathedNode
 
     class << self
+      # JSI::Base.new_jsi behaves the same as .new, and is defined for compatibility so you may call #new_jsi
+      # on any of a JSI::Schema, a JSI::SchemaModule, or a JSI schema class.
+      # @return [JSI::Base] a JSI whose instance is the given instance
+      def new_jsi(instance, *a, &b)
+        new(instance, *a, &b)
+      end
+
       # is the constant JSI::SchemaClasses::{self.schema_classes_const_name} defined?
       # (if so, we will prefer to use something more human-readable than that ugly mess.)
-      attr_accessor :in_schema_classes
+      def in_schema_classes
+        # #name sets @in_schema_classes
+        name
+        @in_schema_classes
+      end
 
       # @return [String] absolute schema_id of the schema this class represents.
       #   see {Schema#schema_id}.
@@ -26,46 +39,39 @@ module JSI
         schema.schema_id
       end
 
-      # @return [String] a string representing the class, with schema_id
+      # @return [String] a string representing the class, with schema_id or schema ptr fragment
       def inspect
-        name # see #name for side effects
         if !respond_to?(:schema)
           super
-        elsif in_schema_classes
-          %Q(#{SchemaClasses.inspect}[#{schema_id.inspect}])
-        elsif !name
-          %Q(#<Class for Schema: #{schema_id}>)
         else
-          %Q(#{name} (#{schema_id}))
+          idfrag = schema_id || schema.node_ptr.fragment
+          if name && !in_schema_classes
+            "#{name} (#{idfrag})"
+          else
+            "(JSI Schema Class: #{idfrag})"
+          end
         end
       end
 
-      # @return [String] a string representing the class - a class name if one
-      #   was explicitly defined, otherwise a reference to JSI::SchemaClasses
-      def to_s
-        if !respond_to?(:schema)
-          super
-        elsif !name || name =~ /\AJSI::SchemaClasses::/
-          %Q(#{SchemaClasses.inspect}[#{schema_id.inspect}])
-        else
-          name
-        end
-      end
+      alias_method :to_s, :inspect
 
       # @return [String] a name for a constant for this class, generated from the
       #   schema_id. only used if the class is not assigned to another constant.
       def schema_classes_const_name
-        name = schema.schema_id.gsub(/[^\w]/, '_')
-        name = 'X' + name unless name[/\A[a-zA-Z]/]
-        name = name[0].upcase + name[1..-1]
-        name
+        if schema_id
+          'X' + schema_id.gsub(/[^\w]/, '_')
+        end
       end
 
       # @return [String] a constant name of this class
       def name
-        unless super || SchemaClasses.const_defined?(schema_classes_const_name)
-          SchemaClasses.const_set(schema_classes_const_name, self)
-          self.in_schema_classes = true
+        unless instance_variable_defined?(:@in_schema_classes)
+          if super || !schema_id || SchemaClasses.const_defined?(schema_classes_const_name)
+            @in_schema_classes = false
+          else
+            SchemaClasses.const_set(schema_classes_const_name, self)
+            @in_schema_classes = true
+          end
         end
         super
       end
@@ -87,17 +93,16 @@ module JSI
     # @param jsi_ptr [JSI::JSON::Pointer] for internal use. a JSON pointer specifying
     #   the path of this instance in the `jsi_document` param. `jsi_ptr` must be passed
     #   iff `jsi_document` is passed, i.e. when `instance` is `NOINSTANCE`
-    # @param ancestor_jsi [JSI::Base] for internal use, specifies an ancestor_jsi
-    #   from which this JSI originated to calculate #parents
-    def initialize(instance, jsi_document: nil, jsi_ptr: nil, ancestor_jsi: nil)
+    # @param jsi_root_node [JSI::Base] for internal use, specifies the JSI at the root of the document
+    def initialize(instance, jsi_document: nil, jsi_ptr: nil, jsi_root_node: nil)
       unless respond_to?(:schema)
         raise(TypeError, "cannot instantiate #{self.class.inspect} which has no method #schema. please use JSI.class_for_schema")
       end
 
-      if instance.is_a?(JSI::Base)
-        raise(TypeError, "assigning another JSI::Base instance to #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
-      elsif instance.is_a?(JSI::Schema)
-        raise(TypeError, "assigning a schema to #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
+      if instance.is_a?(JSI::Schema)
+        raise(TypeError, "assigning a schema to a #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
+      elsif instance.is_a?(JSI::Base)
+        raise(TypeError, "assigning another JSI::Base instance to a #{self.class.inspect} instance is incorrect. received: #{instance.pretty_inspect.chomp}")
       end
 
       if instance == NOINSTANCE
@@ -106,33 +111,33 @@ module JSI
           raise(TypeError, "jsi_ptr must be a JSI::JSON::Pointer; got: #{jsi_ptr.inspect}")
         end
         @jsi_ptr = jsi_ptr
-      else
-        raise(Bug, 'incorrect usage') if jsi_document || jsi_ptr || ancestor_jsi
-        if instance.is_a?(PathedNode)
-          @jsi_document = instance.document_root_node
-          # this can result in the unusual situation where ancestor_jsi is nil, though jsi_ptr is not root.
-          # #document_root_node will then return a JSI::JSON::Pointer instead of a root JSI.
-          @jsi_ptr = instance.node_ptr
+        if @jsi_ptr.root?
+          raise(Bug, "jsi_root_node cannot be specified for root JSI") if jsi_root_node
+          @jsi_root_node = self
         else
-          @jsi_document = instance
-          @jsi_ptr = JSI::JSON::Pointer.new([])
-        end
-      end
-      if ancestor_jsi
-        if !ancestor_jsi.is_a?(JSI::Base)
-          raise(TypeError, "ancestor_jsi must be a JSI::Base; got: #{ancestor_jsi.inspect}")
-        end
-        if !ancestor_jsi.jsi_ptr.contains?(@jsi_ptr)
-          raise(Bug, "ancestor_jsi ptr #{ancestor_jsi.jsi_ptr.inspect} is not ancestor of #{@jsi_ptr.inspect}")
+          if !jsi_root_node.is_a?(JSI::Base)
+            raise(TypeError, "jsi_root_node must be a JSI::Base; got: #{jsi_root_node.inspect}")
+          end
+          if !jsi_root_node.jsi_ptr.root?
+            raise(Bug, "jsi_root_node ptr #{jsi_root_node.jsi_ptr.inspect} is not root")
+          end
+          @jsi_root_node = jsi_root_node
         end
+      else
+        raise(Bug, 'incorrect usage') if jsi_document || jsi_ptr || jsi_root_node
+        @jsi_document = instance
+        @jsi_ptr = JSI::JSON::Pointer.new([])
+        @jsi_root_node = self
       end
-      @ancestor_jsi = ancestor_jsi
 
       if self.jsi_instance.respond_to?(:to_hash)
         extend BaseHash
       elsif self.jsi_instance.respond_to?(:to_ary)
         extend BaseArray
       end
+      if self.schema.describes_schema?
+        extend JSI::Schema
+      end
     end
 
     # document containing the instance of this JSI
@@ -141,11 +146,12 @@ module JSI
     # JSI::JSON::Pointer pointing to this JSI's instance within the jsi_document
     attr_reader :jsi_ptr
 
-    # a JSI which is an ancestor_jsi of this
-    attr_reader :ancestor_jsi
+    # the JSI at the root of this JSI's document
+    attr_reader :jsi_root_node
 
     alias_method :node_document, :jsi_document
     alias_method :node_ptr, :jsi_ptr
+    alias_method :document_root_node, :jsi_root_node
 
     # the instance of the json-schema
     alias_method :jsi_instance, :node_content
@@ -154,27 +160,18 @@ module JSI
     # each is overridden by BaseHash or BaseArray when appropriate. the base
     # #each is not actually implemented, along with all the methods of Enumerable.
     def each
-      raise NoMethodError, "Enumerable methods and #each not implemented for instance that is not like a hash or array: #{instance.pretty_inspect.chomp}"
+      raise NoMethodError, "Enumerable methods and #each not implemented for instance that is not like a hash or array: #{jsi_instance.pretty_inspect.chomp}"
     end
 
-    # an array of JSI instances above this one in the document. empty if this
-    # JSI does not have a known ancestor.
+    # an array of JSI instances above this one in the document.
     #
     # @return [Array<JSI::Base>]
     def parent_jsis
-      ancestor_jsi = @ancestor_jsi || self
-      parent = ancestor_jsi
-
-      (ancestor_jsi.jsi_ptr.reference_tokens.size...self.jsi_ptr.reference_tokens.size).map do |i|
-        current = parent
-        parent = parent[self.jsi_ptr.reference_tokens[i]]
-        if current.is_a?(JSI::Base)
-          current
-        else
-          # sometimes after a deref, we may end up with parents whose schema we do not know.
-          # TODO this is kinda crap; hopefully we can remove it along with deref instantiating
-          # a deref ptr as the same JSI class it is
-          SimpleWrap.new(NOINSTANCE, jsi_document: jsi_document, jsi_ptr: jsi_ptr.take(i), ancestor_jsi: @ancestor_jsi)
+      parent = jsi_root_node
+
+      jsi_ptr.reference_tokens.map do |token|
+        parent.tap do
+          parent = parent[token]
         end
       end.reverse
     end
@@ -186,40 +183,84 @@ module JSI
       parent_jsis.first
     end
 
-    # @return [JSI::PathedNode] a pathed node at the root of the document. this is generally a JSI::Base
-    #   but may be a JSI::JSON::Node in unusual circumstances.
-    def document_root_node
-      if @jsi_ptr.root?
-        self
-      elsif @ancestor_jsi
-        @ancestor_jsi.document_root_node
-      elsif instance.is_a?(PathedNode)
-        instance.document_root_node
+    alias_method :parent_node, :parent_jsi
+
+    # @deprecated
+    alias_method :parents, :parent_jsis
+    # @deprecated
+    alias_method :parent, :parent_jsi
+
+    # @param token [String, Integer, Object] the token to subscript
+    # @return [JSI::Base, Object] the instance's subscript value at the given token.
+    #   if there is a subschema defined for that token on this JSI's schema,
+    #   returns that value as a JSI instantiation of that subschema.
+    def [](token)
+      if respond_to?(:to_hash)
+        token_in_range = node_content_hash_pubsend(:key?, token)
+        value = node_content_hash_pubsend(:[], token)
+      elsif respond_to?(:to_ary)
+        token_in_range = node_content_ary_pubsend(:each_index).include?(token)
+        value = node_content_ary_pubsend(:[], token)
       else
-        JSI::JSON::Node.new_doc(@jsi_document)
+        raise(NoMethodError, "cannot subcript (using token: #{token.inspect}) from instance: #{jsi_instance.pretty_inspect.chomp}")
       end
-    end
 
-    # @return [JSI::PathedNode]
-    def parent_node
-      if @jsi_ptr.root?
-        nil
-      elsif @ancestor_jsi
-        parent_jsis.first.tap do |parent_node|
-          raise(Bug, 'is @ancestor_jsi == self? it should not be') if parent_node.nil?
-          raise(Bug, "parent_node not PathedNode: #{parent_node.pretty_inspect.chomp}") unless parent_node.is_a?(JSI::PathedNode)
+      jsi_memoize(:[], token, value, token_in_range) do |token, value, token_in_range|
+        if respond_to?(:to_ary)
+          token_schema = schema.subschema_for_index(token)
+        else
+          token_schema = schema.subschema_for_property(token)
+        end
+        token_schema = token_schema && token_schema.match_to_instance(value)
+
+        if token_in_range
+          complex_value = token_schema && (value.respond_to?(:to_hash) || value.respond_to?(:to_ary))
+          schema_value = token_schema && token_schema.describes_schema?
+
+          if complex_value || schema_value
+            class_for_schema(token_schema).new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: @jsi_ptr[token], jsi_root_node: @jsi_root_node)
+          else
+            value
+          end
+        else
+          defaults = Set.new
+          if token_schema
+            if token_schema.respond_to?(:to_hash) && token_schema.key?('default')
+              defaults << token_schema['default']
+            end
+          end
+
+          if defaults.size == 1
+            # use the default value
+            # we are using #dup so that we get a modified copy of self, in which we set dup[token]=default.
+            dup.tap { |o| o[token] = defaults.first }[token]
+          else
+            # I kind of want to just return nil here. the preferred mechanism for
+            # a JSI's default value should be its schema. but returning nil ignores
+            # any value returned by Hash#default/#default_proc. there's no compelling
+            # reason not to support both, so I'll return that.
+            value
+          end
         end
-      elsif instance.is_a?(PathedNode)
-        instance.parent_node
-      else
-        JSI::JSON::Node.new_by_type(@jsi_document, @jsi_ptr.parent)
       end
     end
 
-    # @deprecated
-    alias_method :parents, :parent_jsis
-    # @deprecated
-    alias_method :parent, :parent_jsi
+    # assigns the subscript of the instance identified by the given token to the given value.
+    # if the value is a JSI, its instance is assigned instead of the JSI value itself.
+    #
+    # @param token [String, Integer, Object] token identifying the subscript to assign
+    # @param value [JSI::Base, Object] the value to be assigned
+    def []=(token, value)
+      unless respond_to?(:to_hash) || respond_to?(:to_ary)
+        raise(NoMethodError, "cannot assign subcript (using token: #{token.inspect}) to instance: #{jsi_instance.pretty_inspect.chomp}")
+      end
+      jsi_clear_memo(:[])
+      if value.is_a?(Base)
+        self[token] = value.jsi_instance
+      else
+        jsi_instance[token] = value
+      end
+    end
 
     # if this JSI is a $ref then the $ref is followed. otherwise this JSI
     # is returned.
@@ -230,19 +271,7 @@ module JSI
     # @return [JSI::Base, self]
     def deref(&block)
       node_ptr_deref do |deref_ptr|
-        jsi_from_root = deref_ptr.evaluate(document_root_node)
-        if jsi_from_root.is_a?(JSI::Base)
-          return jsi_from_root.tap(&(block || Util::NOOP))
-        else
-          # TODO I want to get rid of this ... just return jsi_from_root whatever it is
-          # NOTE when I get rid of this, simplify #parent_jsis too
-          if @ancestor_jsi && @ancestor_jsi.jsi_ptr.contains?(deref_ptr)
-            derefed = self.class.new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: deref_ptr, ancestor_jsi: @ancestor_jsi)
-          else
-            derefed = self.class.new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: deref_ptr)
-          end
-          return derefed.tap(&(block || Util::NOOP))
-        end
+        deref_ptr.evaluate(jsi_root_node).tap(&(block || Util::NOOP))
       end
       return self
     end
@@ -255,33 +284,25 @@ module JSI
     #   in a (nondestructively) modified copy of this.
     # @return [JSI::Base subclass the same as self] the modified copy of self
     def modified_copy(&block)
-      if @ancestor_jsi
-        raise(Bug, 'bad @ancestor_jsi') if @ancestor_jsi.object_id == self.object_id
-
-        modified_ancestor = @ancestor_jsi.modified_copy do |anc|
-          mod_anc = @jsi_ptr.ptr_relative_to(@ancestor_jsi.jsi_ptr).modified_document_copy(anc, &block)
-          mod_anc
-        end
-        self.class.new(Base::NOINSTANCE, jsi_document: modified_ancestor.jsi_document, jsi_ptr: @jsi_ptr, ancestor_jsi: modified_ancestor)
-      else
+      if node_ptr.root?
         modified_document = @jsi_ptr.modified_document_copy(@jsi_document, &block)
         self.class.new(Base::NOINSTANCE, jsi_document: modified_document, jsi_ptr: @jsi_ptr)
+      else
+        modified_jsi_root_node = @jsi_root_node.modified_copy do |root|
+          @jsi_ptr.modified_document_copy(root, &block)
+        end
+        self.class.new(Base::NOINSTANCE, jsi_document: modified_jsi_root_node.node_document, jsi_ptr: @jsi_ptr, jsi_root_node: modified_jsi_root_node)
       end
     end
 
-    # @return [String] the fragment representation of a pointer to this JSI's instance within its document
-    def fragment
-      @jsi_ptr.fragment
-    end
-
-    # @return [Array<String>] array of schema validation error messages for this instance
-    def fully_validate
-      schema.fully_validate_instance(instance)
+    # @return [Array] array of schema validation errors for this instance
+    def fully_validate(errors_as_objects: false)
+      schema.fully_validate_instance(jsi_instance, errors_as_objects: errors_as_objects)
     end
 
     # @return [true, false] whether the instance validates against its schema
     def validate
-      schema.validate_instance(instance)
+      schema.validate_instance(jsi_instance)
     end
 
     # @return [true] if this method does not raise, it returns true to
@@ -289,7 +310,7 @@ module JSI
     # @raise [::JSON::Schema::ValidationError] raises if the instance has
     #   validation errors
     def validate!
-      schema.validate_instance!(instance)
+      schema.validate_instance!(jsi_instance)
     end
 
     def dup
@@ -299,56 +320,77 @@ module JSI
     # @return [String] a string representing this JSI, indicating its class
     #   and inspecting its instance
     def inspect
-      "\#<#{self.class.to_s} #{instance.inspect}>"
+      "\#<#{object_group_text.join(' ')} #{jsi_instance.inspect}>"
     end
 
     # pretty-prints a representation this JSI to the given printer
     # @return [void]
     def pretty_print(q)
-      q.instance_exec(self) do |obj|
-        text "\#<#{obj.class.to_s}"
-        group_sub {
-          nest(2) {
-            breakable ' '
-            pp obj.instance
-          }
+      q.text '#<'
+      q.text object_group_text.join(' ')
+      q.group_sub {
+        q.nest(2) {
+          q.breakable ' '
+          q.pp jsi_instance
         }
-        breakable ''
-        text '>'
-      end
+      }
+      q.breakable ''
+      q.text '>'
     end
 
     # @return [Array<String>]
     def object_group_text
-      instance.respond_to?(:object_group_text) ? instance.object_group_text : [instance.class.inspect]
+      class_name = self.class.name unless self.class.in_schema_classes
+      class_txt = begin
+        if class_name
+          # ignore ID
+          schema_name = schema.jsi_schema_module.name
+          if !schema_name
+            class_name
+          else
+            "#{class_name} (#{schema_name})"
+          end
+        else
+          schema_name = schema.jsi_schema_module.name || schema.schema_id
+          if !schema_name
+            "JSI"
+          else
+            "JSI (#{schema_name})"
+          end
+        end
+      end
+
+      if (is_a?(PathedArrayNode) || is_a?(PathedHashNode)) && ![Array, Hash].include?(node_content.class)
+        if node_content.respond_to?(:object_group_text)
+          node_content_txt = node_content.object_group_text
+        else
+          node_content_txt = [node_content.class.to_s]
+        end
+      else
+        node_content_txt = []
+      end
+
+      [
+        class_txt,
+        is_a?(Metaschema) ? "Metaschema" : is_a?(Schema) ? "Schema" : nil,
+        *node_content_txt,
+      ].compact
     end
 
     # @return [Object] a jsonifiable representation of the instance
     def as_json(*opt)
-      Typelike.as_json(instance, *opt)
+      Typelike.as_json(jsi_instance, *opt)
     end
 
     # @return [Object] an opaque fingerprint of this JSI for FingerprintHash. JSIs are equal
     #   if their instances are equal, and if the JSIs are of the same JSI class or subclass.
-    def fingerprint
+    def jsi_fingerprint
       {class: jsi_class, jsi_document: jsi_document, jsi_ptr: jsi_ptr}
     end
     include FingerprintHash
 
     private
 
-    # assigns a subscript, unwrapping a JSI if given.
-    # @param subscript [Object] the bit between the [ and ]
-    # @param value [JSI::Base, Object] the value to be assigned
-    def subscript_assign(subscript, value)
-      clear_memo(:[])
-      if value.is_a?(Base)
-        instance[subscript] = value.instance
-      else
-        instance[subscript] = value
-      end
-    end
-
     # this is an instance method in order to allow subclasses of JSI classes to
     # override it to point to other subclasses corresponding to other schemas.
     def class_for_schema(schema)
@@ -359,114 +401,10 @@ module JSI
   # module extending a {JSI::Base} object when its instance is Hash-like (responds to #to_hash)
   module BaseHash
     include PathedHashNode
-
-    alias_method :jsi_instance_hash_pubsend, :node_content_hash_pubsend
-
-    # @param property_name [String, Object] the property name to subscript
-    # @return [JSI::Base, Object] the instance's subscript value at the given
-    #   key property_name_. if there is a subschema defined for that property
-    #   on this JSI's schema, returns the instance's subscript as a JSI
-    #   instiation of that subschema.
-    def [](property_name)
-      instance_property_key_ = jsi_instance_hash_pubsend(:key?, property_name)
-      if !instance_property_key_
-        deref do |deref_jsi|
-          return deref_jsi[property_name]
-        end
-      end
-      instance_property_value_ = jsi_instance_sub(property_name)
-      memoize(:[], property_name, instance_property_value_, instance_property_key_) do |property_name_, instance_property_value, instance_property_key|
-        begin
-          property_schema = schema.subschema_for_property(property_name_)
-          property_schema = property_schema && property_schema.match_to_instance(instance_property_value)
-
-          if !instance_property_key && property_schema && property_schema.schema_object.key?('default')
-            # use the default value
-            default = property_schema.schema_object['default']
-            if default.respond_to?(:to_hash) || default.respond_to?(:to_ary)
-              # we are using #dup so that we get a modified copy of self, in which we set dup[property_name_]=default.
-              # this avoids duplication of code with #modified_copy and below in #[] to handle pathing and such.
-              dup.tap { |o| o[property_name_] = default }[property_name_]
-            else
-              default
-            end
-          elsif property_schema && (instance_property_value.respond_to?(:to_hash) || instance_property_value.respond_to?(:to_ary))
-            class_for_schema(property_schema).new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: @jsi_ptr[property_name_], ancestor_jsi: @ancestor_jsi || self)
-          else
-            instance_property_value
-          end
-        end
-      end
-    end
-
-    # assigns the given property name of the instance to the given value.
-    # if the value is a JSI, its instance is assigned.
-    # @param property_name [Object] this should generally be a String, but JSI
-    #   does not enforce any constraint on it.
-    # @param value [Object] the value to be assigned to the given subscript
-    #   property_name
-    def []=(property_name, value)
-      subscript_assign(property_name, value)
-    end
-
-    private
-
-    # @param token [String, Object]
-    # @return [Object]
-    def jsi_instance_sub(token)
-      jsi_instance_hash_pubsend(:[], token)
-    end
   end
 
   # module extending a {JSI::Base} object when its instance is Array-like (responds to #to_ary)
   module BaseArray
     include PathedArrayNode
-
-    alias_method :jsi_instance_ary_pubsend, :node_content_ary_pubsend
-
-    # @param i [Integer] the array index to subscript
-    # @return [JSI::Base, Object] the instance's subscript value at the given index
-    #   i. if there is a subschema defined for that index on this JSI's schema,
-    #   returns the instance's subscript as a JSI instiation of that subschema.
-    def [](i)
-      memoize(:[], i, jsi_instance_sub(i), jsi_instance_ary_pubsend(:each_index).to_a.include?(i)) do |i_, instance_idx_value, i_in_range|
-        begin
-          index_schema = schema.subschema_for_index(i_)
-          index_schema = index_schema && index_schema.match_to_instance(instance_idx_value)
-
-          if !i_in_range && index_schema && index_schema.schema_object.key?('default')
-            # use the default value
-            default = index_schema.schema_object['default']
-            if default.respond_to?(:to_hash) || default.respond_to?(:to_ary)
-              # we are using #dup so that we get a modified copy of self, in which we set dup[i]=default.
-              # this avoids duplication of code with #modified_copy and below in #[] to handle pathing and such.
-              dup.tap { |o| o[i_] = default }[i_]
-            else
-              default
-            end
-          elsif index_schema && (instance_idx_value.respond_to?(:to_hash) || instance_idx_value.respond_to?(:to_ary))
-            class_for_schema(index_schema).new(Base::NOINSTANCE, jsi_document: @jsi_document, jsi_ptr: @jsi_ptr[i_], ancestor_jsi: @ancestor_jsi || self)
-          else
-            instance_idx_value
-          end
-        end
-      end
-    end
-
-    # assigns the given index of the instance to the given value.
-    # if the value is a JSI, its instance is assigned.
-    # @param i [Object] the array index to assign
-    # @param value [Object] the value to be assigned to the given subscript i
-    def []=(i, value)
-      subscript_assign(i, value)
-    end
-
-    private
-
-    # @param token [Integer]
-    # @return [Object]
-    def jsi_instance_sub(token)
-      jsi_instance_ary_pubsend(:[], token)
-    end
   end
 end