jsonschema_rs 0.58.4 → 0.58.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eebce6f817d3f7c3f2735c03d72c8e70ae14399ec0379cf97e08c4af53f82ac6
-  data.tar.gz: 11532b9e972888378db6428b9f42427aa338da51a456b6e2a4df9320a32a7008
+  metadata.gz: c602494a0fa886d7e8ea3b14a5a707014b7723234371424cdb2315aa0a1d451f
+  data.tar.gz: 1634e82743fe6cd6c4634809a38dccc8bfbbf488e8e55a4038359ad8b0630399
 SHA512:
-  metadata.gz: b71d1b975f2621fa079548c032dfb6277046d01595a3f17ffe5a2b5d29f42d85f1216db919a5183e2b148f6364210b41792d0cf4802c50740e3d1cbfad420cfd
-  data.tar.gz: 03fa98bcd49da60b01087762c3a3b58831258a29781e098c24abf85e8a9b2945bfe663a2c9b36f2263ebc1b964e51a801fe5e93dec23bedb3e4d3d8e86eda47c
+  metadata.gz: 105326b4a1e627bdc426e746b7bf5e2e1521aee3a6fe98739735799d4b6b7f5e49652d5c00beff8c8b66cee37b4ed7619692f8cb3318aa42dff77727f0b4d05a
+  data.tar.gz: 336eda3d631ac7f02af86b94488a49d7c720051360328f5d1e269a75b3144200f07de18e507be070248a04d509909334b66f5310bc9cf5c2bb7f413ed6a81cc2

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/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jsonschema-rb"
-version = "0.58.4"
+version = "0.58.5"
 edition = "2021"
 authors = ["Dmitry Dygalo <dmitry@dygalo.dev>"]
 license = "MIT"
@@ -14,8 +14,8 @@ crate-type = ["cdylib"]
 
 [dependencies]
 strum = "0.28.0"
-jsonschema = { version = "0.58.4", default-features = false, features = ["magnus", "arbitrary-precision", "resolve-http", "resolve-file", "tls-ring", "macros", "idna"] }
-magnus = { version = "0.8", features = ["rb-sys"] }
+jsonschema = { version = "0.58.5", default-features = false, features = ["magnus", "arbitrary-precision", "resolve-http", "resolve-file", "tls-ring", "macros", "idna"] }
+magnus = { version = "0.9", features = ["rb-sys"] }
 rb-sys = "0.9"
 serde = { workspace = true }
 serde_json = { workspace = true, features = ["arbitrary_precision"] }

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/ext/jsonschema/Cargo.lock

