easy_talk 3.1.0 → 3.2.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,55 @@
+# 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
+```
+
+## Compliance Strategy
+
+The goal is to incrementally improve compliance by enabling more tests and fixing the underlying issues in `EasyTalk`.
+
+### 1. Identify Gaps
+The current test runner skips many tests (marked as `pending` or explicit `skip`).
+*   **Root Primitives**: `EasyTalk` models are Objects. Tests for root integers/strings are skipped.
+*   **Strict Naming**: Tests with property names that are invalid Ruby identifiers (e.g., `foo-bar`, `123`, `constructor`) are currently skipped.
+*   **Missing Keywords**: Keywords like `patternProperties`, `const`, and `oneOf` (in specific contexts) may fail.
+
+### 2. Workflow for Improvements
+1.  **Select a Feature**: Pick a specific file (e.g., `properties.json`, `required.json`) or a skipped section.
+2.  **Un-skip Tests**: Remove the `skip` logic in `spec/integration/json_schema_compliance_spec.rb` for that feature.
+3.  **Run & Analyze**: Run the specific test file.
+    ```bash
+    bundle exec rspec --tag json_schema_compliance
+    ```
+4.  **Implement Fix**: Modify `EasyTalk` internals (e.g., `keywords.rb`, `schema_definition.rb`) to support the feature.
+5.  **Sanitize Inputs**: Update `JsonSchemaConverter` if the test case requires adaptation (e.g., mapping a JSON key to a safe Ruby method name via `as:`) without changing the underlying validation logic.
+
+### 3. Known Critical Issues
+*   **Reserved Words**: Properties like `method`, `class`, `constructor` conflict with Ruby. Fix requires a robust proxy or sanitization layer in `EasyTalk::Model`.
+*   **Boolean Schemas**: `properties: { foo: false }` is valid JSON Schema (property forbidden) but not currently supported by `EasyTalk`.
+*   **Strict Property Validation**: `EasyTalk` raises errors for invalid property names at definition time. Compliance requires allowing arbitrary property keys (perhaps via `validates_with` logic instead of metaprogramming methods).
+
+## 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.  Add the filename to the `FOCUS_FILES` list in `spec/integration/json_schema_compliance_spec.rb`.
+3.  Implement the feature and verify pass.

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