jsi-dev 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d7ad6ce212930473a08a37e5da2684166c65e7655dd8f401583dc83b2095a50
-  data.tar.gz: 0c8364cb1a94ace31cecbe2c0f7018ec5c3c4d5f0677f80fbc96de92830536c5
+  metadata.gz: 599d7abb635e1cf9cc2ac8918047bf811d17d18833205fa6f07689ba4e065faa
+  data.tar.gz: ae0ce6b1348f5278d9df66bd799513673d7f68a2e363d4955bf0097d255419fe
 SHA512:
-  metadata.gz: efed82db1002e5d0afc6b097271f492075813e944984bed20d02c1822c4df9d71bc1c1d29ed80c230ca5bdf9342158612a1b97e4f65c556b9fa5e2056144f7d9
-  data.tar.gz: fc347ee67d8662c10a88197b21b1a2ace3d9ccc27f9b9c211fce1cc5e686d4a6894d349cd727119e41a79a896ba210913e0e42c73743fa140e8398237f63640e
+  metadata.gz: 2aae63956bb9561a5aac559ba3ab1ca91a2722adf10a7b639c103abe2c2cdd1361fb6917b80d05b4c6b25bb41e97e9d79e11cb6505187d050523b6cee91ec2b6
+  data.tar.gz: afc015ad1476ddbdb031ac4f5c154d453787a9a643db362b60f1a712dd64eeddfa8dee08e3b4ad0ee98719f056b6cb0e62b51be38de83474fbc4256fda8ba1c5

data/.yardopts

@@ -1,8 +1,7 @@
 --main README.md
 --markup=markdown
---markup-provider=maruku
+--markup-provider=commonmarker
 --no-private
 --hide-void-return
--
-docs/**/*.md
-{lib}/**/*.rb
+--files docs/**/*.md
+lib/**/*.rb

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+# v0.8.1
+
+- JSIs are immutable by default
+
+# v0.8.0
+
+- Immutable JSIs with new_jsi param `mutable`
+  - JSIs are still mutable by default, but in the next release they will default to immutable
+- Base#jsi_indicated_schemas
+- Base::StringNode
+- rename metaschema modules /JSONSchemaOrgDraft0X/JSONSchemaDraft0X/
+- terminology: /Metaschema/Meta-Schema/ and /metaschema/meta-schema/ (where hyphen is allowed)
+- Base::HashNode#jsi_each_propertyName
+- new_schema and/or new_jsi params register, schema_registry, stringify_symbol_keys, to_immutable
+- new_schema block param will module_exec on schema module
+- Base#[] param use_default default false, overridable
+- SchemaModule::Connects, SchemaModule::Connection
+- rm Schema#jsi_schema_instance_modules
+
 # v0.7.0
 
 - JSI::Base instances include Array/Hash-like modules on subclasses rather than extending each instance; are only Enumerable when appropriate instead of always

data/LICENSE.md