@@ -693,9 +693,9 @@ dependencies = [
 
 [[package]]
 name = "jsonschema"
-version = "0.58.4"
+version = "0.58.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5761b0ca0a31464030d7c2a98087fde3124ebb5e09b5a112cdb815f03b8ee150"
+checksum = "ea18b8d5e1469b1bdd6b349169305141316a7c26da27f239773b65c830c0f5d6"
 dependencies = [
  "ahash",
  "bytecount",
@@ -709,7 +709,7 @@ dependencies = [
  "jsonschema-macros",
  "jsonschema-regex",
  "jsonschema-value",
- "magnus",
+ "magnus 0.9.1",
  "num-bigint",
  "num-cmp",
  "num-traits",
@@ -727,9 +727,9 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-macros"
-version = "0.58.4"
+version = "0.58.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "75e6d7c2c9afe6aa7de831af841801c954b83b1742f0e228b505326456a70b8f"
+checksum = "ef3da09f0a27daeae23033d6e018a5c4b606953a3a90eee16f3e360e975444d3"
 dependencies = [
  "jsonschema-macros-core",
  "proc-macro2",
@@ -737,9 +737,9 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-macros-core"
-version = "0.58.4"
+version = "0.58.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "65bcdd5a5c9e2c6ddefdddef36f1a27f5183649bd135f633e1bc6bfa97982407"
+checksum = "a12bd067dca38b8182b307bca050da4c5a73f9be452d06415e03a0957517a70b"
 dependencies = [
  "fancy-regex",
  "indexmap",
@@ -756,10 +756,10 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-rb-ext"
-version = "0.58.4"
+version = "0.58.5"
 dependencies = [
  "jsonschema",
- "magnus",
+ "magnus 0.8.2",
  "rb-sys",
  "referencing",
  "serde",
@@ -770,24 +770,24 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-regex"
-version = "0.58.4"
+version = "0.58.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f1ffba4378a3d6ee7f1ab65a8ed95c711ccfe4a3870932bdce89d8260abed38a"
+checksum = "854e9e22c420535035e95eed240cbfb4a5f4b7da74d122d63144e0c31926dbfd"
 dependencies = [
  "regex-syntax",
 ]
 
 [[package]]
 name = "jsonschema-value"
-version = "0.58.4"
+version = "0.58.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "386121f898b560ff6aaa7974952720e9d9276a201eca31296387c2ed8707855e"
+checksum = "4e3bfac11ac357ec620880025757d38c67da8fd5b9ef5024d19f0f360002b4ca"
 dependencies = [
  "ahash",
  "bytecount",
  "fraction",
  "getrandom 0.3.4",
- "magnus",
+ "magnus 0.9.1",
  "num-bigint",
  "num-cmp",
  "num-traits",
@@ -845,7 +845,19 @@ version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3b36a5b126bbe97eb0d02d07acfeb327036c6319fd816139a49824a83b7f9012"
 dependencies = [
- "magnus-macros",
+ "magnus-macros 0.8.0",
+ "rb-sys",
+ "rb-sys-env",
+ "seq-macro",
+]
+
+[[package]]
+name = "magnus"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c01bef153b8d0f086991f0e166474a1d57b738221f9a9c11405d498ac95a44d"
+dependencies = [
+ "magnus-macros 0.9.1",
  "rb-sys",
  "rb-sys-env",
  "seq-macro",
@@ -862,6 +874,17 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "magnus-macros"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "memchr"
 version = "2.8.0"
@@ -1136,9 +1159,9 @@ dependencies = [
 
 [[package]]
 name = "referencing"
-version = "0.58.4"
+version = "0.58.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5cfa1c91745dbca76a406b926918d7c63e15a4525ebab939fec3e015a1fb82b1"
+checksum = "590efadb0a669f1712c1e3ab810a55d4c3d20d0127c455f7236dd0710aba0346"
 dependencies = [
  "ahash",
  "fluent-uri",

data/ext/jsonschema/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jsonschema-rb-ext"
-version = "0.58.4"
+version = "0.58.5"
 edition = "2021"
 publish = false
 
@@ -10,10 +10,10 @@ name = "jsonschema_rb"
 path = "../../src/lib.rs"
 
 [dependencies]
-jsonschema = { version = "0.58.4", default-features = false, features = ["magnus", "arbitrary-precision", "resolve-http", "resolve-file", "tls-ring", "macros", "idna"] }
+jsonschema = { version = "0.58.5", default-features = false, features = ["magnus", "arbitrary-precision", "resolve-http", "resolve-file", "tls-ring", "macros", "idna"] }
 magnus = { version = "0.8", features = ["rb-sys"] }
 rb-sys = "0.9"
-referencing = "0.58.4"
+referencing = "0.58.5"
 serde = { version = "1", features = ["derive"] }
 serde_json = { version = "1", features = ["arbitrary_precision"] }
 strum = "0.28.0"

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.

data/src/canonical.rs

@@ -58,7 +58,7 @@ macro_rules! canonical_error_class {
             let exception_class =
                 ExceptionClass::from_value(error_class.as_value()).expect("ExceptionClass");
             // The cached handle is invisible to Ruby's GC; registration pins it across compaction.
-            magnus::gc::register_mark_object(exception_class);
+            ruby.gc_register_mark_object(exception_class);
             exception_class
         });
     };

data/src/lib.rs

@@ -25,9 +25,7 @@ use jsonschema::{
 };
 use magnus::{
     error::ErrorType,
-    function,
-    gc::{register_address, register_mark_object, unregister_address},
-    method,
+    function, method,
     prelude::*,
     rb_sys::AsRawValue,
     scan_args::scan_args,
@@ -133,7 +131,7 @@ fn build_validator(
 ///
 /// Persistent `Validator` instances protect their callbacks via the GC mark phase
 /// (see `Validator::mark_callback_roots`). One-off calls have no such wrapper, so
-/// this guard calls `register_address` on construction and `unregister_address` on
+/// this guard calls `gc_register_address` on construction and `gc_unregister_address` on
 /// drop to keep callbacks alive while validation runs.
 struct CallbackRootGuard {
     roots: Vec<Value>,
@@ -154,7 +152,7 @@ impl CallbackRootGuard {
         // We do not mutate `roots` after this point, so references used for GC address
         // registration remain valid for the lifetime of the guard.
         for root in &roots {
-            register_address(root);
+            ruby.gc_register_address(root);
         }
 
         Self { roots }
@@ -163,8 +161,9 @@ impl CallbackRootGuard {
 
 impl Drop for CallbackRootGuard {
     fn drop(&mut self) {
+        let ruby = Ruby::get().expect("Ruby VM should be initialized");
         for root in &self.roots {
-            unregister_address(root);
+            ruby.gc_unregister_address(root);
         }
     }
 }
@@ -250,7 +249,7 @@ static VALIDATION_ERROR_CLASS: Lazy<ExceptionClass> = Lazy::new(|ruby| {
         .expect("JSONSchema::ValidationError must be defined before native extension is used");
     let exc_cls = ExceptionClass::from_value(cls.as_value())
         .expect("JSONSchema::ValidationError must be an exception class");
-    register_mark_object(exc_cls);
+    ruby.gc_register_mark_object(exc_cls);
     exc_cls
 });
 
@@ -264,7 +263,7 @@ static REFERENCING_ERROR_CLASS: Lazy<ExceptionClass> = Lazy::new(|ruby| {
         .expect("JSONSchema::ReferencingError must be defined before native extension is used");
     let exc_cls = ExceptionClass::from_value(cls.as_value())
         .expect("JSONSchema::ReferencingError must be an exception class");
-    register_mark_object(exc_cls);
+    ruby.gc_register_mark_object(exc_cls);
     exc_cls
 });
 
@@ -585,9 +584,9 @@ pub struct Validator {
     mask: Option<String>,
     /// Marked during Ruby's GC mark phase to keep runtime callbacks alive.
     callback_roots: CallbackRoots,
-    /// Protects callbacks via `register_address` during schema compilation —
+    /// Protects callbacks via `gc_register_address` during schema compilation —
     /// before this wrapper exists and `mark()` can run. Held so that its `Drop`
-    /// impl calls `unregister_address` to balance the registrations.
+    /// impl calls `gc_unregister_address` to balance the registrations.
     _compilation_roots: CompilationRootsRef,
 }
 

data/src/options.rs

@@ -6,9 +6,7 @@ use std::{
 
 use magnus::{
     block::Proc,
-    function,
-    gc::{register_address, unregister_address},
-    method,
+    function, method,
     prelude::*,
     scan_args::{get_kwargs, scan_args, KwArgs},
     value::Opaque,
@@ -19,7 +17,7 @@ use jsonschema::json::{magnus_invalidate_members_cache, Magnus, RbNode};
 
 use crate::{
     registry::Registry,
-    retriever::{make_retriever, RubyRetriever},
+    retriever::{make_retriever, DetachedRetriever, RubyRetriever},
     ser::{map_to_ruby, value_to_ruby},
     static_id::{define_rb_intern, StaticId},
     CUSTOM_KEYWORD_CAUSE, LAST_CALLBACK_ERROR,
@@ -85,10 +83,10 @@ pub struct ParsedOptions<'i> {
 ///   mechanism for preventing collection of objects referenced by native extensions.
 ///   For one-off validation functions (module-level `valid?`, `validate!`, etc.),
 ///   where no persistent `Validator` exists, a [`CallbackRootGuard`](crate::CallbackRootGuard)
-///   temporarily registers the same roots via `register_address` for the duration
+///   temporarily registers the same roots via `gc_register_address` for the duration
 ///   of the call.
 ///
-/// * **`CompilationRoots`** — registered via `register_address` immediately when
+/// * **`CompilationRoots`** — registered via `gc_register_address` immediately when
 ///   added, so callbacks are protected during schema compilation (before the
 ///   `Validator` wrapper and its mark function exist). Unregistered on drop.
 ///
@@ -104,10 +102,10 @@ pub struct CompilationRoots {
 }
 
 impl CompilationRoots {
-    fn add(&self, value: Opaque<Value>) -> Result<(), ()> {
+    fn add(&self, ruby: &Ruby, value: Opaque<Value>) -> Result<(), ()> {
         let mut roots = self.roots.lock().map_err(|_| ())?;
         let pinned = Box::pin(value);
-        register_address(pinned.as_ref().get_ref());
+        ruby.gc_register_address(pinned.as_ref().get_ref());
         roots.push(pinned);
         Ok(())
     }
@@ -119,8 +117,9 @@ impl Drop for CompilationRoots {
             Ok(roots) => roots,
             Err(poisoned) => poisoned.into_inner(),
         };
+        let ruby = Ruby::get().expect("Ruby VM should be initialized");
         for root in roots.drain(..) {
-            unregister_address(root.as_ref().get_ref());
+            ruby.gc_unregister_address(root.as_ref().get_ref());
         }
     }
 }
@@ -523,7 +522,7 @@ pub fn make_options_from_kwargs(
             "`offline` cannot be used together with `retriever`",
         ));
     }
-    let mut opts = jsonschema::options_for::<Magnus>();
+    let mut opts = jsonschema::options_for::<Magnus>().with_retriever(DetachedRetriever(None));
     let mut registry = None;
     let mut retriever = None;
     let retriever_was_provided = retriever_val.is_some();
@@ -553,12 +552,14 @@ pub fn make_options_from_kwargs(
 
     if let Some(val) = retriever_val {
         if let Some(ret) = make_retriever(ruby, val)? {
-            compilation_roots.add(Opaque::from(val)).map_err(|()| {
-                Error::new(
-                    ruby.exception_runtime_error(),
-                    "Compilation callback root storage is poisoned",
-                )
-            })?;
+            compilation_roots
+                .add(ruby, Opaque::from(val))
+                .map_err(|()| {
+                    Error::new(
+                        ruby.exception_runtime_error(),
+                        "Compilation callback root storage is poisoned",
+                    )
+                })?;
             {
                 let mut roots = callback_roots.lock().map_err(|_| {
                     Error::new(
@@ -586,7 +587,7 @@ pub fn make_options_from_kwargs(
                 if let Some(registry_retriever_value) = reg.retriever_value(ruby) {
                     if let Some(ret) = make_retriever(ruby, registry_retriever_value)? {
                         compilation_roots
-                            .add(Opaque::from(registry_retriever_value))
+                            .add(ruby, Opaque::from(registry_retriever_value))
                             .map_err(|()| {
                                 Error::new(
                                     ruby.exception_runtime_error(),
@@ -633,7 +634,7 @@ pub fn make_options_from_kwargs(
             })?;
 
             compilation_roots
-                .add(Opaque::from(callback))
+                .add(ruby, Opaque::from(callback))
                 .map_err(|()| {
                     Error::new(
                         ruby.exception_runtime_error(),
@@ -692,7 +693,7 @@ pub fn make_options_from_kwargs(
                 class: Opaque::from(callback),
             });
             compilation_roots
-                .add(Opaque::from(callback))
+                .add(ruby, Opaque::from(callback))
                 .map_err(|()| {
                     Error::new(
                         ruby.exception_runtime_error(),
@@ -755,7 +756,7 @@ pub fn make_options_from_kwargs(
                         Ok(inst) => {
                             let opaque_inst = Opaque::from(inst);
                             compilation_roots_for_keyword
-                                .add(opaque_inst)
+                                .add(&inner_ruby, opaque_inst)
                                 .map_err(|()| {
                                     jsonschema::ValidationError::custom(
                                         "Compilation callback root storage is poisoned",
@@ -839,9 +840,9 @@ pub fn make_options_from_kwargs(
         if let Some(ref ca_cert) = hopts.ca_cert {
             http_opts = http_opts.add_root_certificate(ca_cert);
         }
-        opts = opts
-            .with_http_options(&http_opts)
+        let retriever = jsonschema::HttpRetriever::new(&http_opts)
             .map_err(|e| Error::new(ruby.exception_arg_error(), e.to_string()))?;
+        opts = opts.with_retriever(DetachedRetriever(Some(retriever)));
     }
 
     if offline {

data/src/registry.rs

@@ -1,9 +1,7 @@
 use std::sync::Arc;
 
 use magnus::{
-    function,
-    gc::{register_address, unregister_address},
-    method,
+    function, method,
     prelude::*,
     scan_args::{get_kwargs, scan_args},
     value::Opaque,
@@ -23,13 +21,13 @@ struct RetrieverBuildRootGuard {
 }
 
 impl RetrieverBuildRootGuard {
-    fn new(root: Option<Value>) -> Self {
+    fn new(ruby: &Ruby, root: Option<Value>) -> Self {
         let mut roots = Vec::new();
         if let Some(value) = root {
             roots.push(value);
         }
         for value in &roots {
-            register_address(value);
+            ruby.gc_register_address(value);
         }
         Self { roots }
     }
@@ -37,8 +35,9 @@ impl RetrieverBuildRootGuard {
 
 impl Drop for RetrieverBuildRootGuard {
     fn drop(&mut self) {
+        let ruby = Ruby::get().expect("Ruby VM should be initialized");
         for value in &self.roots {
-            unregister_address(value);
+            ruby.gc_unregister_address(value);
         }
     }
 }
@@ -148,7 +147,7 @@ impl Registry {
 
         // Keep the retriever proc GC-rooted for the entire build, because `build`
         // may call into retriever callbacks while traversing referenced resources.
-        let _retriever_build_guard = RetrieverBuildRootGuard::new(retriever_build_root);
+        let _retriever_build_guard = RetrieverBuildRootGuard::new(ruby, retriever_build_root);
         for item in resources {
             let pair: RArray = TryConvert::try_convert(item)?;
             if pair.len() != 2 {

data/src/retriever.rs

@@ -2,6 +2,7 @@
 use jsonschema::{Retrieve, Uri};
 use magnus::{block::Proc, prelude::*, value::Opaque, Error, Ruby, Value};
 use serde_json::Value as JsonValue;
+use std::{ffi::c_void, panic::AssertUnwindSafe};
 
 use crate::ser::to_value;
 
@@ -98,3 +99,52 @@ pub fn make_retriever(ruby: &Ruby, value: Value) -> Result<Option<RubyRetriever>
 
     Ok(Some(RubyRetriever::new(proc)))
 }
+
+/// The built-in HTTP and file retriever, run with the GVL released so other Ruby threads keep running while it waits.
+pub struct DetachedRetriever(pub Option<jsonschema::HttpRetriever>);
+
+type RetrieveResult = Result<JsonValue, Box<dyn std::error::Error + Send + Sync>>;
+
+#[allow(unsafe_code)]
+impl Retrieve for DetachedRetriever {
+    fn retrieve(&self, uri: &Uri<String>) -> RetrieveResult {
+        struct Call<'a> {
+            retriever: &'a DetachedRetriever,
+            uri: &'a Uri<String>,
+            result: Option<std::thread::Result<RetrieveResult>>,
+        }
+
+        unsafe extern "C" fn call(data: *mut c_void) -> *mut c_void {
+            // SAFETY: `data` is the `Call` below, alive until `rb_thread_call_without_gvl` returns
+            let call = unsafe { &mut *data.cast::<Call<'_>>() };
+            call.result = Some(std::panic::catch_unwind(AssertUnwindSafe(|| {
+                match &call.retriever.0 {
+                    Some(retriever) => retriever.retrieve(call.uri),
+                    // A client per retrieval, as the core default retriever does; building one up front would cost every validator build
+                    None => jsonschema::HttpRetriever::new(&jsonschema::HttpOptions::new())?
+                        .retrieve(call.uri),
+                }
+            })));
+            std::ptr::null_mut()
+        }
+
+        let mut data = Call {
+            retriever: self,
+            uri,
+            result: None,
+        };
+        // SAFETY: `call` touches no Ruby objects, so it may run without the GVL
+        unsafe {
+            rb_sys::rb_thread_call_without_gvl(
+                Some(call),
+                (&raw mut data).cast(),
+                None,
+                std::ptr::null_mut(),
+            );
+        }
+        match data.result.expect("Retrieval runs to completion") {
+            Ok(result) => result,
+            Err(panic) => std::panic::resume_unwind(panic),
+        }
+    }
+}

data/src/ser.rs

@@ -3,7 +3,6 @@ use jsonschema::canonical::json::{canonical_number, BorrowedNumber};
 use magnus::{
     error::ErrorType,
     exception::ExceptionClass,
-    gc::register_mark_object,
     prelude::*,
     rb_sys::AsRawValue,
     value::{Lazy, ReprValue},
@@ -28,7 +27,7 @@ static BIG_DECIMAL_CLASS: Lazy<RClass> = Lazy::new(|ruby| {
     let cls: RClass = ruby
         .eval("BigDecimal")
         .expect("BigDecimal class must exist");
-    register_mark_object(cls);
+    ruby.gc_register_mark_object(cls);
     cls
 });
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonschema_rs
 version: !ruby/object:Gem::Version
-  version: 0.58.4
+  version: 0.58.5
 platform: ruby
 authors:
 - Dmitry Dygalo
@@ -80,7 +80,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'