easy_talk 3.1.0 → 3.3.0

data/README.md

@@ -2,1832 +2,745 @@
 
 [![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)
+[![codecov](https://codecov.io/gh/sergiobayona/easy_talk/graph/badge.svg)](https://codecov.io/gh/sergiobayona/easy_talk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/ruby-3.2%2B-ruby.svg)](https://www.ruby-lang.org)
+[![Downloads](https://img.shields.io/gem/dt/easy_talk.svg)](https://rubygems.org/gems/easy_talk)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/easy_talk)
+[![GitHub stars](https://img.shields.io/github/stars/sergiobayona/easy_talk?style=social)](https://github.com/sergiobayona/easy_talk)
 
-## Introduction
-
-### What is EasyTalk?
-EasyTalk is a Ruby library that simplifies defining and generating JSON Schema. It provides an intuitive interface for Ruby developers to define structured data models that can be used for validation and documentation.
-
-### 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 ActiveModel classes**: 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.
-* **Enhanced Model Integration**: Automatic instantiation of nested EasyTalk models from hash attributes.
-* **Flexible Configuration**: Global and per-model configuration options for fine-tuned control.
-* **JSON Schema Version Support**: Configure the `$schema` keyword to declare which JSON Schema draft version your schemas conform to (Draft-04 through Draft 2020-12).
-* **Schema Identification**: Configure the `$id` keyword to provide a unique identifier URI for your schemas.
-* **Schema References**: Use `$ref` and `$defs` for reusable schema definitions, reducing duplication when models are used in multiple places.
-
-### Use Cases
-- API request/response validation
-- LLM function definitions
-- Object structure documentation
-- Data validation and transformation
-- Configuration schema definitions
-
-### Inspiration
-Inspired by Python's Pydantic library, EasyTalk brings similar functionality to the Ruby ecosystem, providing a Ruby-friendly approach to JSON Schema operations.
+Ruby library for defining **structured data contracts** that generate **JSON Schema** *and* (optionally) **runtime validations** from the same definition.
 
-## Installation
+Think “Pydantic-style ergonomics” for Ruby, with first-class JSON Schema output.
 
-### Requirements
-- Ruby 3.2 or higher
+---
 
-### Version 2.0.0 Breaking Changes
+## Why EasyTalk?
 
-⚠️ **IMPORTANT**: Version 2.0.0 includes breaking changes. Please review before upgrading:
+You can hand-write JSON Schema, then hand-write validations, then hand-write error responses… and eventually you’ll ship a bug where those three disagree.
 
-- **Removed**: Block-style nested object definitions (using `Hash do ... end`)
-- **Migration**: Use class references instead of inline Hash definitions
+EasyTalk makes the schema definition the single source of truth, so you can:
 
-```ruby
-# ❌ No longer supported (v1.x style)
-define_schema do
-  property :address, Hash do
-    property :street, String
-    property :city, String
-  end
-end
+- **Define once, use everywhere**  
+  One Ruby DSL gives you:
+  - `json_schema` for docs, OpenAPI, LLM tools, and external validators
+  - `valid?` / `errors` (when using `EasyTalk::Model`) for runtime validation
 
-# ✅ New approach (v2.x style)
-class Address
-  include EasyTalk::Model
-  define_schema do
-    property :street, String
-    property :city, String
-  end
-end
+- **Stop arguing with JSON Schema’s verbosity**  
+  Express constraints in Ruby where you already live:
+  ```ruby
+  property :email, String, format: "email"
+  property :age, Integer, minimum: 18
+  property :tags, T::Array[String], min_items: 1
+  ```
 
-class User
-  include EasyTalk::Model
-  define_schema do
-    property :address, Address  # Reference the class directly
-  end
-end
-```
+- **Use a richer type system than "string/integer/object"**
+  EasyTalk supports Sorbet-style types and composition:
+  - `T.nilable(Type)` for nullable fields
+  - `T::Array[Type]` for typed arrays
+  - `T::Tuple[Type1, Type2, ...]` for fixed-position typed arrays
+  - `T::Boolean`
+  - `T::AnyOf`, `T::OneOf`, `T::AllOf` for schema composition
 
-### Installation Steps
-Add EasyTalk to your application's Gemfile:
+- **Get validations for free (when you want them)**  
+  With `auto_validations` enabled (default), schema constraints generate ActiveModel validations—**including nested models**, even inside arrays.
 
-```ruby
-gem 'easy_talk'
-```
+- **Make API errors consistent**  
+  Format validation errors as:
+  - flat lists
+  - JSON Pointer
+  - **RFC 7807** problem details
+  - **JSON:API** error objects
 
-Or install it directly:
+- **LLM tool/function schemas without a second schema layer**  
+  Use the same contract to generate JSON Schema for function/tool calling.
 
-```bash
-$ gem install easy_talk
-```
+EasyTalk is for teams who want their data contracts to be **correct, reusable, and boring** (the good kind of boring).
+
+---
+
+## Installation
+
+### Requirements
+- Ruby **3.2+**
 
-### Verification
-After installation, you can verify it's working by creating a simple model:
+Add to your Gemfile:
 
 ```ruby
-require 'easy_talk'
+gem "easy_talk"
+```
 
-class Test
-  include EasyTalk::Model
-  
-  define_schema do
-    property :name, String
-  end
-end
+Then:
 
-puts Test.json_schema
+```bash
+bundle install
 ```
 
-## Quick Start
+---
 
-### Minimal Example
-Here's a basic example to get you started with EasyTalk:
+## Quick start
 
 ```ruby
+require "easy_talk"
+
 class User
   include EasyTalk::Model
 
   define_schema do
     title "User"
     description "A user of the system"
-    property :name, String, description: "The user's name"
+
+    property :id, String
+    property :name, String, min_length: 2
     property :email, String, format: "email"
     property :age, Integer, minimum: 18
   end
 end
+
+User.json_schema   # => Ruby Hash (JSON Schema)
+user = User.new(name: "A")  # invalid: min_length is 2
+user.valid?        # => false
+user.errors        # => ActiveModel::Errors
 ```
 
-### Generated JSON Schema
-Calling `User.json_schema` will generate:
+**Generated JSON Schema:**
 
-```ruby
+```json
 {
-  "type" => "object",
-  "title" => "User",
-  "description" => "A user of the system",
-  "properties" => {
-    "name" => {
-      "type" => "string", 
-      "description" => "The user's name"
-    },
-    "email" => {
-      "type" => "string", 
-      "format" => "email"
-    },
-    "age" => {
-      "type" => "integer", 
-      "minimum" => 18
-    }
+  "type": "object",
+  "title": "User",
+  "description": "A user of the system",
+  "properties": {
+    "id": { "type": "string" },
+    "name": { "type": "string", "minLength": 2 },
+    "email": { "type": "string", "format": "email" },
+    "age": { "type": "integer", "minimum": 18 }
   },
-  "required" => ["name", "email", "age"]
+  "required": ["id", "name", "email", "age"]
 }
 ```
 
-### Basic Usage
-Creating and validating an instance of your model:
-
-```ruby
-user = User.new(name: "John Doe", email: "john@example.com", age: 25)
-user.valid? # => true (automatically validates based on schema constraints)
+---
 
-user.age = 17
-user.valid? # => false (violates minimum: 18 constraint)
-user.errors[:age] # => ["must be greater than or equal to 18"]
-```
+## Property constraints
 
-## Core Concepts
+| Constraint | Applies to | Example |
+|------------|-----------|---------|
+| `min_length` / `max_length` | String | `property :name, String, min_length: 2, max_length: 50` |
+| `minimum` / `maximum` | Integer, Float | `property :age, Integer, minimum: 18, maximum: 120` |
+| `format` | String | `property :email, String, format: "email"` |
+| `pattern` | String | `property :zip, String, pattern: '^\d{5}$'` |
+| `enum` | Any | `property :status, String, enum: ["active", "inactive"]` |
+| `min_items` / `max_items` | Array, Tuple | `property :tags, T::Array[String], min_items: 1` |
+| `unique_items` | Array, Tuple | `property :ids, T::Array[Integer], unique_items: true` |
+| `additional_items` | Tuple | `property :coords, T::Tuple[Float, Float], additional_items: false` |
+| `optional` | Any | `property :nickname, String, optional: true` |
+| `default` | Any | `property :role, String, default: "user"` |
+| `description` | Any | `property :name, String, description: "Full name"` |
+| `title` | Any | `property :name, String, title: "User Name"` |
 
-### Schema Definition
-In EasyTalk, you define your schema by including the `EasyTalk::Model` module and using the `define_schema` method. This method takes a block where you can define the properties and constraints of your schema.
+**Object-level constraints** (applied in `define_schema` block):
+- `min_properties` / `max_properties` - Minimum/maximum number of properties
+- `pattern_properties` - Schema for properties matching regex patterns
+- `dependent_required` - Conditional property requirements
 
-```ruby
-class MyModel
-  include EasyTalk::Model
+When `auto_validations` is enabled (default), these constraints automatically generate corresponding ActiveModel validations.
 
-  define_schema do
-    title "My Model"
-    description "Description of my model"
-    property :some_property, String
-    property :another_property, Integer
-  end
-end
-```
+---
 
-### Property Types
+## Core concepts
 
-#### Ruby Types
-EasyTalk supports standard Ruby types directly:
+### Required vs optional vs nullable (don't get tricked)
 
-- `String`: String values
-- `Integer`: Integer values
-- `Float`: Floating-point numbers
-- `Date`: Date values
-- `DateTime`: Date and time values
+JSON Schema distinguishes:
+- **Optional**: property may be omitted (not in `required`)
+- **Nullable**: property may be `null` (type includes `"null"`)
 
-#### Sorbet-Style Types
-For complex types, EasyTalk uses Sorbet-style type notation:
+EasyTalk mirrors that precisely:
 
-- `T::Boolean`: Boolean values (true/false)
-- `T::Array[Type]`: Arrays with items of a specific type
-- `T.nilable(Type)`: Type that can also be nil
+```ruby
+class Profile
+  include EasyTalk::Model
 
-#### Custom Types
-EasyTalk supports special composition types:
+  define_schema do
+    # required, not nullable
+    property :name, String
 
-- `T::AnyOf[Type1, Type2, ...]`: Value can match any of the specified schemas
-- `T::OneOf[Type1, Type2, ...]`: Value must match exactly one of the specified schemas
-- `T::AllOf[Type1, Type2, ...]`: Value must match all of the specified schemas
+    # required, nullable (must exist, may be null)
+    property :age, T.nilable(Integer)
 
-### Property Constraints
-Property constraints depend on the type of property. Some common constraints include:
+    # optional, not nullable (may be omitted, but cannot be null if present)
+    property :nickname, String, optional: true
 
-- `description`: A description of the property
-- `title`: A title for the property
-- `format`: A format hint for the property (e.g., "email", "date")
-- `enum`: A list of allowed values
-- `minimum`/`maximum`: Minimum/maximum values for numbers
-- `min_length`/`max_length`: Minimum/maximum length for strings
-- `pattern`: A regular expression pattern for strings
-- `min_items`/`max_items`: Minimum/maximum number of items for arrays
-- `unique_items`: Whether array items must be unique
+    # optional + nullable (may be omitted OR null)
+    property :bio, T.nilable(String), optional: true
+    # or, equivalently:
+    nullable_optional_property :website, String
+  end
+end
+```
 
-### Required vs Optional Properties
-By default, all properties defined in an EasyTalk model are required. You can make a property optional by specifying `optional: true`:
+By default, `T.nilable(Type)` makes a field **nullable but still required**.  
+If you want “nilable implies optional” behavior globally:
 
 ```ruby
-define_schema do
-  property :name, String
-  property :middle_name, String, optional: true
+EasyTalk.configure do |config|
+  config.nilable_is_optional = true
 end
 ```
 
-In this example, `name` is required but `middle_name` is optional.
+---
 
-### Automatic Validation Generation
-EasyTalk automatically generates ActiveModel validations from your schema constraints. This feature is enabled by default but can be configured:
+### Nested models (and automatic instantiation)
+
+Define nested objects as separate classes, then reference them:
 
 ```ruby
+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, 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"]
+    property :name, String
+    property :address, Address
   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"]
+user = User.new(
+  name: "John",
+  address: { street: "123 Main St", city: "Boston" } # Hash becomes Address automatically
+)
+
+user.address.class  # => Address
 ```
 
-### Manual Validation Overrides
-You can still add manual validations alongside automatic ones:
+Nested models inside arrays work too:
 
 ```ruby
-class User
+class Order
   include EasyTalk::Model
-  
-  # 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
+    property :line_items, T::Array[Address], min_items: 1
   end
 end
 ```
 
-## Defining Schemas
+---
 
-### Basic Schema Structure
-A schema definition consists of a class that includes `EasyTalk::Model` and a `define_schema` block:
+### Tuple arrays (fixed-position types)
+
+Use `T::Tuple` for arrays where each position has a specific type (e.g., coordinates, CSV rows, database records):
 
 ```ruby
-class Person
+class GeoLocation
   include EasyTalk::Model
 
   define_schema do
-    title "Person"
     property :name, String
-    property :age, Integer
+    # Fixed: [latitude, longitude]
+    property :coordinates, T::Tuple[Float, Float]
   end
 end
-```
-
-### Property Definitions
-Properties are defined using the `property` method, which takes a name, a type, and optional constraints:
 
-```ruby
-property :name, String, description: "The person's name", title: "Full Name"
-property :age, Integer, minimum: 0, maximum: 120, description: "The person's age"
+location = GeoLocation.new(
+  name: 'Office',
+  coordinates: [40.7128, -74.0060]
+)
 ```
 
-### Arrays and Collections
-Arrays can be defined using the `T::Array` type:
+**Generated JSON Schema:**
 
-```ruby
-property :tags, T::Array[String], min_items: 1, unique_items: true
-property :scores, T::Array[Integer], description: "List of scores"
+```json
+{
+  "properties": {
+    "coordinates": {
+      "type": "array",
+      "items": [
+        { "type": "number" },
+        { "type": "number" }
+      ]
+    }
+  }
+}
 ```
 
-You can also define arrays of complex types:
+**Mixed-type tuples:**
 
 ```ruby
-property :addresses, T::Array[Address], description: "List of addresses"
-```
-
-### Constraints and Automatic Validations
-Constraints are added to properties and are used for both schema generation and automatic validation generation:
+class DataRow
+  include EasyTalk::Model
 
-```ruby
-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
+  define_schema do
+    # Fixed: [name, age, active]
+    property :row, T::Tuple[String, Integer, T::Boolean]
+  end
 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 }
 ```
 
-### Supported Constraint-to-Validation Mappings
-
-| 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:
+**Controlling extra items:**
 
 ```ruby
 define_schema do
-  property :name, String
-  additional_properties true
+  # Reject extra items (strict tuple)
+  property :rgb, T::Tuple[Integer, Integer, Integer], additional_items: false
+
+  # Allow extra items of specific type
+  property :header_values, T::Tuple[String], additional_items: Integer
+
+  # Allow any extra items (default)
+  property :flexible, T::Tuple[String, Integer]
 end
 ```
 
-With `additional_properties true`, you can add arbitrary properties to your model instances:
+**Tuple validation:**
 
 ```ruby
-company = Company.new
-company.name = "Acme Corp"        # Defined property
-company.location = "New York"     # Additional property
-company.employee_count = 100      # Additional property
+model = GeoLocation.new(coordinates: [40.7, "invalid"])
+model.valid?  # => false
+model.errors[:coordinates]
+# => ["item at index 1 must be a Float"]
 ```
 
-## Schema Composition
+---
 
-### Using T::AnyOf
-The `T::AnyOf` type allows a property to match any of the specified schemas:
+### Composition (AnyOf / OneOf / AllOf)
 
 ```ruby
-class Payment
+class ProductA
   include EasyTalk::Model
-
   define_schema do
-    property :details, T::AnyOf[CreditCard, Paypal, BankTransfer]
+    property :sku, String
+    property :weight, Float
   end
 end
-```
 
-### Using T::OneOf
-The `T::OneOf` type requires a property to match exactly one of the specified schemas:
+class ProductB
+  include EasyTalk::Model
+  define_schema do
+    property :sku, String
+    property :color, String
+  end
+end
 
-```ruby
-class Contact
+class Cart
   include EasyTalk::Model
 
   define_schema do
-    property :contact, T::OneOf[PhoneContact, EmailContact]
+    property :items, T::Array[T::AnyOf[ProductA, ProductB]]
   end
 end
 ```
 
-### Using T::AllOf
-The `T::AllOf` type requires a property to match all of the specified schemas:
+---
+
+## Validations
+
+### Automatic validations (default)
+
+EasyTalk can generate ActiveModel validations from constraints:
 
 ```ruby
-class VehicleRegistration
-  include EasyTalk::Model
-  
-  define_schema do
-    compose T::AllOf[VehicleIdentification, OwnerInfo, RegistrationDetails]
-  end
+EasyTalk.configure do |config|
+  config.auto_validations = true
 end
 ```
 
-### Complex Compositions
-You can combine composition types to create complex schemas:
+Disable globally:
 
 ```ruby
-class ComplexObject
-  include EasyTalk::Model
-  
-  define_schema do
-    property :basic_info, BaseInfo
-    property :specific_details, T::OneOf[DetailTypeA, DetailTypeB]
-    property :metadata, T::AnyOf[AdminMetadata, UserMetadata, nil]
-  end
+EasyTalk.configure do |config|
+  config.auto_validations = false
 end
 ```
 
-### Reusing Models
-Models can reference other models to create hierarchical schemas:
+When auto validations are off, you can still write validations manually:
 
 ```ruby
-class Address
+class User
   include EasyTalk::Model
-  
+
+  validates :name, presence: true, length: { minimum: 2 }
+
   define_schema do
-    property :street, String
-    property :city, String
-    property :state, String
-    property :zip, String
+    property :name, String, min_length: 2
   end
 end
+```
 
-class User
+### Per-model validation control
+
+```ruby
+class LegacyModel
   include EasyTalk::Model
-  
-  define_schema do
-    property :name, String
-    property :address, Address
+
+  define_schema(validations: false) do
+    property :data, String, min_length: 1  # no validation generated
   end
 end
 ```
 
-## ActiveModel Integration
-
-### Enhanced Validation System
-EasyTalk models include comprehensive ActiveModel validation support with automatic generation:
+### Per-property validation control
 
 ```ruby
 class User
   include EasyTalk::Model
-  
-  # 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, 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)
+    property :name, String, min_length: 2
+    property :legacy_field, String, validate: false
   end
 end
 ```
 
-### Error Handling
-You can access validation errors using the standard ActiveModel methods:
+### Validation adapters
+
+EasyTalk uses a pluggable adapter system:
 
 ```ruby
-user = User.new(name: "J", age: 18, height: -5.9)
-user.valid? # => false
-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
+EasyTalk.configure do |config|
+  config.validation_adapter = :active_model  # default
+  # config.validation_adapter = :none        # disable validation generation
+end
 ```
 
-### Model Attributes
-EasyTalk models provide getters and setters for all defined properties:
+---
+
+## Error formatting
+
+Instance helpers:
 
 ```ruby
-user = User.new
-user.name = "John"
-user.age = 30
-puts user.name # => "John"
+user.validation_errors_flat
+user.validation_errors_json_pointer
+user.validation_errors_rfc7807
+user.validation_errors_jsonapi
 ```
 
-You can also initialize a model with a hash of attributes, including nested EasyTalk models:
+Format directly:
 
 ```ruby
-user = User.new(name: "John", age: 30, height: 5.9)
+EasyTalk::ErrorFormatter.format(user.errors, format: :rfc7807, title: "User Validation Failed")
+```
 
-# 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
+Global defaults:
 
-class User
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :address, Address
-  end
+```ruby
+EasyTalk.configure do |config|
+  config.default_error_format = :rfc7807
+  config.error_type_base_uri = "https://api.example.com/errors"
+  config.include_error_codes = true
 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"
 ```
 
-## Advanced Features
+---
+
+## Schema-only mode
 
-### LLM Function Generation
-EasyTalk provides a helper method for generating OpenAI function specifications:
+If you want schema generation and attribute accessors **without** ActiveModel validation:
 
 ```ruby
-class Weather
-  include EasyTalk::Model
-  
+class ApiContract
+  include EasyTalk::Schema
+
   define_schema do
-    title "GetWeather"
-    description "Get the current weather in a given location"
-    property :location, String, description: "The city and state, e.g. San Francisco, CA"
-    property :unit, String, enum: ["celsius", "fahrenheit"], default: "fahrenheit"
+    title "API Contract"
+    property :name, String, min_length: 2
+    property :age, Integer, minimum: 0
   end
 end
 
-function_spec = EasyTalk::Tools::FunctionBuilder.new(Weather)
+ApiContract.json_schema
+contract = ApiContract.new(name: "Test", age: 25)
+
+# No validations available:
+# contract.valid?  # => NoMethodError
 ```
 
-This generates a function specification compatible with OpenAI's function calling API.
+Use this for documentation, OpenAPI generation, or when validation happens elsewhere.
 
-### Schema Transformation
-You can transform EasyTalk schemas into various formats:
+---
+
+## Configuration highlights
 
 ```ruby
-# Get Ruby hash representation
-schema_hash = User.schema
+EasyTalk.configure do |config|
+  # Schema behavior
+  config.default_additional_properties = false
+  config.nilable_is_optional = false
+  config.schema_version = :none
+  config.schema_id = nil
+  config.use_refs = false
+  config.base_schema_uri = nil                 # Base URI for auto-generating $id
+  config.auto_generate_ids = false             # Auto-generate $id from base_schema_uri
+  config.prefer_external_refs = false          # Use external URI in $ref when available
+  config.property_naming_strategy = :identity  # :snake_case, :camel_case, :pascal_case
 
-# Get JSON Schema representation
-json_schema = User.json_schema
+  # Validations
+  config.auto_validations = true
+  config.validation_adapter = :active_model
 
-# Convert to JSON string
-json_string = User.json_schema.to_json
+  # Error formatting
+  config.default_error_format = :flat          # :flat, :json_pointer, :rfc7807, :jsonapi
+  config.error_type_base_uri = "about:blank"
+  config.include_error_codes = true
+end
 ```
 
-### Type Checking and Validation
-EasyTalk performs basic type checking during schema definition:
-
-```ruby
-# This will raise an error because "minimum" should be used with numeric types
-property :name, String, minimum: 1  # Error!
-
-# This will raise an error because enum values must match the property type
-property :age, Integer, enum: ["young", "old"]  # Error!
-```
+---
 
-### Custom Type Builders
-For advanced use cases, you can create custom type builders:
+## Advanced topics
 
-```ruby
-module EasyTalk
-  module Builders
-    class MyCustomTypeBuilder < BaseBuilder
-      # Custom implementation
-    end
-  end
-end
-```
+For more detailed documentation, see the [full API reference on RubyDoc](https://rubydoc.info/gems/easy_talk).
 
-## Configuration
+### JSON Schema drafts, `$id`, and `$ref`
 
-### Global Settings
-You can configure EasyTalk globally:
+EasyTalk can emit `$schema` for multiple drafts (Draft-04 through 2020-12), supports `$id`, and can use `$ref`/`$defs` for reusable definitions:
 
 ```ruby
 EasyTalk.configure do |config|
-  # Schema behavior options
-  config.default_additional_properties = false  # Control additional properties on all models
-  config.nilable_is_optional = false           # Makes T.nilable properties also optional
-  config.auto_validations = true               # Automatically generate ActiveModel validations
-  config.schema_version = :none                # JSON Schema version for $schema keyword
-                                               # Options: :none, :draft202012, :draft201909, :draft7, :draft6, :draft4
-  config.schema_id = nil                       # Base URI for $id keyword (nil = no $id)
-  config.use_refs = false                      # Use $ref for nested models instead of inlining
+  config.schema_version = :draft202012
+  config.schema_id = "https://example.com/schemas/user.json"
+  config.use_refs = true  # Use $ref/$defs for nested models
 end
 ```
 
-### Automatic Validation Configuration
-The new `auto_validations` option (enabled by default) automatically generates ActiveModel validations from your schema constraints:
+#### External schema references
+
+Use external URIs in `$ref` for modular, reusable schemas:
 
 ```ruby
-# Disable automatic validations globally
 EasyTalk.configure do |config|
-  config.auto_validations = false
+  config.use_refs = true
+  config.prefer_external_refs = true
+  config.base_schema_uri = 'https://example.com/schemas'
+  config.auto_generate_ids = true
 end
 
-# Now you must manually define validations
-class User
+class Address
   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
+    property :street, String
+    property :city, String
   end
 end
-```
 
-### Per-Model Configuration
-You can configure additional properties for individual models:
-
-```ruby
-class User
+class Customer
   include EasyTalk::Model
-  
+
   define_schema do
-    title "User"
-    additional_properties true  # Allow arbitrary additional properties on this model
     property :name, String
-    property :email, String, format: "email"
+    property :address, Address
   end
 end
-```
 
-## Examples
+Customer.json_schema
+# =>
+# {
+#   "properties": {
+#     "address": { "$ref": "https://example.com/schemas/address" }
+#   },
+#   "$defs": {
+#     "Address": {
+#       "$id": "https://example.com/schemas/address",
+#       "properties": { "street": {...}, "city": {...} }
+#     }
+#   }
+# }
+```
 
-### User Registration (with Auto-Validations)
+**Explicit schema IDs:**
 
 ```ruby
-class User
+class Address
   include EasyTalk::Model
 
-  # 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, 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, max_length: 128, description: "User's password"
-    property :notify, T::Boolean, optional: true, description: "Whether to send notifications"
+    schema_id 'https://example.com/schemas/address'
+    property :street, String
   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
+**Per-property ref control:**
 
 ```ruby
-class CreditCard
+class Customer
   include EasyTalk::Model
 
   define_schema do
-    property :CardNumber, String
-    property :CardType, String, enum: %w[Visa MasterCard AmericanExpress]
-    property :CardExpMonth, Integer, minimum: 1, maximum: 12
-    property :CardExpYear, Integer, minimum: Date.today.year, maximum: Date.today.year + 10
-    property :CardCVV, String, pattern: '^[0-9]{3,4}$'
-    additional_properties false
+    property :address, Address, ref: false  # Inline instead of ref
+    property :billing, Address              # Uses ref (global setting)
   end
 end
+```
 
-class Paypal
-  include EasyTalk::Model
+### Additional properties with types
 
-  define_schema do
-    property :PaypalEmail, String, format: 'email'
-    property :PaypalPasswordEncrypted, String
-    additional_properties false
-  end
-end
+Beyond boolean values, `additional_properties` now supports type constraints for dynamic properties:
 
-class BankTransfer
+```ruby
+class Config
   include EasyTalk::Model
 
   define_schema do
-    property :BankName, String
-    property :AccountNumber, String
-    property :RoutingNumber, String
-    property :AccountType, String, enum: %w[Checking Savings]
-    additional_properties false
+    property :name, String
+
+    # Allow any string-typed additional properties
+    additional_properties String
   end
 end
 
-class Payment
+config = Config.new(name: 'app')
+config.label = 'Production'  # Dynamic property
+config.as_json
+# => { 'name' => 'app', 'label' => 'Production' }
+```
+
+**With constraints:**
+
+```ruby
+class StrictConfig
   include EasyTalk::Model
 
   define_schema do
-    title 'Payment'
-    description 'Payment info'
-    property :PaymentMethod, String, enum: %w[CreditCard Paypal BankTransfer]
-    property :Details, T::AnyOf[CreditCard, Paypal, BankTransfer]
+    property :id, Integer
+    # Integer values between 0 and 100 only
+    additional_properties Integer, minimum: 0, maximum: 100
   end
 end
+
+StrictConfig.json_schema
+# =>
+# {
+#   "properties": { "id": { "type": "integer" } },
+#   "additionalProperties": {
+#     "type": "integer",
+#     "minimum": 0,
+#     "maximum": 100
+#   }
+# }
 ```
 
-### Complex Object Hierarchies
+**Nested models as additional properties:**
 
 ```ruby
-class Address
+class Person
   include EasyTalk::Model
 
   define_schema do
-    property :street, String
-    property :city, String
-    property :state, String
-    property :zip, String, pattern: '^[0-9]{5}(?:-[0-9]{4})?$'
+    property :name, String
+    additional_properties Address  # All additional properties must be Address objects
   end
 end
+```
+
+### Object-level constraints
 
-class Employee
+Apply schema-wide constraints to limit or validate object structure:
+
+```ruby
+class StrictObject
   include EasyTalk::Model
 
   define_schema do
-    title 'Employee'
-    description 'Company employee'
-    property :name, String, title: 'Full Name'
-    property :gender, String, enum: %w[male female other]
-    property :department, T.nilable(String)
-    property :hire_date, Date
-    property :active, T::Boolean, default: true
-    property :addresses, T.nilable(T::Array[Address])
+    property :required1, String
+    property :required2, String
+    property :optional1, String, optional: true
+    property :optional2, String, optional: true
+
+    # Require at least 2 properties
+    min_properties 2
+    # Allow at most 3 properties
+    max_properties 3
   end
 end
 
-class Company
+obj = StrictObject.new(required1: 'a')
+obj.valid?  # => false (only 1 property, needs at least 2)
+```
+
+**Pattern properties:**
+
+```ruby
+class DynamicConfig
   include EasyTalk::Model
 
   define_schema do
-    title 'Company'
     property :name, String
-    property :employees, T::Array[Employee], title: 'Company Employees', description: 'A list of company employees'
+
+    # Properties matching /^env_/ must be strings
+    pattern_properties(
+      '^env_' => { type: 'string' }
+    )
   end
 end
 ```
 
-### API Integration
+**Dependent required:**
 
 ```ruby
-# app/controllers/api/users_controller.rb
-class Api::UsersController < ApplicationController
-  def create
-    schema = User.json_schema
-    
-    # Validate incoming request against the schema
-    validation_result = JSONSchemer.schema(schema).valid?(params.to_json)
-    
-    if validation_result
-      user = User.new(user_params)
-      if user.save
-        render json: user, status: :created
-      else
-        render json: { errors: user.errors }, status: :unprocessable_entity
-      end
-    else
-      render json: { errors: "Invalid request" }, status: :bad_request
-    end
-  end
-  
-  private
-  
-  def user_params
-    params.require(:user).permit(:name, :email, :password)
-  end
-end
-```
-
-## Troubleshooting
-
-### Common Errors
-
-#### "Invalid property name"
-Property names must start with a letter or underscore and can only contain letters, numbers, and underscores:
-
-```ruby
-# Invalid
-property "1name", String  # Starts with a number
-property "name!", String  # Contains a special character
-
-# Valid
-property :name, String
-property :user_name, String
-```
-
-#### "Property type is missing"
-You must specify a type for each property:
-
-```ruby
-# Invalid
-property :name
-
-# Valid
-property :name, String
-```
-
-#### "Unknown option"
-You specified an option that is not valid for the property type:
-
-```ruby
-# Invalid (min_length is for strings, not integers)
-property :age, Integer, min_length: 2
-
-# Valid
-property :age, Integer, minimum: 18
-```
-
-### Schema Validation Issues
-If you're having issues with validation:
-
-1. Make sure you've defined ActiveModel validations for your model
-2. Check for mismatches between schema constraints and validations
-3. Verify that required properties are present
-
-### Type Errors
-Type errors usually occur when there's a mismatch between a property type and its constraints:
-
-```ruby
-# Error: enum values must be strings for a string property
-property :status, String, enum: [1, 2, 3]
-
-# Correct
-property :status, String, enum: ["active", "inactive", "pending"]
-```
-
-### Best Practices
-
-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
-
-One of the most important distinctions when defining schemas is understanding the difference between **nullable** properties and **optional** properties. This guide explains these concepts and how to use them effectively in EasyTalk.
-
-## Key Concepts
-
-| Concept | Description | JSON Schema Effect | EasyTalk Syntax |
-|---------|-------------|-------------------|-----------------|
-| **Nullable** | Property can have a `null` value | Adds `"null"` to the type array | `T.nilable(Type)` |
-| **Optional** | Property doesn't have to exist | Omits property from `"required"` array | `optional: true` constraint |
-
-## Nullable Properties
-
-A **nullable** property can contain a `null` value, but the property itself must still be present in the object:
-
-```ruby
-property :age, T.nilable(Integer)
-```
-
-This produces the following JSON Schema:
-
-```json
-{
-  "properties": {
-    "age": { "type": ["integer", "null"] }
-  },
-  "required": ["age"]
-}
-```
-
-In this case, the following data would be valid:
-- `{ "age": 25 }`
-- `{ "age": null }`
-
-But this would be invalid:
-- `{ }` (missing the age property entirely)
-
-## Optional Properties
-
-An **optional** property doesn't have to be present in the object at all:
-
-```ruby
-property :nickname, String, optional: true
-```
-
-This produces:
-
-```json
-{
-  "properties": {
-    "nickname": { "type": "string" }
-  }
-  // Note: "nickname" is not in the "required" array
-}
-```
-
-In this case, the following data would be valid:
-- `{ "nickname": "Joe" }`
-- `{ }` (omitting nickname entirely)
-
-But this would be invalid:
-- `{ "nickname": null }` (null is not allowed because the property isn't nullable)
-
-## Nullable AND Optional Properties
-
-For properties that should be both nullable and optional (can be omitted or null), you need to combine both approaches:
-
-```ruby
-property :bio, T.nilable(String), optional: true
-```
-
-This produces:
-
-```json
-{
-  "properties": {
-    "bio": { "type": ["string", "null"] }
-  }
-  // Note: "bio" is not in the "required" array
-}
-```
-
-For convenience, EasyTalk also provides a helper method:
-
-```ruby
-nullable_optional_property :bio, String
-```
-
-Which is equivalent to the above.
-
-## Configuration Options
-
-By default, nullable properties are still required. You can change this global behavior:
-
-```ruby
-EasyTalk.configure do |config|
-  config.nilable_is_optional = true # Makes all T.nilable properties also optional
-end
-```
-
-With this configuration, any property defined with `T.nilable(Type)` will be treated as both nullable and optional.
-
-## Practical Examples
-
-### User Profile Schema
-
-```ruby
-class UserProfile
-  include EasyTalk::Model
-  
-  define_schema do
-    # Required properties (must exist, cannot be null)
-    property :id, String
-    property :name, String
-    
-    # Required but nullable (must exist, can be null)
-    property :age, T.nilable(Integer)
-    
-    # Optional but not nullable (can be omitted, cannot be null if present)
-    property :email, String, optional: true
-    
-    # Optional and nullable (can be omitted, can be null if present)
-    nullable_optional_property :bio, String
-  end
-end
-```
-
-This creates clear expectations for data validation:
-- `id` and `name` must be present and cannot be null
-- `age` must be present but can be null
-- `email` doesn't have to be present, but if it is, it cannot be null
-- `bio` doesn't have to be present, and if it is, it can be null
-
-## Common Gotchas
-
-### Misconception: Nullable Implies Optional
-
-A common mistake is assuming that `T.nilable(Type)` makes a property optional. By default, it only allows the property to have a null value - the property itself is still required to exist in the object.
-
-### Misconception: Optional Properties Accept Null
-
-An optional property (defined with `optional: true`) can be omitted entirely, but if it is present, it must conform to its type constraint. If you want to allow null values, you must also make it nullable with `T.nilable(Type)`.
-
-## Migration from Earlier Versions
-
-If you're upgrading from EasyTalk version 1.0.1 or earlier, be aware that the handling of nullable vs optional properties has been improved for clarity.
-
-To maintain backward compatibility with your existing code, you can use:
-
-```ruby
-EasyTalk.configure do |config|
-  config.nilable_is_optional = true # Makes T.nilable properties behave as they did before
-end
-```
-
-We recommend updating your schema definitions to explicitly declare which properties are optional using the `optional: true` constraint, as this makes your intent clearer.
-
-## Best Practices
-
-1. **Be explicit about intent**: Always clarify whether properties should be nullable, optional, or both
-2. **Use the helper method**: For properties that are both nullable and optional, use `nullable_optional_property`
-3. **Document expectations**: Use comments to clarify validation requirements for complex schemas
-4. **Consider validation implications**: Remember that ActiveModel validations operate independently of the schema definition
-
-## JSON Schema Comparison
-
-| EasyTalk Definition | Required | Nullable | JSON Schema Equivalent |
-|--------------------|----------|----------|------------------------|
-| `property :p, String` | Yes | No | `{ "properties": { "p": { "type": "string" } }, "required": ["p"] }` |
-| `property :p, T.nilable(String)` | Yes | Yes | `{ "properties": { "p": { "type": ["string", "null"] } }, "required": ["p"] }` |
-| `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.default_additional_properties = false
-  # ... 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
-- **ActiveModel Integration**: Fully backward compatible
-
-## Development and Contributing
-
-### Setting Up the Development Environment
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that lets you experiment.
-
-To install this gem onto your local machine, run:
-
-```bash
-bundle exec rake install
-```
-
-### Running Tests
-Run the test suite with:
-
-```bash
-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.
-
-## JSON Schema Version (`$schema` Keyword)
-
-The `$schema` keyword declares which JSON Schema dialect (draft version) a schema conforms to. EasyTalk supports configuring this at both the global and per-model level.
-
-### Why Use `$schema`?
-
-The `$schema` keyword:
-- Declares the JSON Schema version your schema is written against
-- Helps validators understand which specification to use
-- Enables tooling to provide appropriate validation and autocomplete
-- Documents the schema dialect for consumers of your API
-
-### Supported Draft Versions
-
-EasyTalk supports the following JSON Schema draft versions:
-
-| Symbol | JSON Schema Version | URI |
-|--------|---------------------|-----|
-| `:draft202012` | Draft 2020-12 (latest) | `https://json-schema.org/draft/2020-12/schema` |
-| `:draft201909` | Draft 2019-09 | `https://json-schema.org/draft/2019-09/schema` |
-| `:draft7` | Draft-07 | `http://json-schema.org/draft-07/schema#` |
-| `:draft6` | Draft-06 | `http://json-schema.org/draft-06/schema#` |
-| `:draft4` | Draft-04 | `http://json-schema.org/draft-04/schema#` |
-| `:none` | No `$schema` output (default) | N/A |
-
-### Global Configuration
-
-Configure the schema version globally to apply to all models:
-
-```ruby
-EasyTalk.configure do |config|
-  config.schema_version = :draft202012  # Use JSON Schema Draft 2020-12
-end
-```
-
-With this configuration, all models will include `$schema` in their output:
-
-```ruby
-class User
+class ShippingInfo
   include EasyTalk::Model
 
   define_schema do
     property :name, String
-  end
-end
-
-User.json_schema
-# => {
-#      "$schema" => "https://json-schema.org/draft/2020-12/schema",
-#      "type" => "object",
-#      "properties" => { "name" => { "type" => "string" } },
-#      "required" => ["name"],
-#      "additionalProperties" => false
-#    }
-```
-
-### Per-Model Configuration
-
-Override the global setting for individual models using the `schema_version` keyword in the schema definition:
-
-```ruby
-class LegacyModel
-  include EasyTalk::Model
+    property :credit_card, String, optional: true
+    property :billing_address, String, optional: true
 
-  define_schema do
-    schema_version :draft7  # Use Draft-07 for this specific model
-    property :name, String
+    # If credit_card is present, billing_address is required
+    dependent_required(
+      'credit_card' => ['billing_address']
+    )
   end
 end
-
-LegacyModel.json_schema
-# => {
-#      "$schema" => "http://json-schema.org/draft-07/schema#",
-#      "type" => "object",
-#      ...
-#    }
 ```
 
-### Disabling `$schema` for Specific Models
+### Custom type builders
 
-If you have a global schema version configured but want to exclude `$schema` from a specific model, use `:none`:
+Register custom types with their own schema builders:
 
 ```ruby
 EasyTalk.configure do |config|
-  config.schema_version = :draft202012  # Global default
-end
-
-class InternalModel
-  include EasyTalk::Model
-
-  define_schema do
-    schema_version :none  # No $schema for this model
-    property :data, String
-  end
+  config.register_type(Money, MoneySchemaBuilder)
 end
 
-InternalModel.json_schema
-# => {
-#      "type" => "object",
-#      "properties" => { "data" => { "type" => "string" } },
-#      ...
-#    }
-# Note: No "$schema" key present
+# Or directly:
+EasyTalk::Builders::Registry.register(Money, MoneySchemaBuilder)
 ```
 
-### Custom Schema URIs
-
-You can also specify a custom URI if you're using a custom meta-schema or a different schema registry:
-
-```ruby
-class CustomModel
-  include EasyTalk::Model
-
-  define_schema do
-    schema_version 'https://my-company.com/schemas/v1/meta-schema.json'
-    property :id, String
-  end
-end
-```
-
-### Nested Models
-
-The `$schema` keyword only appears at the root level of the schema. When you have nested EasyTalk models, only the top-level model's `json_schema` output will include `$schema`:
-
-```ruby
-EasyTalk.configure do |config|
-  config.schema_version = :draft202012
-end
-
-class Address
-  include EasyTalk::Model
-  define_schema do
-    property :city, String
-  end
-end
-
-class User
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :address, Address
-  end
-end
-
-User.json_schema
-# => {
-#      "$schema" => "https://json-schema.org/draft/2020-12/schema",  # Only at root
-#      "type" => "object",
-#      "properties" => {
-#        "name" => { "type" => "string" },
-#        "address" => {
-#          "type" => "object",  # No $schema here
-#          "properties" => { "city" => { "type" => "string" } },
-#          ...
-#        }
-#      },
-#      ...
-#    }
-```
-
-### Default Behavior
-
-By default, `schema_version` is set to `:none`, meaning no `$schema` keyword is included in the generated schemas. This maintains backward compatibility with previous versions of EasyTalk.
-
-### Best Practices
-
-1. **Choose a version appropriate for your validators**: If you're using a specific JSON Schema validator, check which drafts it supports.
-
-2. **Use Draft 2020-12 for new projects**: It's the latest stable version with the most features.
-
-3. **Be consistent**: Use global configuration for consistency across your application, and only override per-model when necessary.
-
-4. **Consider your consumers**: If your schemas are consumed by external systems, ensure they support the draft version you're using.
-
-## Schema Identifier (`$id` Keyword)
-
-The `$id` keyword provides a unique identifier for your JSON Schema document. EasyTalk supports configuring this at both the global and per-model level.
-
-### Why Use `$id`?
-
-The `$id` keyword:
-- Establishes a unique URI identifier for the schema
-- Enables referencing schemas from other documents via `$ref`
-- Provides a base URI for resolving relative references within the schema
-- Documents the canonical location of the schema
-
-### Global Configuration
-
-Configure the schema ID globally to apply to all models:
-
-```ruby
-EasyTalk.configure do |config|
-  config.schema_id = 'https://example.com/schemas/base.json'
-end
-```
-
-With this configuration, all models will include `$id` in their output:
-
-```ruby
-class User
-  include EasyTalk::Model
-
-  define_schema do
-    property :name, String
-  end
-end
-
-User.json_schema
-# => {
-#      "$id" => "https://example.com/schemas/base.json",
-#      "type" => "object",
-#      "properties" => { "name" => { "type" => "string" } },
-#      "required" => ["name"],
-#      "additionalProperties" => false
-#    }
-```
-
-### Per-Model Configuration
-
-Override the global setting for individual models using the `schema_id` keyword in the schema definition:
-
-```ruby
-class User
-  include EasyTalk::Model
-
-  define_schema do
-    schema_id 'https://example.com/schemas/user.schema.json'
-    property :name, String
-    property :email, String
-  end
-end
-
-User.json_schema
-# => {
-#      "$id" => "https://example.com/schemas/user.schema.json",
-#      "type" => "object",
-#      ...
-#    }
-```
-
-### Disabling `$id` for Specific Models
-
-If you have a global schema ID configured but want to exclude `$id` from a specific model, use `:none`:
-
-```ruby
-EasyTalk.configure do |config|
-  config.schema_id = 'https://example.com/schemas/default.json'
-end
-
-class InternalModel
-  include EasyTalk::Model
-
-  define_schema do
-    schema_id :none  # No $id for this model
-    property :data, String
-  end
-end
-
-InternalModel.json_schema
-# => {
-#      "type" => "object",
-#      "properties" => { "data" => { "type" => "string" } },
-#      ...
-#    }
-# Note: No "$id" key present
-```
-
-### Combining `$schema` and `$id`
-
-When both `$schema` and `$id` are configured, they appear in the standard order (`$schema` first, then `$id`):
-
-```ruby
-class Product
-  include EasyTalk::Model
-
-  define_schema do
-    schema_version :draft202012
-    schema_id 'https://example.com/schemas/product.schema.json'
-    property :name, String
-    property :price, Float
-  end
-end
-
-Product.json_schema
-# => {
-#      "$schema" => "https://json-schema.org/draft/2020-12/schema",
-#      "$id" => "https://example.com/schemas/product.schema.json",
-#      "type" => "object",
-#      ...
-#    }
-```
-
-### Nested Models
-
-The `$id` keyword only appears at the root level of the schema. When you have nested EasyTalk models, only the top-level model's `json_schema` output will include `$id`:
-
-```ruby
-EasyTalk.configure do |config|
-  config.schema_id = 'https://example.com/schemas/user.json'
-end
-
-class Address
-  include EasyTalk::Model
-  define_schema do
-    property :city, String
-  end
-end
-
-class User
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :address, Address
-  end
-end
-
-User.json_schema
-# => {
-#      "$id" => "https://example.com/schemas/user.json",  # Only at root
-#      "type" => "object",
-#      "properties" => {
-#        "name" => { "type" => "string" },
-#        "address" => {
-#          "type" => "object",  # No $id here
-#          "properties" => { "city" => { "type" => "string" } },
-#          ...
-#        }
-#      },
-#      ...
-#    }
-```
-
-### URI Formats
-
-The `$id` accepts various URI formats:
-
-```ruby
-# Absolute URI (recommended for published schemas)
-schema_id 'https://example.com/schemas/user.schema.json'
-
-# Relative URI
-schema_id 'user.schema.json'
-
-# URN format
-schema_id 'urn:example:user-schema'
-```
-
-### Default Behavior
-
-By default, `schema_id` is set to `nil`, meaning no `$id` keyword is included in the generated schemas. This maintains backward compatibility with previous versions of EasyTalk.
-
-### Best Practices
-
-1. **Use absolute URIs for published schemas**: This ensures global uniqueness and enables external references.
-
-2. **Follow a consistent naming convention**: For example, `https://yourdomain.com/schemas/{model-name}.schema.json`.
-
-3. **Keep IDs stable**: Once published, avoid changing schema IDs as external systems may reference them.
-
-4. **Combine with `$schema`**: When publishing schemas, include both `$schema` (for validation) and `$id` (for identification).
-
-## Schema References (`$ref` and `$defs`)
-
-The `$ref` keyword allows you to reference reusable schema definitions, reducing duplication when the same model is used in multiple places. EasyTalk supports automatic `$ref` generation for nested models.
-
-### Why Use `$ref`?
-
-The `$ref` keyword:
-- Reduces schema duplication when the same model appears multiple times
-- Produces cleaner, more organized schemas
-- Improves schema readability and maintainability
-- Aligns with JSON Schema best practices for reusable definitions
-
-### Default Behavior (Inline Schemas)
-
-By default, EasyTalk inlines nested model schemas directly:
-
-```ruby
-class Address
-  include EasyTalk::Model
-  define_schema do
-    property :street, String
-    property :city, String
-  end
-end
-
-class Person
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :address, Address
-  end
-end
-
-Person.json_schema
-# => {
-#      "type" => "object",
-#      "properties" => {
-#        "name" => { "type" => "string" },
-#        "address" => {
-#          "type" => "object",
-#          "properties" => {
-#            "street" => { "type" => "string" },
-#            "city" => { "type" => "string" }
-#          },
-#          ...
-#        }
-#      },
-#      ...
-#    }
-```
-
-### Enabling `$ref` References
-
-#### Global Configuration
-
-Enable `$ref` generation for all nested models:
-
-```ruby
-EasyTalk.configure do |config|
-  config.use_refs = true
-end
-```
-
-With this configuration, nested models are referenced via `$ref` and their definitions are placed in `$defs`:
-
-```ruby
-Person.json_schema
-# => {
-#      "type" => "object",
-#      "properties" => {
-#        "name" => { "type" => "string" },
-#        "address" => { "$ref" => "#/$defs/Address" }
-#      },
-#      "$defs" => {
-#        "Address" => {
-#          "type" => "object",
-#          "properties" => {
-#            "street" => { "type" => "string" },
-#            "city" => { "type" => "string" }
-#          },
-#          ...
-#        }
-#      },
-#      ...
-#    }
-```
-
-#### Per-Property Configuration
-
-You can also enable `$ref` for specific properties using the `ref: true` constraint:
-
-```ruby
-class Person
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :address, Address, ref: true  # Use $ref for this property
-  end
-end
-```
-
-Or disable `$ref` for specific properties when it's enabled globally:
-
-```ruby
-EasyTalk.configure do |config|
-  config.use_refs = true
-end
-
-class Person
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :address, Address, ref: false  # Inline this property despite global setting
-  end
-end
-```
-
-### Arrays of Models
-
-When using `$ref` with arrays of models, the `$ref` applies to the array items:
-
-```ruby
-EasyTalk.configure do |config|
-  config.use_refs = true
-end
-
-class Company
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :addresses, T::Array[Address]
-  end
-end
-
-Company.json_schema
-# => {
-#      "type" => "object",
-#      "properties" => {
-#        "name" => { "type" => "string" },
-#        "addresses" => {
-#          "type" => "array",
-#          "items" => { "$ref" => "#/$defs/Address" }
-#        }
-#      },
-#      "$defs" => {
-#        "Address" => { ... }
-#      },
-#      ...
-#    }
-```
-
-You can also use the per-property `ref` constraint with arrays:
-
-```ruby
-property :addresses, T::Array[Address], ref: true
-```
-
-### Nilable Models with `$ref`
-
-When using `$ref` with nilable model types, EasyTalk uses `anyOf` to combine the reference with the null type:
-
-```ruby
-EasyTalk.configure do |config|
-  config.use_refs = true
-end
-
-class Person
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :address, T.nilable(Address)
-  end
-end
-
-Person.json_schema
-# => {
-#      "type" => "object",
-#      "properties" => {
-#        "name" => { "type" => "string" },
-#        "address" => {
-#          "anyOf" => [
-#            { "$ref" => "#/$defs/Address" },
-#            { "type" => "null" }
-#          ]
-#        }
-#      },
-#      "$defs" => {
-#        "Address" => { ... }
-#      },
-#      ...
-#    }
-```
-
-### Multiple References to the Same Model
-
-When the same model is used multiple times, it only appears once in `$defs`:
-
-```ruby
-class Person
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :home_address, Address, ref: true
-    property :work_address, Address, ref: true
-    property :shipping_addresses, T::Array[Address], ref: true
-  end
-end
-
-Person.json_schema
-# => {
-#      "type" => "object",
-#      "properties" => {
-#        "name" => { "type" => "string" },
-#        "home_address" => { "$ref" => "#/$defs/Address" },
-#        "work_address" => { "$ref" => "#/$defs/Address" },
-#        "shipping_addresses" => {
-#          "type" => "array",
-#          "items" => { "$ref" => "#/$defs/Address" }
-#        }
-#      },
-#      "$defs" => {
-#        "Address" => { ... }  # Only defined once
-#      },
-#      ...
-#    }
-```
-
-### Combining `$ref` with Other Constraints
-
-You can add additional constraints alongside `$ref`:
-
-```ruby
-class Person
-  include EasyTalk::Model
-  define_schema do
-    property :address, Address, ref: true, description: "Primary address", title: "Main Address"
-  end
-end
-
-Person.json_schema["properties"]["address"]
-# => {
-#      "$ref" => "#/$defs/Address",
-#      "description" => "Primary address",
-#      "title" => "Main Address"
-#    }
-```
-
-### Interaction with `compose`
-
-When using `compose` with `T::AllOf`, `T::AnyOf`, or `T::OneOf`, the composed models are also placed in `$defs`:
-
-```ruby
-class Employee
-  include EasyTalk::Model
-  define_schema do
-    compose T::AllOf[Person, EmployeeDetails]
-    property :badge_number, String
-  end
-end
-```
-
-If you also have properties using `$ref`, both the composed models and property models will appear in `$defs`.
-
-### Best Practices
-
-1. **Use global configuration for consistency**: If you prefer `$ref` style, enable it globally rather than per-property.
-
-2. **Consider schema consumers**: Some JSON Schema validators and tools work better with inlined schemas, while others prefer `$ref`. Choose based on your use case.
-
-3. **Use `$ref` for frequently reused models**: If a model appears in many places, `$ref` reduces schema size and improves maintainability.
+See the [Custom Type Builders documentation](https://rubydoc.info/gems/easy_talk/EasyTalk/Builders/Registry) for details on creating builders.
 
-4. **Keep inline for simple, single-use models**: For models used only once, inlining may be more readable.
+---
 
-### Default Behavior
+## Known limitations
 
-By default, `use_refs` is set to `false`, meaning nested models are inlined. This maintains backward compatibility with previous versions of EasyTalk.
+EasyTalk aims to produce broadly compatible JSON Schema, but:
+- Some draft-specific keywords/features may require manual schema tweaks
+- Custom formats are limited (extend via custom builders when needed)
+- Extremely complex composition can outgrow “auto validations” and may need manual validations or external schema validators
 
-## JSON Schema Compatibility
+---
 
-### Supported Versions
-EasyTalk supports generating schemas compatible with JSON Schema Draft-04 through Draft 2020-12. Use the `schema_version` configuration option to declare which version your schemas conform to (see [JSON Schema Version](#json-schema-version-schema-keyword) above).
+## Contributing
 
-While EasyTalk allows you to specify any draft version via the `$schema` keyword, the generated schema structure is generally compatible across versions. Some newer draft features may require manual adjustment.
+- Run `bin/setup`
+- Run specs: `bundle exec rake spec`
+- Run lint: `bundle exec rubocop`
 
-### Specification Compliance
-To learn about current capabilities, see the [spec/easy_talk/examples](https://github.com/sergiobayona/easy_talk/tree/main/spec/easy_talk/examples) folder. The examples illustrate how EasyTalk generates JSON Schema in different scenarios.
+Bug reports and PRs welcome.
 
-### Known Limitations
-- Limited support for custom formats
-- Some draft-specific keywords may not be supported
-- Complex composition scenarios may require manual adjustment
+---
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT