easy_talk 3.1.0 → 3.3.0

data/Rakefile

@@ -3,9 +3,36 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
+require 'yard'
 
 RSpec::Core::RakeTask.new(:spec)
 
 RuboCop::RakeTask.new
 
+YARD::Rake::YardocTask.new(:yard) do |t|
+  t.files = ['lib/**/*.rb']
+  t.options = ['--readme', 'README.md', '--output-dir', 'docs/api']
+end
+
+namespace :docs do
+  desc 'Generate YARD API documentation'
+  task api: :yard
+
+  desc 'Serve Jekyll documentation locally'
+  task :serve do
+    Dir.chdir('docs') do
+      sh 'bundle install --quiet'
+      sh 'bundle exec jekyll serve'
+    end
+  end
+
+  desc 'Build all documentation (Jekyll + YARD)'
+  task build: :yard do
+    Dir.chdir('docs') do
+      sh 'bundle install --quiet'
+      sh 'bundle exec jekyll build'
+    end
+  end
+end
+
 task default: %i[spec rubocop]

data/docs/.gitignore

@@ -3,3 +3,4 @@ _site
 .jekyll-cache
 .jekyll-metadata
 vendor
+api/

data/docs/about.markdown

@@ -4,15 +4,35 @@ title: About
 permalink: /about/
 ---
 
