easy_talk 1.0.4 → 2.0.0

data/README.md

@@ -1,5 +1,8 @@
 # EasyTalk
 
+[![Gem Version](https://badge.fury.io/rb/easy_talk.svg)](https://badge.fury.io/rb/easy_talk)
+[![Ruby](https://github.com/sergiobayona/easy_talk/actions/workflows/dev-build.yml/badge.svg)](https://github.com/sergiobayona/easy_talk/actions/workflows/dev-build.yml)
+
 ## Introduction
 
 ### What is EasyTalk?
@@ -7,10 +10,12 @@ EasyTalk is a Ruby library that simplifies defining and generating JSON Schema.
 
 ### Key Features
 * **Intuitive Schema Definition**: Use Ruby classes and methods to define JSON Schema documents easily.
+* **Automatic ActiveModel Validations**: Schema constraints automatically generate corresponding ActiveModel validations (configurable).
 * **Works for plain Ruby classes and ActiveRecord models**: Integrate with existing code or build from scratch.
 * **LLM Function Support**: Ideal for integrating with Large Language Models (LLMs) such as OpenAI's GPT series. EasyTalk enables you to effortlessly create JSON Schema documents describing the inputs and outputs of LLM function calls.
 * **Schema Composition**: Define EasyTalk models and reference them in other EasyTalk models to create complex schemas.
-* **Validation**: Write validations using ActiveModel's validations.
+* **Enhanced Model Integration**: Automatic instantiation of nested EasyTalk models from hash attributes.
+* **Flexible Configuration**: Global and per-model configuration options for fine-tuned control.
 
 ### Use Cases
 - API request/response validation
@@ -26,8 +31,39 @@ Inspired by Python's Pydantic library, EasyTalk brings similar functionality to
 
 ### Requirements
 - Ruby 3.2 or higher
-- ActiveModel 7.0 or higher
-- ActiveSupport 7.0 or higher
+
+### Version 2.0.0 Breaking Changes
+
+⚠️ **IMPORTANT**: Version 2.0.0 includes breaking changes. Please review before upgrading:
+
+- **Removed**: Block-style nested object definitions (using `Hash do ... end`)
+- **Migration**: Use class references instead of inline Hash definitions
+
+```ruby
+# ❌ No longer supported (v1.x style)
+define_schema do
+  property :address, Hash do
+    property :street, String
+    property :city, String
+  end
+end
+
+# ✅ New approach (v2.x style)
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :street, String
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :address, Address  # Reference the class directly
+  end
+end
+```
 
 ### Installation Steps
 Add EasyTalk to your application's Gemfile:
@@ -109,10 +145,11 @@ Creating and validating an instance of your model:
 
 ```ruby
 user = User.new(name: "John Doe", email: "john@example.com", age: 25)
-user.valid? # => true
+user.valid? # => true (automatically validates based on schema constraints)
 
 user.age = 17
-user.valid? # => false
+user.valid? # => false (violates minimum: 18 constraint)
+user.errors[:age] # => ["must be greater than or equal to 18"]
 ```
 
 ## Core Concepts
@@ -143,7 +180,6 @@ EasyTalk supports standard Ruby types directly:
 - `Float`: Floating-point numbers
 - `Date`: Date values
 - `DateTime`: Date and time values
-- `Hash`: Object/dictionary values
 
 #### Sorbet-Style Types
 For complex types, EasyTalk uses Sorbet-style type notation:
@@ -184,25 +220,57 @@ end
 
 In this example, `name` is required but `middle_name` is optional.
 
-### Schema Validation
-EasyTalk models include ActiveModel validations. You can validate your models using the standard ActiveModel validation methods:
+### Automatic Validation Generation
+EasyTalk automatically generates ActiveModel validations from your schema constraints. This feature is enabled by default but can be configured:
+
+```ruby
+class User
+  include EasyTalk::Model
+  
+  define_schema do
+    property :name, String, min_length: 2, max_length: 50
+    property :email, String, format: "email"
+    property :age, Integer, minimum: 18, maximum: 120
+    property :status, String, enum: ["active", "inactive", "pending"]
+  end
+  # Validations are automatically generated:
+  # validates :name, presence: true, length: { minimum: 2, maximum: 50 }
+  # validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  # validates :age, presence: true, numericality: { greater_than_or_equal_to: 18, less_than_or_equal_to: 120 }
+  # validates :status, presence: true, inclusion: { in: ["active", "inactive", "pending"] }
+end
+
+user = User.new(name: "Jo", email: "invalid-email", age: 17)
+user.valid? # => false
+user.errors.full_messages 
+# => ["Name is too short (minimum is 2 characters)", 
+#     "Email is invalid", 
+#     "Age must be greater than or equal to 18"]
+```
+
+### Manual Validation Overrides
+You can still add manual validations alongside automatic ones:
 
 ```ruby
 class User
   include EasyTalk::Model
   
-  validates :name, presence: true
-  validates :age, numericality: { greater_than_or_equal_to: 18 }
+  # Custom validation in addition to automatic ones
+  validates :email, uniqueness: true
+  validate :complex_business_rule
   
   define_schema do
     property :name, String
+    property :email, String, format: "email"
     property :age, Integer, minimum: 18
   end
+  
+  private
+  
+  def complex_business_rule
+    # Custom validation logic
+  end
 end
-
-user = User.new(name: "John", age: 17)
-user.valid? # => false
-user.errors.full_messages # => ["Age must be greater than or equal to 18"]
 ```
 
 ## Defining Schemas
@@ -230,16 +298,6 @@ property :name, String, description: "The person's name", title: "Full Name"
 property :age, Integer, minimum: 0, maximum: 120, description: "The person's age"
 ```
 
-### Nested Objects
-You can define nested objects using a block:
-
-```ruby
-property :email, Hash do
-  property :address, String, format: "email"
-  property :verified, T::Boolean
-end
-```
-
 ### Arrays and Collections
 Arrays can be defined using the `T::Array` type:
 
@@ -254,22 +312,38 @@ You can also define arrays of complex types:
 property :addresses, T::Array[Address], description: "List of addresses"
 ```
 
-### Constraints and Validations
-Constraints can be added to properties and are used for schema generation:
+### Constraints and Automatic Validations
+Constraints are added to properties and are used for both schema generation and automatic validation generation:
 
 ```ruby
-property :name, String, min_length: 2, max_length: 50
-property :email, String, format: "email"
-property :category, String, enum: ["A", "B", "C"], default: "A"
+define_schema do
+  property :name, String, min_length: 2, max_length: 50
+  property :email, String, format: "email"
+  property :category, String, enum: ["A", "B", "C"]
+  property :score, Float, minimum: 0.0, maximum: 100.0
+  property :tags, T::Array[String], min_items: 1, max_items: 10
+end
+# Automatically generates equivalent ActiveModel validations:
+# validates :name, presence: true, length: { minimum: 2, maximum: 50 }
+# validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+# validates :category, presence: true, inclusion: { in: ["A", "B", "C"] }
+# validates :score, presence: true, numericality: { greater_than_or_equal_to: 0.0, less_than_or_equal_to: 100.0 }
+# validates :tags, presence: true, length: { minimum: 1, maximum: 10 }
 ```
 
-For validation, you can use ActiveModel validations:
+### Supported Constraint-to-Validation Mappings
 
-```ruby
-validates :name, presence: true, length: { minimum: 2, maximum: 50 }
-validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
-validates :category, inclusion: { in: ["A", "B", "C"] }
-```
+| Constraint | Validation Generated |
+|------------|---------------------|
+| `min_length`, `max_length` | `length: { minimum: X, maximum: Y }` |
+| `minimum`, `maximum` | `numericality: { greater_than_or_equal_to: X, less_than_or_equal_to: Y }` |
+| `format: "email"` | `format: { with: URI::MailTo::EMAIL_REGEXP }` |
+| `format: "url"` or `format: "uri"` | `format: { with: URI::regexp }` |
+| `pattern: /regex/` | `format: { with: /regex/ }` |
+| `enum: [...]` | `inclusion: { in: [...] }` |
+| `min_items`, `max_items` (arrays) | `length: { minimum: X, maximum: Y }` |
+| `optional: true` | Skips presence validation |
+| `T.nilable(Type)` | Allows nil values, skips presence validation |
 
 ### Additional Properties
 By default, EasyTalk models do not allow additional properties beyond those defined in the schema. You can change this behavior using the `additional_properties` keyword:
@@ -373,20 +447,21 @@ end
 
 ## ActiveModel Integration
 
-### Validations
-EasyTalk models include ActiveModel validations:
+### Enhanced Validation System
+EasyTalk models include comprehensive ActiveModel validation support with automatic generation:
 
 ```ruby
 class User
   include EasyTalk::Model
   
-  validates :age, comparison: { greater_than: 21 }
-  validates :height, presence: true, numericality: { greater_than: 0 }
+  # Manual validations work alongside automatic ones
+  validates :age, comparison: { greater_than: 21 }  # Additional business rule
+  validates :height, numericality: { greater_than: 0 }  # Overrides auto-validation
   
   define_schema do
-    property :name, String
-    property :age, Integer
-    property :height, Float
+    property :name, String, min_length: 2  # Auto-generates presence + length validations
+    property :age, Integer, minimum: 18   # Auto-generates presence + numericality validations
+    property :height, Float               # Auto-generates presence validation (overridden above)
   end
 end
 ```
@@ -395,10 +470,11 @@ end
 You can access validation errors using the standard ActiveModel methods:
 
 ```ruby
-user = User.new(name: "Jim", age: 18, height: -5.9)
+user = User.new(name: "J", age: 18, height: -5.9)
 user.valid? # => false
-user.errors[:age] # => ["must be greater than 21"]
-user.errors[:height] # => ["must be greater than 0"]
+user.errors[:name] # => ["is too short (minimum is 2 characters)"]
+user.errors[:age] # => ["must be greater than 21"] # Custom validation
+user.errors[:height] # => ["must be greater than 0"] # Overridden validation
 ```
 
 ### Model Attributes
@@ -411,10 +487,35 @@ user.age = 30
 puts user.name # => "John"
 ```
 
-You can also initialize a model with a hash of attributes:
+You can also initialize a model with a hash of attributes, including nested EasyTalk models:
 
 ```ruby
 user = User.new(name: "John", age: 30, height: 5.9)
+
+# NEW in v2.0.0: Automatic nested model instantiation
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :street, String
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address
+  end
+end
+
+# Hash attributes automatically instantiate nested models
+user = User.new(
+  name: "John",
+  address: { street: "123 Main St", city: "Boston" }
+)
+user.address.class # => Address (automatically instantiated)
+user.address.street # => "123 Main St"
 ```
 
 ## ActiveRecord Integration
@@ -597,12 +698,42 @@ You can configure EasyTalk globally:
 
 ```ruby
 EasyTalk.configure do |config|
+  # ActiveRecord integration options
   config.excluded_columns = [:created_at, :updated_at, :deleted_at]
   config.exclude_foreign_keys = true
   config.exclude_primary_key = true
   config.exclude_timestamps = true
   config.exclude_associations = false
+  
+  # Schema behavior options
   config.default_additional_properties = false
+  config.nilable_is_optional = false  # Makes T.nilable properties also optional
+  
+  # NEW in v2.0.0: Automatic validation generation
+  config.auto_validations = true      # Automatically generate ActiveModel validations
+end
+```
+
+### Automatic Validation Configuration
+The new `auto_validations` option (enabled by default) automatically generates ActiveModel validations from your schema constraints:
+
+```ruby
+# Disable automatic validations globally
+EasyTalk.configure do |config|
+  config.auto_validations = false
+end
+
+# Now you must manually define validations
+class User
+  include EasyTalk::Model
+  
+  validates :name, presence: true, length: { minimum: 2 }
+  validates :age, presence: true, numericality: { greater_than_or_equal_to: 18 }
+  
+  define_schema do
+    property :name, String, min_length: 2
+    property :age, Integer, minimum: 18
+  end
 end
 ```
 
@@ -651,25 +782,51 @@ end
 
 ## Examples
 
-### User Registration
+### User Registration (with Auto-Validations)
 
 ```ruby
 class User
   include EasyTalk::Model
 
-  validates :name, :email, :password, presence: true
-  validates :password, length: { minimum: 8 }
-  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  # Additional custom validations beyond automatic ones
+  validates :email, uniqueness: true
+  validates :password, confirmation: true
 
   define_schema do
     title "User Registration"
     description "User registration information"
-    property :name, String, description: "User's full name"
+    property :name, String, min_length: 2, max_length: 100, description: "User's full name"
     property :email, String, format: "email", description: "User's email address"
-    property :password, String, min_length: 8, description: "User's password"
-    property :notify, T::Boolean, default: true, description: "Whether to send notifications"
+    property :password, String, min_length: 8, max_length: 128, description: "User's password"
+    property :notify, T::Boolean, optional: true, description: "Whether to send notifications"
   end
+  # Auto-generated validations:
+  # validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+  # validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  # validates :password, presence: true, length: { minimum: 8, maximum: 128 }
+  # validates :notify, inclusion: { in: [true, false] } - only if present (optional: true)
 end
+
+# Usage with automatic validation
+user = User.new(
+  name: "John Doe",
+  email: "john@example.com",
+  password: "secretpassword123",
+  notify: true
+)
+user.valid? # => true (assuming email is unique)
+
+# Invalid data triggers auto-generated validations
+invalid_user = User.new(
+  name: "J",                    # Too short
+  email: "invalid-email",      # Invalid format
+  password: "123"               # Too short
+)
+invalid_user.valid? # => false
+invalid_user.errors.full_messages
+# => ["Name is too short (minimum is 2 characters)",
+#     "Email is invalid",
+#     "Password is too short (minimum is 8 characters)"]
 ```
 
 ### Payment Processing
@@ -852,13 +1009,16 @@ property :status, String, enum: ["active", "inactive", "pending"]
 
 ### Best Practices
 
-1. Define clear property names and descriptions
-2. Use appropriate types for each property
-3. Add validations for important business rules
-4. Keep schemas focused and modular
-5. Reuse models when appropriate
-6. Use explicit types instead of relying on inference
-7. Test your schemas with sample data
+1. **Define clear property names and descriptions** for better documentation
+2. **Use appropriate types** for each property with proper constraints
+3. **Leverage automatic validations** by defining schema constraints instead of manual validations
+4. **Keep schemas focused and modular** - extract nested objects to separate classes
+5. **Reuse models when appropriate** instead of duplicating schema definitions
+6. **Use explicit types** instead of relying on inference
+7. **Test your schemas with sample data** to ensure validations work as expected
+8. **Configure auto-validations globally** to maintain consistency across your application
+9. **Use nullable_optional_property** for fields that can be omitted or null
+10. **Document breaking changes** when updating schema definitions
 
 # Nullable vs Optional Properties in EasyTalk
 
@@ -983,14 +1143,6 @@ class UserProfile
     
     # Optional and nullable (can be omitted, can be null if present)
     nullable_optional_property :bio, String
-    
-    # Nested object with mixed property types
-    property :address, Hash do
-      property :street, String # Required
-      property :city, String # Required
-      property :state, String, optional: true # Optional
-      nullable_optional_property :zip, String # Optional and nullable
-    end
   end
 end
 ```
@@ -1041,6 +1193,102 @@ We recommend updating your schema definitions to explicitly declare which proper
 | `property :p, String, optional: true` | No | No | `{ "properties": { "p": { "type": "string" } } }` |
 | `nullable_optional_property :p, String` | No | Yes | `{ "properties": { "p": { "type": ["string", "null"] } } }` |
 
+## Migration Guide from v1.x to v2.0
+
+### Breaking Changes Summary
+
+1. **Removed Block-Style Sub-Schemas**: Hash-based nested definitions are no longer supported
+2. **Enhanced Validation System**: Automatic validation generation is now enabled by default
+3. **Improved Model Initialization**: Better support for nested model instantiation
+
+### Migration Steps
+
+#### 1. Replace Hash-based Nested Schemas
+
+```ruby
+# OLD (v1.x) - No longer works
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :address, Hash do
+      property :street, String
+      property :city, String
+    end
+  end
+end
+
+# NEW (v2.x) - Extract to separate classes
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :street, String
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :address, Address
+  end
+end
+```
+
+#### 2. Review Automatic Validations
+
+With `auto_validations: true` (default), you may need to remove redundant manual validations:
+
+```ruby
+# OLD (v1.x) - Manual validations required
+class User
+  include EasyTalk::Model
+  
+  validates :name, presence: true, length: { minimum: 2 }
+  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+  
+  define_schema do
+    property :name, String
+    property :email, String
+  end
+end
+
+# NEW (v2.x) - Automatic validations from constraints
+class User
+  include EasyTalk::Model
+  
+  # Only add validations not covered by schema constraints
+  validates :email, uniqueness: true
+  
+  define_schema do
+    property :name, String, min_length: 2     # Auto-generates presence + length
+    property :email, String, format: "email"  # Auto-generates presence + format
+  end
+end
+```
+
+#### 3. Configuration Updates
+
+Review your configuration for new options:
+
+```ruby
+EasyTalk.configure do |config|
+  # New option in v2.0
+  config.auto_validations = true  # Enable/disable automatic validation generation
+  
+  # Existing options (unchanged)
+  config.nilable_is_optional = false
+  config.exclude_foreign_keys = true
+  # ... other existing config
+end
+```
+
+### Compatibility Notes
+
+- **Ruby Version**: Still requires Ruby 3.2+
+- **Dependencies**: Core dependencies remain the same
+- **JSON Schema Output**: No changes to generated schemas
+- **ActiveRecord Integration**: Fully backward compatible
+
 ## Development and Contributing
 
 ### Setting Up the Development Environment
@@ -1059,6 +1307,13 @@ Run the test suite with:
 bundle exec rake spec
 ```
 
+### Code Quality
+Run the linter:
+
+```bash
+bundle exec rubocop
+```
+
 ### Contributing Guidelines
 Bug reports and pull requests are welcome on GitHub at https://github.com/sergiobayona/easy_talk.
 

data/easy_talk.gemspec

@@ -0,0 +1,38 @@
+# 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 = 'Generate json-schema from Ruby classes.'
+  spec.description = 'Generate json-schema from plain Ruby classes.'
+  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'
+  spec.add_dependency 'activesupport', '~> 7.0'
+  spec.add_dependency 'sorbet-runtime', '~> 0.5'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/easy_talk/active_record_schema_builder.rb

@@ -136,7 +136,11 @@ module EasyTalk
       end
 
       # Add default value if present and not a proc
-      constraints[:default] = column.default if column.default && !column.default.is_a?(Proc)
+      if column.default && !column.default.is_a?(Proc) && column.type == :boolean
+        constraints[:default] = ActiveModel::Type::Boolean.new.cast(column.default)
+      elsif column.default && !column.default.is_a?(Proc)
+        constraints[:default] = column.default
+      end
 
       # Remove nil values
       constraints.compact

data/lib/easy_talk/builders/composition_builder.rb

@@ -50,7 +50,18 @@ module EasyTalk
       # @return [Array<Hash>] The array of schemas.
       def schemas
         items.map do |type|
-          type.respond_to?(:schema) ? type.schema : { type: type.to_s.downcase }
+          if type.respond_to?(:schema)
+            type.schema
+          else
+            # Map Float type to 'number' in JSON Schema
+            json_type = case type.to_s
+                       when 'Float', 'BigDecimal'
+                         'number'
+                       else
+                         type.to_s.downcase
+                       end
+            { type: json_type }
+          end
         end
       end
 

data/lib/easy_talk/builders/object_builder.rb

@@ -8,7 +8,7 @@ module EasyTalk
     # ObjectBuilder is responsible for turning a SchemaDefinition of an "object" type
     # into a validated JSON Schema hash. It:
     #
-    # 1) Recursively processes the schema’s :properties,
+    # 1) Recursively processes the schema's :properties,
     # 2) Determines which properties are required (unless optional),
     # 3) Handles sub-schema composition (allOf, anyOf, oneOf, not),
     # 4) Produces the final object-level schema hash.
@@ -55,7 +55,7 @@ module EasyTalk
 
       ##
       # Main aggregator: merges the top-level schema keys (like :properties, :subschemas)
-      # into a single hash that we’ll feed to BaseBuilder.
+      # into a single hash that we'll feed to BaseBuilder.
       def build_options_hash
         # Start with a copy of the raw schema
         merged = @original_schema.dup
@@ -119,9 +119,7 @@ module EasyTalk
         return true if prop_options.dig(:constraints, :optional)
 
         # Check for nil_optional config to determine if nilable should also mean optional
-        if prop_options[:type].respond_to?(:nilable?) && prop_options[:type].nilable?
-          return EasyTalk.configuration.nilable_is_optional
-        end
+        return EasyTalk.configuration.nilable_is_optional if prop_options[:type].respond_to?(:nilable?) && prop_options[:type].nilable?
 
         false
       end
@@ -134,24 +132,12 @@ module EasyTalk
         @property_cache ||= {}
 
         # Memoize so we only build each property once
-        @property_cache[prop_name] ||= if prop_options[:properties]
-                                         # This indicates block-style definition => nested schema
-                                         nested_schema_builder(prop_options)
-                                       else
-                                         # Remove optional constraints from the property
-                                         constraints = prop_options[:constraints].except(:optional)
-                                         # Normal property: e.g. { type: String, constraints: {...} }
-                                         Property.new(prop_name, prop_options[:type], constraints)
-                                       end
-      end
-
-      ##
-      # Build a child schema by calling another ObjectBuilder on the nested SchemaDefinition.
-      #
-      def nested_schema_builder(prop_options)
-        child_schema_def = prop_options[:properties]
-        # If user used T.nilable(...) with a block, unwrap the nilable
-        ObjectBuilder.new(child_schema_def).build
+        @property_cache[prop_name] ||= begin
+          # Remove optional constraints from the property
+          constraints = prop_options[:constraints].except(:optional)
+          # Normal property: e.g. { type: String, constraints: {...} }
+          Property.new(prop_name, prop_options[:type], constraints)
+        end
       end
 
       ##