json_schemer 0.2.18 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 426a95173deee91594b5ad1df05dac15ea3c90bac6e17b3136a7170744555c50
-  data.tar.gz: 25268e7f5cb108245aad3d112624eee96774fe8820eda5e24a4f91d97d91e676
+  metadata.gz: 4013d2026a3ac04ca50649b4cf6437ea2ee477ed1e9d350942cfa7e56ead0828
+  data.tar.gz: 810f08388b21cc68d849181a87a820982c2fc7a577c402d5e05699b0c8d07507
 SHA512:
-  metadata.gz: 5534a623dfece170bd27bbb2cbc34978e9e81c075ddad60213d8ce4538d50a6ee119b7efcb2b750068cee0cf565ee582a35eac990c14c2ca647d9d8cc314d4f5
-  data.tar.gz: b813c1b1acd0b1cf0680bf0ecae7eef33b6eb576ff5735d76f072e82fc5cfb36e80ec5b0a3fde6829ec3de856e903b42164a917b833019c33a11d79d6db6080b
+  metadata.gz: f4c5bb6fe5e6d4e0ccfd8abd28a0c12ae23254e74c807ba94278680bf7b706970276cef14f26eaf488f9c46ebd8d418b5aef90bf4abd886b9fd1d7513bb6d27a
+  data.tar.gz: 19a0c839189ba44d6688c389fa38b3f0b1ccc9986643471e2df4d50c347c5ce22ec3fa170002fc000fc877e05080842b57cc01351f46ff1e876ba972880e6584

data/.github/workflows/ci.yml

@@ -6,21 +6,17 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        ruby: [2.4, 2.5, 2.6, 2.7, 3.0, head, jruby, jruby-head, truffleruby, truffleruby-head]
+        ruby: [2.5, 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, head, jruby, jruby-head, truffleruby, truffleruby-head]
         exclude:
-          - os: windows-latest
-            ruby: jruby
-          - os: windows-latest
-            ruby: jruby-head
           - os: windows-latest
             ruby: truffleruby
           - os: windows-latest
             ruby: truffleruby-head
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}
         bundler-cache: true
-    - run: bundle exec rake test
+    - run: bin/rake test

