ruby_llm-contract 0.10.2 → 0.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac8c19463285a3e2c0f9050e835125454b21d2b1500dcb5bad2dd4a114666bd0
-  data.tar.gz: 339c0609e3dccbf55da649c3470ed234c5abafa55c8649aee5d8dd41f9bd82ec
+  metadata.gz: 4dc75c6a5ec293047bd2e2c480cf0aaff0fb3f5043f668a9291553a30002ed53
+  data.tar.gz: 4bd5960d8ff68b8708992755a95e8b265f28cdc3734db80dbdeada251eebfba9
 SHA512:
-  metadata.gz: c04fea66393868fbdb369f5a75eaeb66a28172c8f9ddabd0a8c053fd55e5daa06174aeeb00c4bb7e9aabaf613bd1ef4ea354ff7d0f4b817f2ec41af1a4c61667
-  data.tar.gz: 71f502ebe497ede22df508d3b56396660fbd1eba109066885d5e905724bd82d30a0d46fddfe4f1c1e7efe47f95ea41b4f61341a4698c12d3f3a397cab2510068
+  metadata.gz: aa5741f4728be169c42ee861aa6c8366481b21d49e2ff66105028d22d027ba7939959c784b13f7f8707ae0483608a0360cd035aee2ba4eadd6c2e4b30edfe680
+  data.tar.gz: 875ffe28d243189193d8dad0a4d2201329b92d9701f9eec49349719ac20d678b4de21a15db7db7f827fa19bb5d1adbdf22496186a17802147156cc88e1664a9d

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.10.3 (2026-06-10)
+
+Hot-fix release: the schema validator now correctly accepts `nil` on **required-but-nullable** fields. This unblocks OpenAI structured-output strict mode, where every property has to be in `required` and "nullable" is expressed as a `null` branch in `anyOf`/`oneOf` or as an array `type` — exactly the combination the prior validator wrongly rejected.
+
+### Fixed
+
+- **`SchemaValidator` no longer rejects legal `nil` on required-nullable fields.** Pre-0.10.3 (every published version 0.2.x–0.10.2) conflated "required" (must be present) with "non-nullable" (cannot be null) — JSON Schema treats those as orthogonal. The validator now honours all three idioms for nullability:
+  - `type: ["string", "null"]` (array form)
+  - `type: "null"` (degenerate scalar form)
+  - `anyOf: [{type: "string"}, {type: "null"}]` and `oneOf` equivalents
+
+  **Adopter impact:** if you bypassed the bug by setting `required: false` + disabling OpenAI `strict: true` on every nullable field, you can now restore `strict: true` and keep the field required (= OpenAI's standard nullable idiom). Non-nullable required fields still reject `nil` exactly as before; this is a strictly additive fix.
+
+  Discovered via dogfooding in a production adopter using OpenAI strict structured output with 17 nullable fields (`"set the rest to null"` prompt). Smoking-gun mutation: remove `nullable_schema?` short-circuit from `validate_nil_field` — the three new spec cases in `spec/ruby_llm/contract/contract/schema_validator_spec.rb` fail.
+
 ## 0.10.2 (2026-06-10)
 
 Patch release: ship the `docs/guide/` directory inside the gem so adopters and LLM integration agents can read the manuals locally (via `bundle show ruby_llm-contract` or `gem unpack`) without an internet round-trip to GitHub. No code behavior change.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ruby_llm-contract (0.10.2)
+    ruby_llm-contract (0.10.3)
       dry-types (~> 1.7)
       ruby_llm (~> 1.12)
       ruby_llm-schema (~> 0.3)
@@ -258,7 +258,7 @@ CHECKSUMS
   rubocop-ast (1.49.1) sha256=4412f3ee70f6fe4546cc489548e0f6fcf76cafcfa80fa03af67098ffed755035
   ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
   ruby_llm (1.14.0) sha256=57c6f7034fc4a44504ea137d70f853b07824f1c1cdbe774ab3ab3522e7098deb
-  ruby_llm-contract (0.10.2)
+  ruby_llm-contract (0.10.3)
   ruby_llm-schema (0.3.0) sha256=a591edc5ca1b7f0304f0e2261de61ba4b3bea17be09f5cf7558153adfda3dec6
   ruby_parser (3.22.0) sha256=1eb4937cd9eb220aa2d194e352a24dba90aef00751e24c8dfffdb14000f15d23
   rubycritic (4.12.0) sha256=024fed90fe656fa939f6ea80aab17569699ac3863d0b52fd72cb99892247abc8

data/README.md

@@ -157,7 +157,7 @@ Different layers, complementary. [`ruby_llm-tribunal`](https://github.com/Alqemi
 
 ## Status & versioning
 
-Pre-1.0 (currently **0.10.2**). Semver tracked; breaking changes flagged in [CHANGELOG](CHANGELOG.md). Pin `~> 0.10.2` until 1.0 ships.
+Pre-1.0 (currently **0.10.3**). Semver tracked; breaking changes flagged in [CHANGELOG](CHANGELOG.md). Pin `~> 0.10.3` until 1.0 ships.
 
 ## FAQ
 

data/lib/ruby_llm/contract/contract/schema_validator/object_rules.rb

@@ -45,11 +45,35 @@ module RubyLLM
 
         def validate_nil_field(path, field_schema, required)
           return unless required
+          return if nullable_schema?(field_schema)
 
           expected_type = field_schema[:type] || "non-null"
           @errors << "#{path}: expected #{expected_type}, got nil"
         end
 
+        # JSON Schema permits nil when the field schema explicitly accepts
+        # null. Three idiomatic forms are recognised:
+        #   - `type: ["string", "null"]`     (array form)
+        #   - `type: "null"`                 (degenerate scalar form)
+        #   - `anyOf` / `oneOf` containing a branch with `type: "null"`
+        # Without this gate the validator wrongly rejected legal nulls on
+        # required-but-nullable fields, forcing adopters into `required: false`
+        # + `strict: false` workarounds. Fixed in 0.10.3.
+        def nullable_schema?(field_schema)
+          return false unless field_schema.is_a?(Hash)
+
+          type = field_schema[:type] || field_schema["type"]
+          return true if type.is_a?(Array) && type.any? { |t| t.to_s == "null" }
+          return true if type.to_s == "null"
+
+          %i[anyOf oneOf].any? do |key|
+            branches = field_schema[key] || field_schema[key.to_s]
+            branches.is_a?(Array) && branches.any? do |branch|
+              branch.is_a?(Hash) && (branch[:type] || branch["type"]).to_s == "null"
+            end
+          end
+        end
+
         def validate_additional_properties(node)
           return unless node.schema[:additionalProperties] == false
 

data/lib/ruby_llm/contract/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLLM
   module Contract
-    VERSION = "0.10.2"
+    VERSION = "0.10.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-contract
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.10.3
 platform: ruby
 authors:
 - Justyna