open_router_enhanced 2.2.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f4936ab4591643976d7cf5f63b92fec61fef1fda2900ce6ed022ce35671bd3a
-  data.tar.gz: 1ac1e6ea82c9eacc1bc28e4b99490507bcf1f335446f3ab1cbab2a2ca8d749b4
+  metadata.gz: '08f395125182c8bc6fdedec8b3c1057750344bc56f5988373a5a4deaaccf6585'
+  data.tar.gz: c98f3b9e15d8838b0fcc160c55a7b9ae0a4ade6fe05495d3663e016666c48914
 SHA512:
-  metadata.gz: ef3a651dee0fec1b4d0508e88578c78ed1d259b5dc7c5fb5917d7af0690a2e69c12732f6fc5a0b423340da7afddbc4de80f08f8a27e616c9d7c15a1051508a39
-  data.tar.gz: 017ec8a29aeb205e396265409c8f9d53f3f7280d025543e89b2c95510d6b21fe78f230461dcc5291a433c1b60f850425ba754dcfc1ab32e98517b1f522688692
+  metadata.gz: 5526e571d28a4c3d93726d67f4441c90890980c929b36938e2ed0f8137c29e0ac8773a7d438de4422119e0660522334447bab2585837333c2ae1651f79ef0cd9
+  data.tar.gz: 6977214b59795346e76855586eb04ff50f173e45ea6189ad1b514ad80ff5edabb1a68f433b8535977789516685eb321db6d820ca7fe18564821c9cd392a9ecf7

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [2.3.0] - 2026-07-08
+
+### Fixed
+
+- **Structured output schemas now honor optional keys.** `Schema#to_h` previously forced *every* property — at every nesting level — into the `required` array, so fields declared with `required: false` (the DSL default) were silently made mandatory in the prompt, the native `json_schema` payload, and the healer. `to_h` now emits the schema honestly, respecting the `required` arrays exactly as declared. Optional fields stay optional and the model may omit them.
+- `to_h` and local validation now agree, so what is described to the model matches what is accepted.
+
+### Added
+
+- `Schema#to_strict_h` — the provider-strict form for native `json_schema` decoding. It still lists every property in `required` (so strict providers don't `400` on nested `required: []`), but expresses optionality the correct way: fields not declared required are made **nullable** (their type gains `"null"`) rather than mandatory. The native serialization path uses this form automatically for strict schemas.
+
 ## [2.0.0] - 2025-12-28
 
 ### Overview

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    open_router_enhanced (2.2.1)
+    open_router_enhanced (2.3.0)
       activesupport (>= 6.0, < 9.0)
       dotenv (>= 2.0, < 4.0)
       faraday (>= 1.0, < 3.0)

data/lib/open_router/schema.rb

@@ -28,40 +28,37 @@ module OpenRouter
       new(name, builder.to_h, strict:)
     end
 
-    # Convert to the format expected by OpenRouter API
+    # Convert to the format expected by OpenRouter API.
+    #
+    # This is the *honest* representation: it respects the `required` arrays
+    # exactly as declared, so fields you left optional stay optional. It is what
+    # we describe to the model (prompt injection), what we validate against, and
+    # what we hand the healer — keeping "what we ask for" and "what we accept" in
+    # agreement. The provider-strict, all-required form lives in #to_strict_h and
+    # is used only when serializing a native `json_schema` request.
     def to_h
       {
         name: @name,
         strict: @strict,
-        schema: enforce_all_required(@schema)
+        schema: @schema
       }
     end
 
+    # Provider-strict form for native `json_schema` decoding.
+    #
     # OpenRouter / OpenAI strict mode requires EVERY object — at every nesting
     # level, including nested objects and array items — to list all of its
-    # properties in its `required` array. Forcing this only at the top level
-    # makes nested objects come back with `required: []`, which strict providers
-    # reject with a 400. Walk the schema and enforce it recursively.
-    #
-    # (Optional fields are expressed in strict mode by adding "null" to the
-    # property's type union, not by omitting them from `required`.)
-    def enforce_all_required(node)
-      case node
-      when Hash
-        transformed = node.each_with_object({}) { |(key, value), acc| acc[key] = enforce_all_required(value) }
-
-        props = transformed[:properties] || transformed["properties"]
-        if props.is_a?(Hash) && props.any?
-          key = transformed.key?(:properties) ? :required : "required"
-          transformed[key] = props.keys.map(&:to_s)
-        end
-
-        transformed
-      when Array
-        node.map { |element| enforce_all_required(element) }
-      else
-        node
-      end
+    # properties in its `required` array; a nested `required: []` gets a 400.
+    # We satisfy that WITHOUT silently making optional fields mandatory: any
+    # property that was not declared required is made nullable (its type gains
+    # "null"), which is exactly how strict mode expresses optionality. The model
+    # may then return `null` for it instead of being forced to invent a value.
+    def to_strict_h
+      {
+        name: @name,
+        strict: @strict,
+        schema: enforce_all_required(@schema)
+      }
     end
 
     # Get the pure JSON Schema (respects required flags) for testing/validation
@@ -137,6 +134,51 @@ module OpenRouter
 
     private
 
+    # Recursively force every object to list all its properties in `required`,
+    # keeping declared-optional properties optional by making them nullable.
+    # Reads each node's OWN existing `required` before overwriting, so nested
+    # optionality is preserved at every level.
+    def enforce_all_required(node)
+      case node
+      when Hash
+        transformed = node.each_with_object({}) { |(key, value), acc| acc[key] = enforce_all_required(value) }
+
+        props = transformed[:properties] || transformed["properties"]
+        if props.is_a?(Hash) && props.any?
+          key = transformed.key?(:properties) ? :required : "required"
+          already_required = Array(transformed[key]).map(&:to_s)
+          props.each do |prop_name, prop_def|
+            next if already_required.include?(prop_name.to_s)
+
+            props[prop_name] = make_nullable(prop_def)
+          end
+          transformed[key] = props.keys.map(&:to_s)
+        end
+
+        transformed
+      when Array
+        node.map { |element| enforce_all_required(element) }
+      else
+        node
+      end
+    end
+
+    # Add "null" to a property's type union so it can be omitted (as null) under
+    # strict mode. Leaves the property untouched if it has no determinable type.
+    def make_nullable(prop_def)
+      return prop_def unless prop_def.is_a?(Hash)
+
+      type_key = if prop_def.key?(:type) then :type
+                 elsif prop_def.key?("type") then "type"
+                 end
+      return prop_def unless type_key
+
+      types = Array(prop_def[type_key]).map(&:to_s)
+      return prop_def if types.include?("null")
+
+      prop_def.merge(type_key => types + ["null"])
+    end
+
     def validate_schema!
       raise ArgumentError, "Schema name is required" if @name.nil? || @name.empty?
       raise ArgumentError, "Schema must be a hash" unless @schema.is_a?(Hash)

data/lib/open_router/tool_serializer.rb

@@ -94,17 +94,24 @@ module OpenRouter
       case response_format
       when Hash
         if response_format[:json_schema].is_a?(Schema)
-          response_format.merge(json_schema: response_format[:json_schema].to_h)
+          response_format.merge(json_schema: native_schema_hash(response_format[:json_schema]))
         else
           response_format
         end
       when Schema
-        { type: "json_schema", json_schema: response_format.to_h }
+        { type: "json_schema", json_schema: native_schema_hash(response_format) }
       else
         response_format
       end
     end
 
+    # Provider-side json_schema decoding requires every property in `required`.
+    # For strict schemas we emit the all-required-with-nullable-optionals form so
+    # the request doesn't 400; non-strict schemas are sent honestly.
+    def native_schema_hash(schema)
+      schema.strict ? schema.to_strict_h : schema.to_h
+    end
+
     def inject_schema_instructions!(messages, schema)
       return unless schema
 

data/lib/open_router/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenRouter
-  VERSION = "2.2.1"
+  VERSION = "2.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: open_router_enhanced
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.3.0
 platform: ruby
 authors:
 - Eric Stiens
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport