jsonschema_rs 0.49.9-aarch64-linux → 0.50.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2656e11a6b0c73563c4654d5bddc77dfbafce7bd9533dc537502da4e07e50ba
-  data.tar.gz: ede529f84246513d55bd47c7875a6894f91fb756d55764054f614228f7c81dab
+  metadata.gz: 25eabdf997035d336701b550d29389ed1f9b894beb03d77fc45a0b10ccb4d29c
+  data.tar.gz: d62cff75ffb98e41ce3977d518c2427f38b3625925b76c036b46c0f45b75de8e
 SHA512:
-  metadata.gz: 72f5be7b2725263ef888a4b4ea585d76c84fb960403efe931bd4007bdc8583869184794211cc2af92c10a9ba61b7141b7791f0303ed7a9730160a80055f4475b
-  data.tar.gz: 9d56ecadae2bd0db1fe0dfb319f9996b78236c08623223115cc7b5a2314c43e7da1ab08fa7e30da3cd4573b10c816c6150bc5f1fb60f4f91f68cf9165bd6b111
+  metadata.gz: 46b9f8e8fc9a227c31299f26f3542ca5885ec1f680956d723cbe6978fd4b280a87a24e9b0a277e103ba6290a1fe2392a28e7387f590e7801f254f3de9f0d37f2
+  data.tar.gz: fe336068954a246f515ea3adf1f9c269891fabeed2e286a7109df28f80d7ae2d100bebfa80cd62bb66251d472a800d87805dcec7d0fe95e440e988d55bf427d2

data/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## [Unreleased]
 
+## [0.50.0] - 2026-08-20
+
+### Added
+
+- `CanonicalSchema#union` and `CanonicalSchema#subtract`.
+- `JSONSchema::Canonical::UnsupportedResult`, raised where the canonical form does not support a set operation's result.
+- `JSONSchema::Canonical::IncompatibleOperands` where both operands read `#` and it names a different document on each side.
+- `JSONSchema::Canonical::Containment`, `Satisfiability`, `Distinctness` and `Kind`: named constants for the symbols `covers`, `satisfiability`, `kind` and `ArrayView#distinctness` return, each with an `ALL` list.
+
+### Changed
+
+- `CanonicalSchema#satisfiable?` is now `CanonicalSchema#satisfiability`, answering `:yes`, `:no`, or `:unknown` - `:yes` wherever a value can be exhibited, not only for the forms listing their members.
+- `CanonicalSchema#covers` decides through the difference as well: `:no` where the argument keeps values the receiver rejects, `:yes` where nothing is left over.
+- `CanonicalSchema#is_subset_of` is now `CanonicalSchema#covers`, answering `:yes`, `:no`, or `:unknown` for whether the receiver admits every value the argument admits.
+- `CanonicalSchema#negate` raises where it used to return `nil`.
+- `JSONSchema::Canonical::UnmodeledOperand` is now `JSONSchema::Canonical::UnsupportedOperand`, and means only that an operand is a `Raw` pass-through.
+
+### Fixed
+
+- Combining nodes of two different documents repointing a `$ref` to `#` at the combined result instead of the document it was written in, including one named by a definition the result keeps.
+- Intersecting a `$ref` whose target is `true` or `false`, which crashed the interpreter.
+- A key constraint left un-narrowed once a run is out of intersections, which crashed the interpreter on the next read of it.
+- `CanonicalSchema#covers` answering `:unknown` for a schema against itself, where that schema is a `$ref`.
+- `CanonicalSchema#union` keeping a `$ref` beside the schema it names, where the other three operations read through it.
+- `CanonicalSchema#covers` and `CanonicalSchema#subtract` cancelling two nodes written the same way whose `#` names a different document.
+- Two results accepting the same values comparing unequal over the part of their documents neither reads.
+- `additionalProperties` reaching a key the pattern map matches when a finite key constraint closes the map, which dropped values both operands accept.
+- A recursive definition stopping every other pointer in the document from being read through.
+- One `$defs` entry read past a wider schema written out at every use, rather than kept as the pointer it was.
+- Set operations rejecting one document canonicalized twice, and a pruned result rejected against the document it came from, where the maps resolve every shared reference the same way.
+- Set operations comparing a `$ref` as a pointer instead of reading through it, so a schema written with a `$ref` did not cancel against the same schema written out.
+- `CanonicalSchema#subtract` asking for a complement where the difference is one of the operands or empty, declining on schemas it can subtract.
+- Set operations keeping `$defs` entries the result no longer references, which then showed up in the emitted schema.
+- `CanonicalSchema#union` declining over an approximated intersection, where the union itself is exact.
+
 ## [0.49.9] - 2026-08-10
 
 ### Added
