jsonschema_rs 0.58.4-x86_64-linux → 0.58.5-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1367fe986e5e10343a016ffbbbf4102d6bd8fb3f2d4fa3a95ab0910a6d5bcefc
-  data.tar.gz: ea28a97d4e2df110b0e8e0dc9f374fe05976f33e3180f3ce49e3b46bc67c605c
+  metadata.gz: 609381d7d1434b191f8a4baf7419da3ed20aade3158453a003828e8514fe271a
+  data.tar.gz: 520691c03c36c7b4a76e58f10262596229d3c7113193917b87e67e62b523b604
 SHA512:
-  metadata.gz: 67ca8481e73e7015f2af0b58d9529f5b82810bb1bd4880ed988d1ea911780a797bdb627e690588e285326aec9ceebaf9ad02ce9928102de414c10e2e0d08d5e5
-  data.tar.gz: 6c782a5efb03a129bd4de7ad0228ccac6ae659a080388a4755d7e227841da981db3ae0988bf4eea101e76bb007329efd93b3b41d8bbfa46d87d1d6e81c73a442
+  metadata.gz: 9177a2102587dfc344015a8994ce836dc80aa8010acb42eec4abef86866988ceec8f0d33fb2fcba12dafc2b1ded51bf26adc7d5d266b609f854aaa6e80a68884
+  data.tar.gz: 5047aab2859b1dc3839013ea99abe15b4cc846bbb86591431636dfd3dc4750b589063fd37376c3a30478fcc684727f9a611a4c985a30a452602715dd94d12d5b

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.58.5] - 2026-10-02
+
+### Fixed
+
+- `canonicalize` keeping a reference to a cycle of bare references under `not` or `oneOf` instead of treating it as accepting every value.
+- Validator construction holding the GVL while it retrieves external resources over HTTP or from files.
+
 ## [0.58.4] - 2026-10-01
 
 ### Fixed
@@ -637,7 +644,8 @@
 
 - Initial public release
 
-[Unreleased]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.58.4...HEAD
+[Unreleased]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.58.5...HEAD
+[0.58.5]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.58.4...ruby-v0.58.5
 [0.58.4]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.58.3...ruby-v0.58.4
 [0.58.3]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.58.2...ruby-v0.58.3
 [0.58.2]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.58.1...ruby-v0.58.2

data/README.md

@@ -45,29 +45,29 @@ end
 
 ## Highlights
 
-- 📚 Full support for popular JSON Schema drafts
-- 🌐 Remote reference fetching (network/file)
+- 📚 Drafts 4, 6, 7, 2019-09 and 2020-12
 - 🔧 Custom keywords and format validators
-- ✨ Meta-schema validation for schema documents
+- ⚡ Compile-time validators for your own native extensions, via the Rust crate
+- 🌐 `$ref` resolution over HTTP and from files
 - 📦 Schema bundling into Compound Schema Documents, and `$ref` dereferencing
+- 🎨 Structured Output v1 reports (flag/list/hierarchical)
+- ✨ Meta-schema validation for schema documents, including custom metaschemas
 - 🧮 Experimental schema canonicalization
 - ♦️ Supports Ruby 3.2, 3.4 and 4.0
 
 ### Supported drafts
 
