jsonschema_rs 0.55.1 → 0.57.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2514fe367de6ec6e45655fb8a9a06b0e10edb78f2a795f4cc7db63c223435ae5
-  data.tar.gz: 79027de8d2b2ffcda419cd3248b22f956f259a49d52dd9961f813ca6b10d31ff
+  metadata.gz: 11217286a118f4602ff911fcb2b4bd68810935fd7bf08fcffdd6ad906804683f
+  data.tar.gz: cdbf9193f44e167d360fd34032089368d86dc6971f87fe7118da6549b46efd36
 SHA512:
-  metadata.gz: a2d648f5826ce9490f9ec562015ece34eac2f296a5566d746d380de601ce1799d4acdf91aa99014e8aec1a5d1d79d65f5ec9cced8e4bbae9412e672e55fb5e9a
-  data.tar.gz: 6387cb7a07b4f4bf260109770e3e81aff8ff7c31ec560231cdb0abf9abb592876046e0fec456754c413d5ff85dcb5085e25eac6bf858d7ad0cf853933c4d8bf6
+  metadata.gz: '0875f5b26b56167b3e71a6278620d72db85ea80d5c8b14fa44197c5cfc36b12ec85703c809ed07bd5bb847dcebfc018a18cecb1d5727c05809ff50af3903a85d'
+  data.tar.gz: 537158f7caeba6c57e103b6630869cd78b929c2e3ffee0e12c7b267797b89449fb97446d7d163040e65a9e39c9d1916e61e298441ccb01ea90061d447a923033

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [0.57.0] - 2026-09-22
+
+### Added
+
+- `Canonical.find_unsatisfiable`, naming every subschema of a document that admits no value, and the keywords that leave it empty.
+
+### Fixed
+
+- The instance path of a schema build error, which was empty instead of naming the keyword location that failed to compile.
+
+## [0.56.0] - 2026-09-10
+
+### Added
+
+- `JSONSchema::Canonical::RawReason`, what stopped a run from modeling a document, and `RawView#reason` and `RawView#pointer`, carrying it beside the subschema the run stopped on.
+
+### Changed
+
+- Canonicalization of a `oneOf` whose branches share a region too wide to expand, which spent the document's whole intersection allowance on that choice and kept the document `Raw`.
+
+### Performance
+
+- Preparing or building a schema that names no base URI parses the default one once for the process instead of once per schema.
+- Canonicalization reads the facets no checker covers once per node instead of once per containment query.
+
 ## [0.55.1] - 2026-09-08
 
 ### Changed
@@ -552,7 +577,9 @@
 
 - Initial public release
 
-[Unreleased]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.55.1...HEAD
+[Unreleased]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.57.0...HEAD
+[0.57.0]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.56.0...ruby-v0.57.0
+[0.56.0]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.55.1...ruby-v0.56.0
 [0.55.1]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.55.0...ruby-v0.55.1
 [0.55.0]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.54.0...ruby-v0.55.0
 [0.54.0]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.53.0...ruby-v0.54.0

data/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jsonschema-rb"
-version = "0.55.1"
+version = "0.57.0"
 edition = "2021"
 authors = ["Dmitry Dygalo <dmitry@dygalo.dev>"]
 license = "MIT"