data/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+## [2.2.0] - XXXX-XX-XX
+
+## Bug Fixes
+
+- Support symbol keys when accessing original instance: https://github.com/davishmcclurg/json_schemer/commit/d52c130e9967919c6cf1c9dbc3f0babfb8b01cf8
+- Support custom keywords in nested schemas: https://github.com/davishmcclurg/json_schemer/commit/93c85a5006981347c7e9a4c11b73c6bdb65d8ba2
+- Stringify instance location for custom keywords: https://github.com/davishmcclurg/json_schemer/commit/513c99130b9e7986b09881e7efd3fb7143744754
+- Reduce unhelpful error output in `unevaluated` keywords: https://github.com/davishmcclurg/json_schemer/pull/164
+- Handle parse errors during schema validation: https://github.com/davishmcclurg/json_schemer/pull/171
+- Follow refs when finding default property values: https://github.com/davishmcclurg/json_schemer/pull/175
+
+## Features
+
+- Global configuration with `Configuration` object: https://github.com/davishmcclurg/json_schemer/pull/170
+- Symbol key property defaults with `insert_property_defaults: :symbol`: https://github.com/davishmcclurg/json_schemer/commit/a72473dc84199107ddedc8998950e5b82273232a
+- Consistent schema type support for schema validation methods: https://github.com/davishmcclurg/json_schemer/commit/bbcd0cea20cbaa61cf2bdae5f53840861cae54b8
+- Validation option support for schema validation methods: https://github.com/davishmcclurg/json_schemer/commit/2eeef77de522f127619b7d0faa51e0d7e40977ad
+
+[2.2.0]: https://github.com/davishmcclurg/json_schemer/releases/tag/v2.2.0
+
+## [2.1.1] - 2023-11-28
+
+### Bug Fixes
+
+- Fix refs to/through keyword objects: https://github.com/davishmcclurg/json_schemer/pull/160
+- Temporary fix for incorrect `uri-reference` format in OpenAPI 3.x: https://github.com/davishmcclurg/json_schemer/pull/161
+
+[2.1.1]: https://github.com/davishmcclurg/json_schemer/releases/tag/v2.1.1
+
+## [2.1.0] - 2023-11-17
+
+### Bug Fixes
+
+- Limit anyOf/oneOf discriminator to listed refs: https://github.com/davishmcclurg/json_schemer/pull/145
+- Require discriminator `propertyName` property: https://github.com/davishmcclurg/json_schemer/pull/145
+- Support `Schema#ref` in subschemas: https://github.com/davishmcclurg/json_schemer/pull/145
+- Resolve JSON pointer refs using correct base URI: https://github.com/davishmcclurg/json_schemer/pull/147
+- `date` format in OpenAPI 3.0: https://github.com/davishmcclurg/json_schemer/commit/69fe7a815ecf0cfb1c40ac402bf46a789c05e972
+
+### Features
+
+- Custom error messages with `x-error` keyword and I18n: https://github.com/davishmcclurg/json_schemer/pull/149
+- Custom content encodings and media types: https://github.com/davishmcclurg/json_schemer/pull/148
+
+[2.1.0]: https://github.com/davishmcclurg/json_schemer/releases/tag/v2.1.0
+
+## [2.0.0] - 2023-08-20
+
+For 2.0.0, much of the codebase was rewritten to simplify support for the two new JSON Schema draft versions (2019-09 and 2020-12). The major change is moving each keyword into its own class and organizing them into vocabularies. [Output formats](https://json-schema.org/draft/2020-12/json-schema-core.html#section-12) and [annotations](https://json-schema.org/draft/2020-12/json-schema-core.html#section-7.7) from the new drafts are also supported. The known breaking changes are listed below, but there may be others that haven't been identified.
+
+### Breaking Changes
+
+- The default meta schema is now Draft 2020-12. Other meta schemas can be specified using `meta_schema`.
+- Schemas use `json-schemer://schema` as the default base URI. Relative `$id` and `$ref` values are joined to the default base URI and are always absolute. For example, the schema `{ '$id' => 'foo', '$ref' => 'bar' }` uses `json-schemer://schema/foo` as the base URI and passes `json-schemer://schema/bar` to the ref resolver. For relative refs, `URI#path` can be used in the ref resolver to access the relative portion, ie: `URI('json-schemer://schema/bar').path => "/bar"`.
+- Property validation hooks (`before_property_validation` and `after_property_validation`) run immediately before and after `properties` validation. Previously, `before_property_validation` ran before all "object" validations (`dependencies`, `patternProperties`, `additionalProperties`, etc) and `after_property_validation` was called after them.
+- `insert_property_defaults` now inserts defaults in conditional subschemas when possible (if there's only one default or if there's only one unique default from a valid subtree).
+- Error output
+  - Special characters in `schema_pointer` are no longer percent encoded (eg, `definitions/foo\"bar` instead of `/definitions/foo%22bar`)
+  - Keyword validation order changed so errors may be returned in a different order (eg, `items` errors before `contains`).
+  - Array `dependencies` return `"type": "dependencies"` errors instead of `"required"` and point to the schema that contains the `dependencies` keyword.
+  - `not` errors point to the schema that contains the `not` keyword (instead of the schema defined by the `not` keyword).
+  - Custom keyword errors are now always wrapped in regular error hashes. Returned strings are used to set `type`:
+      ```
+      >> JSONSchemer.schema({ 'x' => 'y' }, :keywords => { 'x' => proc { false } }).validate({}).to_a
+      => [{"data"=>{}, "data_pointer"=>"", "schema"=>{"x"=>"y"}, "schema_pointer"=>"", "root_schema"=>{"x"=>"y"}, "type"=>"x"}]
+      >> JSONSchemer.schema({ 'x' => 'y' }, :keywords => { 'x' => proc { 'wrong!' } }).validate({}).to_a
+      => [{"data"=>{}, "data_pointer"=>"", "schema"=>{"x"=>"y"}, "schema_pointer"=>"", "root_schema"=>{"x"=>"y"}, "type"=>"wrong!"}]
+      ```
+
+[2.0.0]: https://github.com/davishmcclurg/json_schemer/releases/tag/v2.0.0
+
+## [1.0.0] - 2023-05-26
+
+### Breaking Changes
+
+- Ruby 2.4 is no longer supported.
+- The default `regexp_resolver` is now `ruby`, which passes patterns directly to `Regexp`. The previous default, `ecma`, rewrites patterns to behave more like Javascript (ECMA-262) regular expressions:
+  - Beginning of string: `^` -> `\A`
+  - End of string: `$` -> `\z`
+  - Space: `\s` -> `[\t\r\n\f\v\uFEFF\u2029\p{Zs}]`
+  - Non-space: `\S` -> `[^\t\r\n\f\v\uFEFF\u2029\p{Zs}]`
+- Invalid ECMA-262 regular expressions raise `JSONSchemer::InvalidEcmaRegexp` when `regexp_resolver` is set to `ecma`.
+- Embedded subschemas (ie, subschemas referenced by `$id`) can only be found under "known" keywords (eg, `definitions`). Previously, the entire schema object was scanned for `$id`.
+- Empty fragments are now removed from `$ref` URIs before calling `ref_resolver`.
+- Refs that are fragment-only JSON pointers with special characters must use the proper encoding (eg, `"$ref": "#/definitions/some-%7Bid%7D"`).
+
+[1.0.0]: https://github.com/davishmcclurg/json_schemer/releases/tag/v1.0.0

data/Gemfile.lock

@@ -1,31 +1,56 @@
 PATH
   remote: .
   specs:
-    json_schemer (0.2.18)
-      ecma-re-validator (~> 0.3)
+    json_schemer (2.2.0)
+      base64
+      bigdecimal
       hana (~> 1.3)
       regexp_parser (~> 2.0)
-      uri_template (~> 0.7)
+      simpleidn (~> 0.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ecma-re-validator (0.3.0)
-      regexp_parser (~> 2.0)
+    base64 (0.2.0)
+    bigdecimal (3.1.6)
+    bigdecimal (3.1.6-java)
+    concurrent-ruby (1.2.2)
+    csv (3.2.8)
+    docile (1.4.0)
     hana (1.3.7)
-    minitest (5.14.3)
-    rake (13.0.1)
-    regexp_parser (2.1.1)
-    uri_template (0.7.0)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    i18n-debug (1.2.0)
+      i18n (< 2)
+    minitest (5.15.0)
+    rake (13.1.0)
+    regexp_parser (2.9.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    simpleidn (0.2.1)
+      unf (~> 0.1.4)
+    unf (0.1.4)
+      unf_ext
+    unf (0.1.4-java)
+    unf_ext (0.0.9.1)
 
 PLATFORMS
+  java
   ruby
 
 DEPENDENCIES
   bundler (~> 2.0)
+  csv
+  i18n
+  i18n-debug
   json_schemer!
   minitest (~> 5.0)
   rake (~> 13.0)
+  simplecov (~> 0.22)
 
 BUNDLED WITH
-   2.2.11
+   2.3.27

data/README.md

@@ -1,6 +1,6 @@
 # JSONSchemer
 
-JSON Schema validator. Supports drafts 4, 6, and 7.
+JSON Schema validator. Supports drafts 4, 6, 7, 2019-09, 2020-12, OpenAPI 3.0, and OpenAPI 3.1.
 
 ## Installation
 
@@ -45,7 +45,13 @@ schemer.valid?({ 'abc' => 10 })
 # error validation (`validate` returns an enumerator)
 
 schemer.validate({ 'abc' => 10 }).to_a
-# => [{"data"=>10, "schema"=>{"type"=>"integer", "minimum"=>11}, "pointer"=>"#/abc", "type"=>"minimum"}]
+# => [{"data"=>10,
+#      "data_pointer"=>"/abc",
+#      "schema"=>{"type"=>"integer", "minimum"=>11},
+#      "schema_pointer"=>"/properties/abc",
+#      "root_schema"=>{"type"=>"object", "properties"=>{"abc"=>{"type"=>"integer", "minimum"=>11}}},
+#      "type"=>"minimum",
+#      "error"=>"number at `/abc` is less than: 11"}]
 
 # default property values
 
@@ -74,6 +80,80 @@ schemer = JSONSchemer.schema(schema)
 
 schema = '{ "type": "integer" }'
 schemer = JSONSchemer.schema(schema)
+
+# schema validation
+
+JSONSchemer.valid_schema?({ '$id' => 'valid' })
+# => true
+
+JSONSchemer.validate_schema({ '$id' => '#invalid' }).to_a
+# => [{"data"=>"#invalid",
+#      "data_pointer"=>"/$id",
+#      "schema"=>{"$ref"=>"#/$defs/uriReferenceString", "$comment"=>"Non-empty fragments not allowed.", "pattern"=>"^[^#]*#?$"},
+#      "schema_pointer"=>"/properties/$id",
+#      "root_schema"=>{...meta schema},
+#      "type"=>"pattern",
+#      "error"=>"string at `/$id` does not match pattern: ^[^#]*#?$"}]
+
+JSONSchemer.schema({ '$id' => 'valid' }).valid_schema?
+# => true
+
+JSONSchemer.schema({ '$id' => '#invalid' }).validate_schema.to_a
+# => [{"data"=>"#invalid",
+#      "data_pointer"=>"/$id",
+#      "schema"=>{"$ref"=>"#/$defs/uriReferenceString", "$comment"=>"Non-empty fragments not allowed.", "pattern"=>"^[^#]*#?$"},
+#      "schema_pointer"=>"/properties/$id",
+#      "root_schema"=>{...meta schema},
+#      "type"=>"pattern",
+#      "error"=>"string at `/$id` does not match pattern: ^[^#]*#?$"}]
+
+# subschemas
+
+schema = {
+  'type' => 'integer',
+  '$defs' => {
+    'foo' => {
+      'type' => 'string'
+    }
+  }
+}
+schemer = JSONSchemer.schema(schema)
+
+schemer.ref('#/$defs/foo').validate(1).to_a
+# => [{"data"=>1,
+#      "data_pointer"=>"",
+#      "schema"=>{"type"=>"string"},
+#      "schema_pointer"=>"/$defs/foo",
+#      "root_schema"=>{"type"=>"integer", "$defs"=>{"foo"=>{"type"=>"string"}}},
+#      "type"=>"string",
+#      "error"=>"value at root is not a string"}]
+
+# schema bundling (https://json-schema.org/draft/2020-12/json-schema-core.html#section-9.3)
+
+schema = {
+  '$id' => 'http://example.com/schema',
+  'allOf' => [
+    { '$ref' => 'schema/one' },
+    { '$ref' => 'schema/two' }
+  ]
+}
+refs = {
+  URI('http://example.com/schema/one') => {
+    'type' => 'integer'
+  },
+  URI('http://example.com/schema/two') => {
+    'minimum' => 11
+  }
+}
+schemer = JSONSchemer.schema(schema, :ref_resolver => refs.to_proc)
+
+schemer.bundle
+# => {"$id"=>"http://example.com/schema",
+#     "allOf"=>[{"$ref"=>"schema/one"}, {"$ref"=>"schema/two"}],
+#     "$schema"=>"https://json-schema.org/draft/2020-12/schema",
+#     "$defs"=>
+#      {"http://example.com/schema/one"=>{"type"=>"integer", "$id"=>"http://example.com/schema/one", "$schema"=>"https://json-schema.org/draft/2020-12/schema"},
+#       "http://example.com/schema/two"=>{"minimum"=>11, "$id"=>"http://example.com/schema/two", "$schema"=>"https://json-schema.org/draft/2020-12/schema"}}}
 ```
 
 ## Options
@@ -82,13 +162,58 @@ schemer = JSONSchemer.schema(schema)
 JSONSchemer.schema(
   schema,
 
-  # validate `format` (https://tools.ietf.org/html/draft-handrews-json-schema-validation-00#section-7)
+  # meta schema to use for vocabularies (keyword behavior) and schema validation
+  # String/JSONSchemer::Schema
+  # 'https://json-schema.org/draft/2020-12/schema': JSONSchemer.draft202012
+  # 'https://json-schema.org/draft/2019-09/schema': JSONSchemer.draft201909
+  # 'http://json-schema.org/draft-07/schema#': JSONSchemer.draft7
+  # 'http://json-schema.org/draft-06/schema#': JSONSchemer.draft6
+  # 'http://json-schema.org/draft-04/schema#': JSONSchemer.draft4
+  # 'http://json-schema.org/schema#': JSONSchemer.draft4
+  # 'https://spec.openapis.org/oas/3.1/dialect/base': JSONSchemer.openapi31
+  # 'json-schemer://openapi30/schema': JSONSchemer.openapi30
+  # default: JSONSchemer.draft202012
+  meta_schema: 'https://json-schema.org/draft/2020-12/schema',
+
+  # validate `format` (https://json-schema.org/draft/2020-12/json-schema-validation.html#section-7)
   # true/false
   # default: true
   format: true,
 
+  # custom formats
+  formats: {
+    'int32' => proc do |instance, _format|
+      instance.is_a?(Integer) && instance.bit_length <= 32
+    end,
+    # disable specific format
+    'email' => false
+  },
+
+  # custom content encodings
+  # only `base64` is available by default
+  content_encodings: {
+    # return [success, annotation] tuple
+    'urlsafe_base64' => proc do |instance|
+      [true, Base64.urlsafe_decode64(instance)]
+    rescue
+      [false, nil]
+    end
+  },
+
+  # custom content media types
+  # only `application/json` is available by default
+  content_media_types: {
+    # return [success, annotation] tuple
+    'text/csv' => proc do |instance|
+      [true, CSV.parse(instance)]
+    rescue
+      [false, nil]
+    end
+  },
+
   # insert default property values during validation
-  # true/false
+  # string keys by default (use `:symbol` to insert symbol keys)
+  # true/false/:symbol
   # default: false
   insert_property_defaults: true,
 
@@ -110,10 +235,275 @@ JSONSchemer.schema(
   # 'net/http'/proc/lambda/respond_to?(:call)
   # 'net/http': proc { |uri| JSON.parse(Net::HTTP.get(uri)) }
   # default: proc { |uri| raise UnknownRef, uri.to_s }
-  ref_resolver: 'net/http'
+  ref_resolver: 'net/http',
+  
+  # use different method to match regexes
+  # 'ruby'/'ecma'/proc/lambda/respond_to?(:call)
+  # 'ruby': proc { |pattern| Regexp.new(pattern) }
+  # default: 'ruby'
+  regexp_resolver: proc do |pattern|
+    RE2::Regexp.new(pattern)
+  end,
+
+  # output formatting (https://json-schema.org/draft/2020-12/json-schema-core.html#section-12)
+  # 'classic'/'flag'/'basic'/'detailed'/'verbose'
+  # default: 'classic'
+  output_format: 'basic',
+
+  # validate `readOnly`/`writeOnly` keywords (https://spec.openapis.org/oas/v3.0.3#fixed-fields-19)
+  # 'read'/'write'/nil
+  # default: nil
+  access_mode: 'read'
 )
 ```
 
+## Global Configuration
+
+Configuration options can be set globally by modifying `JSONSchemer.configuration`. Global options are applied to any new schemas at creation time (global configuration changes are not reflected in existing schemas). They can be overridden with the regular keyword arguments described [above](#options).
+
+```ruby
+# configuration block
+JSONSchemer.configure do |config|
+  config.regexp_resolver = 'ecma'
+end
+
+# configuration accessors
+JSONSchemer.configuration.insert_property_defaults = true
+```
+
+## Custom Error Messages
+
+Error messages can be customized using the `x-error` keyword and/or [I18n](https://github.com/ruby-i18n/i18n) translations. `x-error` takes precedence if both are defined.
+
+### `x-error` Keyword
+
+```ruby
+# override all errors for a schema
+schemer = JSONSchemer.schema({
+  'type' => 'string',
+  'x-error' => 'custom error for schema and all keywords'
+})
+
+schemer.validate(1).first
+# => {"data"=>1,
+#     "data_pointer"=>"",
+#     "schema"=>{"type"=>"string", "x-error"=>"custom error for schema and all keywords"},
+#     "schema_pointer"=>"",
+#     "root_schema"=>{"type"=>"string", "x-error"=>"custom error for schema and all keywords"},
+#     "type"=>"string",
+#     "error"=>"custom error for schema and all keywords",
+#     "x-error"=>true}
+
+schemer.validate(1, :output_format => 'basic')
+# => {"valid"=>false,
+#     "keywordLocation"=>"",
+#     "absoluteKeywordLocation"=>"json-schemer://schema#",
+#     "instanceLocation"=>"",
+#     "error"=>"custom error for schema and all keywords",
+#     "x-error"=>true,
+#     "errors"=>#<Enumerator: ...>}
+
+# keyword-specific errors
+schemer = JSONSchemer.schema({
+  'type' => 'string',
+  'minLength' => 10,
+  'x-error' => {
+    'type' => 'custom error for `type` keyword',
+    # special `^` keyword for schema-level error
+    '^' => 'custom error for schema',
+    # same behavior as when `x-error` is a string
+    '*' => 'fallback error for schema and all keywords'
+  }
+})
+
+schemer.validate(1).map { _1.fetch('error') }
+# => ["custom error for `type` keyword"]
+
+schemer.validate('1').map { _1.fetch('error') }
+# => ["custom error for schema and all keywords"]
+
+schemer.validate(1, :output_format => 'basic').fetch('error')
+# => "custom error for schema"
+
+# variable interpolation (instance/instanceLocation/keywordLocation/absoluteKeywordLocation)
+schemer = JSONSchemer.schema({
+  '$id' => 'https://example.com/schema',
+  'properties' => {
+    'abc' => {
+      'type' => 'string',
+      'x-error' => <<~ERROR
+        instance: %{instance}
+        instance location: %{instanceLocation}
+        keyword location: %{keywordLocation}
+        absolute keyword location: %{absoluteKeywordLocation}
+      ERROR
+    }
+  }
+})
+
+puts schemer.validate({ 'abc' => 1 }).first.fetch('error')
+# instance: 1
+# instance location: /abc
+# keyword location: /properties/abc/type
+# absolute keyword location: https://example.com/schema#/properties/abc/type
+```
+
+### I18n
+
+When the [I18n gem](https://github.com/ruby-i18n/i18n) is loaded, custom error messages are looked up under the `json_schemer` key. It may be necessary to restart your application after adding the root key because the existence check is cached for performance reasons.
+
+Translation keys are looked up in this order:
+
+1. `$LOCALE.json_schemer.errors.$ABSOLUTE_KEYWORD_LOCATION`
+2. `$LOCALE.json_schemer.errors.$SCHEMA_ID.$KEYWORD_LOCATION`
+3. `$LOCALE.json_schemer.errors.$KEYWORD_LOCATION`
+4. `$LOCALE.json_schemer.errors.$SCHEMA_ID.$KEYWORD`
+5. `$LOCALE.json_schemer.errors.$SCHEMA_ID.*`
+6. `$LOCALE.json_schemer.errors.$META_SCHEMA_ID.$KEYWORD`
+7. `$LOCALE.json_schemer.errors.$META_SCHEMA_ID.*`
+8. `$LOCALE.json_schemer.errors.$KEYWORD`
+9. `$LOCALE.json_schemer.errors.*`
+
+Example translations file:
+
+```yaml
+en:
+  json_schemer:
+    errors:
+      'https://example.com/schema#/properties/abc/type': custom error for absolute keyword location
+      'https://example.com/schema':
+        '#/properties/abc/type': custom error for keyword location, nested under schema $id
+        'type': custom error for `type` keyword, nested under schema $id
+        '^': custom error for schema, nested under schema $id
+        '*': fallback error for schema and all keywords, nested under schema $id
+      '#/properties/abc/type': custom error for keyword location
+      'http://json-schema.org/draft-07/schema#':
+        'type': custom error for `type` keyword, nested under meta-schema $id ($schema)
+        '^': custom error for schema, nested under meta-schema $id
+        '*': fallback error for schema and all keywords, nested under meta-schema $id ($schema)
+      'type': custom error for `type` keyword
+      '^': custom error for schema
+      # variable interpolation (instance/instanceLocation/keywordLocation/absoluteKeywordLocation)
+      '*': |
+        fallback error for schema and all keywords
+        instance: %{instance}
+        instance location: %{instanceLocation}
+        keyword location: %{keywordLocation}
+        absolute keyword location: %{absoluteKeywordLocation}
+```
+
+And output:
+
+```ruby
+require 'i18n'
+I18n.locale = :en                                         # $LOCALE=en
+
+schemer = JSONSchemer.schema({
+  '$id' => 'https://example.com/schema',                  # $SCHEMA_ID=https://example.com/schema
+  '$schema' => 'http://json-schema.org/draft-07/schema#', # $META_SCHEMA_ID=http://json-schema.org/draft-07/schema#
+  'properties' => {
+    'abc' => {
+      'type' => 'integer'                                 # $KEYWORD=type
+    }                                                     # $KEYWORD_LOCATION=#/properties/abc/type
+  }                                                       # $ABSOLUTE_KEYWORD_LOCATION=https://example.com/schema#/properties/abc/type
+})
+
+schemer.validate({ 'abc' => 'not-an-integer' }).first
+# => {"data"=>"not-an-integer",
+#     "data_pointer"=>"/abc",
+#     "schema"=>{"type"=>"integer"},
+#     "schema_pointer"=>"/properties/abc",
+#     "root_schema"=>{"$id"=>"https://example.com/schema", "$schema"=>"http://json-schema.org/draft-07/schema#", "properties"=>{"abc"=>{"type"=>"integer"}}},
+#     "type"=>"integer",
+#     "error"=>"custom error for absolute keyword location",
+#     "i18n"=>true
+```
+
+In the example above, custom error messsages are looked up using the following keys (in order until one is found):
+
+1. `en.json_schemer.errors.'https://example.com/schema#/properties/abc/type'`
+2. `en.json_schemer.errors.'https://example.com/schema'.'#/properties/abc/type'`
+3. `en.json_schemer.errors.'#/properties/abc/type'`
+4. `en.json_schemer.errors.'https://example.com/schema'.type`
+5. `en.json_schemer.errors.'https://example.com/schema'.*`
+6. `en.json_schemer.errors.'http://json-schema.org/draft-07/schema#'.type`
+7. `en.json_schemer.errors.'http://json-schema.org/draft-07/schema#'.*`
+8. `en.json_schemer.errors.type`
+9. `en.json_schemer.errors.*`
+
+## OpenAPI
+
+```ruby
+document = JSONSchemer.openapi({
+  'openapi' => '3.1.0',
+  'info' => {
+    'title' => 'example'
+  },
+  'components' => {
+    'schemas' => {
+      'example' => {
+        'type' => 'integer'
+      }
+    }
+  }
+})
+
+# document validation using meta schema
+
+document.valid?
+# => false
+
+document.validate.to_a
+# => [{"data"=>{"title"=>"example"},
+#      "data_pointer"=>"/info",
+#      "schema"=>{...info schema},
+#      "schema_pointer"=>"/$defs/info",
+#      "root_schema"=>{...meta schema},
+#      "type"=>"required",
+#      "details"=>{"missing_keys"=>["version"]}},
+#     ...]
+
+# data validation using schema by name (in `components/schemas`)
+
+document.schema('example').valid?(1)
+# => true
+
+document.schema('example').valid?('one')
+# => false
+
+# data validation using schema by ref
+
+document.ref('#/components/schemas/example').valid?(1)
+# => true
+
+document.ref('#/components/schemas/example').valid?('one')
+# => false
+```
+
+## CLI
+
+The `json_schemer` executable takes a JSON schema file as the first argument followed by one or more JSON data files to validate. If there are any validation errors, it outputs them and returns an error code.
+
+Validation errors are output as single-line JSON objects. The `--errors` option can be used to limit the number of errors returned or prevent output entirely (and fail fast).
+
+The schema or data can also be read from stdin using `-`.
+
+```
+% json_schemer --help
+Usage:
+  json_schemer [options] <schema> <data>...
+  json_schemer [options] <schema> -
+  json_schemer [options] - <data>...
+  json_schemer -h | --help
+  json_schemer --version
+
+Options:
+  -e, --errors MAX                 Maximum number of errors to output
+                                   Use "0" to validate with no output
+  -h, --help                       Show help
+  -v, --version                    Show version
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.