@@ -1,8 +1,7 @@
-Copright © [Ethan](https://github.com/notEthan/) <ethan.jsi@unth.net>
+JSI Copyright © [Ethan](https://github.com/notEthan/) <ethan.jsi@unth.net>, licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
 
-[<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)
+[<img align="right" src="https://www.gnu.org/graphics/agplv3-155x51.png">](https://www.gnu.org/licenses/agpl-3.0.html)
 
-JSI is licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
 
 GNU Affero General Public License
 =================================

data/README.md

@@ -1,13 +1,13 @@
 # JSI: JSON Schema Instantiation
 
-![Test CI Status](https://github.com/notEthan/jsi/actions/workflows/test.yml/badge.svg?branch=stable)
+![Test CI Status](https://github.com/notEthan/jsi/actions/workflows/test.yml/badge.svg?branch=main)
 [![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 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/>.
 
-JSI marries object-oriented programming with JSON Schemas by associating a module with each schema, and extending every instance described by a schema with that module. When an application adds methods to a schema module, those methods can be used on its instances.
+JSI marries object-oriented programming with JSON Schemas by associating a module with each schema, and constructing every instance described by a schema to be an instance of that module. When an application adds methods to a schema module, those methods can be used on the schema's instances.
 
 A JSI instance aims to offer a fairly unobtrusive wrapper around its JSON data, which is usually a Hash (JSON Object) or Array described by one or more JSON Schemas. JSI instances have accessors for property names described by schemas, 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`.
 
@@ -15,7 +15,9 @@ Note: The canonical location of this README is on [RubyDoc](http://rubydoc.info/
 
 ## Example
 
-Words are boring, let's code. Here's a schema in yaml:
+Words are boring, let's code. You can follow along from the code blocks - install the gem (`gem install jsi`), load an irb (`irb -r jsi`), and copy/paste/hack.
+
+Here's a schema in yaml:
 
 ```yaml
 $schema: "http://json-schema.org/draft-07/schema"
@@ -36,7 +38,8 @@ properties:
 We pass that to {JSI.new_schema} which will instantiate a JSI Schema which represents it:
 
 ```ruby
-# this would usually load YAML or JSON; the schema object is inlined for copypastability.
+# this would usually load YAML or JSON; the schema content
+# is inlined here for copypastability.
 contact_schema = JSI.new_schema({"$schema" => "http://json-schema.org/draft-07/schema", "description" => "A Contact", "type" => "object", "properties" => {"name" => {"type" => "string"}, "phone" => {"type" => "array", "items" => {"type" => "object", "properties" => {"location" => {"type" => "string"}, "number" => {"type" => "string"}}}}}})
 ```
 
@@ -61,8 +64,13 @@ nickname: big b
 So, if we construct an instance like:
 
 ```ruby
-# this would usually load YAML or JSON; the schema instance is inlined for copypastability.
-bill = Contact.new_jsi({"name" => "bill", "phone" => [{"location" => "home", "number" => "555"}], "nickname" => "big b"})
+bill = Contact.new_jsi(
+  # this would usually load JSON or YAML; the instance content
+  # is inlined for copypastability.
+  {"name" => "bill", "phone" => [{"location" => "home", "number" => "555"}], "nickname" => "big b"},
+  # note: bill is mutable to demonstrate setters below; the default is immutable.
+  mutable: true
+)
 # => #{<JSI (Contact)>
 #   "name" => "bill",
 #   "phone" => #[<JSI (Contact.properties["phone"])>
@@ -91,7 +99,7 @@ bill.phone.map(&:location)
 # => ["home"]
 ```
 
-We also get validations, as you'd expect given that's largely what json-schema exists to do:
+We also get validations, as you'd expect given that's largely what JSON Schema exists to do:
 
 ```ruby
 bill.jsi_valid?
@@ -109,17 +117,28 @@ bad = Contact.new_jsi({'phone' => [{'number' => [5, 5, 5]}]})
 #     }
 #   ]
 # }
-bad.phone.jsi_validate
-# => #<JSI::Validation::FullResult
-#  @validation_errors=
-#   #<Set: {#<JSI::Validation::Error
-#      message: "instance type does not match `type` value",
-#      keyword: "type",
-#      schema: #{<JSI (JSI::JSONSchemaDraft07) Schema> "type" => "string"},
-#      instance_ptr: JSI::Ptr["phone", 0, "number"],
-#      instance_document: {"phone"=>[{"number"=>[5, 5, 5]}]}
-#   >,
-#  ...
+bad.phone[0].jsi_validate
+# =>
+# #<JSI::Validation::Result::Full (INVALID)
+#   validation errors: JSI::Set[
+#     #<JSI::Validation::Error
+#       message: "instance object properties are not all valid against corresponding `properties` schemas",
+#       instance: {"number" => [5, 5, 5]},
+#       instance_ptr: JSI::Ptr["phone", 0],
+#       keyword: "properties",
+#       schema uri: JSI::URI["#/properties/phone/items"],
+#       nested_errors: JSI::Set[
+#         #<JSI::Validation::Error
+#           message: "instance type does not match `type` value",
+#           instance: [5, 5, 5],
+#           instance_ptr: JSI::Ptr["phone", 0, "number"],
+#           keyword: "type",
+#           schema uri: JSI::URI["#/properties/phone/items/properties/number"],
+#           nested_errors: JSI::Set[]
+#         >
+#       ]
+#     >
+#   ]
 # >
 ```
 
@@ -140,9 +159,9 @@ There's plenty more JSI has to offer, but this should give you a pretty good ide
 ## Terminology and Concepts
 
 - `JSI::Base` is the base class for each JSI schema class representing instances of JSON Schemas.
-- a "JSI Schema" is a JSON Schema, instantiated as (usually) a JSI::Base described by a metaschema (see the sections on Metaschemas below). a JSI Schema is an instance of the module `JSI::Schema`.
-- a "JSI Schema Module" is a module which represents one schema, dynamically created by that Schema. Instances of that schema are extended with its JSI schema module. applications may reopen these modules to add functionality to JSI instances described by a given schema.
-- a "JSI schema class" is a subclass of `JSI::Base` representing one or more JSON schemas. Instances of such a class are described by all of the represented schemas. A JSI schema class includes the JSI schema module of each represented schema.
+- a "JSI Schema" is a JSON Schema, instantiated as (usually) a JSI::Base described by a meta-schema (see the section on meta-schemas below). A JSI Schema is an instance of the module `JSI::Schema`.
+- a "JSI Schema Module" is a module associated with one schema, dynamically created by that schema. Instances of that schema are ruby instances of its JSI schema module. Applications may reopen these modules to add functionality to JSI instances described by the schema.
+- a "JSI schema class" is a subclass of `JSI::Base` representing any number of JSON schemas. Instances of such a class are described by all of the represented schemas. A JSI schema class includes the JSI schema module of each represented schema.
 - "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 schema class (subclass of `JSI::Base`). This wraps the content of the schema instance (see `JSI::Base#jsi_instance`), and ties it to the schemas which describe the instance (`JSI::Base#jsi_schemas`).
@@ -157,6 +176,15 @@ JSI supports these JSON Schema specification versions:
 | Draft 4 | `http://json-schema.org/draft-04/schema#` | {JSI::JSONSchemaDraft04} |
 | Draft 6 | `http://json-schema.org/draft-06/schema#` | {JSI::JSONSchemaDraft06} |
 | Draft 7 | `http://json-schema.org/draft-07/schema#` | {JSI::JSONSchemaDraft07} |
+| Draft 2020-12 | `https://json-schema.org/draft/2020-12/schema` | {JSI::JSONSchemaDraft202012} |
+
+Caveats:
+
+- Regular expressions are interpreted by Ruby's Regexp class, whereas JSON Schema recommends interpreting these as ECMA 262 regular expressions. Certain expressions behave differently, particularly `^` and `$`.
+- The `format` keyword does not perform validation. This may be implemented in the future.
+- Draft 2020-12: `$schema` has no effect except at the document root ([#341](https://github.com/notEthan/jsi/issues/341))
+- Draft 7: Keywords `contentMediaType` and `contentEncoding` do not perform validation.
+- Draft 4: `$ref` is only used as a reference from schemas - it will not be followed when used on objects that are not schemas. This is consistent with specifications since Draft 4, but in Draft 4 the [JSON Reference](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03) specification would allow `$ref` to be used anywhere. JSI does not do this.
 
 ## JSI and Object Oriented Programming
 
@@ -190,9 +218,9 @@ bill['name']
 
 For `#name` and `#name=`, we're overriding existing accessor methods. note the use of `super` - this invokes the accessor methods defined by JSI which these override. You could alternatively use `self['name']` and `self['name']=` in these methods, with the same effect as `super`.
 
-Working with subschemas is just about as easy as with root schemas.
+Working with subschemas to add methods is just about as easy as with root schemas.
 
-You can subscript or use property accessors on a JSI schema module to refer to the schema modules of its subschemas, e.g.:
+You can use `#[]` or property accessors on a JSI schema module to refer to the schema modules of its subschemas, e.g.:
 
 ```ruby
 Contact.properties['phone'].items
@@ -211,8 +239,7 @@ bill.phone.first.number_with_dashes
 # => "5-5-5"
 ```
 
-A recommended convention for naming subschemas is to define them in the namespace of the module of their
-parent schema. The module can then be opened to add methods to the subschema's module.
+A recommended convention for naming subschemas is to define them in the namespace of the module of their parent schema. The module can then be opened to add methods to the subschema's module.
 
 ```ruby
 module Contact
@@ -240,31 +267,31 @@ end
 
 The classes used to instantiate JSIs are dynamically generated subclasses of JSI::Base which include the JSI Schema Module of each schema describing the given instance. These are mostly intended to be ignored: applications aren't expected to instantiate these directly (rather, `#new_jsi` on a Schema or Schema Module is intended), and they are not intended for subclassing or method definition (applications should instead define methods on a schema's {JSI::Schema#jsi_schema_module}).
 
+## Mutability
+
+JSI instances are immutable by default. Mutable JSIs may be instantiated using the `mutable` param of `new_jsi`. Immutable JSIs are much more performant, because mutation may change what schemas apply to nodes in a document, and checking for that is costly. It is not recommended to instantiate large documents as mutable; their JSI instances become unusably slow.
+
+If you are parsing with JSON.parse or YAML.load, it is recommended to pass the `freeze: true` option to these, which lets JSI skip making a frozen copy.
+
 ## Registration
 
-In order for references across documents (generally from a `$ref` schema keyword) to resolve, JSI provides a registry (a {JSI::SchemaRegistry}) which associates URIs with schemas (or resources containing schemas). The default registry is accessible on {JSI.schema_registry}.
+In order for references across documents (generally from a `$ref` schema keyword) to resolve, JSI provides a registry (a {JSI::Registry}) which associates URIs with schemas (or resources containing schemas). The default registry is accessible on {JSI.registry}.
 
-Schemas instantiated with `.new_schema`, and their subschemas, are by default registered with `JSI.schema_registry` if they are identified by an absolute URI. This can be controlled by params `register` and `schema_registry`.
+Schemas instantiated with `.new_schema`, and their subschemas, are by default registered with `JSI.registry` if they are identified by an absolute URI. This can be controlled by the `register` param and `registry` configuration.
 
-Schemas can automatically be lazily loaded by registering a block which instantiates them with {JSI::SchemaRegistry#autoload_uri} (see its documentation).
+Schemas can automatically be lazily loaded by registering a block which instantiates them with {JSI::Registry#autoload_uri} (see its documentation).
 
 ## Validation
 
 JSI implements all required features, and many optional features, for validation according to supported JSON Schema specifications. To validate instances, see methods {JSI::Base#jsi_validate}, {JSI::Base#jsi_valid?}, {JSI::Schema#instance_validate}, {JSI::Schema#instance_valid?}.
 
-The following optional features are not completely supported:
+## Meta-Schemas
 
-- The `format` keyword does not perform any validation.
-- Regular expressions are interpreted by Ruby's Regexp class, whereas JSON Schema recommends interpreting these as ECMA 262 regular expressions. Certain expressions behave differently, particularly `^` and `$`.
-- Keywords `contentMediaType` and `contentEncoding` do not perform validation.
-
-## Metaschemas
+A meta-schema is a schema that describes schemas. Likewise, a schema is an instance of a meta-schema.
 
-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 schemas include a meta-schema.
 
-In JSI, a schema is generally a JSI::Base instance whose schemas include a metaschema.
-
-A self-descriptive metaschema - most commonly one of the JSON schema draft metaschemas - is an object whose schemas include itself. This is instantiated in JSI as a JSI::MetaschemaNode, a special subclass of JSI::Base.
+A self-descriptive meta-schema - most commonly one of the JSON schema draft meta-schemas - is an object whose schemas include itself. This is instantiated in JSI as a JSI::MetaSchemaNode, a special subclass of JSI::Base.
 
 ## ActiveRecord serialization
 
@@ -272,7 +299,7 @@ A really excellent place to use JSI is when dealing with serialized columns in A
 
 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 / simple types. You have to use `#[]` 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 {JSI::JSICoder}. This coder dumps objects which are simple JSON types, and loads instances of a specified JSON Schema. Here's an example, supposing a `users` table with a JSON column `contact_info` to be instantiated using the `Contact` schema module defined in the Example section above:
 
@@ -282,13 +309,30 @@ class User < ActiveRecord::Base
 end
 ```
 
-Now `user.contact_info` will be instantiated as a `Contact` JSI instance, from the JSON type in the database, with Contact's accessors, validations, and user-defined instance methods.
+Now `user.contact_info` will be instantiated as a `Contact` JSI instance, from the JSON type in the database, with Contact's accessors, validations, and application-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.
 
-## Keying Hashes (JSON Objects)
+## Hash keys (JSON Object property names)
+
+For JSI instances containing Hashes, their keys should be strings. Hashes keyed with symbols are popular in Ruby, but this is not compatible with JSON.
+
+JSI generally does not accommodate symbol keys. However, the syntax for Hash literals with symbol keys (`key: "value"` or `"key": "value"` rather than `"key" => "value"`) conveniently resembles JSON such that you can often paste JSON right into your Ruby (apart from Ruby's `nil` vs JSON's `null`). To enable this, JSI offers key conversion on instantiation: methods `new_jsi` and `new_schema` take a boolean param `stringify_symbol_keys` to recursively convert. This _only_ affects instantiation - no key conversion is done once the JSI has been initialized, e.g. by {JSI::Base#[]} or any methods of {JSI::Base::HashNode}.
+
+```ruby
+# instantiate schema s and instance j, converting keys
+s = JSI.new_schema(
+  # valid JSON
+  {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "array"
+  },
+  stringify_symbol_keys: true,
+)
+j = s.new_jsi([{"foo": "bar"}, {"foo": "baz"}], stringify_symbol_keys: true)
+```
 
-Unlike Ruby, JSON only supports string keys. It is recommended to use strings as hash keys for all JSI instances, but JSI does not enforce this, nor does it do any key conversion. You may also use [ActiveSupport::HashWithIndifferentAccess](https://api.rubyonrails.org/classes/ActiveSupport/HashWithIndifferentAccess.html) as the instance of a JSI in order to gain the benefits that offers over a plain hash. Note that activesupport is not a dependency of jsi and would be required separately for this.
+Third party libraries such as [ActiveSupport::HashWithIndifferentAccess](https://api.rubyonrails.org/classes/ActiveSupport/HashWithIndifferentAccess.html) or [Hashie](https://github.com/hashie/hashie) with [IndifferentAccess](https://github.com/hashie/hashie#indifferentaccess) exist to make symbol keys interchangeable with string keys. A JSI can be instantiated with an indifferent Hash as its content, but there will be various inconsistencies when accessing values with a string vs a symbol, and this is not recommended or supported.
 
 ## Contributing
 
@@ -296,7 +340,7 @@ Issues and pull requests are welcome on GitHub at https://github.com/notEthan/js
 
 ## License
 
-[<img align="right" src="https://github.com/notEthan/jsi/raw/v0.3.0/resources/icons/AGPL-3.0.png">](https://www.gnu.org/licenses/agpl-3.0.html)
+[<img align="right" src="https://www.gnu.org/graphics/agplv3-155x51.png">](https://www.gnu.org/licenses/agpl-3.0.html)
 
 JSI is licensed under the terms of the [GNU Affero General Public License version 3](https://www.gnu.org/licenses/agpl-3.0.html).
 

data/docs/{glossary.md → Glossary.md}

@@ -24,18 +24,16 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
   [JSI]: #JSI
   [a JSI]: #JSI
 
-  JSI is the name of this library. As a [countable](https://en.wikipedia.org/wiki/Count_noun), "a JSI" refers to the library's instantiation of an instance of a set of [schema]s. This is a Ruby instance of a subclass of {JSI::Base}.
-
-  The subclass of JSI::Base which a JSI is instantiated as includes the [schema module] of each schema that describes the instance (its {JSI::Base#jsi_schemas}), as well as type-specific modules for [array] and [hash/object] instances.
+  JSI is the name of this library. As a [countable](https://en.wikipedia.org/wiki/Count_noun), "a JSI" refers to the library's instantiation of an instance described by a set of [schema]s. This is a Ruby instance of {JSI::Base}, and also an instance of the [schema module] belonging to each schema that describes it (its {JSI::Base#jsi_schemas}).
 
 
 - ### node
 
   [node]: #node
 
-  A node is an element in a [document] at a location identified by a [pointer].
+  A node is part of a [document] at a location identified by a [pointer].
 
-  In JSI a node generally means [a JSI] - a JSI::Base instance is often referred to just as "a JSI", but is referred to as a node in the context of its relationship to other nodes in its document.
+  In JSI a node generally means [a JSI] - a {JSI::Base} instance is often referred to just as "a JSI", but is referred to as a node in the context of its relationship to other nodes in its document.
 
 
 - ### node content
@@ -70,31 +68,20 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
   See {JSI::Base#jsi_root_node}.
 
 
-- ### complex
-
-  [complex]: #complex
-
-  A [node] that can have [child]ren is complex. Its [content] is an [array] or a [hash/object].
-
-  Hash and Array nodes can mostly be used like Ruby Hashes and Arrays. JSI defines or delegates the methods of Hash and Array with nearly perfect compatibility, and supports [implicit conversion](https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html) with `#to_hash` and `#to_ary`.
-
-  These nodes also support implicit conversion for the instance's content, treating any object responding to `#to_hash` or `#to_ary` like Hash or Array - though it is most common that actual Hash and Array instances will be the content. (This support may be incomplete for node content that is implicitly convertible but does not respond to certain methods, especially `#[]`.)
-
-
 - ### child
 
   [child]: #child
 
   A [node] immediately below another node, its [parent]. Identified by one [token] relative to the parent.
 
-  See {JSI::Base#[]}.
+  See {JSI::Base#[]} and {JSI::Base#jsi_child_node}.
 
 
 - ### parent
 
   [parent]: #parent
 
-  A [node] immediately above some number of other nodes, its [child]ren. A node that can be a parent node must be [complex].
+  A [node] immediately above some number of other nodes, its [child]ren. Only a [hash/object] or [array] can be a parent.
 
   See {JSI::Base#jsi_parent_node}.
 
@@ -112,7 +99,7 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
 
   [ancestor]: #ancestor
 
-  A [node] anywhere above another node, its [descendent]. A node is considered to be an ancestor of itself, and the [root] node is an ancestor of every node in the [document].
+  A [node] above any number of other nodes, its [descendent]s. A node is considered to be an ancestor of itself, and the [root] node is an ancestor of every node in the [document].
 
   See {JSI::Base#jsi_ancestor_nodes}.
 
@@ -121,7 +108,7 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
 
   [token]: #token
 
-  An [array] [index] or [hash/object] [property name/key] that identifies a child node of its parent. Generally a String or non-negative Integer. [JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901) calls this a "reference token".
+  An [array] [index] or [hash/object] [key/property name] that identifies a child node of its parent. Generally a String or non-negative Integer. [JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901) calls this a "reference token".
 
   A sequence of tokens comprises a [pointer].
 
@@ -134,28 +121,36 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
 
   [JSON Pointers](https://www.rfc-editor.org/rfc/rfc6901) are parsed to JSI pointers.
 
-  A pointer may be referred to as 'absolute' when identifying a descendent of the root node (see {JSI::Base#jsi_ptr}), or 'relative' identifying a descendent of any node (such as the pointer passed to {JSI::Base#jsi_descendent_node}).
+  A pointer may be referred to as 'absolute' when identifying a descendent of the root node (see {JSI::Base#jsi_ptr}), or 'relative' identifying a descendent of any ancestor node (such as the pointer passed to {JSI::Base#jsi_descendent_node}).
 
 
 - ### hash/object
 
   [hash/object]: #hash_object
 
-  The [content] of a [complex] JSI Hash [node] (see {JSI::Base::HashNode}), representing a JSON object, is typically a Ruby Hash, or [implicitly convertible](https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html) with `#to_hash`.
+  In JSON, an object; in Ruby, a Hash, or something [implicitly convertible](https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html) with `#to_hash`.
+
+  In JSI, a [node] whose content is a Hash/`#to_hash`, and which is a {JSI::Base::HashNode}). These nodes are largely used as one would use a Hash, aiming to replicate Hash's API, as well being implicitly convertible with `#to_hash`.
+
+  A hash/object has [child] nodes on each [key/property name].
 
 
 - ### array
 
   [array]: #array
 
-  The [content] of a [complex] JSI Array [node] (see {JSI::Base::ArrayNode}) is typically a Ruby Array, or [implicitly convertible](https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html) with `#to_ary`.
+  In JSON, an array; in Ruby, an Array, or something [implicitly convertible](https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html) with `#to_ary`.
+
+  In JSI, a [node] whose content is an Array/`#to_ary`, and which is a {JSI::Base::ArrayNode}). These nodes are largely used as one would use an Array, aiming to replicate Array's API, as well being implicitly convertible with `#to_ary`.
+
+  An array has [child] nodes on each [index].
 
 
-- ### property name/key
+- ### key/property name
 
-  [property name/key]: #property_name_key
+  [key/property name]: #key_property_name
 
-  A [token] identifying a [child] of a [hash/object] [node]. In Ruby, a Hash key; in JSON Schema, an object property name. Property names are expected to be strings, though Ruby Hash keys do not have this limitation. Note that Symbols are not Strings, and Symbols should not be used in JSI [node content].
+  A [token] identifying a [child] of a [hash/object] [node]. In Ruby, a Hash key; in JSON Schema, an object property name. Property names are always strings in JSON. Note that symbols are not compatible and generally should not be used.
 
   Property names can be described by schemas (using the `propertyNames` keyword), and can be JSI instances of those schemas. See {JSI::Base::HashNode#jsi_each_propertyName}.
 
@@ -164,7 +159,7 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
 
   [index]: #index
 
-  A [token] identifying a [child] of an [array] [node]. A non-negative integer.
+  A [token] identifying a [child] of an [array] [node]. A non-negative integer. This may be represented in string form in a [pointer].
 
 
 - ### instance
@@ -173,18 +168,18 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
 
   A heavily-overloaded term. Context should make it clear in what sense it is being used. 'Instance' can refer to an *object* or a *relationship*, in Ruby or JSON Schema or JSI instantiation:
 
-    - JSON Schema: the _instance_ (JSON data) is an _instance_ (relationship) of [JSON Schemas][schema] that describe it
-    - Ruby: the _instance_ (an Object) is an _instance_ (relationship) of a Class and included Modules
-    - JSI: the _instance_ ([a JSI]) is an _instance_ (relationship) of JSI Schemas
+    - JSON Schema: the *instance* (JSON data) is an *instance* (relationship) of JSON Schemas that describe it
+    - Ruby: the *instance* (an Object) is an *instance* (relationship) of a Class and included Modules
+    - JSI: the *instance* ([a JSI]) is an *instance* (relationship) of [JSI Schemas][schema]
 
-  These all operate in parallel in JSI: a JSI instance represents a JSON instance, it is described by JSI Schemas which represent JSON Schemas, and it is a Ruby instance of [JSI Schema Modules][schema module] of each schema that describes it.
+  These all operate in parallel in JSI: a JSI instance represents a JSON instance, it is described by JSI Schemas which represent JSON Schemas, and it is a Ruby instance of the [JSI Schema Modules][schema module] of the schemas that describe it.
 
 
 - ### schema
 
   [schema]: #schema
 
-  A JSI Schema is [a JSI] that represents a JSON Schema. It is a Ruby instance of the module {JSI::Schema}.
+  A JSI Schema is [a JSI] that represents a JSON Schema. It is a Ruby instance of {JSI::Base} and the module {JSI::Schema}.
 
   A schema describes a set of [instance]s. Any JSI instance that is described by a given schema is a Ruby instance of that schema's [schema module].
 
@@ -195,7 +190,7 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
 
   [schema module]: #schema_module
 
-  A JSI Schema Module is a Ruby module associated with a particular [schema]. Any JSI [instance] that is described by the schema is a Ruby instance of the schema's schema module. This is a {JSI::SchemaModule}.
+  A JSI Schema Module is a Ruby module associated with a particular [schema]. Any JSI instance that is described by that schema is a Ruby instance of the schema's schema module. This is a {JSI::SchemaModule}.
 
   See {JSI::Schema#jsi_schema_module}.
 
@@ -208,13 +203,49 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
 
   A meta-schema is a [schema] that describes schemas, i.e. [instance]s of the meta-schema are schemas.
 
-  As with any other instance, a JSI schema includes the [schema module] of the meta-schema that describes it. The meta-schema's schema module defines the functionality for its instances to behave as schemas, including the module {JSI::Schema} as well as other modules implementing functionality particular to that meta-schema.
+  As with any other JSI instance, a JSI schema is an instance of the [schema module] of the meta-schema that describes it. The meta-schema's schema module defines the functionality for its instances to behave as schemas. It includes the module {JSI::Schema}.
 
-  A meta-schema is described by a meta-schema, which may be itself or another meta-schema. Examples of self-describing meta-schemas are the JSON Schema meta-schemas. An example of the latter is the [schema describing the OpenAPI v3.0 Schema object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/schemas/v3.0/schema.yaml#L203), which describes schemas in OpenAPI documents, but is itself described by JSON Schema draft 04.
+  A meta-schema is described by a meta-schema, which may be itself or another meta-schema. Examples of self-describing meta-schemas are the JSON Schema meta-schemas. An example of the latter is the [schema describing the OpenAPI v3.0 Schema object](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/schemas/v3.0/schema.yaml#L203), which describes schemas in OpenAPI documents, but is itself described by the JSON Schema draft-04 meta-schema.
 
   A self-describing meta-schema is a Ruby instance of its own schema module.
 
-  See {JSI::Schema::DescribesSchema} and {JSI::SchemaModule::DescribesSchemaModule}, {JSI::Schema#describes_schema?} and {JSI::Schema#describes_schema!}
+  A meta-schema has a [dialect] that defines the functionality of the schemas it describes.
+
+  In JSI, a meta-schema is a {JSI::Base} that is a {JSI::Schema::MetaSchema}. Its schema module is a {JSI::SchemaModule::MetaSchemaModule}, and includes {JSI::Schema}. See also {JSI::Schema#describes_schema?} and {JSI::Schema#describes_schema!}.
+
+
+- ### dialect
+
+  [dialect]: #dialect
+
+  A dialect defines all the keywords of a JSON Schema, how they operate, and any other aspects of schema behavior. It consists of a set of one or more [vocabularies][vocabulary]. Note that while not all specifications of dialects use the terms 'dialect' or 'vocabulary', JSI uses these abstractions for all supported specifications.
+
+  Examples of dialects include:
+  - Each published JSON Schema specification
+  - variants of JSON Schema defined by OpenAPI 2.x and 3.x
+  - custom dialects composed of vocabularies specified using the `$vocabulary` keyword
+
+  A dialect defines some or all of:
+
+  - a set of keywords
+  - those keywords' behavior and interactions with other keywords
+  - non-keyword behaviors of a schema (e.g. boolean schemas)
+  - division of keywords into vocabularies
+  - how vocabularies operate
+  - a meta-schema that describes/validates instances of the schema the dialect defines
+
+  Represented as a {JSI::Schema::Dialect}.
+
+
+- ### vocabulary
+
+  [vocabulary]: #vocabulary
+
+  A vocabulary is one part of a [dialect]'s definition of schema keywords and behaviors. Dialects are composed of one or more vocabularies.
+
+  A dialect whose specification does not define vocabularies is implemented using one vocabulary. Vocabularies were not defined for JSON Schema up to draft 07.
+
+  Represented as a {JSI::Schema::Vocabulary}.
 
 
 - ### resource
@@ -223,27 +254,27 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
 
   A resource, or schema resource, is either:
 
-  - A [schema] that is identified by an absolute URI (declared with an id keyword)
+  - A [schema] that is identified by an absolute URI (typically declared with an id keyword)
   - The root of a document containing schemas, whether or not the root is itself a schema. (Technically the root of any document can be considered a resource, but it is only useful when the document contains schemas.)
 
-  The nearest ancestor that is a resource is a node's "resource root" - this is distinct from the [root] node of the whole document.
+  For a given node, its *resource root* is the nearest ancestor that is a resource - this is distinct from the [root] node of the whole document.
 
   Relative URIs and [pointer]s used by a schema (e.g. in `$ref` or `$id`) are resolved relative to its resource root and that resource's id.
 
-  See {JSI::Schema#schema_resource_root}
+  See {JSI::Schema#schema_resource_root}.
 
 
 - ### schema application
 
   [schema application]: #schema_application
 
-  The computation of schemas that apply describing a [node] at a given location. This involves several steps:
+  The computation of the [schema]s that apply describing a particular [node]. This involves resolving `$ref`s, choosing what conditional schemas apply (e.g. which subschema of a `oneOf` applies), and recursing down children applying child applicator schemas. The steps of this process:
 
   - **root indicated schemas**: Application begins with the schemas (usually just one schema) indicated as describing the [root]. `#new_jsi` is invoked on a {JSI::SchemaSet} of the indicated schemas, or more commonly on one schema or [schema module]. These are the root's {JSI::Base#jsi_indicated_schemas}.
-  - **root applied schemas**: [in-place application] is performed on each of the root indicated schemas to compute its applied schemas, i.e. its {JSI::Base#jsi_schemas}.
+  - **root applied schemas**: [in-place application] is performed on each of the root's indicated schemas to compute its applied schemas.
   - Descending from the root to the given node, for each [token] of the node's [pointer]:
     - **child indicated schemas**: [child application] is performed on each applied schema of the parent on the current token. This results in the child's indicated schemas.
-    - **child applied schemas**: [in-place application] is performed on each child indicated schema to compute its applied schemas.
+    - **child applied schemas**: [in-place application] is performed on each of the child's indicated schemas to compute its applied schemas.
 
   The schemas that apply describing the node are the result of the final in-place application.
 
@@ -252,30 +283,31 @@ The terminology from these can be contradictory, e.g. 'object' in JSON meaning w
 
   [child application]: #child_application
 
-  The computation of subschemas of a given schema that apply to a [child] of a [complex] instance on a given [token]. These come from subschemas defined on child applicator keywords such as `properties` and `items`. The result may be an empty schema set if no such keywords are present or none apply.
+  The computation of subschemas of a given schema that describe a [child] of an instance on a given [token]. These come from subschemas defined on child applicator keywords such as `properties` and `items`. The result may be an empty schema set if no such keywords are present or none apply.
 
 
 - ### in-place application
 
   [in-place application]: #in_place_application
 
-  The resolution or expansion of a schema to a set of **applied schemas** for a given instance. "In-place" means all the schemas apply to the same location in the instance, in contrast to [child application]. This is a recursive process.
+  The expansion of a schema to a set of **applied schemas** for a given instance. "In-place" means all the schemas apply to the same location in the instance, in contrast to [child application]. This is a recursive process.
 
-  - If the schema contains a `$ref` keyword:
-    - The reference is resolved and in-place application is performed on the resolved schema.
-    - The schema containing the reference is _not_ applied.
-    - No other applicator keywords should be present; if present they are ignored.
+  - If the schema contains a `$ref` keyword, *and* the specification for the schema is draft-07 or older:
+    - The reference is resolved.
+    - In-place application recurses on the resolved schema.
+    - The rest of the schema is ignored. The schema does not apply itself, and any other applicator keywords are ignored (none should be present).
 
-    The resulting applied schemas are those of the reference's resolved schema.
+    The resulting applied schemas are the resolved schema's in-place applicator schemas.
 
   - Otherwise:
     - The schema applies itself (it is added to the set of applied schemas).
-    - Any in-place applicator keywords (`anyOf`, `dependencies`, etc.) are evaluated for subschemas that apply to the instance. For each such subschema, in-place application is performed and the resulting schemas are added to the applied schemas.
+    - Any in-place applicator keywords (`anyOf`, `dependencies`, etc.) are evaluated for subschemas that apply to the instance. References are resolved from `$ref` or `$dynamicRef`, if present. For each such schema, in-place application recurses.
+
+    The resulting applied schemas consist of each recursively applied in-place applicator schema.
 
-    The resulting applied schemas are the given schema plus the results of in-place application of each applicable subschema.
 
 - ### validation
 
   [validation]: #validation
 
-  The process of determining whether a given [instance] is valid against the [schema]s that describe it, or collecting validation errors indicating why the instance is not valid. See {JSI::Base#jsi_valid?}, {JSI::Base#jsi_validate}, {JSI::Schema#instance_valid?}, {JSI::Schema#instance_validate}
+  The process of determining whether a given [instance] is valid against the [schema]s that describe it, or collecting validation errors indicating why the instance is not valid. See {JSI::Base#jsi_valid?}, {JSI::Base#jsi_validate}, {JSI::Base#jsi_valid!}, {JSI::Schema#instance_valid?}, {JSI::Schema#instance_validate}, {JSI::Schema#instance_valid!}.

data/jsi.gemspec

@@ -26,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "addressable", '~> 2.3'
-  spec.add_development_dependency "maruku"
+  spec.add_dependency "bigdecimal"
 end