@@ -14,7 +14,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 strum = "0.28.0"
-jsonschema = { version = "0.55.1", default-features = false, features = ["magnus", "arbitrary-precision", "resolve-http", "resolve-file", "tls-ring", "macros", "idna"] }
+jsonschema = { version = "0.57.0", 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"
 serde = { workspace = true }

data/README.md

@@ -371,6 +371,33 @@ Compare a request schema new-against-old and a response schema old-against-new:
 
 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`.
 
+### 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:
+
+```ruby
+reasons = JSONSchema::Canonical.find_unsatisfiable(
+  {
+    "properties" => {
+      "tag" => { "type" => "string", "minLength" => 5, "maxLength" => 2 },
+      "name" => { "type" => "string" }
+    }
+  }
+)
+
+case reasons["/properties/tag"]
+in JSONSchema::Canonical::ConflictReason[causes:]
+  causes.map { |cause| [cause.pointer, cause.keywords] }
+  # => [["/properties/tag", ["type"]], ["/properties/tag", ["minLength", "maxLength"]]]
+end
+
+# A live subschema is not reported
+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`.
+
 ## 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.

data/ext/jsonschema/Cargo.lock

@@ -693,9 +693,9 @@ dependencies = [
 
 [[package]]
 name = "jsonschema"
-version = "0.55.1"
+version = "0.57.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b68339c3d874e48151d74ffe256d93a58cffa240983cb0967d3cbaea083a44fe"
+checksum = "71160ed5f6dbe36a2d6be79f4ca03ee09a99d2866f340faed49458913449aefa"
 dependencies = [
  "ahash",
  "bytecount",
@@ -726,9 +726,9 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-macros"
-version = "0.55.1"
+version = "0.57.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0ee1d26bd968d4f88b291615dada57b6acc38662bae4e2244c6c9fc31e70bacc"
+checksum = "9b5421caa3ea97392a353a9bc57b33ac844a6a128f4c3d11ac6c12cc462072ac"
 dependencies = [
  "jsonschema-macros-core",
  "proc-macro2",
@@ -736,9 +736,9 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-macros-core"
-version = "0.55.1"
+version = "0.57.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "676d45db449ae16bce2582dcff3e7b2dfb177a3c2f885af072257815bc8825c4"
+checksum = "7c1e51f90029687e9fe880db5ff56b1a99e66eef2464a862f7a8408aed851168"
 dependencies = [
  "fancy-regex",
  "indexmap",
@@ -755,7 +755,7 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-rb-ext"
-version = "0.55.1"
+version = "0.57.0"
 dependencies = [
  "jsonschema",
  "magnus",
@@ -769,18 +769,18 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-regex"
-version = "0.55.1"
+version = "0.57.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6307b5b51216ec9b941b52244c74043fa0b1d6b657b56199f57cb1416d3641c5"
+checksum = "48d2120d8466ffcdc1b3be4b88ff0e9191bf5b6b09b1b1af1eef9aff8f465ea3"
 dependencies = [
  "regex-syntax",
 ]
 
 [[package]]
 name = "jsonschema-value"
-version = "0.55.1"
+version = "0.57.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0230ac05e09c6111e96c147b75c390579f5cbd45654b980c68ac60fe17b3f129"
+checksum = "3fbfa40a42415369d940b3848f3ce08099f1f1ac04d73e8580f4d652617c4f44"
 dependencies = [
  "ahash",
  "bytecount",
@@ -1135,9 +1135,9 @@ dependencies = [
 
 [[package]]
 name = "referencing"
-version = "0.55.1"
+version = "0.57.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a196a5b4a8a12f46b6353174df865a05d41a6055aff212ec30877492788618b6"
+checksum = "b06f6798be4fed305e74df8b1fb90cf59c6b8cc17aa3febeb1830c0c6b627b3e"
 dependencies = [
  "ahash",
  "fluent-uri",

data/ext/jsonschema/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "jsonschema-rb-ext"
-version = "0.55.1"
+version = "0.57.0"
 edition = "2021"
 publish = false
 
@@ -10,10 +10,10 @@ name = "jsonschema_rb"
 path = "../../src/lib.rs"
 
 [dependencies]
-jsonschema = { version = "0.55.1", default-features = false, features = ["magnus", "arbitrary-precision", "resolve-http", "resolve-file", "tls-ring", "macros", "idna"] }
+jsonschema = { version = "0.57.0", 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.55.1"
+referencing = "0.57.0"
 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.55.1"
+  VERSION = "0.57.0"
 end

data/sig/jsonschema.rbs

@@ -23,6 +23,10 @@ module JSONSchema
     # What an array requires of its elements: all distinct, some repeated, or neither.
     type distinctness = :unconstrained | :all_distinct | :some_repeated
 
+    # What stopped a run from modeling a document.
+    type raw_reason = :unknown_dialect | :unmodeled | :outgrew_intersections
+                    | :outgrew_cases | :inexact_intersection
+
     # Whether one schema admits every value another does. Only `:yes` proves containment: test
     # for `:yes`, and treat `:unknown` like `:no`.
     type containment = :yes | :no | :unknown
@@ -57,6 +61,15 @@ module JSONSchema
       ALL: Array[distinctness]
     end
 
+    module RawReason
+      UNKNOWN_DIALECT: :unknown_dialect
+      UNMODELED: :unmodeled
+      OUTGREW_INTERSECTIONS: :outgrew_intersections
+      OUTGREW_CASES: :outgrew_cases
+      INEXACT_INTERSECTION: :inexact_intersection
+      ALL: Array[raw_reason]
+    end
+
     module Kind
       MULTI_TYPE: :multi_type
       TYPED_GROUP: :typed_group
@@ -288,9 +301,60 @@ module JSONSchema
     # A schema the canonical form does not support structurally, kept verbatim.
     class RawView
       def schema: () -> untyped
+      def reason: () -> raw_reason
+      def pointer: () -> String?
       def inspect: () -> String
       def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
     end
+
+    # One part of a schema object, as a reason names it.
+    class Cause
+      # JSON Pointer of the schema object holding `keywords`, or of the subschema itself.
+      def pointer: () -> String
+      # Keywords of one family present at `pointer`; empty for a whole subschema.
+      def keywords: () -> Array[String]
+      def ==: (untyped other) -> bool
+      def inspect: () -> String
+      def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
+    end
+
+    # The subschema is written as `false`.
+    class LiteralReason
+      def inspect: () -> String
+      def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
+    end
+
+    # One part every value must satisfy admits nothing by itself. A subschema part has a reason
+    # of its own under its pointer.
+    class EmptyReason
+      def cause: () -> Cause
+      def inspect: () -> String
+      def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
+    end
+
+    # Each part admits values; no value satisfies all of them together.
+    class ConflictReason
+      def causes: () -> Array[Cause]
+      def inspect: () -> String
+      def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
+    end
+
+    # Why a subschema admits no value.
+    type unsatisfiable_reason = LiteralReason | EmptyReason | ConflictReason
+
+    # The subschemas that admit no value, by JSON Pointer, each with why.
+    #
+    # A pointer left out is not proven satisfiable: a document the canonical form does not model
+    # reports nothing, as `satisfiability` answers `:unknown`.
+    def self.find_unsatisfiable: (
+      untyped schema,
+      ?draft: JSONSchema::draft?,
+      ?validate_formats: bool?,
+      ?pattern_options: (RegexOptions | FancyRegexOptions)?,
+      ?retriever: (^(String) -> untyped)?,
+      ?registry: Registry?,
+      ?base_uri: String?
+    ) -> Hash[String, unsatisfiable_reason]
   end
 
   # Reduce a schema to its canonical form.

data/src/canonical.rs

@@ -1,8 +1,9 @@
 use jsonschema::{
     canonical::{
-        CanonicalKind, CanonicalSchema, CanonicalView, CanonicalizationError, Containment,
-        ContainsView as CoreContainsView, Distinctness,
-        ObjectViolationView as CoreObjectViolationView, Satisfiability,
+        CanonicalKind, CanonicalSchema, CanonicalView, CanonicalizationError, Cause as CoreCause,
+        Containment, ContainsView as CoreContainsView, Distinctness,
+        ObjectViolationView as CoreObjectViolationView, RawReason, Satisfiability,
+        UnsatisfiableReason as CoreUnsatisfiableReason,
     },
     JsonType,
 };
@@ -226,7 +227,13 @@ impl RbCanonicalSchema {
             CanonicalView::AnyOf(branches) => ruby.obj_wrap(AnyOfView { branches }).as_value(),
             CanonicalView::OneOf(branches) => ruby.obj_wrap(OneOfView { branches }).as_value(),
             CanonicalView::Reference(uri) => ruby.obj_wrap(ReferenceView { uri }).as_value(),
-            CanonicalView::Raw(schema) => ruby.obj_wrap(RawView { schema }).as_value(),
+            CanonicalView::Raw(raw) => ruby
+                .obj_wrap(RawView {
+                    schema: raw.schema,
+                    reason: raw.reason,
+                    pointer: raw.pointer,
+                })
+                .as_value(),
         }
     }
 
@@ -293,6 +300,8 @@ impl RbCanonicalSchema {
 #[magnus(class = "JSONSchema::Canonical::RawView", free_immediately)]
 pub struct RawView {
     schema: serde_json::Value,
+    reason: RawReason,
+    pointer: Option<String>,
 }
 
 impl DataTypeFunctions for RawView {}
@@ -302,10 +311,23 @@ impl RawView {
         value_to_ruby(ruby, &rb_self.schema)
     }
 
+    fn reason(ruby: &Ruby, rb_self: &Self) -> Value {
+        ruby.sym_new(rb_self.reason.as_str()).as_value()
+    }
+
+    fn pointer(ruby: &Ruby, rb_self: &Self) -> Value {
+        rb_self.pointer.as_ref().map_or_else(
+            || ruby.qnil().as_value(),
+            |pointer| ruby.str_new(pointer).as_value(),
+        )
+    }
+
     fn inspect(ruby: &Ruby, rb_self: &Self) -> Result<String, Error> {
         Ok(format!(
-            "#<JSONSchema::Canonical::RawView schema={}>",
-            Self::schema(ruby, rb_self)?.inspect()
+            "#<JSONSchema::Canonical::RawView schema={} reason={} pointer={}>",
+            Self::schema(ruby, rb_self)?.inspect(),
+            Self::reason(ruby, rb_self).inspect(),
+            Self::pointer(ruby, rb_self).inspect()
         ))
     }
 
@@ -315,6 +337,8 @@ impl RawView {
             ruby.sym_new("schema"),
             value_to_ruby(ruby, &rb_self.schema)?,
         )?;
+        hash.aset(ruby.sym_new("reason"), Self::reason(ruby, rb_self))?;
+        hash.aset(ruby.sym_new("pointer"), Self::pointer(ruby, rb_self))?;
         Ok(hash)
     }
 }
@@ -1351,10 +1375,154 @@ impl EnumView {
     }
 }
 
-fn canonicalize(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
-    let parsed = scan_args::<(Value,), (), (), (), _, ()>(args)?;
-    let (schema_arg,) = parsed.required;
-    let keywords: RHash = parsed.keywords;
+/// One part of a schema object, as a reason names it.
+#[derive(magnus::TypedData)]
+#[magnus(class = "JSONSchema::Canonical::Cause", free_immediately)]
+pub struct Cause {
+    pointer: String,
+    keywords: Vec<String>,
+}
+
+impl DataTypeFunctions for Cause {}
+
+impl Cause {
+    fn pointer(ruby: &Ruby, rb_self: &Self) -> Value {
+        ruby.str_new(&rb_self.pointer).as_value()
+    }
+
+    fn keywords(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
+        let array = ruby.ary_new_capa(rb_self.keywords.len());
+        for keyword in &rb_self.keywords {
+            array.push(ruby.str_new(keyword))?;
+        }
+        Ok(array.as_value())
+    }
+
+    fn eq(rb_self: &Self, other: Value) -> bool {
+        let Ok(other_ref) = <&Cause>::try_convert(other) else {
+            return false;
+        };
+        rb_self.pointer == other_ref.pointer && rb_self.keywords == other_ref.keywords
+    }
+
+    fn inspect(ruby: &Ruby, rb_self: &Self) -> Result<String, Error> {
+        Ok(format!(
+            "#<JSONSchema::Canonical::Cause pointer={} keywords={}>",
+            Self::pointer(ruby, rb_self).inspect(),
+            Self::keywords(ruby, rb_self)?.inspect()
+        ))
+    }
+
+    fn deconstruct_keys(ruby: &Ruby, rb_self: &Self, _keys: Value) -> Result<RHash, Error> {
+        let hash = ruby.hash_new();
+        hash.aset(ruby.sym_new("pointer"), Self::pointer(ruby, rb_self))?;
+        hash.aset(ruby.sym_new("keywords"), Self::keywords(ruby, rb_self)?)?;
+        Ok(hash)
+    }
+}
+
+/// The subschema is written as `false`.
+#[derive(magnus::TypedData)]
+#[magnus(class = "JSONSchema::Canonical::LiteralReason", free_immediately)]
+pub struct LiteralReason;
+
+impl DataTypeFunctions for LiteralReason {}
+
+impl LiteralReason {
+    fn inspect(_rb_self: &Self) -> &'static str {
+        "#<JSONSchema::Canonical::LiteralReason>"
+    }
+
+    fn deconstruct_keys(ruby: &Ruby, _rb_self: &Self, _keys: Value) -> RHash {
+        ruby.hash_new()
+    }
+}
+
+/// One part every value must satisfy admits nothing by itself. A subschema part has a reason of
+/// its own under its pointer.
+#[derive(magnus::TypedData)]
+#[magnus(class = "JSONSchema::Canonical::EmptyReason", free_immediately)]
+pub struct EmptyReason {
+    cause: CoreCause,
+}
+
+impl DataTypeFunctions for EmptyReason {}
+
+impl EmptyReason {
+    fn cause(ruby: &Ruby, rb_self: &Self) -> Value {
+        cause_to_ruby(ruby, rb_self.cause.clone())
+    }
+
+    fn inspect(ruby: &Ruby, rb_self: &Self) -> String {
+        format!(
+            "#<JSONSchema::Canonical::EmptyReason cause={}>",
+            Self::cause(ruby, rb_self).inspect()
+        )
+    }
+
+    fn deconstruct_keys(ruby: &Ruby, rb_self: &Self, _keys: Value) -> Result<RHash, Error> {
+        let hash = ruby.hash_new();
+        hash.aset(ruby.sym_new("cause"), Self::cause(ruby, rb_self))?;
+        Ok(hash)
+    }
+}
+
+/// Each part admits values; no value satisfies all of them together.
+#[derive(magnus::TypedData)]
+#[magnus(class = "JSONSchema::Canonical::ConflictReason", free_immediately)]
+pub struct ConflictReason {
+    causes: Vec<CoreCause>,
+}
+
+impl DataTypeFunctions for ConflictReason {}
+
+impl ConflictReason {
+    fn causes(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
+        let array = ruby.ary_new_capa(rb_self.causes.len());
+        for cause in &rb_self.causes {
+            array.push(cause_to_ruby(ruby, cause.clone()))?;
+        }
+        Ok(array.as_value())
+    }
+
+    fn inspect(ruby: &Ruby, rb_self: &Self) -> Result<String, Error> {
+        Ok(format!(
+            "#<JSONSchema::Canonical::ConflictReason causes={}>",
+            Self::causes(ruby, rb_self)?.inspect()
+        ))
+    }
+
+    fn deconstruct_keys(ruby: &Ruby, rb_self: &Self, _keys: Value) -> Result<RHash, Error> {
+        let hash = ruby.hash_new();
+        hash.aset(ruby.sym_new("causes"), Self::causes(ruby, rb_self)?)?;
+        Ok(hash)
+    }
+}
+
+fn cause_to_ruby(ruby: &Ruby, cause: CoreCause) -> Value {
+    ruby.obj_wrap(Cause {
+        pointer: cause.pointer,
+        keywords: cause.keywords,
+    })
+    .as_value()
+}
+
+fn reason_to_ruby(ruby: &Ruby, reason: CoreUnsatisfiableReason) -> Value {
+    match reason {
+        CoreUnsatisfiableReason::Literal => ruby.obj_wrap(LiteralReason).as_value(),
+        CoreUnsatisfiableReason::Empty(cause) => ruby.obj_wrap(EmptyReason { cause }).as_value(),
+        CoreUnsatisfiableReason::Conflict(causes) => {
+            ruby.obj_wrap(ConflictReason { causes }).as_value()
+        }
+    }
+}
+
+/// Read the keyword arguments every canonicalization entry point takes, and run `call` with them.
+fn with_canonical_options<R>(
+    ruby: &Ruby,
+    keywords: RHash,
+    call: impl FnOnce(jsonschema::canonical::CanonicalizeOptions<'_>) -> Result<R, Error>,
+) -> Result<R, Error> {
     let base_kwargs: CanonicalKwArgs = get_kwargs(
         keywords,
         &[],
@@ -1370,7 +1538,6 @@ fn canonicalize(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
     let (draft_val, validate_formats, pattern_options, retriever_val, registry_val, base_uri) =
         base_kwargs.optional;
 
-    let schema_value = to_schema_value(ruby, schema_arg)?;
     let mut options = jsonschema::canonical::options();
     if let Some(draft) = draft_val {
         options = options.with_draft(parse_draft_symbol(ruby, draft)?);
@@ -1391,31 +1558,61 @@ fn canonicalize(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
             has_retriever = true;
         }
     }
-    if let Some(val) = registry_val {
-        if !val.is_nil() {
-            let registry: &Registry = TryConvert::try_convert(val).map_err(|_| {
-                Error::new(
-                    ruby.exception_type_error(),
-                    "registry must be a JSONSchema::Registry instance",
-                )
-            })?;
-            if !has_retriever {
-                if let Some(value) = registry.retriever_value(ruby) {
-                    if let Some(retriever) = make_retriever(ruby, value)? {
-                        options = options.with_retriever(retriever);
-                    }
-                }
-            }
-            options = options.with_registry(registry.inner.as_ref());
-        }
-    }
     if let Some(base_uri) = base_uri {
         options = options.with_base_uri(base_uri);
     }
-    options
-        .canonicalize(&schema_value)
-        .map(|inner| ruby.obj_wrap(RbCanonicalSchema { inner }).as_value())
-        .map_err(|error| canonicalization_error(ruby, error))
+    let Some(val) = registry_val else {
+        return call(options);
+    };
+    if val.is_nil() {
+        return call(options);
+    }
+    let registry: &Registry = TryConvert::try_convert(val).map_err(|_| {
+        Error::new(
+            ruby.exception_type_error(),
+            "registry must be a JSONSchema::Registry instance",
+        )
+    })?;
+    if !has_retriever {
+        if let Some(value) = registry.retriever_value(ruby) {
+            if let Some(retriever) = make_retriever(ruby, value)? {
+                options = options.with_retriever(retriever);
+            }
+        }
+    }
+    call(options.with_registry(registry.inner.as_ref()))
+}
+
+/// The subschemas of `schema` that admit no value, by JSON Pointer, each with why.
+fn find_unsatisfiable(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
+    let parsed = scan_args::<(Value,), (), (), (), _, ()>(args)?;
+    let (schema_arg,) = parsed.required;
+    let schema_value = to_schema_value(ruby, schema_arg)?;
+    with_canonical_options(ruby, parsed.keywords, |options| {
+        let prepared = options
+            .prepare(&schema_value)
+            .map_err(|error| canonicalization_error(ruby, error))?;
+        let reasons = prepared
+            .unsatisfiable()
+            .map_err(|error| canonicalization_error(ruby, error))?;
+        let hash = ruby.hash_new();
+        for (pointer, reason) in reasons {
+            hash.aset(ruby.str_new(&pointer), reason_to_ruby(ruby, reason))?;
+        }
+        Ok(hash.as_value())
+    })
+}
+
+fn canonicalize(ruby: &Ruby, args: &[Value]) -> Result<Value, Error> {
+    let parsed = scan_args::<(Value,), (), (), (), _, ()>(args)?;
+    let (schema_arg,) = parsed.required;
+    let schema_value = to_schema_value(ruby, schema_arg)?;
+    with_canonical_options(ruby, parsed.keywords, |options| {
+        options
+            .canonicalize(&schema_value)
+            .map(|inner| ruby.obj_wrap(RbCanonicalSchema { inner }).as_value())
+            .map_err(|error| canonicalization_error(ruby, error))
+    })
 }
 
 fn define_labels<Label: Copy + Into<&'static str>>(
@@ -1467,6 +1664,7 @@ pub(crate) fn init_canonical(ruby: &Ruby, module: &RModule) -> Result<(), Error>
         Distinctness::VARIANTS,
     )?;
     define_labels(ruby, &canonical_module, "Kind", CanonicalKind::VARIANTS)?;
+    define_labels(ruby, &canonical_module, "RawReason", RawReason::VARIANTS)?;
 
     let canonical_schema = canonical_module.define_class("CanonicalSchema", ruby.class_object())?;
     canonical_schema.define_method(
@@ -1687,9 +1885,44 @@ pub(crate) fn init_canonical(ruby: &Ruby, module: &RModule) -> Result<(), Error>
 
     let raw_view = canonical_module.define_class("RawView", ruby.class_object())?;
     raw_view.define_method("schema", method!(RawView::schema, 0))?;
+    raw_view.define_method("reason", method!(RawView::reason, 0))?;
+    raw_view.define_method("pointer", method!(RawView::pointer, 0))?;
     raw_view.define_method("inspect", method!(RawView::inspect, 0))?;
     raw_view.define_method("deconstruct_keys", method!(RawView::deconstruct_keys, 1))?;
 
+    let cause = canonical_module.define_class("Cause", ruby.class_object())?;
+    cause.define_method("pointer", method!(Cause::pointer, 0))?;
+    cause.define_method("keywords", method!(Cause::keywords, 0))?;
+    cause.define_method("==", method!(Cause::eq, 1))?;
+    cause.define_method("inspect", method!(Cause::inspect, 0))?;
+    cause.define_method("deconstruct_keys", method!(Cause::deconstruct_keys, 1))?;
+
+    let literal_reason = canonical_module.define_class("LiteralReason", ruby.class_object())?;
+    literal_reason.define_method("inspect", method!(LiteralReason::inspect, 0))?;
+    literal_reason.define_method(
+        "deconstruct_keys",
+        method!(LiteralReason::deconstruct_keys, 1),
+    )?;
+
+    let empty_reason = canonical_module.define_class("EmptyReason", ruby.class_object())?;
+    empty_reason.define_method("cause", method!(EmptyReason::cause, 0))?;
+    empty_reason.define_method("inspect", method!(EmptyReason::inspect, 0))?;
+    empty_reason.define_method(
+        "deconstruct_keys",
+        method!(EmptyReason::deconstruct_keys, 1),
+    )?;
+
+    let conflict_reason = canonical_module.define_class("ConflictReason", ruby.class_object())?;
+    conflict_reason.define_method("causes", method!(ConflictReason::causes, 0))?;
+    conflict_reason.define_method("inspect", method!(ConflictReason::inspect, 0))?;
+    conflict_reason.define_method(
+        "deconstruct_keys",
+        method!(ConflictReason::deconstruct_keys, 1),
+    )?;
+
+    canonical_module
+        .define_singleton_method("find_unsatisfiable", function!(find_unsatisfiable, -1))?;
+
     let json_module = canonical_module.define_module("JSON")?;
     json_module
         .define_singleton_method("to_string", function!(crate::canonical_json_to_string, 1))?;

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsonschema_rs
 version: !ruby/object:Gem::Version
-  version: 0.55.1
+  version: 0.57.0
 platform: ruby
 authors:
 - Dmitry Dygalo