-The following drafts are supported:
-
 - [![Draft 2020-12](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Frust-jsonschema%2Fcompliance%2Fdraft2020-12.json)](https://bowtie.report/#/implementations/rust-jsonschema)
 - [![Draft 2019-09](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Frust-jsonschema%2Fcompliance%2Fdraft2019-09.json)](https://bowtie.report/#/implementations/rust-jsonschema)
 - [![Draft 7](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Frust-jsonschema%2Fcompliance%2Fdraft7.json)](https://bowtie.report/#/implementations/rust-jsonschema)
 - [![Draft 6](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Frust-jsonschema%2Fcompliance%2Fdraft6.json)](https://bowtie.report/#/implementations/rust-jsonschema)
 - [![Draft 4](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Frust-jsonschema%2Fcompliance%2Fdraft4.json)](https://bowtie.report/#/implementations/rust-jsonschema)
 
-You can check the current status on the [Bowtie Report](https://bowtie.report/#/implementations/rust-jsonschema).
+Per-draft compliance results are on the [Bowtie Report](https://bowtie.report/#/implementations/rust-jsonschema).
 
 ## Playground
 
-If you'd like to try `jsonschema`, you can check the WebAssembly-powered [playground](https://jsonschema.dygalo.dev/) to see the results instantly.
+Try schemas in the browser with the WebAssembly [playground](https://jsonschema.dygalo.dev/).
 
 ## Installation
 
@@ -77,13 +77,13 @@ Add to your Gemfile:
 gem 'jsonschema_rs'
 ```
 
-Pre-built native gems are available for:
+Pre-built native gems:
 
 - **Linux**: `x86_64`, `aarch64` (glibc and musl)
 - **macOS**: `x86_64`, `arm64`
 - **Windows**: `x64` (mingw-ucrt)
 
-If no pre-built gem is available for your platform, it will be compiled from source during installation. You'll need:
+On other platforms, `gem install` compiles from source and needs:
 - Ruby 3.2+
 - Rust toolchain ([rustup](https://rustup.rs/))
 
@@ -91,8 +91,8 @@ If no pre-built gem is available for your platform, it will be compiled from sou
 
 ### Reusable validators
 
-For validating multiple instances against the same schema, create a reusable validator.
-`validator_for` automatically detects the draft version from the `$schema` keyword in the schema and falls back to Draft 2020-12:
+Build a validator once to check many instances against one schema.
+`validator_for` detects the draft from `$schema` and falls back to Draft 2020-12:
 
 ```ruby
 validator = JSONSchema.validator_for({
@@ -108,7 +108,7 @@ validator.valid?({ "name" => "Alice", "age" => 30 })  # => true
 validator.valid?({ "age" => 30 })                      # => false
 ```
 
-You can use draft-specific validators for different JSON Schema versions:
+To pick the draft yourself, use a draft-specific class:
 
 ```ruby
 validator = JSONSchema::Draft7Validator.new(schema)
@@ -119,6 +119,8 @@ validator = JSONSchema::Draft7Validator.new(schema)
 
 ### Custom format validators
 
+Pass a callable that takes a `String` and returns a boolean via `formats`. Drafts 2019-09 and 2020-12 treat `format` as an annotation, so set `validate_formats: true` to get it checked:
+
 ```ruby
 phone_format = ->(value) { value.match?(/^\+?[1-9]\d{1,14}$/) }
 
@@ -150,10 +152,10 @@ validator = JSONSchema.validator_for(
 ```
 
 Each custom keyword class must implement:
-- `initialize(parent_schema, value, schema_path)` - called during schema compilation
-- `validate(instance)` - raise on failure, return normally on success
+- `initialize(parent_schema, value, schema_path)`: called once when the validator is built
+- `validate(instance)`: raise to reject the value, return to accept it
 
-A class may also implement `iter_errors(instance)`, returning an array of exceptions, to report several problems from one keyword. `each_error` then surfaces each of them; when the method is absent it falls back to the single error from `validate`:
+To report several problems from one keyword, also implement `iter_errors(instance)` returning an array of exceptions. `each_error` yields each of them. Without it, `each_error` yields the single error from `validate`:
 
 ```ruby
 class AllPositive
@@ -172,7 +174,7 @@ class AllPositive
 end
 ```
 
-When `validate` raises, the original exception is preserved as the `cause` of the `ValidationError`, so callers can inspect it (errors from `iter_errors` keep their exception as `cause` in the same way):
+The resulting `ValidationError` keeps the raised exception as `cause`, for both `validate` and `iter_errors`:
 
 ```ruby
 begin
@@ -185,7 +187,7 @@ end
 
 ### Structured evaluation output
 
-When you need more than a boolean result, use the `evaluate` API to access the [JSON Schema Output v1](https://json-schema.org/draft/2020-12/json-schema-core#name-output-formatting) formats:
+`evaluate` returns the [JSON Schema Output v1](https://json-schema.org/draft/2020-12/json-schema-core#name-output-formatting) formats instead of a boolean:
 
 ```ruby
 schema = {
@@ -203,14 +205,14 @@ evaluation = validator.evaluate({ "age" => "not_an_integer" })
 evaluation.valid?  # => false
 ```
 
-**Flag output** — simplest, just valid/invalid:
+**Flag output**: valid or invalid, nothing else:
 
 ```ruby
 evaluation.flag
 # => {valid: false}
 ```
 
-**List output** — flat list of all evaluation nodes:
+**List output**: every evaluation node in a flat list:
 
 ```ruby
 evaluation.list
@@ -231,7 +233,7 @@ evaluation.list
 #     ]}
 ```
 
-**Hierarchical output** — nested tree following schema structure:
+**Hierarchical output**: the same nodes nested by schema structure:
 
 ```ruby
 evaluation.hierarchical
@@ -255,7 +257,7 @@ evaluation.hierarchical
 #     ]}
 ```
 
-**Collected errors** — flat list of all errors across evaluation nodes:
+**Collected errors**: every error across all nodes:
 
 ```ruby
 evaluation.errors
@@ -266,8 +268,8 @@ evaluation.errors
 #      error: "\"not_an_integer\" is not of type \"integer\""}]
 ```
 
-**Collected annotations** — flat list of annotations from successfully validated nodes.
-When a node fails validation, its annotations appear as `droppedAnnotations` in the list/hierarchical output instead.
+**Collected annotations**: annotations from the nodes that passed.
+A failed node reports its annotations as `droppedAnnotations` in the list and hierarchical output instead.
 
 ```ruby
 valid_eval = validator.evaluate({ "name" => "Alice", "age" => 30 })
@@ -278,7 +280,7 @@ valid_eval.annotations
 
 ### Canonical JSON serialization
 
-Use `Canonical::JSON.to_string` when you need a stable JSON representation:
+`Canonical::JSON.to_string` serializes equal JSON values to the same string, regardless of key order:
 
 ```ruby
 schema_a = { "type" => "object", "properties" => { "b" => { "type" => "integer" }, "a" => { "type" => "string" } } }
@@ -290,13 +292,13 @@ dump_b = JSONSchema::Canonical::JSON.to_string(schema_b)
 dump_a == dump_b # => true
 ```
 
-Main use case: deduplicating equivalent JSON Schemas.
+Use it to deduplicate schemas that differ only in key order.
 
 ## Schema Canonicalization
 
 > **Experimental**: the canonicalization API may change in minor releases.
 
-`JSONSchema.canonicalize` reduces a schema to a normal form without changing the values it accepts. Schemas that accept the same values reduce to equal `CanonicalSchema` objects, and contradictions reduce to `false`:
+`JSONSchema.canonicalize` reduces a schema to a normal form that accepts the same values. Schemas that accept the same values reduce to equal `CanonicalSchema` objects, and a schema proven to accept nothing reduces to `false`:
 
 ```ruby
 canonical = JSONSchema.canonicalize(
@@ -315,7 +317,9 @@ JSONSchema.canonicalize({ "type" => "integer", "minimum" => 10, "maximum" => 5 }
 # => :no, which is JSONSchema::Canonical::Satisfiability::NO
 ```
 
-A canonical schema *is* the set of values it accepts, so canonical schemas combine as sets. Every emitted schema carries `$schema`, left out of the comments below:
+A schema the canonical form cannot model exactly comes back unchanged, with `kind == :raw`. Its `view.reason` names what stopped the run, and `view.pointer` the subschema at fault when a single one is.
+
+Canonical schemas combine like sets of values. Every emitted schema carries `$schema`; the comments below leave it out:
 
 ```ruby
 positive = JSONSchema.canonicalize({ "type" => "integer", "minimum" => 0 })
@@ -333,19 +337,19 @@ positive.union(bounded).to_json_schema
 positive.subtract(bounded).to_json_schema
 # => {"type"=>"integer", "minimum"=>101}
 
-# Every value `positive` rejects, across the types it never admitted
+# Every value `positive` rejects: other types, negative integers and non-integer numbers
 positive.negate.to_json_schema
 # => {"anyOf"=>[{"type"=>["null", "boolean", "string", "array", "object"]},
 #               {"type"=>"integer", "maximum"=>-1},
 #               {"type"=>"number", "not"=>{"multipleOf"=>1}}]}
 
-positive.covers(bounded)        # => :no - `bounded` takes negative integers, `positive` does not
+positive.covers(bounded)        # => :no: `bounded` takes negative integers, `positive` does not
 positive.satisfiability         # => :yes
 ```
 
 ### Comparing two versions of a schema
 
-The difference answers what editing a schema did to the values it takes: it accepts exactly what the old schema took and the new one turns away, and is unsatisfiable exactly when nothing was lost.
+`subtract` tells you what an edit did to a schema. `old.subtract(new)` accepts exactly the values `old` accepts and `new` rejects, so it accepts nothing when the edit lost nothing.
 
 ```ruby
 old = JSONSchema.canonicalize({ "type" => "string" })
@@ -361,19 +365,23 @@ new.subtract(old).satisfiability
 # => :no
 ```
 
-Compare a request schema new-against-old and a response schema old-against-new: narrowing a request turns away payloads a caller used to send, widening a response returns values a caller never agreed to read.
+The direction to check depends on who sends the value:
 
-`:no` on the difference proves nothing was lost. `:unknown` proves nothing either way.
+- For a request schema, check `old.subtract(new)`. It accepts the payloads existing callers send that the new schema rejects.
+- For a response schema, check `new.subtract(old)`. It accepts the values the new schema lets a server return that callers never agreed to read.
 
-`:unknown` is undecided, not negative, so the two questions have opposite safe tests: only `satisfiability == :no` proves a schema admits nothing, and only `covers == :yes` proves containment.
+`:no` on the difference proves the edit safe in that direction. `:unknown` means the canonicalizer could not decide, and proves nothing either way. Read it as the answer that keeps you safe:
+
+- `satisfiability`: only `:no` proves a schema accepts nothing. Treat `:unknown` like `:yes`.
+- `a.covers(b)`: only `:yes` proves `a` accepts every value `b` accepts. Treat `:unknown` like `:no`.
 
 `JSONSchema::Canonical::Containment`, `Satisfiability`, `Distinctness` and `Kind` hold these symbols as constants, each with an `ALL` list.
 
-Both operands must share one setup - the same draft, format policy, regular-expression engine and definitions - or `IncompatibleOperands` is raised. `UnsupportedOperand` means an operand is a `Raw` pass-through, and `UnsupportedResult` that the canonical form does not support the result. All three live under `JSONSchema::Canonical`.
+The set operations raise `IncompatibleOperands` when the operands differ in draft, `format` assertion or regular-expression engine, or resolve `#` or one external resource to different schemas. They raise `UnsupportedOperand` when an operand is `:raw`, and `UnsupportedResult` when the canonical form cannot express the result exactly. All three live under `JSONSchema::Canonical`.
 
 ### Finding the dead subschemas of a document
 
-`JSONSchema::Canonical.find_unsatisfiable` walks a whole document and answers which of its subschemas admit no value, and why - the keywords at fault and where they sit:
+`JSONSchema::Canonical.find_unsatisfiable` walks a whole document and reports each subschema that accepts no value, with the keywords at fault and their pointers:
 
 ```ruby
 reasons = JSONSchema::Canonical.find_unsatisfiable(
@@ -396,11 +404,11 @@ reasons.key?("/properties/name")
 # => false
 ```
 
-A reason is a `LiteralReason` (written as `false`), an `EmptyReason` (one part admits nothing by itself) or a `ConflictReason` (each part admits values, together they admit none). A pointer left out is not proven satisfiable: a document canonicalization cannot model reports nothing, as `satisfiability` answers `:unknown`.
+A reason is a `LiteralReason` (written as `false`), an `EmptyReason` (one part admits nothing by itself) or a `ConflictReason` (each part admits values, together they admit none). A missing pointer does not prove that subschema satisfiable. For a document the canonical form cannot model, `find_unsatisfiable` reports nothing, the same way `satisfiability` answers `:unknown`.
 
 ## Schema Bundling and Dereferencing
 
-Produce a Compound Schema Document ([Appendix B](https://json-schema.org/draft/2020-12/json-schema-core#appendix-B)) by embedding all external `$ref` targets into a draft-appropriate container. The result validates identically to the original.
+Produce a Compound Schema Document ([Appendix B](https://json-schema.org/draft/2020-12/json-schema-core#appendix-B)) by embedding all external `$ref` targets into a draft-appropriate container. The bundle accepts the same values as the original.
 
 ```ruby
 address_schema = {
@@ -430,7 +438,7 @@ dereferenced = JSONSchema.dereference(schema, registry: registry)
 
 ## Meta-Schema Validation
 
-Validate that a JSON Schema document is itself valid:
+`JSONSchema::Meta` checks a schema against the meta-schema of its draft:
 
 ```ruby
 JSONSchema::Meta.valid?({ "type" => "string" })      # => true
@@ -443,9 +451,24 @@ rescue JSONSchema::ValidationError => e
 end
 ```
 
+For a custom metaschema, register it and point `$schema` at its URI:
+
+```ruby
+metaschema = {
+  "$schema" => "https://json-schema.org/draft/2020-12/schema",
+  "$id" => "https://example.com/meta",
+  "type" => "object",
+  "required" => ["title"]
+}
+meta_registry = JSONSchema::Registry.new([["https://example.com/meta", metaschema]])
+
+JSONSchema::Meta.valid?({ "$schema" => "https://example.com/meta", "title" => "Person" }, registry: meta_registry)  # => true
+JSONSchema::Meta.valid?({ "$schema" => "https://example.com/meta" }, registry: meta_registry)                      # => false
+```
+
 ## External References
 
-By default, `jsonschema` resolves HTTP references and file references from the local file system. You can implement a custom retriever to handle external references:
+By default, `jsonschema_rs` fetches external `$ref` targets over HTTP and from the local file system. Pass a `retriever:` to load them yourself:
 
 ```ruby
 schemas = {
@@ -468,9 +491,21 @@ validator.valid?({ "name" => "Alice", "age" => 30 })  # => true
 validator.valid?({ "name" => "Bob" })                  # => false (missing "age")
 ```
 
+For schemas from untrusted sources, pass `offline: true`. The validator then refuses to fetch any `$ref` target, so a schema cannot reach your network or file system. Schemas held in a `Registry` still resolve:
+
+```ruby
+begin
+  JSONSchema.validator_for({ "$ref" => "https://example.com/other.json" }, offline: true)
+rescue JSONSchema::ReferencingError => e
+  e.message  # => "Resource 'https://example.com/other.json' is not present in a registry ..."
+end
+```
+
+`bundle` and `dereference` take `offline:` too.
+
 ## Schema Registry
 
-For applications that frequently use the same schemas, create a registry to store and reference them:
+A `Registry` holds schemas by URI, so a validator resolves `$ref`s to them without fetching anything:
 
 ```ruby
 registry = JSONSchema::Registry.new([
@@ -501,7 +536,7 @@ validator.valid?({
 })  # => true
 ```
 
-The registry also accepts `draft:` and `retriever:` options:
+`Registry` also takes a default `draft:` and a `retriever:` for URIs it does not hold:
 
 ```ruby
 registry = JSONSchema::Registry.new(
@@ -513,7 +548,7 @@ registry = JSONSchema::Registry.new(
 
 ## Regular Expression Configuration
 
-When validating schemas with regex patterns (in `pattern` or `patternProperties`), you can configure the underlying regex engine:
+`pattern_options:` picks the regex engine for `pattern` and `patternProperties` and sets its limits:
 
 ```ruby
 # Default fancy-regex engine with backtracking limits
@@ -540,24 +575,22 @@ validator = JSONSchema.validator_for(
 )
 ```
 
-The available options:
-
-  - `FancyRegexOptions`: Default engine with lookaround and backreferences support
+  - `FancyRegexOptions`: default engine, supports lookaround and backreferences
 
     - `backtrack_limit`: Maximum backtracking steps
     - `size_limit`: Maximum compiled regex size in bytes
     - `dfa_size_limit`: Maximum DFA cache size in bytes
 
-  - `RegexOptions`: Safer engine with linear-time guarantee
+  - `RegexOptions`: matches in linear time, no lookaround or backreferences
 
     - `size_limit`: Maximum compiled regex size in bytes
     - `dfa_size_limit`: Maximum DFA cache size in bytes
 
-This configuration is crucial when working with untrusted schemas where attackers might craft malicious regex patterns.
+If you validate against schemas from untrusted sources, use `RegexOptions`: a crafted pattern cannot make it backtrack.
 
 ## Email Format Configuration
 
-When validating email addresses using `{"format": "email"}`, you can customize the validation behavior:
+`email_options:` makes `{"format": "email"}` stricter or looser than the spec default:
 
 ```ruby
 # Require a top-level domain (reject "user@localhost")
@@ -587,16 +620,14 @@ validator = JSONSchema.validator_for(
 )
 ```
 
-Available options:
-
-  - `require_tld`: Require a top-level domain (e.g., reject "user@localhost")
+  - `require_tld`: Require a top-level domain (e.g., reject "user@localhost") (default: false)
   - `allow_domain_literal`: Allow IP address literals like "user@[127.0.0.1]" (default: true)
   - `allow_display_text`: Allow display names like "Name <user@example.com>" (default: true)
   - `minimum_sub_domains`: Minimum number of domain segments required
 
 ## Error Handling
 
-`jsonschema` provides detailed validation errors through the `ValidationError` class:
+A `ValidationError` carries the message, both locations and a `kind` with keyword-specific details:
 
 ```ruby
 schema = { "type" => "string", "maxLength" => 5 }
@@ -619,7 +650,7 @@ end
 
 ### Error Kind Properties
 
-Each error has a `kind` property with convenient accessors:
+`kind` has generic accessors:
 
 ```ruby
 JSONSchema.each_error({ "minimum" => 5 }, 3).each do |error|
@@ -632,7 +663,7 @@ end
 
 ### Error Message Masking
 
-When working with sensitive data, you can mask instance values in error messages:
+Pass `mask:` to replace instance values in error messages with a placeholder:
 
 ```ruby
 schema = {
@@ -657,19 +688,19 @@ end
 
 ### Exception Classes
 
-- **`JSONSchema::ValidationError`** - raised on validation failure
+- **`JSONSchema::ValidationError`**: raised on validation failure
   - `message`, `verbose_message`, `instance_path`, `schema_path`, `evaluation_path`, `kind`, `instance`
   - JSON Pointer helpers: `instance_path_pointer`, `schema_path_pointer`, `evaluation_path_pointer`
-- **`JSONSchema::ReferencingError`** - raised when `$ref` cannot be resolved
+- **`JSONSchema::ReferencingError`**: raised when a `$ref` cannot be resolved
 
 ## Options Reference
 
-One-off validation methods (`valid?`, `validate!`, `each_error`, `evaluate`) accept these keyword arguments:
+The one-off methods `valid?`, `validate!` and `each_error` accept these keyword arguments:
 
 ```ruby
 JSONSchema.valid?(schema, instance,
   draft: :draft7,                  # Specific draft version (symbol)
-  validate_formats: true,          # Enable format validation (default: false)
+  validate_formats: true,          # Check `format` (default: on up to Draft 7, off for 2019-09 and 2020-12)
   ignore_unknown_formats: true,    # Don't error on unknown formats (default: true)
   base_uri: "https://example.com", # Base URI for reference resolution
   mask: "[REDACTED]",              # Mask sensitive data in error messages
@@ -680,25 +711,26 @@ JSONSchema.valid?(schema, instance,
   vocabularies: ["https://..."],   # Vocabularies implemented by custom keywords
   pattern_options: opts,           # RegexOptions or FancyRegexOptions
   email_options: opts,             # EmailOptions
-  http_options: opts               # HttpOptions
+  http_options: opts,              # HttpOptions
+  offline: false                   # true refuses to fetch $refs; conflicts with retriever:
 )
 ```
 
 `evaluate` accepts the same options except `mask` (currently unsupported for evaluation output).
 
-`validator_for` accepts the same options except `draft:` — use draft-specific validators (`Draft7Validator.new`, etc.) to pin a draft version.
+`validator_for` accepts the same options except `draft:`. To pin a draft, use a draft-specific class such as `Draft7Validator.new`.
 
 Valid draft symbols: `:draft4`, `:draft6`, `:draft7`, `:draft201909`, `:draft202012`.
 
 ## Performance
 
-`jsonschema` is designed for high performance, outperforming other Ruby JSON Schema validators in most scenarios:
+Compared with other Ruby validators:
 
 - **28-148x** faster than `json_schemer` for complex schemas and large instances
 - **200-567x** faster than `json-schema` where supported
 - **7-130x** faster than `rj_schema` (RapidJSON/C++)
 
-For detailed benchmarks, see our [full performance comparison](https://github.com/Stranger6667/jsonschema/blob/master/crates/jsonschema-rb/BENCHMARKS.md).
+Full results and methodology are in [BENCHMARKS.md](https://github.com/Stranger6667/jsonschema/blob/master/crates/jsonschema-rb/BENCHMARKS.md).
 
 ### Compile-Time Validators
 
@@ -714,15 +746,15 @@ A complete extension with its build and test commands lives in
 
 ## Acknowledgements
 
-This library draws API design inspiration from the Python [`jsonschema`](https://github.com/python-jsonschema/jsonschema) package. We're grateful to the Python `jsonschema` maintainers and contributors for their pioneering work in JSON Schema validation.
+The API design draws on the Python [`jsonschema`](https://github.com/python-jsonschema/jsonschema) package. Thanks to its maintainers and contributors.
 
 ## Support
 
-If you have questions, need help, or want to suggest improvements, please use [GitHub Discussions](https://github.com/Stranger6667/jsonschema/discussions).
+Ask questions and suggest improvements in [GitHub Discussions](https://github.com/Stranger6667/jsonschema/discussions).
 
 ## Sponsorship
 
-If you find `jsonschema` useful, please consider [sponsoring its development](https://github.com/sponsors/Stranger6667).
+If you find `jsonschema_rs` useful, please consider [sponsoring its development](https://github.com/sponsors/Stranger6667).
 
 ## Contributing
 

data/lib/jsonschema/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONSchema
-  VERSION = "0.58.4"
+  VERSION = "0.58.5"
 end

data/sig/jsonschema.rbs

@@ -391,7 +391,8 @@ module JSONSchema
     ?registry: Registry?,
     ?pattern_options: (RegexOptions | FancyRegexOptions)?,
     ?email_options: EmailOptions?,
-    ?http_options: HttpOptions?
+    ?http_options: HttpOptions?,
+    ?offline: bool?
   ) -> Validator
 
   # Create a map of validators for all sub-schemas in a JSON Schema.
@@ -408,7 +409,8 @@ module JSONSchema
     ?keywords: ::Hash[::String, untyped]?,
     ?pattern_options: (RegexOptions | FancyRegexOptions)?,
     ?email_options: EmailOptions?,
-    ?http_options: HttpOptions?
+    ?http_options: HttpOptions?,
+    ?offline: bool?
   ) -> ValidatorMap
 
   # Bundle a JSON Schema into a Compound Schema Document.
@@ -421,7 +423,8 @@ module JSONSchema
     ?draft: draft?,
     ?retriever: (^(String) -> untyped)?,
     ?registry: Registry?,
-    ?base_uri: String?
+    ?base_uri: String?,
+    ?offline: bool?
   ) -> Hash[String, untyped]
 
   # Dereference a JSON Schema by recursively replacing all $ref values
@@ -431,7 +434,8 @@ module JSONSchema
     ?draft: draft?,
     ?retriever: (^(String) -> untyped)?,
     ?registry: Registry?,
-    ?base_uri: String?
+    ?base_uri: String?,
+    ?offline: bool?
   ) -> untyped
 
   # Detect the JSON Schema draft for a schema and return the corresponding validator class.
@@ -454,7 +458,8 @@ module JSONSchema
     ?registry: Registry?,
     ?pattern_options: (RegexOptions | FancyRegexOptions)?,
     ?email_options: EmailOptions?,
-    ?http_options: HttpOptions?
+    ?http_options: HttpOptions?,
+    ?offline: bool?
   ) -> bool
 
   # One-off validation raising on error.
@@ -473,7 +478,8 @@ module JSONSchema
     ?registry: Registry?,
     ?pattern_options: (RegexOptions | FancyRegexOptions)?,
     ?email_options: EmailOptions?,
-    ?http_options: HttpOptions?
+    ?http_options: HttpOptions?,
+    ?offline: bool?
   ) -> nil
 
   # Iterate validation errors. Returns Array when no block given, nil when block given.
@@ -492,7 +498,8 @@ module JSONSchema
     ?registry: Registry?,
     ?pattern_options: (RegexOptions | FancyRegexOptions)?,
     ?email_options: EmailOptions?,
-    ?http_options: HttpOptions?
+    ?http_options: HttpOptions?,
+    ?offline: bool?
   ) -> Array[ValidationError]
                       | (
     untyped schema,
@@ -509,7 +516,8 @@ module JSONSchema
     ?registry: Registry?,
     ?pattern_options: (RegexOptions | FancyRegexOptions)?,
     ?email_options: EmailOptions?,
-    ?http_options: HttpOptions?
+    ?http_options: HttpOptions?,
+    ?offline: bool?
   ) { (ValidationError) -> void } -> nil
 
   # One-off evaluation returning structured output.
@@ -527,7 +535,8 @@ module JSONSchema
     ?registry: Registry?,
     ?pattern_options: (RegexOptions | FancyRegexOptions)?,
     ?email_options: EmailOptions?,
-    ?http_options: HttpOptions?
+    ?http_options: HttpOptions?,
+    ?offline: bool?
   ) -> Evaluation
 
   # Reusable JSON Schema validator.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonschema_rs
 version: !ruby/object:Gem::Version
-  version: 0.58.4
+  version: 0.58.5
 platform: x86_64-linux
 authors:
 - Dmitry Dygalo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -56,7 +56,7 @@ metadata:
   homepage_uri: https://github.com/Stranger6667/jsonschema/tree/master/crates/jsonschema-rb
   source_code_uri: https://github.com/Stranger6667/jsonschema
   changelog_uri: https://github.com/Stranger6667/jsonschema/blob/master/crates/jsonschema-rb/CHANGELOG.md
-  documentation_uri: https://github.com/Stranger6667/jsonschema/tree/master/crates/jsonschema-rb#readme
+  documentation_uri: https://github.com/Stranger6667/jsonschema/blob/ruby-v0.58.5/crates/jsonschema-rb/README.md
   bug_tracker_uri: https://github.com/Stranger6667/jsonschema/issues
   funding_uri: https://github.com/sponsors/Stranger6667
   rubygems_mfa_required: 'true'