@@ -387,7 +422,8 @@
 
 - Initial public release
 
-[Unreleased]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.49.9...HEAD
+[Unreleased]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.50.0...HEAD
+[0.50.0]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.49.9...ruby-v0.50.0
 [0.49.9]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.49.8...ruby-v0.49.9
 [0.49.8]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.49.7...ruby-v0.49.8
 [0.49.7]: https://github.com/Stranger6667/jsonschema/compare/ruby-v0.49.6...ruby-v0.49.7

data/README.md

@@ -50,6 +50,7 @@ end
 - 🔧 Custom keywords and format validators
 - ✨ Meta-schema validation for schema documents
 - 📦 Schema bundling into Compound Schema Documents
+- 🧮 Experimental schema canonicalization
 - ♦️ Supports Ruby 3.2, 3.4 and 4.0
 
 ### Supported drafts
@@ -291,6 +292,83 @@ dump_a == dump_b # => true
 
 Main use case: deduplicating equivalent JSON Schemas.
 
+## 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`:
+
+```ruby
+canonical = JSONSchema.canonicalize(
+  { "allOf" => [{ "type" => "integer", "minimum" => 0 }, { "minimum" => 10, "maximum" => 100 }] }
+)
+canonical.to_json_schema
+# => {"$schema"=>"https://json-schema.org/draft/2020-12/schema",
+#     "type"=>"integer", "minimum"=>10, "maximum"=>100}
+
+# However they were written, equivalent schemas compare equal
+canonical == JSONSchema.canonicalize({ "type" => "integer", "maximum" => 100, "minimum" => 10 })
+# => true
+
+# A schema no value can satisfy collapses
+JSONSchema.canonicalize({ "type" => "integer", "minimum" => 10, "maximum" => 5 }).satisfiability
+# => :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:
+
+```ruby
+positive = JSONSchema.canonicalize({ "type" => "integer", "minimum" => 0 })
+bounded  = JSONSchema.canonicalize({ "type" => "integer", "maximum" => 100 })
+
+# Every value both admit
+positive.intersect(bounded).to_json_schema
+# => {"type"=>"integer", "minimum"=>0, "maximum"=>100}
+
+# Every value either admits
+positive.union(bounded).to_json_schema
+# => {"type"=>"integer"}
+
+# Every value `positive` admits and `bounded` rejects
+positive.subtract(bounded).to_json_schema
+# => {"type"=>"integer", "minimum"=>101}
+
+# Every value `positive` rejects, across the types it never admitted
+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.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.
+
+```ruby
+old = JSONSchema.canonicalize({ "type" => "string" })
+new = JSONSchema.canonicalize({ "type" => "string", "maxLength" => 50 })
+
+# What `new` stopped accepting, as a schema
+old.subtract(new).to_json_schema
+# => {"$schema"=>"https://json-schema.org/draft/2020-12/schema",
+#     "type"=>"string", "minLength"=>51}
+
+# Nothing is accepted that was not accepted before, so the change only narrows
+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.
+
+`:no` on the difference proves nothing was lost. `:unknown` proves nothing either way.
+
+`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`.
+
 ## Schema Bundling
 
 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/lib/jsonschema/version.rb

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

data/sig/jsonschema.rbs

@@ -17,11 +17,64 @@ module JSONSchema
 
     # Structural discriminant of a canonical schema, one per view class.
     type kind = :multi_type | :typed_group | :string | :integer | :number | :array
-              | :object | :const | :enum | :any_of | :true | :false | :raw
+              | :object | :const | :enum | :not | :all_of | :any_of | :one_of
+              | :reference | :true | :false | :raw
+
+    # What an array requires of its elements: all distinct, some repeated, or neither.
+    type distinctness = :unconstrained | :all_distinct | :some_repeated
+
+    # Whether one schema admits every value another does.
+    type containment = :yes | :no | :unknown
+
+    # Whether any value satisfies a schema.
+    type satisfiability = :yes | :no | :unknown
 
     type view = TrueView | FalseView | MultiTypeView | TypedGroupView | StringView
-              | IntegerView | NumberView | ArrayView | ObjectView | AnyOfView
-              | ConstView | EnumView | RawView
+              | IntegerView | NumberView | ArrayView | ObjectView | NotView
+              | AllOfView | AnyOfView | OneOfView | ReferenceView | ConstView
+              | EnumView | RawView
+
+    module Containment
+      YES: :yes
+      NO: :no
+      UNKNOWN: :unknown
+      ALL: Array[containment]
+    end
+
+    module Satisfiability
+      YES: :yes
+      NO: :no
+      UNKNOWN: :unknown
+      ALL: Array[satisfiability]
+    end
+
+    module Distinctness
+      UNCONSTRAINED: :unconstrained
+      ALL_DISTINCT: :all_distinct
+      SOME_REPEATED: :some_repeated
+      ALL: Array[distinctness]
+    end
+
+    module Kind
+      MULTI_TYPE: :multi_type
+      TYPED_GROUP: :typed_group
+      STRING: :string
+      INTEGER: :integer
+      NUMBER: :number
+      ARRAY: :array
+      OBJECT: :object
+      CONST: :const
+      ENUM: :enum
+      NOT: :not
+      ALL_OF: :all_of
+      ANY_OF: :any_of
+      ONE_OF: :one_of
+      REFERENCE: :reference
+      TRUE: :true
+      FALSE: :false
+      RAW: :raw
+      ALL: Array[kind]
+    end
 
     class CanonicalizationError < StandardError
     end
@@ -35,7 +88,10 @@ module JSONSchema
     class IncompatibleOperands < CanonicalizationError
     end
 
-    class UnmodeledOperand < CanonicalizationError
+    class UnsupportedOperand < CanonicalizationError
+    end
+
+    class UnsupportedResult < CanonicalizationError
     end
 
     # A schema reduced to canonical form: schemas accepting the same values share one form.
@@ -45,11 +101,13 @@ module JSONSchema
       def kind: () -> kind
       def view: () -> view
       def intersect: (CanonicalSchema other) -> CanonicalSchema
-      def is_subset_of: (CanonicalSchema other) -> bool?
-      def negate: () -> CanonicalSchema?
+      def union: (CanonicalSchema other) -> CanonicalSchema
+      def subtract: (CanonicalSchema other) -> CanonicalSchema
+      def covers: (CanonicalSchema other) -> containment
+      def negate: () -> CanonicalSchema
       def definition: (String uri) -> CanonicalSchema?
       def definitions: () -> Hash[String, CanonicalSchema]
-      def satisfiable?: () -> bool
+      def satisfiability: () -> satisfiability
       def inspect: () -> String
       def ==: (untyped other) -> bool
       def eql?: (untyped other) -> bool
@@ -121,7 +179,7 @@ module JSONSchema
     class ArrayView
       def min_items: () -> Integer?
       def max_items: () -> Integer?
-      def distinctness: () -> (:unconstrained | :all_distinct | :some_repeated)
+      def distinctness: () -> distinctness
       def prefix_items: () -> Array[CanonicalSchema]
       def items: () -> CanonicalSchema?
       def contains: () -> Array[ContainsView]
@@ -129,7 +187,7 @@ module JSONSchema
       def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
     end
 
-    # One `contains` demand of an array; an absent minimum spells the default of one.
+    # One `contains` requirement of an array; an absent minimum means the default of one.
     class ContainsView
       def schema: () -> CanonicalSchema
       def min_contains: () -> Integer?
@@ -168,6 +226,34 @@ module JSONSchema
       def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
     end
 
+    # The complement of an opaque schema.
+    class NotView
+      def schema: () -> CanonicalSchema
+      def inspect: () -> String
+      def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
+    end
+
+    # A value matches iff every branch matches.
+    class AllOfView
+      def branches: () -> Array[CanonicalSchema]
+      def inspect: () -> String
+      def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
+    end
+
+    # A value matches iff exactly one branch matches.
+    class OneOfView
+      def branches: () -> Array[CanonicalSchema]
+      def inspect: () -> String
+      def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
+    end
+
+    # The target a `$ref` names.
+    class ReferenceView
+      def uri: () -> String
+      def inspect: () -> String
+      def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
+    end
+
     # A value matches iff at least one branch matches.
     class AnyOfView
       def branches: () -> Array[CanonicalSchema]
@@ -189,7 +275,7 @@ module JSONSchema
       def deconstruct_keys: (untyped keys) -> Hash[Symbol, untyped]
     end
 
-    # A schema the canonical form does not model structurally, kept verbatim.
+    # A schema the canonical form does not support structurally, kept verbatim.
     class RawView
       def schema: () -> untyped
       def inspect: () -> String

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonschema_rs
 version: !ruby/object:Gem::Version
-  version: 0.49.9
+  version: 0.50.0
 platform: aarch64-linux
 authors:
 - Dmitry Dygalo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal