easy_talk 3.3.1 → 3.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1b72ef842cb6e49f4cbc0d1eab096e737f26c118e715170c35e791ceb28a0cd
-  data.tar.gz: 800ce6db8a8d0607589250fb76a0834bc1372de11617f2746abad2c00496bc77
+  metadata.gz: b571b59c30a196b82285a7fa67c275002cb9f4bc6a07a0e0c70cc69d04d60b50
+  data.tar.gz: 599c489167248facc490dbc3add9c0fddb005b9aab654d919e0377a1ae2352af
 SHA512:
-  metadata.gz: 1cb143e9d16027929bcaf119cdcc12254fd4324f2f902a493be7a55095cfce1f8d721bd44c5233fb5ef62cde19aab3017f6fdc78cb66c57ab670a304293b6fb0
-  data.tar.gz: 2968e2ab36843d8237759d9b7528cbe9a72388123b677b8c8117c27192c51d50f577df884a0a96d9cc7e308f2119e2485bcbf0b13bb5742675fb5cd1338ae31a
+  metadata.gz: 8f27233da948ebf61071d179f8b8b1031df4ffa262bd9050488aa09e82e462d8c8a52b25290b8af1965c7c23f39c73a43c8b95972ac3d388aea645c50d7754c9
+  data.tar.gz: 8cba0f544c9746674f15005232c714d385a3e407c3add6d4089eb2260a1a6889a0e7a0160283d42fdc388f91c26ac96c52d8fae8147458821cd346bde2c60651

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [3.3.2] - 2026-03-09
+
+### Fixed
+
+- **Schema Cache Corruption**: Fixed schema cache corruption when nested models have constraints (#163)
+- **Mutable Default Values (Model)**: Fixed mutable default values (arrays, hashes) being shared across `EasyTalk::Model` instances (#165)
+- **Nilable Properties Rejecting Nil**: Fixed nilable properties incorrectly rejecting `nil` in ActiveModel validations (#166)
+- **Nested Model Blank False Positive**: Fixed nested model blank false positive in `apply_object_validations` (#167)
+- **Nilable Boolean Validation**: Fixed `T.nilable(T::Boolean)` rejecting `nil` in ActiveModel validations (#168)
+- **Schema False Value Discard**: Fixed `EasyTalk::Schema` silently discarding `false` values on initialization (#169)
+- **Mutable Default Values (Schema)**: Fixed mutable default values shared across `EasyTalk::Schema` instances (#170)
+- **Double-Call Stale Schema**: Fixed `define_schema` double-call leaving stale schema and validators (#171)
+- **Incorrect Fallback String**: Fixed incorrect fallback string in type introspection for composition types (#175)
+- **Optional Array Nil Rejection**: Fixed optional array properties incorrectly rejecting `nil` (#177)
+
+### Added
+
+- **Option Validation for UnionBuilder and NullBuilder**: Added constraint option validation to `UnionBuilder` and `NullBuilder`, raising errors on unsupported options (#176)
+
+### Internal
+
+- **SchemaBase Extraction**: Extracted `SchemaBase` module to eliminate duplication between `Model` and `Schema` (#172)
+- **Type Introspection Consolidation**: Consolidated type introspection logic into the `TypeIntrospection` module, removing duplicate checks from adapters and helpers (#173, #174)
+- **Test Suite Consolidation**: Consolidated standalone bug-fix specs into the regular test suite for better organization
+
 ## [3.3.1] - 2026-02-03
 
 ### Added

data/easy_talk.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'lib/easy_talk/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'easy_talk'
+  spec.version = EasyTalk::VERSION
+  spec.authors = ['Sergio Bayona']
+  spec.email = ['bayona.sergio@gmail.com']
+
+  spec.summary = 'JSON Schema generation and validation for Ruby classes, ideal for LLM function calling.'
+  spec.description = 'Define schemas using a clean DSL and get both JSON Schema documents and runtime validations. ' \
+                     'Perfect for API request/response validation, LLM function definitions (OpenAI, Anthropic), ' \
+                     'and structured data modeling. Features Sorbet-style types, schema composition, ' \
+                     'pluggable validation adapters, and multiple error output formats (JSON:API, RFC 7807).'
+  spec.homepage = 'https://github.com/sergiobayona/easy_talk'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = 'https://github.com/sergiobayona/easy_talk/blob/main/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ spec/ .git .github Gemfile])
+    end
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activemodel', ['>= 7.0', '< 9.0']
+  spec.add_dependency 'activesupport', ['>= 7.0', '< 9.0']
+  spec.add_dependency 'js_regex', '~> 3.0'
+  spec.add_dependency 'sorbet-runtime', '~> 0.5'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/easy_talk/builders/composition_builder.rb

@@ -17,6 +17,8 @@ module EasyTalk
         'OneOfBuilder' => 'oneOf'
       }.freeze
 
+      VALID_OPTIONS = %i[title description optional as validate ref].freeze
+
       sig { params(name: Symbol, type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).void }
       # Initializes a new instance of the CompositionBuilder class.
       #
@@ -24,6 +26,7 @@ module EasyTalk
       # @param type [Class] The type of the composition.
       # @param constraints [Hash] The constraints for the composition.
       def initialize(name, type, constraints)
+        EasyTalk.assert_valid_property_options(name, constraints, VALID_OPTIONS)
         @composer_type = self.class.name.split('::').last
         @name = name
         @type = type

data/lib/easy_talk/builders/null_builder.rb

@@ -9,10 +9,12 @@ module EasyTalk
     class NullBuilder < BaseBuilder
       extend T::Sig
 
+      VALID_OPTIONS = {}.freeze
+
       # Initializes a new instance of the NullBuilder class.
-      sig { params(name: Symbol, _constraints: T::Hash[Symbol, T.untyped]).void }
-      def initialize(name, _constraints = {})
-        super(name, { type: 'null' }, {}, {})
+      sig { params(name: Symbol, constraints: T::Hash[Symbol, T.untyped]).void }
+      def initialize(name, constraints = {})
+        super(name, { type: 'null' }, constraints, VALID_OPTIONS)
       end
     end
   end

data/lib/easy_talk/builders/object_builder.rb

@@ -41,7 +41,7 @@ module EasyTalk
         # Keep a reference to the original schema definition
         @schema_definition = schema_definition
         # Deep duplicate the raw schema hash so we can mutate it safely
-        @original_schema = deep_dup(schema_definition.schema)
+        @original_schema = EasyTalk.deep_dup(schema_definition.schema)
 
         # We'll collect required property names in this Set
         @required_properties = Set.new
@@ -71,24 +71,6 @@ module EasyTalk
 
       private
 
-      ##
-      # Deep duplicates a hash, including nested hashes.
-      # This prevents mutations from leaking back to the original schema.
-      #
-      def deep_dup(obj)
-        case obj
-        when Hash
-          obj.transform_values { |v| deep_dup(v) }
-        when Array
-          obj.map { |v| deep_dup(v) }
-        when Class, Module
-          # Don't duplicate Class or Module objects - they represent types
-          obj
-        else
-          obj.duplicable? ? obj.dup : obj
-        end
-      end
-
       ##
       # Main aggregator: merges the top-level schema keys (like :properties, :subschemas)
       # into a single hash that we'll feed to BaseBuilder.
@@ -250,7 +232,7 @@ module EasyTalk
         elsif prop_type.is_a?(EasyTalk::Types::Composer)
           collect_ref_models(prop_type.items, constraints)
         # Handle typed arrays with EasyTalk model items
-        elsif typed_array?(prop_type)
+        elsif TypeIntrospection.typed_array?(prop_type)
           extract_inner_types(prop_type).each { |inner_type| collect_ref_models(inner_type, constraints) }
         # Handle nilable types
         elsif nilable_with_model?(prop_type)
@@ -272,12 +254,8 @@ module EasyTalk
         EasyTalk.configuration.use_refs
       end
 
-      def typed_array?(prop_type)
-        prop_type.is_a?(T::Types::TypedArray)
-      end
-
       def extract_inner_types(prop_type)
-        return [] unless typed_array?(prop_type)
+        return [] unless TypeIntrospection.typed_array?(prop_type)
 
         if prop_type.type.is_a?(EasyTalk::Types::Composer)
           prop_type.type.items
@@ -302,9 +280,7 @@ module EasyTalk
       # Adds $defs entries for all collected ref models.
       #
       def add_ref_model_defs(schema_hash)
-        definitions = @ref_models.each_with_object({}) do |model, acc|
-          acc[model.name] = model.schema
-        end
+        definitions = @ref_models.to_h { |model| [model.name, EasyTalk.deep_dup(model.schema)] }
 
         existing_defs = schema_hash[:defs] || {}
         schema_hash[:defs] = existing_defs.merge(definitions)
@@ -327,9 +303,7 @@ module EasyTalk
       #
       def add_defs_from_subschema(schema_hash, subschema)
         # Build up a hash of class_name => schema for each sub-item
-        definitions = subschema.items.each_with_object({}) do |item, acc|
-          acc[item.name] = item.schema
-        end
+        definitions = subschema.items.to_h { |item| [item.name, EasyTalk.deep_dup(item.schema)] }
         # Merge or create :defs
         existing_defs = schema_hash[:defs] || {}
         schema_hash[:defs] = existing_defs.merge(definitions)

data/lib/easy_talk/builders/union_builder.rb

@@ -10,8 +10,11 @@ module EasyTalk
       extend CollectionHelpers
       extend T::Sig
 
+      VALID_OPTIONS = %i[title description optional as validate].freeze
+
       sig { params(name: Symbol, type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, type, constraints)
+        EasyTalk.assert_valid_property_options(name, constraints, VALID_OPTIONS)
         @name = name
         @type = type
         @constraints = constraints

data/lib/easy_talk/errors_helper.rb

@@ -25,7 +25,7 @@ module EasyTalk
       raise UnknownOptionError, message
     end
 
-    def self.extract_inner_type(type_info)
+    def self.extract_element_type(type_info)
       # No change needed here
       if type_info.respond_to?(:type) && type_info.type.respond_to?(:raw_type)
         type_info.type.raw_type
@@ -49,7 +49,7 @@ module EasyTalk
     def self.validate_typed_array_values(property_name:, constraint_name:, type_info:, array_value:)
       # Raise error if value is not an array but type expects one
       unless array_value.is_a?(Array)
-        inner_type = extract_inner_type(type_info)
+        inner_type = extract_element_type(type_info)
         expected_desc = TypeIntrospection.boolean_type?(inner_type) ? 'Boolean (true or false)' : inner_type.to_s
         raise_constraint_error(
           property_name: property_name,
@@ -59,7 +59,7 @@ module EasyTalk
         )
       end
 
-      inner_type = extract_inner_type(type_info)
+      inner_type = extract_element_type(type_info)
       array_value.each_with_index do |element, index|
         validate_array_element(
           property_name: property_name,
@@ -153,7 +153,7 @@ module EasyTalk
       # Handle Sorbet type objects
       elsif value_type.class.ancestors.include?(T::Types::Base)
         # Extract the inner type
-        inner_type = extract_inner_type(value_type)
+        inner_type = extract_element_type(value_type)
 
         if inner_type.is_a?(Array)
           # For union types, check if the value matches any of the allowed types

data/lib/easy_talk/model.rb

@@ -8,8 +8,7 @@ require 'active_support/time'
 require 'active_support/concern'
 require 'active_support/json'
 require 'active_model'
-require_relative 'builders/object_builder'
-require_relative 'schema_definition'
+require_relative 'schema_base'
 require_relative 'validation_builder'
 require_relative 'error_formatter'
 require_relative 'extensions/ruby_llm_compatibility'
@@ -55,106 +54,15 @@ module EasyTalk
 
     # Instance methods mixed into models that include EasyTalk::Model
     module InstanceMethods
+      include SchemaBase::InstanceMethods
+
       def initialize(attributes = {})
         @additional_properties = {}
         provided_keys = attributes.keys.to_set(&:to_sym)
 
-        super # Perform initial mass assignment
-
-        schema_def = self.class.schema_definition
-        return unless schema_def.respond_to?(:schema) && schema_def.schema.is_a?(Hash)
-
-        (schema_def.schema[:properties] || {}).each do |prop_name, prop_definition|
-          process_property_initialization(prop_name, prop_definition, provided_keys)
-        end
-      end
-
-      private
-
-      def process_property_initialization(prop_name, prop_definition, provided_keys)
-        defined_type = prop_definition[:type]
-        nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
-
-        apply_default_value(prop_name, prop_definition, provided_keys)
-
-        current_value = public_send(prop_name)
-        return if nilable_type && current_value.nil?
-
-        defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
-        instantiate_nested_models(prop_name, defined_type, current_value)
-      end
-
-      def apply_default_value(prop_name, prop_definition, provided_keys)
-        return if provided_keys.include?(prop_name)
-
-        default_value = prop_definition.dig(:constraints, :default)
-        public_send("#{prop_name}=", default_value) unless default_value.nil?
-      end
-
-      def instantiate_nested_models(prop_name, defined_type, current_value)
-        # Single nested model: convert Hash to model instance
-        if defined_type.is_a?(Class) && defined_type.include?(EasyTalk::Model) && current_value.is_a?(Hash)
-          public_send("#{prop_name}=", defined_type.new(current_value))
-          return
-        end
-
-        # Array of nested models: convert Hash items to model instances
-        instantiate_array_items(prop_name, defined_type, current_value)
-      end
-
-      def instantiate_array_items(prop_name, defined_type, current_value)
-        return unless defined_type.is_a?(T::Types::TypedArray) && current_value.is_a?(Array)
-
-        item_type = defined_type.type.respond_to?(:raw_type) ? defined_type.type.raw_type : nil
-        return unless item_type.is_a?(Class) && item_type.include?(EasyTalk::Model)
-
-        instantiated = current_value.map { |item| item.is_a?(Hash) ? item_type.new(item) : item }
-        public_send("#{prop_name}=", instantiated)
-      end
-
-      public
-
-      def method_missing(method_name, *args)
-        method_string = method_name.to_s
-        if method_string.end_with?('=')
-          property_name = method_string.chomp('=')
-          if self.class.additional_properties_allowed?
-            @additional_properties[property_name] = args.first
-          else
-            super
-          end
-        elsif self.class.additional_properties_allowed? && @additional_properties.key?(method_string)
-          @additional_properties[method_string]
-        else
-          super
-        end
-      end
-
-      def respond_to_missing?(method_name, include_private = false)
-        return super unless self.class.additional_properties_allowed?
-
-        method_string = method_name.to_s
-        method_string.end_with?('=') || @additional_properties.key?(method_string) || super
-      end
-
-      # Add to_hash method to convert defined properties to hash
-      def to_hash
-        properties_to_include = (self.class.schema_definition.schema[:properties] || {}).keys
-        return {} if properties_to_include.empty?
+        super # Perform initial mass assignment via ActiveModel::API
 
-        properties_to_include.each_with_object({}) do |prop, hash|
-          hash[prop.to_s] = send(prop)
-        end
-      end
-
-      # Override as_json to include both defined and additional properties
-      def as_json(_options = {})
-        to_hash.merge(@additional_properties)
-      end
-
-      # to_h includes both defined and additional properties
-      def to_h
-        to_hash.merge(@additional_properties)
+        initialize_schema_properties(provided_keys)
       end
 
       # Returns a Hash representing the schema in a format compatible with RubyLLM.
@@ -164,39 +72,11 @@ module EasyTalk
       def to_json_schema
         self.class.to_json_schema
       end
-
-      # Allow comparison with hashes
-      def ==(other)
-        case other
-        when Hash
-          # Convert both to comparable format for comparison
-          self_hash = (self.class.schema_definition.schema[:properties] || {}).keys.each_with_object({}) do |prop, hash|
-            hash[prop] = send(prop)
-          end
-
-          # Handle both symbol and string keys in the other hash
-          other_normalized = other.transform_keys(&:to_sym)
-          self_hash == other_normalized
-        else
-          super
-        end
-      end
     end
 
     # Module containing class-level methods for defining and accessing the schema of a model.
     module ClassMethods
-      include SchemaMethods
-
-      # Returns the schema for the model.
-      #
-      # @return [Schema] The schema for the model.
-      def schema
-        @schema ||= if defined?(@schema_definition) && @schema_definition
-                      build_schema(@schema_definition)
-                    else
-                      {}
-                    end
-      end
+      include SchemaBase::ClassMethods
 
       # Define the schema for the model using the provided block.
       #
@@ -220,22 +100,11 @@ module EasyTalk
       #     property :name, String
       #   end
       def define_schema(options = {}, &)
-        raise ArgumentError, 'The class must have a name' unless name.present?
-
-        @schema_definition = SchemaDefinition.new(name)
-        @schema_definition.klass = self # Pass the model class to the schema definition
-        @schema_definition.instance_eval(&)
+        super(&)
 
         # Store validation options for this model
         @validation_options = normalize_validation_options(options)
 
-        # Define accessors immediately based on schema_definition
-        defined_properties = (@schema_definition.schema[:properties] || {}).keys
-        attr_accessor(*defined_properties)
-
-        # Track which properties have had validations applied
-        @validated_properties ||= Set.new
-
         # Initialize mutex eagerly for thread-safe schema-level validation application
         @schema_level_validation_lock = Mutex.new
 
@@ -247,6 +116,19 @@ module EasyTalk
 
       private
 
+      # Reset all memoized schema state and clear previously registered
+      # ActiveModel validators so a second define_schema call is never ignored.
+      def clear_schema_state!
+        super
+        @schema_level_validations_applied = false
+        @validated_properties = Set.new
+
+        return unless @schema_definition
+
+        reset_callbacks(:validate)
+        _validators.clear
+      end
+
       # Normalize validation options from various input formats.
       #
       # @param options [Hash] The options hash from define_schema
@@ -313,37 +195,6 @@ module EasyTalk
           @schema_level_validations_applied = true
         end
       end
-
-      public
-
-      # Returns the unvalidated schema definition for the model.
-      #
-      # @return [SchemaDefinition] The unvalidated schema definition for the model.
-      def schema_definition
-        @schema_definition ||= {}
-      end
-
-      def additional_properties_allowed?
-        ap = @schema_definition&.schema&.fetch(:additional_properties, false)
-        # Allow if true, or if it's a schema object (Class or Hash with type)
-        ap == true || ap.is_a?(Class) || ap.is_a?(Hash)
-      end
-
-      # Returns the property names defined in the schema
-      #
-      # @return [Array<Symbol>] Array of property names as symbols
-      def properties
-        (@schema_definition&.schema&.dig(:properties) || {}).keys
-      end
-
-      # Builds the schema using the provided schema definition.
-      # This is the convergence point for all schema generation.
-      #
-      # @param schema_definition [SchemaDefinition] The schema definition.
-      # @return [Schema] The validated schema.
-      def build_schema(schema_definition)
-        Builders::ObjectBuilder.new(schema_definition).build
-      end
     end
   end
 end

data/lib/easy_talk/property.rb

@@ -112,9 +112,8 @@ module EasyTalk
         args = is_collection ? [name, type, constraints] : [name, constraints]
         builder_class.new(*args).build
       elsif type.respond_to?(:schema)
-        # merge the top-level constraints from *this* property
-        # e.g. :title, :description, :default, etc
-        type.schema.merge!(constraints)
+        # deep_dup so nested hashes in the cached schema aren't shared with the result
+        EasyTalk.deep_dup(type.schema).merge(constraints)
       else
         raise UnknownTypeError,
               "Unknown type '#{type.inspect}' for property '#{name}'. " \

data/lib/easy_talk/schema.rb

@@ -7,8 +7,7 @@ require 'active_support/core_ext'
 require 'active_support/time'
 require 'active_support/concern'
 require 'active_support/json'
-require_relative 'builders/object_builder'
-require_relative 'schema_definition'
+require_relative 'schema_base'
 
 module EasyTalk
   # A lightweight module for schema generation without ActiveModel validations.
@@ -50,150 +49,41 @@ module EasyTalk
 
     # Instance methods for schema-only models.
     module InstanceMethods
+      include SchemaBase::InstanceMethods
+
       # Initialize the schema object with attributes.
+      # Performs manual attribute assignment (no ActiveModel) then applies
+      # defaults and nested model instantiation via the shared base.
       #
       # @param attributes [Hash] The attributes to set
       def initialize(attributes = {})
         @additional_properties = {}
-        schema_def = self.class.schema_definition
-
-        return unless schema_def.respond_to?(:schema) && schema_def.schema.is_a?(Hash)
-
-        (schema_def.schema[:properties] || {}).each do |prop_name, prop_definition|
-          value = attributes[prop_name] || attributes[prop_name.to_s]
-
-          # Handle default values
-          if value.nil? && !attributes.key?(prop_name) && !attributes.key?(prop_name.to_s)
-            default_value = prop_definition.dig(:constraints, :default)
-            value = default_value unless default_value.nil?
-          end
-
-          # Handle nested EasyTalk::Schema or EasyTalk::Model objects
-          defined_type = prop_definition[:type]
-          nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
-          defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
-
-          if defined_type.is_a?(Class) &&
-             (defined_type.include?(EasyTalk::Schema) || defined_type.include?(EasyTalk::Model)) &&
-             value.is_a?(Hash)
-            value = defined_type.new(value)
-          end
-
-          instance_variable_set("@#{prop_name}", value)
-        end
-      end
+        provided_keys = Set.new
 
-      # Convert defined properties to a hash.
-      #
-      # @return [Hash] The properties as a hash
-      def to_hash
-        properties_to_include = (self.class.schema_definition.schema[:properties] || {}).keys
-        return {} if properties_to_include.empty?
-
-        properties_to_include.each_with_object({}) do |prop, hash|
-          hash[prop.to_s] = send(prop)
-        end
+        assign_schema_attributes(attributes, provided_keys)
+        initialize_schema_properties(provided_keys)
       end
 
-      # Convert to JSON-compatible hash including additional properties.
-      #
-      # @param _options [Hash] JSON options (ignored)
-      # @return [Hash] The combined hash
-      def as_json(_options = {})
-        to_hash.merge(@additional_properties)
-      end
+      private
 
-      # Convert to hash including additional properties.
-      #
-      # @return [Hash] The combined hash
-      def to_h
-        to_hash.merge(@additional_properties)
-      end
+      def assign_schema_attributes(attributes, provided_keys)
+        defined_properties = self.class.properties.to_set
 
-      # Allow comparison with hashes.
-      #
-      # @param other [Object] The object to compare with
-      # @return [Boolean] True if equal
-      def ==(other)
-        case other
-        when Hash
-          self_hash = (self.class.schema_definition.schema[:properties] || {}).keys.each_with_object({}) do |prop, hash|
-            hash[prop] = send(prop)
+        attributes.each do |key, value|
+          prop_name = key.to_sym
+          if defined_properties.include?(prop_name)
+            provided_keys << prop_name
+            public_send("#{prop_name}=", value)
+          elsif self.class.additional_properties_allowed?
+            @additional_properties[key.to_s] = value
           end
-          other_normalized = other.transform_keys(&:to_sym)
-          self_hash == other_normalized
-        else
-          super
         end
       end
     end
 
     # Class methods for schema-only models.
     module ClassMethods
-      include SchemaMethods
-
-      # Returns the schema for the model.
-      #
-      # @return [Hash] The schema for the model.
-      def schema
-        @schema ||= if defined?(@schema_definition) && @schema_definition
-                      build_schema(@schema_definition)
-                    else
-                      {}
-                    end
-      end
-
-      # Define the schema for the model using the provided block.
-      # Unlike EasyTalk::Model, this does NOT apply any validations.
-      #
-      # @yield The block to define the schema.
-      # @raise [ArgumentError] If the class does not have a name.
-      def define_schema(&)
-        raise ArgumentError, 'The class must have a name' unless name.present?
-
-        @schema_definition = SchemaDefinition.new(name)
-        @schema_definition.klass = self
-        @schema_definition.instance_eval(&)
-
-        # Define accessors for all properties
-        defined_properties = (@schema_definition.schema[:properties] || {}).keys
-        attr_accessor(*defined_properties)
-
-        # NO validations are applied - this is schema-only
-
-        @schema_definition
-      end
-
-      # Returns the schema definition for the model.
-      #
-      # @return [SchemaDefinition] The schema definition.
-      def schema_definition
-        @schema_definition ||= {}
-      end
-
-      # Check if additional properties are allowed.
-      #
-      # @return [Boolean] True if additional properties are allowed.
-      def additional_properties_allowed?
-        @schema_definition&.schema&.fetch(:additional_properties, false)
-      end
-
-      # Returns the property names defined in the schema.
-      #
-      # @return [Array<Symbol>] Array of property names as symbols.
-      def properties
-        (@schema_definition&.schema&.dig(:properties) || {}).keys
-      end
-
-      private
-
-      # Builds the schema using the provided schema definition.
-      #
-      # @param schema_definition [SchemaDefinition] The schema definition.
-      # @return [Hash] The built schema.
-      def build_schema(schema_definition)
-        Builders::ObjectBuilder.new(schema_definition).build
-      end
+      include SchemaBase::ClassMethods
     end
   end
 end

data/lib/easy_talk/schema_base.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+# typed: true
+
+require_relative 'builders/object_builder'
+require_relative 'schema_definition'
+
+module EasyTalk
+  # Shared foundation for both EasyTalk::Schema and EasyTalk::Model.
+  #
+  # This module extracts the common instance and class methods so that
+  # Schema (lightweight, no validations) and Model (full ActiveModel
+  # validations) stay in sync without code duplication.
+  module SchemaBase
+    # Instance methods shared by Schema and Model.
+    #
+    # Each including module provides its own `initialize` that:
+    #   1. Sets `@additional_properties = {}`
+    #   2. Performs attribute assignment (manually or via ActiveModel)
+    #   3. Calls `initialize_schema_properties(provided_keys)`
+    module InstanceMethods
+      private
+
+      def initialize_schema_properties(provided_keys)
+        schema_def = self.class.schema_definition
+        return unless schema_def.respond_to?(:schema) && schema_def.schema.is_a?(Hash)
+
+        (schema_def.schema[:properties] || {}).each do |prop_name, prop_definition|
+          process_property_initialization(prop_name, prop_definition, provided_keys)
+        end
+      end
+
+      def process_property_initialization(prop_name, prop_definition, provided_keys)
+        defined_type = prop_definition[:type]
+        nilable_type = defined_type.respond_to?(:nilable?) && defined_type.nilable?
+
+        apply_default_value(prop_name, prop_definition, provided_keys)
+
+        current_value = public_send(prop_name)
+        return if nilable_type && current_value.nil?
+
+        defined_type = T::Utils::Nilable.get_underlying_type(defined_type) if nilable_type
+        instantiate_nested_models(prop_name, defined_type, current_value)
+      end
+
+      def apply_default_value(prop_name, prop_definition, provided_keys)
+        return if provided_keys.include?(prop_name)
+
+        default_value = prop_definition.dig(:constraints, :default)
+        public_send("#{prop_name}=", EasyTalk.deep_dup(default_value)) unless default_value.nil?
+      end
+
+      def instantiate_nested_models(prop_name, defined_type, current_value)
+        if easy_talk_class?(defined_type) && current_value.is_a?(Hash)
+          public_send("#{prop_name}=", defined_type.new(current_value))
+          return
+        end
+
+        instantiate_array_items(prop_name, defined_type, current_value)
+      end
+
+      def easy_talk_class?(type)
+        type.is_a?(Class) && (
+          type.include?(EasyTalk::Model) || type.include?(EasyTalk::Schema)
+        )
+      end
+
+      def instantiate_array_items(prop_name, defined_type, current_value)
+        return unless defined_type.is_a?(T::Types::TypedArray) && current_value.is_a?(Array)
+
+        item_type = defined_type.type.respond_to?(:raw_type) ? defined_type.type.raw_type : nil
+        return unless easy_talk_class?(item_type)
+
+        instantiated = current_value.map { |item| item.is_a?(Hash) ? item_type.new(item) : item }
+        public_send("#{prop_name}=", instantiated)
+      end
+
+      public
+
+      def method_missing(method_name, *args)
+        method_string = method_name.to_s
+        if method_string.end_with?('=')
+          property_name = method_string.chomp('=')
+          if self.class.additional_properties_allowed?
+            @additional_properties[property_name] = args.first
+          else
+            super
+          end
+        elsif self.class.additional_properties_allowed? && @additional_properties.key?(method_string)
+          @additional_properties[method_string]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        return super unless self.class.additional_properties_allowed?
+
+        method_string = method_name.to_s
+        method_string.end_with?('=') || @additional_properties.key?(method_string) || super
+      end
+
+      def to_hash
+        properties_to_include = (self.class.schema_definition.schema[:properties] || {}).keys
+        return {} if properties_to_include.empty?
+
+        properties_to_include.to_h { |prop| [prop.to_s, send(prop)] }
+      end
+
+      def as_json(_options = {})
+        to_hash.merge(@additional_properties)
+      end
+
+      def to_h
+        to_hash.merge(@additional_properties)
+      end
+
+      def ==(other)
+        case other
+        when Hash
+          self_hash = (self.class.schema_definition.schema[:properties] || {}).keys.to_h { |prop| [prop, send(prop)] }
+          other_normalized = other.transform_keys(&:to_sym)
+          self_hash == other_normalized
+        else
+          super
+        end
+      end
+    end
+
+    # Class methods shared by Schema and Model.
+    module ClassMethods
+      include SchemaMethods
+
+      def schema
+        @schema ||= if defined?(@schema_definition) && @schema_definition
+                      build_schema(@schema_definition)
+                    else
+                      {}
+                    end
+      end
+
+      def define_schema(&)
+        raise ArgumentError, 'The class must have a name' unless name.present?
+
+        clear_schema_state!
+
+        @schema_definition = SchemaDefinition.new(name)
+        @schema_definition.klass = self
+        @schema_definition.instance_eval(&)
+
+        defined_properties = (@schema_definition.schema[:properties] || {}).keys
+        attr_accessor(*defined_properties)
+
+        @schema_definition
+      end
+
+      def schema_definition
+        @schema_definition ||= {}
+      end
+
+      def additional_properties_allowed?
+        ap = @schema_definition&.schema&.fetch(:additional_properties, false)
+        ap == true || ap.is_a?(Class) || ap.is_a?(Hash)
+      end
+
+      def properties
+        (@schema_definition&.schema&.dig(:properties) || {}).keys
+      end
+
+      private
+
+      def clear_schema_state!
+        @schema = nil
+        @json_schema = nil
+      end
+
+      def build_schema(schema_definition)
+        Builders::ObjectBuilder.new(schema_definition).build
+      end
+    end
+  end
+end

data/lib/easy_talk/schema_definition.rb

@@ -121,7 +121,7 @@ module EasyTalk
       if args.size >= 1 && args.first.is_a?(Class)
         type = args.first
         # Merge all hash arguments as constraints
-        constraints = args[1..].select { |arg| arg.is_a?(Hash) }.reduce({}, :merge)
+        constraints = args[1..].grep(Hash).reduce({}, :merge)
         return { type:, **constraints }
       end
 

data/lib/easy_talk/type_introspection.rb

@@ -183,6 +183,11 @@ module EasyTalk
         return Array if type.is_a?(T::Types::TypedArray) || type.is_a?(EasyTalk::Types::Tuple)
         return [TrueClass, FalseClass] if boolean_type?(type)
 
+        if type.is_a?(Symbol) || type.is_a?(String)
+          klass = type.to_s.classify.safe_constantize
+          return klass if klass
+        end
+
         if nilable_type?(type)
           inner = extract_inner_type(type)
           return get_type_class(inner) if inner && inner != type
@@ -208,6 +213,10 @@ module EasyTalk
         end
 
         if type.respond_to?(:types)
+          # Prefer TypedArray if present in the union (for T.nilable(T::Array[...]) via .types path)
+          typed_arr = type.types.find { |t| t.is_a?(T::Types::TypedArray) }
+          return typed_arr if typed_arr
+
           non_nil = type.types.find do |t|
             raw = t.respond_to?(:raw_type) ? t.raw_type : t
             raw != NilClass

data/lib/easy_talk/validation_adapters/active_model_adapter.rb

@@ -128,6 +128,12 @@ module EasyTalk
 
       private
 
+      # Returns true if nil should be allowed by ActiveModel validators.
+      # This is the case when the property is optional or declared T.nilable.
+      def allow_nil?
+        optional? || nilable_type?
+      end
+
       # Apply validations based on the type of the property
       def apply_type_validations(context)
         if context.tuple_type?
@@ -185,7 +191,7 @@ module EasyTalk
         length_options[:maximum] = @constraints[:max_length] if valid_length_constraint?(:max_length)
         return unless length_options.any?
 
-        length_options[:allow_nil] = optional? || nilable_type?
+        length_options[:allow_nil] = allow_nil?
         @klass.validates @property_name, length: length_options
       rescue ArgumentError
         # Silently ignore invalid length constraints
@@ -297,6 +303,7 @@ module EasyTalk
         options[:less_than_or_equal_to] = @constraints[:maximum] if @constraints[:maximum].is_a?(Numeric)
         options[:greater_than] = @constraints[:exclusive_minimum] if @constraints[:exclusive_minimum].is_a?(Numeric)
         options[:less_than] = @constraints[:exclusive_maximum] if @constraints[:exclusive_maximum].is_a?(Numeric)
+        options[:allow_nil] = true if allow_nil?
 
         @klass.validates @property_name, numericality: options
 
@@ -407,16 +414,23 @@ module EasyTalk
         # Get inner type from T::Types::TypedArray (uses .type, which returns T::Types::Simple)
         inner_type_wrapper = type.type
         inner_type = inner_type_wrapper.respond_to?(:raw_type) ? inner_type_wrapper.raw_type : inner_type_wrapper
+        is_boolean = TypeIntrospection.boolean_type?(inner_type)
         prop_name = @property_name
-        is_easy_talk_model = inner_type.is_a?(Class) && inner_type.include?(EasyTalk::Model)
+        is_easy_talk_model = !is_boolean && inner_type.is_a?(Class) && inner_type.include?(EasyTalk::Model)
 
         @klass.validate do |record|
           value = record.public_send(prop_name)
           next unless value.is_a?(Array)
 
           value.each_with_index do |item, index|
-            unless item.is_a?(inner_type)
-              record.errors.add(prop_name, "item at index #{index} must be a #{inner_type}")
+            type_match = if is_boolean
+                           [true, false].include?(item)
+                         else
+                           item.is_a?(inner_type)
+                         end
+            unless type_match
+              type_label = is_boolean ? 'Boolean' : inner_type.to_s
+              record.errors.add(prop_name, "item at index #{index} must be a #{type_label}")
               next
             end
 
@@ -433,15 +447,11 @@ module EasyTalk
 
       # Validate boolean-specific constraints
       def apply_boolean_validations
-        # For boolean values, validate inclusion in [true, false]
-        # If not optional, don't allow nil (equivalent to presence validation for booleans)
-        if optional?
-          @klass.validates @property_name, inclusion: { in: [true, false] }, allow_nil: true
-        else
-          @klass.validates @property_name, inclusion: { in: [true, false] }
-          # Add custom validation for nil values that provides the "can't be blank" message
-          apply_boolean_presence_validation
-        end
+        # allow_nil? covers both optional and T.nilable — nil is explicitly permitted in both cases.
+        @klass.validates @property_name, inclusion: { in: [true, false] }, allow_nil: allow_nil?
+
+        # For required non-nilable booleans, add a custom nil check with the "can't be blank" message.
+        apply_boolean_presence_validation unless allow_nil?
 
         # Add type validation to ensure the value is actually a boolean
         apply_boolean_type_validation
@@ -482,33 +492,22 @@ module EasyTalk
         @klass.validate do |record|
           nested_object = record.public_send(prop_name)
 
-          # Only validate if the nested object is present
+          # Nil is handled by the outer presence validation — nothing to do here.
           next unless nested_object
 
-          # Check if the object is of the expected type (e.g., an actual Email instance)
           if nested_object.is_a?(expected_type)
-            # Check if this object appears to be empty (created from an empty hash)
-            # by checking if all defined properties are nil/blank
-            properties = expected_type.schema_definition.schema[:properties] || {}
-            all_properties_blank = properties.keys.all? do |property|
-              value = nested_object.public_send(property)
-              value.nil? || (value.respond_to?(:empty?) && value.empty?)
-            end
-
-            if all_properties_blank
-              # Treat as blank and add a presence error to the parent field
-              record.errors.add(prop_name, "can't be blank")
-            elsif !nested_object.valid?
-              # If it's the correct type and not empty, validate it
-              # Merge errors from the nested object into the parent
-              nested_object.errors.each do |error|
-                # Prefix the attribute name (e.g., 'email.address')
-                nested_key = "#{prop_name}.#{error.attribute}"
-                record.errors.add(nested_key.to_sym, error.message)
-              end
+            # Delegate entirely to the nested model's own validity.
+            # The outer presence validation already handles the nil case, so there
+            # is no need for a secondary "blank" heuristic here.
+            next if nested_object.valid?
+
+            # Propagate nested errors into the parent with a dotted-path prefix.
+            nested_object.errors.each do |error|
+              nested_key = "#{prop_name}.#{error.attribute}"
+              record.errors.add(nested_key.to_sym, error.message)
             end
           else
-            # If present but not the correct type, add a type error
+            # Value is present but is not the expected type.
             record.errors.add(prop_name, "must be a valid #{expected_type.name}")
           end
         end
@@ -519,7 +518,7 @@ module EasyTalk
         @klass.validates @property_name, inclusion: {
           in: @constraints[:enum],
           message: "must be one of: #{@constraints[:enum].join(', ')}",
-          allow_nil: optional?
+          allow_nil: allow_nil?
         }
       end
 
@@ -560,7 +559,7 @@ module EasyTalk
         end
 
         def array_requires_presence_validation?
-          @array_type && !@nilable
+          @array_type && !@nilable && !@optional
         end
 
         def tuple_type?
@@ -608,6 +607,7 @@ module EasyTalk
 
         return if length_options.empty?
 
+        length_options[:allow_nil] = true if allow_nil?
         @klass.validates @property_name, length: length_options
       end
 

data/lib/easy_talk/validation_adapters/base.rb

@@ -94,62 +94,30 @@ module EasyTalk
       end
 
       # Check if the type is nilable (e.g., T.nilable(String)).
+      # Delegates to TypeIntrospection.
       #
-      # @param t [Class, Object] The type to check (defaults to @type)
+      # @param type_to_check [Class, Object] The type to check (defaults to @type)
       # @return [Boolean] true if the type is nilable
       def nilable_type?(type_to_check = @type)
-        type_to_check.respond_to?(:nilable?) && type_to_check.nilable?
+        TypeIntrospection.nilable_type?(type_to_check)
       end
 
       # Extract the inner type from a complex type like T.nilable(String) or T.nilable(T::Array[Model]).
+      # Delegates to TypeIntrospection.
       #
       # @param type_to_unwrap [Class, Object] The type to unwrap (defaults to @type)
       # @return [Class, Object] The inner type, or the original type if not wrapped
       def extract_inner_type(type_to_unwrap = @type)
-        if type_to_unwrap.respond_to?(:unwrap_nilable)
-          unwrapped = type_to_unwrap.unwrap_nilable
-          # Return TypedArray directly (for T.nilable(T::Array[Model]))
-          return unwrapped if unwrapped.is_a?(T::Types::TypedArray)
-          # Return raw_type for simple types (for T.nilable(String))
-          return unwrapped.raw_type if unwrapped.respond_to?(:raw_type)
-        end
-
-        if type_to_unwrap.respond_to?(:types)
-          # For union types, find the non-nil type
-          # Prefer TypedArray if present, otherwise find type with raw_type
-          type_to_unwrap.types.find { |t| t.is_a?(T::Types::TypedArray) } ||
-            type_to_unwrap.types.find { |t| t.respond_to?(:raw_type) && t.raw_type != NilClass }
-        else
-          type_to_unwrap
-        end
+        TypeIntrospection.extract_inner_type(type_to_unwrap)
       end
 
       # Determine the actual class for a type, handling Sorbet types.
+      # Delegates to TypeIntrospection.
       #
       # @param type_to_resolve [Class, Object] The type to resolve
       # @return [Class, Array<Class>] The resolved class or classes
       def get_type_class(type_to_resolve)
-        if type_to_resolve.is_a?(Class)
-          type_to_resolve
-        elsif type_to_resolve.respond_to?(:raw_type)
-          type_to_resolve.raw_type
-        elsif type_to_resolve.is_a?(T::Types::TypedArray)
-          Array
-        elsif type_to_resolve.is_a?(EasyTalk::Types::Tuple)
-          Array
-        elsif type_to_resolve.is_a?(Symbol) || type_to_resolve.is_a?(String)
-          begin
-            type_to_resolve.to_s.classify.constantize
-          rescue StandardError
-            String
-          end
-        elsif TypeIntrospection.boolean_type?(type_to_resolve)
-          [TrueClass, FalseClass]
-        elsif nilable_type?(type_to_resolve)
-          extract_inner_type(type_to_resolve)
-        else
-          String
-        end
+        TypeIntrospection.get_type_class(type_to_resolve)
       end
     end
   end

data/lib/easy_talk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EasyTalk
-  VERSION = '3.3.1'
+  VERSION = '3.3.2'
 end

data/lib/easy_talk.rb

@@ -21,9 +21,10 @@ module EasyTalk
   # Builder registry for pluggable type support
   require 'easy_talk/builders/registry'
 
+  require 'easy_talk/property'
+  require 'easy_talk/schema_base'
   require 'easy_talk/model'
   require 'easy_talk/schema'
-  require 'easy_talk/property'
   require 'easy_talk/schema_definition'
   require 'easy_talk/validation_builder'
   require 'easy_talk/error_formatter'
@@ -57,6 +58,8 @@ module EasyTalk
   end
 
   def self.assert_valid_property_options(property_name, options, *valid_keys)
+    return if options.nil?
+
     valid_keys.flatten!
     options.each_key do |k|
       next if valid_keys.include?(k)
@@ -68,4 +71,23 @@ module EasyTalk
   def self.configure_nilable_behavior(nilable_is_optional = false)
     configuration.nilable_is_optional = nilable_is_optional
   end
+
+  # Deep duplicates a value, recursing into Hashes and Arrays.
+  # Class and Module objects are returned as-is since they represent types
+  # and cannot (and should not) be duplicated.
+  #
+  # @param obj [Object] The value to deep duplicate.
+  # @return [Object] A deep copy of obj.
+  def self.deep_dup(obj)
+    case obj
+    when Hash
+      obj.transform_values { |v| deep_dup(v) }
+    when Array
+      obj.map { |v| deep_dup(v) }
+    when Class, Module
+      obj
+    else
+      obj.duplicable? ? obj.dup : obj
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_talk
 version: !ruby/object:Gem::Version
-  version: 3.3.1
+  version: 3.3.2
 platform: ruby
 authors:
 - Sergio Bayona
@@ -106,6 +106,7 @@ files:
 - docs/primitive-schema-rfc.md
 - docs/property-types.markdown
 - docs/schema-definition.markdown
+- easy_talk.gemspec
 - examples/ruby_llm/Gemfile
 - examples/ruby_llm/structured_output.rb
 - examples/ruby_llm/tools_integration.rb
@@ -144,6 +145,7 @@ files:
 - lib/easy_talk/property.rb
 - lib/easy_talk/ref_helper.rb
 - lib/easy_talk/schema.rb
+- lib/easy_talk/schema_base.rb
 - lib/easy_talk/schema_definition.rb
 - lib/easy_talk/schema_methods.rb
 - lib/easy_talk/sorbet_extension.rb