-This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](https://jekyllrb.com/)
+# About EasyTalk
 
-You can find the source code for Minima at GitHub:
-[jekyll][jekyll-organization] /
-[minima](https://github.com/jekyll/minima)
+EasyTalk is a Ruby library for defining and generating JSON Schema from Ruby classes. Inspired by Python's Pydantic library, it provides an ActiveModel-like interface for defining structured data models with automatic validation and JSON Schema generation.
 
-You can find the source code for Jekyll at GitHub:
-[jekyll][jekyll-organization] /
-[jekyll](https://github.com/jekyll/jekyll)
+## Why EasyTalk?
 
+- **Type Safety** - Define your data structures once and get validation automatically
+- **JSON Schema Generation** - Produce standards-compliant JSON Schema from Ruby code
+- **LLM Integration** - Generate function schemas for OpenAI and other LLM providers
+- **ActiveModel Compatible** - Works with Rails forms, validations, and serialization
 
-[jekyll-organization]: https://github.com/jekyll
+## Use Cases
+
+- **API Request/Response Validation** - Define expected shapes for API payloads
+- **LLM Function Calling** - Generate structured output schemas for AI applications
+- **Configuration Files** - Validate configuration against a schema
+- **Data Pipelines** - Ensure data conforms to expected structures
+
+## Links
+
+- [GitHub Repository](https://github.com/sergiobayona/easy_talk)
+- [RubyGems](https://rubygems.org/gems/easy_talk)
+- [API Documentation](api/)
+- [Changelog](https://github.com/sergiobayona/easy_talk/blob/main/CHANGELOG.md)
+
+## Author
+
+Created by [Sergio Bayona](https://github.com/sergiobayona).
+
+## License
+
+EasyTalk is released under the [MIT License](https://github.com/sergiobayona/easy_talk/blob/main/LICENSE.txt).

data/docs/getting-started.markdown

@@ -0,0 +1,102 @@
+---
+layout: page
+title: Getting Started
+permalink: /getting-started/
+---
+
+# Getting Started with EasyTalk
+
+## Requirements
+
+- Ruby 3.2 or later
+- ActiveModel/ActiveSupport 7.0-8.x
+
+## Installation
+
+Add EasyTalk to your Gemfile:
+
+```ruby
+gem 'easy_talk'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install easy_talk
+```
+
+## Basic Usage
+
+### 1. Define a Model
+
+Include `EasyTalk::Model` in your class and use `define_schema` to declare properties:
+
+```ruby
+require 'easy_talk'
+
+class Person
+  include EasyTalk::Model
+
+  define_schema do
+    title "Person"
+    description "A person record"
+
+    property :name, String
+    property :age, Integer
+    property :email, String, format: "email"
+  end
+end
+```
+
+### 2. Generate JSON Schema
+
+Call `.json_schema` on your class to get the JSON Schema:
+
+```ruby
+Person.json_schema
+```
+
+This produces:
+
+```json
+{
+  "type": "object",
+  "title": "Person",
+  "description": "A person record",
+  "properties": {
+    "name": { "type": "string" },
+    "age": { "type": "integer" },
+    "email": { "type": "string", "format": "email" }
+  },
+  "required": ["name", "age", "email"],
+  "additionalProperties": false
+}
+```
+
+### 3. Create and Validate Instances
+
+EasyTalk models work like ActiveModel objects:
+
+```ruby
+person = Person.new(name: "Alice", age: 30, email: "alice@example.com")
+person.valid?  # => true
+person.name    # => "Alice"
+
+# Invalid data triggers validation errors
+invalid = Person.new(name: "", age: -5, email: "not-an-email")
+invalid.valid?       # => false
+invalid.errors.full_messages
+# => ["Name is too short", "Age must be greater than or equal to 0", ...]
+```
+
+## Next Steps
+
+- [Schema Definition](schema-definition) - Learn the full DSL
+- [Property Types](property-types) - Explore available types and constraints
+- [Nested Models](nested-models) - Build complex, composable schemas

data/docs/index.markdown

@@ -1,7 +1,54 @@
 ---
-# Feel free to add content and custom Front Matter to this file.
-# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults
-
 layout: home
+title: Home
 ---
-EasyTalk is a Ruby library that simplifies defining and generating JSON Schema documents, and validates that JSON data conforms to these schemas.
+
+# EasyTalk
+
+EasyTalk is a Ruby library for defining and generating JSON Schema from Ruby classes. It provides an ActiveModel-like interface for defining structured data models with validation and JSON Schema generation capabilities.
+
+## Key Features
+
+- **Schema Definition DSL** - Define JSON Schema using a clean Ruby DSL
+- **Type System** - Support for Ruby types and Sorbet-style generics
+- **ActiveModel Integration** - Built-in validations from schema constraints
+- **Nested Models** - Compose complex schemas from simple building blocks
+- **LLM Function Calling** - Generate OpenAI-compatible function schemas
+
+## Quick Start
+
+```ruby
+class User
+  include EasyTalk::Model
+
+  define_schema do
+    title "User"
+    description "A user in the system"
+    property :name, String, min_length: 2
+    property :email, String, format: "email"
+    property :age, Integer, minimum: 0, optional: true
+  end
+end
+
+# Generate JSON Schema
+User.json_schema
+# => {"type"=>"object", "title"=>"User", ...}
+
+# Create and validate instances
+user = User.new(name: "Alice", email: "alice@example.com")
+user.valid? # => true
+```
+
+## Documentation
+
+- [Getting Started](getting-started) - Installation and basic usage
+- [Schema Definition](schema-definition) - How to define schemas
+- [Property Types](property-types) - Available types and constraints
+- [Nested Models](nested-models) - Composing complex schemas
+- [API Reference](api/) - Generated API documentation
+
+## Links
+
+- [GitHub Repository](https://github.com/sergiobayona/easy_talk)
+- [RubyGems](https://rubygems.org/gems/easy_talk)
+- [Changelog](https://github.com/sergiobayona/easy_talk/blob/main/CHANGELOG.md)

data/docs/json_schema_compliance.md

@@ -0,0 +1,169 @@
+# JSON Schema Compliance Guide
+
+This document defines the strategy for testing and improving `EasyTalk`'s compliance with the official [JSON Schema Specification](https://json-schema.org/specification).
+
+## Test Suite Setup
+
+`EasyTalk` integrates the standard [JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) as a git submodule in `spec/fixtures/json_schema_test_suite`. This provides a language-agnostic set of test cases covering all aspects of the specification.
+
+### Infrastructure
+
+- **Submodule**: Located at `spec/fixtures/json_schema_test_suite`.
+- **Converter**: `spec/support/json_schema_converter.rb` dynamically converts raw JSON Schema definitions into `EasyTalk::Model` classes at runtime.
+- **Runner**: `spec/integration/json_schema_compliance_spec.rb` iterates over the test suite files, generates models, and asserts valid/invalid behavior.
+
+## Running the Tests
+
+The compliance tests are **optional** and excluded from the default `rspec` run to prevent noise from known incompatibilities.
+
+To run the compliance suite:
+
+```bash
+bundle exec rspec --tag json_schema_compliance spec/integration/json_schema_compliance_spec.rb
+```
+
+## Schema Wrapping Strategy
+
+Since `EasyTalk` models are always objects, the JSON Schema test suite's root-level primitive tests (e.g., `{"type": "integer"}` with data `5`) require adaptation.
+
+### How It Works
+
+The `JsonSchemaConverter` uses a **wrapper property strategy**:
+
+1. **Detection**: `needs_wrapping?` checks if the schema is non-object (no `type: object` or `properties` key)
+2. **Wrapping**: Non-object schemas become a `value` property on a wrapper object
+3. **Data transformation**: Primitive test data is wrapped as `{"value": data}`
+
+**Example transformation:**
+
+```
+Original JSON Schema test:
+  Schema: {"type": "integer", "minimum": 1}
+  Data: 5
+  Valid: true
+
+Transformed for EasyTalk:
+  Schema: {
+    "type": "object",
+    "properties": { "value": {"type": "integer", "minimum": 1} },
+    "required": ["value"]
+  }
+  Data: {"value": 5}
+  Valid: true
+```
+
+This preserves validation semantics while fitting EasyTalk's object-based model.
+
+## Current Test Results
+
+As of the latest run:
+
+| Metric | Count |
+|--------|-------|
+| Total examples | 916 |
+| Passing | ~193 |
+| Failing | 165 |
+| Pending (known unsupported) | 558 |
+
+### Known Unsupported Features
+
+The following test files are skipped entirely via `KNOWN_FAILURES`:
+
+| File | Reason |
+|------|--------|
+| `not.json` | `not` keyword not supported |
+| `anyOf.json` | `anyOf` validation not supported |
+| `allOf.json` | `allOf` validation not supported |
+| `oneOf.json` | `oneOf` validation not supported |
+| `refRemote.json` | Remote `$ref` not supported |
+| `dependencies.json` | Dependencies not supported |
+| `definitions.json` | `$defs`/definitions not supported |
+| `if-then-else.json` | Conditional logic not supported |
+| `patternProperties.json` | Pattern properties not supported |
+| `properties.json` | Complex property interactions not supported |
+| `propertyNames.json` | Property names validation not supported |
+| `ref.json` | Complex `$ref` not supported |
+| `required.json` | Complex required checks not supported |
+| `additionalItems.json` | Additional items not supported |
+| `additionalProperties.json` | Additional properties validation not supported |
+| `boolean_schema.json` | Boolean schemas (`true`/`false` as schema) not supported |
+| `const.json` | `const` keyword not supported |
+| `default.json` | Default keyword behavior not supported |
+| `enum.json` | Enum validation not fully supported |
+| `infinite-loop-detection.json` | Infinite loop detection not supported |
+| `maxProperties.json` | Max properties not supported |
+| `minProperties.json` | Min properties not supported |
+
+## Compliance Gaps
+
+The 165 failing tests reveal real validation gaps in EasyTalk:
+
+### 1. Type Coercion (Intentional Behavior)
+
+EasyTalk uses ActiveModel's numericality validation which coerces strings to numbers:
+
+```ruby
+user = User.new(age: "30")  # String
+user.valid?  # => true (coerced to integer 30)
+```
+
+Per JSON Schema, `"30"` should be invalid for `type: integer`. This is documented as **intentional behavior** for Rails compatibility. A `strict_types` configuration option is planned (see [#137](https://github.com/sergiobayona/easy_talk/issues/137)).
+
+### 2. Format Validation Scope
+
+JSON Schema specifies that format validations should only apply to strings and ignore other types. EasyTalk currently validates format on the assigned value regardless of type.
+
+### 3. Empty String Presence
+
+EasyTalk uses ActiveModel's presence validation for required fields, which rejects empty strings. JSON Schema considers `""` a valid string.
+
+### 4. Array Type Validation
+
+Array element types are not strictly validated at runtime.
+
+### 5. Null Type
+
+The `null` type is not fully implemented as a standalone type.
+
+### 6. uniqueItems
+
+Array uniqueness constraint is not enforced during validation.
+
+## Workflow for Improvements
+
+1. **Select a Feature**: Pick a specific file from `KNOWN_FAILURES` or analyze failing tests.
+2. **Enable Tests**: Remove the file from `KNOWN_FAILURES` in the spec.
+3. **Run & Analyze**:
+   ```bash
+   bundle exec rspec --tag json_schema_compliance spec/integration/json_schema_compliance_spec.rb
+   ```
+4. **Implement Fix**: Modify EasyTalk internals to support the feature.
+5. **Update Converter**: If needed, update `JsonSchemaConverter` for test adaptation.
+
+## Critical Implementation Notes
+
+### Reserved Words
+
+Properties like `method`, `class`, `constructor` conflict with Ruby. The converter sanitizes these via `sanitize_property_name` and uses the `as:` option to preserve the original JSON key.
+
+### Boolean Schemas
+
+`properties: { foo: false }` is valid JSON Schema (property forbidden) but not currently supported.
+
+### Strict Property Validation
+
+EasyTalk raises `InvalidPropertyNameError` for invalid property names at definition time. Full compliance would require allowing arbitrary property keys.
+
+## Contributing
+
+When adding support for a new JSON Schema keyword:
+
+1. Check if a test file exists in `spec/fixtures/json_schema_test_suite/tests/draft7/`.
+2. Remove the filename from `KNOWN_FAILURES` in `spec/integration/json_schema_compliance_spec.rb`.
+3. Run the tests and analyze failures.
+4. Implement the feature in EasyTalk.
+5. Update this document with any new findings.
+
+## Related Issues
+
+- [#137](https://github.com/sergiobayona/easy_talk/issues/137) - Add `strict_types` configuration option

data/docs/nested-models.markdown

@@ -0,0 +1,216 @@
+---
+layout: page
+title: Nested Models
+permalink: /nested-models/
+---
+
+# Nested Models
+
+EasyTalk supports composing complex schemas from simpler building blocks. This enables clean, reusable data structures.
+
+## Basic Nesting
+
+Reference another EasyTalk model as a property type:
+
+```ruby
+class Address
+  include EasyTalk::Model
+
+  define_schema do
+    property :street, String
+    property :city, String
+    property :zip_code, String, pattern: /^\d{5}$/
+  end
+end
+
+class Person
+  include EasyTalk::Model
+
+  define_schema do
+    property :name, String
+    property :home_address, Address
+    property :work_address, Address, optional: true
+  end
+end
+```
+
+### Generated Schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "home_address": {
+      "type": "object",
+      "properties": {
+        "street": { "type": "string" },
+        "city": { "type": "string" },
+        "zip_code": { "type": "string", "pattern": "^\\d{5}$" }
+      },
+      "required": ["street", "city", "zip_code"]
+    },
+    "work_address": { ... }
+  },
+  "required": ["name", "home_address"]
+}
+```
+
+## Arrays of Models
+
+Use `T::Array[ModelClass]` for collections:
+
+```ruby
+class Order
+  include EasyTalk::Model
+
+  define_schema do
+    property :id, String
+    property :items, T::Array[LineItem], min_items: 1
+    property :shipping_address, Address
+  end
+end
+
+class LineItem
+  include EasyTalk::Model
+
+  define_schema do
+    property :product_id, String
+    property :quantity, Integer, minimum: 1
+    property :price, Float, minimum: 0
+  end
+end
+```
+
+## Auto-Instantiation
+
+When you pass a Hash to a nested model property, EasyTalk automatically instantiates the nested model:
+
+```ruby
+person = Person.new(
+  name: "Alice",
+  home_address: {
+    street: "123 Main St",
+    city: "Boston",
+    zip_code: "02101"
+  }
+)
+
+person.home_address.class  # => Address
+person.home_address.city   # => "Boston"
+```
+
+This works recursively for deeply nested structures.
+
+## Using $ref for Reusability
+
+By default, nested models are inlined. Enable `$ref` for cleaner, more reusable schemas:
+
+```ruby
+class Person
+  include EasyTalk::Model
+
+  define_schema do
+    property :name, String
+    property :address, Address, ref: true
+  end
+end
+```
+
+This generates:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "address": { "$ref": "#/$defs/Address" }
+  },
+  "$defs": {
+    "Address": {
+      "type": "object",
+      "properties": { ... }
+    }
+  }
+}
+```
+
+## Nullable Nested Models
+
+Allow null values for nested models:
+
+```ruby
+property :backup_address, T.nilable(Address)
+```
+
+Or make it both nullable and optional:
+
+```ruby
+property :backup_address, T.nilable(Address), optional: true
+```
+
+## Composition with compose
+
+Use `compose` to merge multiple schemas into one:
+
+```ruby
+class BasicInfo
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :email, String
+  end
+end
+
+class ContactInfo
+  include EasyTalk::Model
+  define_schema do
+    property :phone, String
+    property :address, Address
+  end
+end
+
+class FullProfile
+  include EasyTalk::Model
+  define_schema do
+    compose T::AllOf[BasicInfo, ContactInfo]
+  end
+end
+```
+
+## Polymorphic Types
+
+Use `T::OneOf` or `T::AnyOf` for polymorphic properties:
+
+```ruby
+class EmailContact
+  include EasyTalk::Model
+  define_schema do
+    property :email, String, format: "email"
+  end
+end
+
+class PhoneContact
+  include EasyTalk::Model
+  define_schema do
+    property :phone, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :primary_contact, T::OneOf[EmailContact, PhoneContact]
+  end
+end
+```
+
+This ensures the `primary_contact` matches exactly one of the specified schemas.
+
+## Best Practices
+
+1. **Keep models focused** - Each model should represent one concept
+2. **Reuse models** - Define common structures (Address, Money, etc.) once
+3. **Use $ref for large schemas** - Reduces duplication and improves readability
+4. **Validate at boundaries** - Nested models validate automatically when the parent validates