easy_talk 3.2.0 → 3.3.1

data/README.md

@@ -2,591 +2,375 @@
 
 [![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)
 
-## Table of Contents
+Ruby library for defining **structured data contracts** that generate **JSON Schema** *and* (optionally) **runtime validations** from the same definition.
 
-- [Introduction](#introduction)
-  - [What is EasyTalk?](#what-is-easytalk)
-  - [Key Features](#key-features)
-  - [Use Cases](#use-cases)
-  - [Inspiration](#inspiration)
-- [Installation](#installation)
-  - [Requirements](#requirements)
-  - [Version 2.0.0 Breaking Changes](#version-200-breaking-changes)
-  - [Installation Steps](#installation-steps)
-  - [Verification](#verification)
-- [Quick Start](#quick-start)
-  - [Minimal Example](#minimal-example)
-  - [Generated JSON Schema](#generated-json-schema)
-  - [Basic Usage](#basic-usage)
-- [Core Concepts](#core-concepts)
-  - [Schema Definition](#schema-definition)
-  - [Property Types](#property-types)
-    - [Ruby Types](#ruby-types)
-    - [Sorbet-Style Types](#sorbet-style-types)
-    - [Custom Types](#custom-types)
-  - [Property Constraints](#property-constraints)
-  - [Required vs Optional Properties](#required-vs-optional-properties)
-  - [Automatic Validation Generation](#automatic-validation-generation)
-  - [Manual Validation Overrides](#manual-validation-overrides)
-- [Defining Schemas](#defining-schemas)
-  - [Basic Schema Structure](#basic-schema-structure)
-  - [Property Definitions](#property-definitions)
-  - [Arrays and Collections](#arrays-and-collections)
-  - [Constraints and Automatic Validations](#constraints-and-automatic-validations)
-  - [Supported Constraint-to-Validation Mappings](#supported-constraint-to-validation-mappings)
-  - [Additional Properties](#additional-properties)
-  - [Property Naming](#property-naming)
-- [Schema Composition](#schema-composition)
-  - [Using T::AnyOf](#using-tanyof)
-  - [Using T::OneOf](#using-toneof)
-  - [Using T::AllOf](#using-tallof)
-  - [Array Composition](#array-composition)
-  - [Complex Compositions](#complex-compositions)
-  - [Reusing Models](#reusing-models)
-- [ActiveModel Integration](#activemodel-integration)
-  - [Enhanced Validation System](#enhanced-validation-system)
-  - [Error Handling](#error-handling)
-  - [Standardized Error Formatting](#standardized-error-formatting)
-    - [Available Formats](#available-formats)
-    - [Instance Methods](#instance-methods)
-    - [Direct API Usage](#direct-api-usage)
-    - [Configuration](#configuration)
-  - [Model Attributes](#model-attributes)
-- [Advanced Features](#advanced-features)
-  - [Schema-Only Mode (EasyTalk::Schema)](#schema-only-mode-easytalkschema)
-    - [Key Differences from EasyTalk::Model](#key-differences-from-easytalkmodel)
-    - [When to Use Each](#when-to-use-each)
-  - [LLM Function Generation](#llm-function-generation)
-  - [Schema Transformation](#schema-transformation)
-  - [Type Checking and Validation](#type-checking-and-validation)
-  - [Custom Type Builders](#custom-type-builders)
-    - [Registering Custom Types](#registering-custom-types)
-    - [Creating a Custom Builder](#creating-a-custom-builder)
-    - [Collection Type Builders](#collection-type-builders)
-    - [Overriding Built-in Types](#overriding-built-in-types)
-    - [Registry API](#registry-api)
-  - [Type Introspection](#type-introspection)
-- [Configuration](#configuration-1)
-  - [Global Settings](#global-settings)
-  - [Automatic Validation Configuration](#automatic-validation-configuration)
-  - [Per-Model Configuration](#per-model-configuration)
-  - [Validation Adapters](#validation-adapters)
-    - [Built-in Adapters](#built-in-adapters)
-    - [Global Adapter Configuration](#global-adapter-configuration)
-    - [Per-Model Validation Control](#per-model-validation-control)
-    - [Per-Property Validation Control](#per-property-validation-control)
-    - [Custom Validation Adapters](#custom-validation-adapters)
-- [Examples](#examples)
-  - [User Registration (with Auto-Validations)](#user-registration-with-auto-validations)
-  - [Payment Processing](#payment-processing)
-  - [Complex Object Hierarchies](#complex-object-hierarchies)
-  - [API Integration](#api-integration)
-- [Troubleshooting](#troubleshooting)
-  - [Common Errors](#common-errors)
-    - ["Invalid property name"](#invalid-property-name)
-    - ["Property type is missing"](#property-type-is-missing)
-    - ["Unknown option"](#unknown-option)
-  - [Schema Validation Issues](#schema-validation-issues)
-  - [Type Errors](#type-errors)
-  - [Best Practices](#best-practices)
-- [Nullable vs Optional Properties in EasyTalk](#nullable-vs-optional-properties-in-easytalk)
-  - [Key Concepts](#key-concepts)
-  - [Nullable Properties](#nullable-properties)
-  - [Optional Properties](#optional-properties)
-  - [Nullable AND Optional Properties](#nullable-and-optional-properties)
-  - [Configuration Options](#configuration-options)
-  - [Practical Examples](#practical-examples)
-    - [User Profile Schema](#user-profile-schema)
-  - [Common Gotchas](#common-gotchas)
-    - [Misconception: Nullable Implies Optional](#misconception-nullable-implies-optional)
-    - [Misconception: Optional Properties Accept Null](#misconception-optional-properties-accept-null)
-  - [Migration from Earlier Versions](#migration-from-earlier-versions)
-  - [Best Practices](#best-practices-1)
-  - [JSON Schema Comparison](#json-schema-comparison)
-- [Migration Guide from v1.x to v2.0](#migration-guide-from-v1x-to-v20)
-  - [Breaking Changes Summary](#breaking-changes-summary)
-  - [Migration Steps](#migration-steps)
-    - [1. Replace Hash-based Nested Schemas](#1-replace-hash-based-nested-schemas)
-    - [2. Review Automatic Validations](#2-review-automatic-validations)
-    - [3. Configuration Updates](#3-configuration-updates)
-  - [Compatibility Notes](#compatibility-notes)
-- [Development and Contributing](#development-and-contributing)
-  - [Setting Up the Development Environment](#setting-up-the-development-environment)
-  - [Running Tests](#running-tests)
-  - [Code Quality](#code-quality)
-  - [Contributing Guidelines](#contributing-guidelines)
-- [JSON Schema Version (`$schema` Keyword)](#json-schema-version-schema-keyword)
-  - [Why Use `$schema`?](#why-use-schema)
-  - [Supported Draft Versions](#supported-draft-versions)
-  - [Global Configuration](#global-configuration)
-  - [Per-Model Configuration](#per-model-configuration-1)
-  - [Disabling `$schema` for Specific Models](#disabling-schema-for-specific-models)
-  - [Custom Schema URIs](#custom-schema-uris)
-  - [Nested Models](#nested-models)
-  - [Default Behavior](#default-behavior)
-  - [Best Practices](#best-practices-2)
-- [Schema Identifier (`$id` Keyword)](#schema-identifier-id-keyword)
-  - [Why Use `$id`?](#why-use-id)
-  - [Global Configuration](#global-configuration-1)
-  - [Per-Model Configuration](#per-model-configuration-2)
-  - [Disabling `$id` for Specific Models](#disabling-id-for-specific-models)
-  - [Combining `$schema` and `$id`](#combining-schema-and-id)
-  - [Nested Models](#nested-models-1)
-  - [URI Formats](#uri-formats)
-  - [Default Behavior](#default-behavior-1)
-  - [Best Practices](#best-practices-3)
-- [Schema References (`$ref` and `$defs`)](#schema-references-ref-and-defs)
-  - [Why Use `$ref`?](#why-use-ref)
-  - [Default Behavior (Inline Schemas)](#default-behavior-inline-schemas)
-  - [Enabling `$ref` References](#enabling-ref-references)
-    - [Global Configuration](#global-configuration-2)
-    - [Per-Property Configuration](#per-property-configuration)
-  - [Arrays of Models](#arrays-of-models)
-  - [Nilable Models with `$ref`](#nilable-models-with-ref)
-  - [Multiple References to the Same Model](#multiple-references-to-the-same-model)
-  - [Combining `$ref` with Other Constraints](#combining-ref-with-other-constraints)
-  - [Interaction with `compose`](#interaction-with-compose)
-  - [Best Practices](#best-practices-4)
-  - [Default Behavior](#default-behavior-2)
-- [JSON Schema Compatibility](#json-schema-compatibility)
-  - [Supported Versions](#supported-versions)
-  - [Specification Compliance](#specification-compliance)
-  - [Known Limitations](#known-limitations)
-- [API Reference](#api-reference)
-  - [Core Modules](#core-modules)
-  - [Builders](#builders)
-  - [Configuration & Utilities](#configuration--utilities)
-- [License](#license)
+Think “Pydantic-style ergonomics” for Ruby, with first-class JSON Schema output.
 
-## Introduction
+---
 
-### What is EasyTalk?
-EasyTalk is a Ruby library for defining structured data models with automatic JSON Schema generation and flexible validation. Define your schema once and get both a JSON Schema document and runtime validations from a single source of truth.
+## Why EasyTalk?
 
-### Key Features
-* **Intuitive Schema Definition**: Define JSON Schema using Ruby classes with a clean, declarative DSL.
-* **Rich Type System**: Supports Ruby primitives plus Sorbet-style types (`T::Array[Type]`, `T.nilable(Type)`, `T::Boolean`) and composition types (`T::AnyOf`, `T::OneOf`, `T::AllOf`).
-* **Automatic Validations**: Schema constraints automatically generate ActiveModel validations, including nested model validation within arrays.
-* **API Error Formatting**: Format validation errors in multiple standards (flat, JSON Pointer, RFC 7807, JSON:API).
-* **LLM Function Support**: Generate JSON Schema for LLM function calling (OpenAI, Anthropic, etc.).
-* **Schema Composition**: Reference models within other models and use `$ref`/`$defs` for reusable definitions.
-* **Nested Model Instantiation**: Hash attributes automatically instantiate nested EasyTalk models, including within arrays.
-* **Flexible Configuration**: Global and per-model settings for validation behavior, naming strategies, and schema output.
-* **JSON Schema Versions**: Support for Draft-04 through Draft 2020-12 with configurable `$schema` and `$id` keywords.
+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.
 
-### Use Cases
-- API request/response validation
-- LLM function definitions
-- Object structure documentation
-- Data validation and transformation
-- Configuration schema definitions
+EasyTalk makes the schema definition the single source of truth, so you can:
 
-### Inspiration
-Inspired by Python's [Pydantic](https://docs.pydantic.dev/) library, EasyTalk brings similar functionality to the Ruby ecosystem, providing a Ruby-friendly approach to JSON Schema operations.
+- **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
 
-## Installation
+- **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
+  ```
 
-### Requirements
-- Ruby 3.2 or higher
+- **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
 
-### Version 2.0.0 Breaking Changes
+- **Get validations for free (when you want them)**  
+  With `auto_validations` enabled (default), schema constraints generate ActiveModel validations—**including nested models**, even inside arrays.
 
-⚠️ **IMPORTANT**: Version 2.0.0 includes breaking changes. Please review before upgrading:
+- **Make API errors consistent**  
+  Format validation errors as:
+  - flat lists
+  - JSON Pointer
+  - **RFC 7807** problem details
+  - **JSON:API** error objects
 
-- **Removed**: Block-style nested object definitions (using `Hash do ... end`)
-- **Migration**: Use class references instead of inline Hash definitions
+- **LLM tool/function schemas without a second schema layer**
+  Use the same contract to generate JSON Schema for function/tool calling. See [RubyLLM Integration](#rubyllm-integration).
 
-```ruby
-# ❌ No longer supported (v1.x style)
-define_schema do
-  property :address, Hash do
-    property :street, String
-    property :city, String
-  end
-end
+EasyTalk is for teams who want their data contracts to be **correct, reusable, and boring** (the good kind of boring).
 
-# ✅ New approach (v2.x style)
-class Address
-  include EasyTalk::Model
-  define_schema do
-    property :street, String
-    property :city, String
-  end
-end
+---
 
-class User
-  include EasyTalk::Model
-  define_schema do
-    property :address, Address  # Reference the class directly
-  end
-end
-```
+## Table of Contents
 
-### Installation Steps
-Add EasyTalk to your application's Gemfile:
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Property constraints](#property-constraints)
+- [Core concepts](#core-concepts)
+  - [Required vs optional vs nullable](#required-vs-optional-vs-nullable-dont-get-tricked)
+  - [Nested models](#nested-models-and-automatic-instantiation)
+  - [Tuple arrays](#tuple-arrays-fixed-position-types)
+  - [Composition (AnyOf / OneOf / AllOf)](#composition-anyof--oneof--allof)
+- [Validations](#validations)
+  - [Automatic validations](#automatic-validations-default)
+  - [Per-model validation control](#per-model-validation-control)
+  - [Per-property validation control](#per-property-validation-control)
+  - [Validation adapters](#validation-adapters)
+- [Error formatting](#error-formatting)
+- [Schema-only mode](#schema-only-mode)
+- [RubyLLM Integration](#rubyllm-integration)
+- [Configuration highlights](#configuration-highlights)
+- [Advanced topics](#advanced-topics)
+  - [JSON Schema drafts, `$id`, and `$ref`](#json-schema-drafts-id-and-ref)
+  - [Additional properties with types](#additional-properties-with-types)
+  - [Object-level constraints](#object-level-constraints)
+  - [Custom type builders](#custom-type-builders)
+- [Known limitations](#known-limitations)
+- [Contributing](#contributing)
+- [License](#license)
 
-```ruby
-gem 'easy_talk'
-```
+---
 
-Or install it directly:
+## Installation
 
-```bash
-$ gem install easy_talk
-```
+### 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
+---
+
+## Quick start
 
-### Minimal Example
-Here's a basic example to get you started with EasyTalk:
+<table>
+<tr>
+<th>EasyTalk Model</th>
+<th>Generated JSON Schema</th>
+</tr>
+<tr>
+<td>
 
 ```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
 ```
 
-### Generated JSON Schema
-Calling `User.json_schema` will generate:
+</td>
+<td>
 
-```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:
+</td>
+</tr>
+</table>
 
 ```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"]
+User.json_schema   # => Ruby Hash (JSON Schema)
+user = User.new(name: "A")  # invalid: min_length is 2
+user.valid?        # => false
+user.errors        # => ActiveModel::Errors
 ```
 
-## Core Concepts
+---
 
-### 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.
+## Property constraints
 
-```ruby
-class MyModel
-  include EasyTalk::Model
+| 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"` |
 
-  define_schema do
-    title "My Model"
-    description "Description of my model"
-    property :some_property, String
-    property :another_property, Integer
-  end
-end
-```
+**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
 
-### Property Types
+When `auto_validations` is enabled (default), these constraints automatically generate corresponding ActiveModel validations.
 
-#### Ruby Types
-EasyTalk supports standard Ruby types directly:
+---
 
-- `String`: String values
-- `Integer`: Integer values
-- `Float`: Floating-point numbers
-- `Date`: Date values
-- `DateTime`: Date and time values
+## Core concepts
 
-#### Sorbet-Style Types
-For complex types, EasyTalk uses Sorbet-style type notation:
+### Required vs optional vs nullable (don't get tricked)
 
-- `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
+JSON Schema distinguishes:
+- **Optional**: property may be omitted (not in `required`)
+- **Nullable**: property may be `null` (type includes `"null"`)
 
-#### Custom Types
-EasyTalk supports special composition types:
+EasyTalk mirrors that precisely:
 
-- `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
+```ruby
+class Profile
+  include EasyTalk::Model
 
-### Property Constraints
-Property constraints depend on the type of property. Some common constraints include:
+  define_schema do
+    # required, not nullable
+    property :name, String
 
-- `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
+    # required, nullable (must exist, may be null)
+    property :age, T.nilable(Integer)
 
-### 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`:
+    # optional, not nullable (may be omitted, but cannot be null if present)
+    property :nickname, String, optional: true
 
-```ruby
-define_schema do
-  property :name, String
-  property :middle_name, String, optional: true
+    # optional + nullable (may be omitted OR null)
+    property :bio, T.nilable(String), optional: true
+    # or, equivalently:
+    nullable_optional_property :website, String
+  end
 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:
+By default, `T.nilable(Type)` makes a field **nullable but still required**.  
+If you want “nilable implies optional” behavior globally:
 
 ```ruby
-class User
-  include EasyTalk::Model
-  
-  define_schema do
-    property :name, String, min_length: 2, max_length: 50
-    property :email, String, format: "email"
-    property :age, Integer, minimum: 18, maximum: 120
-    property :status, String, enum: ["active", "inactive", "pending"]
-  end
-  # Validations are automatically generated:
-  # validates :name, presence: true, length: { minimum: 2, maximum: 50 }
-  # validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
-  # validates :age, presence: true, numericality: { greater_than_or_equal_to: 18, less_than_or_equal_to: 120 }
-  # validates :status, presence: true, inclusion: { in: ["active", "inactive", "pending"] }
+EasyTalk.configure do |config|
+  config.nilable_is_optional = true
 end
-
-user = User.new(name: "Jo", email: "invalid-email", age: 17)
-user.valid? # => false
-user.errors.full_messages 
-# => ["Name is too short (minimum is 2 characters)", 
-#     "Email is invalid", 
-#     "Age must be greater than or equal to 18"]
 ```
 
-### Manual Validation Overrides
-You can still add manual validations alongside automatic ones:
+---
+
+### Nested models (and automatic instantiation)
+
+Define nested objects as separate classes, then reference them:
 
 ```ruby
-class User
+class Address
   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 :street, String
+    property :city, String
   end
 end
-```
-
-## Defining Schemas
 
-### Basic Schema Structure
-A schema definition consists of a class that includes `EasyTalk::Model` and a `define_schema` block:
-
-```ruby
-class Person
+class User
   include EasyTalk::Model
 
   define_schema do
-    title "Person"
     property :name, String
-    property :age, Integer
+    property :address, Address
   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"
-```
 
-### Arrays and Collections
-Arrays can be defined using the `T::Array` type:
+user = User.new(
+  name: "John",
+  address: { street: "123 Main St", city: "Boston" } # Hash becomes Address automatically
+)
 
-```ruby
-property :tags, T::Array[String], min_items: 1, unique_items: true
-property :scores, T::Array[Integer], description: "List of scores"
+user.address.class  # => Address
 ```
 
-You can also define arrays of complex types:
+Nested models inside arrays work too:
 
 ```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 Order
+  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
+    property :line_items, T::Array[Address], min_items: 1
+  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:
+### Tuple arrays (fixed-position types)
 
-```ruby
-define_schema do
-  property :name, String
-  additional_properties true
-end
-```
+Use `T::Tuple` for arrays where each position has a specific type (e.g., coordinates, CSV rows, database records):
 
-With `additional_properties true`, you can add arbitrary properties to your model instances:
+<table>
+<tr>
+<th>EasyTalk Model</th>
+<th>Generated JSON Schema</th>
+</tr>
+<tr>
+<td>
 
 ```ruby
-company = Company.new
-company.name = "Acme Corp"        # Defined property
-company.location = "New York"     # Additional property
-company.employee_count = 100      # Additional property
-```
-
-### Property Naming
-You can configure the naming strategy for properties globally or per schema:
+class GeoLocation
+  include EasyTalk::Model
 
-```ruby
-EasyTalk.configure do |config|
-  config.property_naming_strategy = :snake_case  # Options: :identity, :snake_case, :camel_case, :pascal_case
+  define_schema do
+    property :name, String
+    # Fixed: [latitude, longitude]
+    property :coordinates, T::Tuple[Float, Float]
+  end
 end
 
-define_schema do
-  property_naming_strategy :camel_case  # Overrides global setting for this schema
-  property :name, String
-end
+location = GeoLocation.new(
+  name: 'Office',
+  coordinates: [40.7128, -74.0060]
+)
 ```
 
-This affects how property names are represented in the generated JSON Schema. 
-Additionally, names can be overridden per property:
+</td>
+<td>
 
-```ruby
-property :first_name, String, as: "firstName"  # Overrides global naming strategy
+```json
+{
+  "properties": {
+    "coordinates": {
+      "type": "array",
+      "items": [
+        { "type": "number" },
+        { "type": "number" }
+      ]
+    }
+  }
+}
 ```
 
-## Schema Composition
+</td>
+</tr>
+</table>
 
-### Using T::AnyOf
-The `T::AnyOf` type allows a property to match any of the specified schemas:
+**Mixed-type tuples:**
 
 ```ruby
-class Payment
+class DataRow
   include EasyTalk::Model
 
   define_schema do
-    property :details, T::AnyOf[CreditCard, Paypal, BankTransfer]
+    # Fixed: [name, age, active]
+    property :row, T::Tuple[String, Integer, T::Boolean]
   end
 end
 ```
 
-### Using T::OneOf
-The `T::OneOf` type requires a property to match exactly one of the specified schemas:
+**Controlling extra items:**
 
 ```ruby
-class Contact
-  include EasyTalk::Model
+define_schema do
+  # Reject extra items (strict tuple)
+  property :rgb, T::Tuple[Integer, Integer, Integer], additional_items: false
 
-  define_schema do
-    property :contact, T::OneOf[PhoneContact, EmailContact]
-  end
+  # 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
 ```
 
-### Using T::AllOf
-The `T::AllOf` type requires a property to match all of the specified schemas:
+**Tuple validation:**
 
 ```ruby
-class VehicleRegistration
-  include EasyTalk::Model
-  
-  define_schema do
-    compose T::AllOf[VehicleIdentification, OwnerInfo, RegistrationDetails]
-  end
-end
+model = GeoLocation.new(coordinates: [40.7, "invalid"])
+model.valid?  # => false
+model.errors[:coordinates]
+# => ["item at index 1 must be a Float"]
 ```
 
-### Array Composition
-Composition types can be combined with arrays to define collections where each item must match one of several schemas:
+---
+
+### Composition (AnyOf / OneOf / AllOf)
 
 ```ruby
 class ProductA
@@ -601,1814 +385,522 @@ class ProductB
   include EasyTalk::Model
   define_schema do
     property :sku, String
-    property :digital_url, String
+    property :color, String
   end
 end
 
-class Order
+class Cart
   include EasyTalk::Model
 
   define_schema do
-    property :order_id, String
-    # Each item in the array must match exactly one of the product schemas
-    property :items, T::Array[T::OneOf[ProductA, ProductB]]
+    property :items, T::Array[T::AnyOf[ProductA, ProductB]]
   end
 end
 ```
 
-This generates a JSON Schema where the `items` array validates each element against `oneOf`:
+---
 
-```json
-{
-  "properties": {
-    "items": {
-      "type": "array",
-      "items": {
-        "oneOf": [
-          { "type": "object", "properties": { "sku": {...}, "weight": {...} }, ... },
-          { "type": "object", "properties": { "sku": {...}, "digital_url": {...} }, ... }
-        ]
-      }
-    }
-  }
-}
-```
+## Validations
 
-You can use any composition type with arrays:
-- `T::Array[T::OneOf[A, B]]` - each item matches exactly one schema
-- `T::Array[T::AnyOf[A, B]]` - each item matches one or more schemas
-- `T::Array[T::AllOf[A, B]]` - each item matches all schemas
+### Automatic validations (default)
 
-### Complex Compositions
-You can combine composition types to create complex schemas:
+EasyTalk can generate ActiveModel validations from constraints:
 
 ```ruby
-class ComplexObject
-  include EasyTalk::Model
+EasyTalk.configure do |config|
+  config.auto_validations = true
+end
+```
 
-  define_schema do
-    property :basic_info, BaseInfo
-    property :specific_details, T::OneOf[DetailTypeA, DetailTypeB]
-    property :metadata, T::AnyOf[AdminMetadata, UserMetadata, nil]
-  end
+Disable globally:
+
+```ruby
+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
 ```
 
-### Standardized Error Formatting
-
-EasyTalk provides multiple output formats for validation errors, making it easy to build consistent API responses.
+---
 
-#### Available Formats
+## Error formatting
 
-| Format | Description | Use Case |
-|--------|-------------|----------|
-| `:flat` | Simple array of field/message/code objects | General purpose APIs |
-| `:json_pointer` | Array with JSON Pointer (RFC 6901) paths | JSON Schema validation |
-| `:rfc7807` | RFC 7807 Problem Details format | Standards-compliant APIs |
-| `:jsonapi` | JSON:API specification error format | JSON:API implementations |
-
-#### Instance Methods
-
-Every EasyTalk model includes convenient methods for error formatting:
+Instance helpers:
 
 ```ruby
-user = User.new(name: "", email: "invalid")
-user.valid?
-
-# Use default format (configurable globally)
-user.validation_errors
-# => [{"field" => "name", "message" => "can't be blank", "code" => "blank"}, ...]
-
-# Flat format
 user.validation_errors_flat
-# => [{"field" => "name", "message" => "can't be blank", "code" => "blank"}]
-
-# JSON Pointer format
 user.validation_errors_json_pointer
-# => [{"pointer" => "/properties/name", "message" => "can't be blank", "code" => "blank"}]
-
-# RFC 7807 Problem Details
 user.validation_errors_rfc7807
-# => {
-#      "type" => "about:blank#validation-error",
-#      "title" => "Validation Failed",
-#      "status" => 422,
-#      "detail" => "The request contains invalid parameters",
-#      "errors" => [...]
-#    }
-
-# JSON:API format
 user.validation_errors_jsonapi
-# => {
-#      "errors" => [
-#        {"status" => "422", "source" => {"pointer" => "/data/attributes/name"}, ...}
-#      ]
-#    }
 ```
 
-#### Direct API Usage
-
-You can also format errors directly using the `ErrorFormatter` module:
+Format directly:
 
 ```ruby
 EasyTalk::ErrorFormatter.format(user.errors, format: :rfc7807, title: "User Validation Failed")
 ```
 
-#### Configuration
-
-Configure error formatting globally:
+Global defaults:
 
 ```ruby
 EasyTalk.configure do |config|
-  config.default_error_format = :rfc7807        # Default format for validation_errors
-  config.error_type_base_uri = 'https://api.example.com/errors'  # Base URI for RFC 7807
-  config.include_error_codes = true             # Include error codes in output
+  config.default_error_format = :rfc7807
+  config.error_type_base_uri = "https://api.example.com/errors"
+  config.include_error_codes = true
 end
 ```
 
-### Model Attributes
-EasyTalk models provide getters and setters for all defined properties:
+---
 
-```ruby
-user = User.new
-user.name = "John"
-user.age = 30
-puts user.name # => "John"
-```
+## Schema-only mode
 
-You can also initialize a model with a hash of attributes, including nested EasyTalk models:
+If you want schema generation and attribute accessors **without** ActiveModel validation:
 
 ```ruby
-user = User.new(name: "John", age: 30, height: 5.9)
+class ApiContract
+  include EasyTalk::Schema
 
-# NEW in v2.0.0: Automatic nested model instantiation
-class Address
-  include EasyTalk::Model
   define_schema do
-    property :street, String
-    property :city, String
+    title "API Contract"
+    property :name, String, min_length: 2
+    property :age, Integer, minimum: 0
   end
 end
 
-class User
-  include EasyTalk::Model
-  define_schema do
-    property :name, String
-    property :address, Address
-  end
-end
+ApiContract.json_schema
+contract = ApiContract.new(name: "Test", age: 25)
 
-# 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"
+# No validations available:
+# contract.valid?  # => NoMethodError
 ```
 
-## Advanced Features
+Use this for documentation, OpenAPI generation, or when validation happens elsewhere.
 
-### Schema-Only Mode (EasyTalk::Schema)
+---
 
-For scenarios where you need JSON Schema generation without ActiveModel validations, use `EasyTalk::Schema` instead of `EasyTalk::Model`. This is ideal for:
+## RubyLLM Integration
 
-- API documentation and OpenAPI spec generation
-- Schema-first design where validation happens elsewhere
-- High-performance scenarios where validation overhead is unwanted
-- Generating schemas for external systems
+EasyTalk integrates seamlessly with [RubyLLM](https://github.com/crmne/ruby_llm) for structured outputs and tool definitions.
+
+### Structured Outputs
+
+Use any EasyTalk model with RubyLLM's `with_schema` to get structured JSON responses:
 
 ```ruby
-class ApiContract
-  include EasyTalk::Schema  # Not EasyTalk::Model
+class Recipe
+  include EasyTalk::Model
 
   define_schema do
-    title 'API Contract'
-    description 'A schema-only contract'
-    property :name, String, min_length: 2
-    property :age, Integer, minimum: 0
+    description "A cooking recipe"
+    property :name, String, description: "Name of the dish"
+    property :ingredients, T::Array[String], description: "List of ingredients"
+    property :prep_time_minutes, Integer, description: "Preparation time in minutes"
   end
 end
 
-# Schema generation works the same
-ApiContract.json_schema
-# => {"type" => "object", "title" => "API Contract", ...}
-
-# Instances can be created and accessed
-contract = ApiContract.new(name: 'Test', age: 25)
-contract.name  # => 'Test'
+chat = RubyLLM.chat.with_schema(Recipe)
+response = chat.ask("Give me a simple pasta recipe")
 
-# But no validation methods are available
-contract.valid?  # => NoMethodError
-contract.errors  # => NoMethodError
+# RubyLLM returns parsed JSON - instantiate with EasyTalk model
+recipe = Recipe.new(response.content)
+recipe.name           # => "Spaghetti Aglio e Olio"
+recipe.ingredients    # => ["spaghetti", "garlic", "olive oil", ...]
 ```
 
-#### Key Differences from EasyTalk::Model
+### Tools
 
-| Feature | EasyTalk::Model | EasyTalk::Schema |
-|---------|-----------------|------------------|
-| JSON Schema generation | Yes | Yes |
-| Property accessors | Yes | Yes |
-| Nested model instantiation | Yes | Yes |
-| ActiveModel::Validations | Yes | No |
-| `valid?` / `errors` | Yes | No |
-| Validation adapters | Yes | N/A |
-| Error formatting | Yes | No |
-
-#### When to Use Each
-
-- **Use `EasyTalk::Model`** when you need runtime validation of data (form inputs, API requests, user data)
-- **Use `EasyTalk::Schema`** when you only need the schema definition (documentation, code generation, external validation)
-
-### LLM Function Generation
-EasyTalk provides a helper method for generating OpenAI function specifications:
+Create LLM tools by inheriting from `RubyLLM::Tool` and including `EasyTalk::Model`:
 
 ```ruby
-class Weather
+class Weather < RubyLLM::Tool
   include EasyTalk::Model
-  
+
   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"
+    description 'Gets current weather for a location'
+    property :latitude, String, description: 'Latitude (e.g., 52.5200)'
+    property :longitude, String, description: 'Longitude (e.g., 13.4050)'
+  end
+
+  def execute(latitude:, longitude:)
+    # Fetch weather data from API...
+    { temperature: 22, conditions: "sunny" }
   end
 end
 
-function_spec = EasyTalk::Tools::FunctionBuilder.new(Weather)
+chat = RubyLLM.chat.with_tool(Weather)
+response = chat.ask("What's the weather in Berlin?")
 ```
 
-This generates a function specification compatible with OpenAI's function calling API.
+This pattern gives you:
+- Full access to `RubyLLM::Tool` features (`halt`, `call`, etc.)
+- EasyTalk's schema DSL for parameter definitions
+- Automatic JSON Schema generation for the LLM
 
-### 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
+## Advanced topics
 
-EasyTalk provides a type registry that allows you to register custom types with their corresponding schema builders.
+For more detailed documentation, see the [full API reference on RubyDoc](https://rubydoc.info/gems/easy_talk).
 
-#### Registering Custom Types
+### JSON Schema drafts, `$id`, and `$ref`
 
-Register types in your configuration:
+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|
-  config.register_type(Money, MoneySchemaBuilder)
+  config.schema_version = :draft202012
+  config.schema_id = "https://example.com/schemas/user.json"
+  config.use_refs = true  # Use $ref/$defs for nested models
 end
 ```
 
-Or register directly with the registry:
-
-```ruby
-EasyTalk::Builders::Registry.register(Money, MoneySchemaBuilder)
-```
+#### External schema references
 
-#### Creating a Custom Builder
+Use external URIs in `$ref` for modular, reusable schemas:
 
-Custom builders extend `BaseBuilder` and implement the schema generation logic:
+<table>
+<tr>
+<th>EasyTalk Model</th>
+<th>Generated JSON Schema</th>
+</tr>
+<tr>
+<td>
 
 ```ruby
-class MoneySchemaBuilder < EasyTalk::Builders::BaseBuilder
-  VALID_OPTIONS = {
-    currency: { type: T.nilable(String), key: :currency }
-  }.freeze
-
-  def initialize(name, options = {})
-    super(name, { type: 'object' }, options, VALID_OPTIONS)
-  end
-
-  def build
-    schema.merge(
-      properties: {
-        amount: { type: 'number' },
-        currency: { type: 'string', default: options[:currency] || 'USD' }
-      },
-      required: %w[amount currency]
-    )
-  end
+EasyTalk.configure do |config|
+  config.use_refs = true
+  config.prefer_external_refs = true
+  config.base_schema_uri = 'https://example.com/schemas'
+  config.auto_generate_ids = true
 end
 
-# Register and use
-EasyTalk::Builders::Registry.register(Money, MoneySchemaBuilder)
-
-class Order
+class Address
   include EasyTalk::Model
 
   define_schema do
-    property :total, Money, currency: 'EUR'
-  end
-end
-```
-
-#### Collection Type Builders
-
-For types that wrap other types (like arrays), use the `collection: true` option:
-
-```ruby
-EasyTalk::Builders::Registry.register(
-  CustomCollection,
-  CustomCollectionBuilder,
-  collection: true
-)
-```
-
-Collection builders receive `(name, inner_type, constraints)` instead of `(name, constraints)`.
-
-#### Overriding Built-in Types
-
-You can override built-in type builders:
-
-```ruby
-class EnhancedStringBuilder < EasyTalk::Builders::StringBuilder
-  def build
-    result = super
-    result[:custom_extension] = true
-    result
-  end
-end
-
-EasyTalk::Builders::Registry.register(String, EnhancedStringBuilder)
-```
-
-#### Registry API
-
-```ruby
-# Check if a type is registered
-EasyTalk::Builders::Registry.registered?(Money)  # => true
-
-# List all registered types
-EasyTalk::Builders::Registry.registered_types
-
-# Unregister a type
-EasyTalk::Builders::Registry.unregister(Money)
-
-# Reset registry to defaults
-EasyTalk::Builders::Registry.reset!
-```
-
-### Type Introspection
-
-EasyTalk provides a `TypeIntrospection` module for reliable type detection, useful when building custom type builders:
-
-```ruby
-# Check type categories
-EasyTalk::TypeIntrospection.boolean_type?(T::Boolean)   # => true
-EasyTalk::TypeIntrospection.typed_array?(T::Array[String])  # => true
-EasyTalk::TypeIntrospection.nilable_type?(T.nilable(String))  # => true
-EasyTalk::TypeIntrospection.primitive_type?(Integer)    # => true
-
-# Get JSON Schema type string
-EasyTalk::TypeIntrospection.json_schema_type(Integer)   # => 'integer'
-EasyTalk::TypeIntrospection.json_schema_type(Float)     # => 'number'
-
-# Extract inner type from nilable
-EasyTalk::TypeIntrospection.extract_inner_type(T.nilable(String))  # => String
-```
-
-## Configuration
-
-### Global Settings
-You can configure EasyTalk globally:
-
-```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.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.property_naming_strategy = :camel_case # Options: :identity (default), :snake_case, :camel_case, :pascal_case
-
-  # Validation options
-  config.auto_validations = true               # Automatically generate ActiveModel validations
-  config.validation_adapter = :active_model    # Validation backend (:active_model, :none, or custom)
-
-  # Error formatting options
-  config.default_error_format = :flat          # Default format (:flat, :json_pointer, :rfc7807, :jsonapi)
-  config.error_type_base_uri = 'about:blank'   # Base URI for RFC 7807 error types
-  config.include_error_codes = true            # Include error codes in formatted output
-end
-```
-
-### Automatic Validation Configuration
-The new `auto_validations` option (enabled by default) automatically generates ActiveModel validations from your schema constraints:
-
-```ruby
-# Disable automatic validations globally
-EasyTalk.configure do |config|
-  config.auto_validations = false
-end
-
-# Now you must manually define validations
-class User
-  include EasyTalk::Model
-  
-  validates :name, presence: true, length: { minimum: 2 }
-  validates :age, presence: true, numericality: { greater_than_or_equal_to: 18 }
-  
-  define_schema do
-    property :name, String, min_length: 2
-    property :age, Integer, minimum: 18
-  end
-end
-```
-
-### Per-Model Configuration
-You can configure additional properties for individual models:
-
-```ruby
-class User
-  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"
-  end
-end
-```
-
-### Validation Adapters
-
-EasyTalk uses a pluggable validation adapter system that allows you to customize how validations are generated from schema constraints.
-
-#### Built-in Adapters
-
-| Adapter | Description |
-|---------|-------------|
-| `:active_model` | Default. Generates ActiveModel validations from schema constraints |
-| `:none` | Skips validation generation entirely (schema-only mode) |
-
-#### Global Adapter Configuration
-
-```ruby
-EasyTalk.configure do |config|
-  config.validation_adapter = :none  # Disable all automatic validations
-end
-```
-
-#### Per-Model Validation Control
-
-Disable validations for a specific model while keeping them enabled globally:
-
-```ruby
-class LegacyModel
-  include EasyTalk::Model
-
-  define_schema(validations: false) do
-    property :data, String, min_length: 1  # No validation generated
-  end
-end
-```
-
-#### Per-Property Validation Control
-
-Disable validation for specific properties:
-
-```ruby
-class User
-  include EasyTalk::Model
-
-  define_schema do
-    property :name, String, min_length: 2              # Validation generated
-    property :legacy_field, String, validate: false    # No validation for this property
-  end
-end
-```
-
-#### Custom Validation Adapters
-
-Create custom adapters for specialized validation needs:
-
-```ruby
-class MyCustomAdapter < EasyTalk::ValidationAdapters::Base
-  def self.build_validations(klass, property_name, type, constraints)
-    # Custom validation logic
-  end
-end
-
-# Register the adapter
-EasyTalk::ValidationAdapters::Registry.register(:custom, MyCustomAdapter)
-
-# Use it globally
-EasyTalk.configure do |config|
-  config.validation_adapter = :custom
-end
-```
-
-## Examples
-
-### User Registration (with Auto-Validations)
-
-```ruby
-class User
-  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"
-  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
-
-```ruby
-class CreditCard
-  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
-  end
-end
-
-class Paypal
-  include EasyTalk::Model
-
-  define_schema do
-    property :PaypalEmail, String, format: 'email'
-    property :PaypalPasswordEncrypted, String
-    additional_properties false
-  end
-end
-
-class BankTransfer
-  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
-  end
-end
-
-class Payment
-  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]
-  end
-end
-```
-
-### Complex Object Hierarchies
-
-```ruby
-class Address
-  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})?$'
-  end
-end
-
-class Employee
-  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])
-  end
-end
-
-class Company
-  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'
-  end
-end
-```
-
-### API Integration
-
-```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
-  include EasyTalk::Model
-
-  define_schema do
-    property :name, String
+    property :street, String
+    property :city, 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
+class Customer
   include EasyTalk::Model
 
   define_schema do
-    schema_version :draft7  # Use Draft-07 for this specific model
     property :name, String
+    property :address, Address
   end
 end
 
-LegacyModel.json_schema
-# => {
-#      "$schema" => "http://json-schema.org/draft-07/schema#",
-#      "type" => "object",
-#      ...
-#    }
-```
-
-### Disabling `$schema` for Specific Models
-
-If you have a global schema version configured but want to exclude `$schema` from a specific model, use `:none`:
-
-```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
-end
-
-InternalModel.json_schema
-# => {
-#      "type" => "object",
-#      "properties" => { "data" => { "type" => "string" } },
-#      ...
-#    }
-# Note: No "$schema" key present
+Customer.json_schema
 ```
 
-### 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
+</td>
+<td>
 
-  define_schema do
-    schema_version 'https://my-company.com/schemas/v1/meta-schema.json'
-    property :id, String
-  end
-end
+```json
+{
+  "properties": {
+    "address": {
+      "$ref": "https://example.com/schemas/address"
+    }
+  },
+  "$defs": {
+    "Address": {
+      "$id": "https://example.com/schemas/address",
+      "properties": {
+        "street": { "type": "string" },
+        "city": { "type": "string" }
+      }
+    }
+  }
+}
 ```
 
-### Nested Models
+</td>
+</tr>
+</table>
 
-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`:
+**Explicit schema IDs:**
 
 ```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
+    schema_id 'https://example.com/schemas/address'
+    property :street, String
   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:
+**Per-property ref control:**
 
 ```ruby
-class User
+class Customer
   include EasyTalk::Model
 
   define_schema do
-    property :name, String
+    property :address, Address, ref: false  # Inline instead of ref
+    property :billing, Address              # Uses ref (global setting)
   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
+### Additional properties with types
 
-Override the global setting for individual models using the `schema_id` keyword in the schema definition:
+Beyond boolean values, `additional_properties` now supports type constraints for dynamic properties:
 
 ```ruby
-class User
+class Config
   include EasyTalk::Model
 
   define_schema do
-    schema_id 'https://example.com/schemas/user.schema.json'
     property :name, String
-    property :email, String
+
+    # Allow any string-typed additional properties
+    additional_properties String
   end
 end
 
-User.json_schema
-# => {
-#      "$id" => "https://example.com/schemas/user.schema.json",
-#      "type" => "object",
-#      ...
-#    }
+config = Config.new(name: 'app')
+config.label = 'Production'  # Dynamic property
+config.as_json
+# => { 'name' => 'app', 'label' => 'Production' }
 ```
 
-### Disabling `$id` for Specific Models
+**With constraints:**
 
-If you have a global schema ID configured but want to exclude `$id` from a specific model, use `:none`:
+<table>
+<tr>
+<th>EasyTalk Model</th>
+<th>Generated JSON Schema</th>
+</tr>
+<tr>
+<td>
 
 ```ruby
-EasyTalk.configure do |config|
-  config.schema_id = 'https://example.com/schemas/default.json'
-end
-
-class InternalModel
+class StrictConfig
   include EasyTalk::Model
 
   define_schema do
-    schema_id :none  # No $id for this model
-    property :data, String
+    property :id, Integer
+    # Integer values between 0 and 100 only
+    additional_properties Integer,
+      minimum: 0, maximum: 100
   end
 end
 
-InternalModel.json_schema
-# => {
-#      "type" => "object",
-#      "properties" => { "data" => { "type" => "string" } },
-#      ...
-#    }
-# Note: No "$id" key present
+StrictConfig.json_schema
 ```
 
-### 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
+</td>
+<td>
 
-Product.json_schema
-# => {
-#      "$schema" => "https://json-schema.org/draft/2020-12/schema",
-#      "$id" => "https://example.com/schemas/product.schema.json",
-#      "type" => "object",
-#      ...
-#    }
+```json
+{
+  "properties": {
+    "id": { "type": "integer" }
+  },
+  "additionalProperties": {
+    "type": "integer",
+    "minimum": 0,
+    "maximum": 100
+  }
+}
 ```
 
-### Nested Models
+</td>
+</tr>
+</table>
 
-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`:
+**Nested models as additional properties:**
 
 ```ruby
-EasyTalk.configure do |config|
-  config.schema_id = 'https://example.com/schemas/user.json'
-end
-
-class Address
+class Person
   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
+    additional_properties Address  # All additional properties must be Address objects
   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).
+### Object-level constraints
 
-## 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:
+Apply schema-wide constraints to limit or validate object structure:
 
 ```ruby
-class Address
+class StrictObject
   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
+    property :required1, String
+    property :required2, String
+    property :optional1, String, optional: true
+    property :optional2, String, optional: true
 
-#### Global Configuration
-
-Enable `$ref` generation for all nested models:
-
-```ruby
-EasyTalk.configure do |config|
-  config.use_refs = true
+    # Require at least 2 properties
+    min_properties 2
+    # Allow at most 3 properties
+    max_properties 3
+  end
 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" }
-#          },
-#          ...
-#        }
-#      },
-#      ...
-#    }
+obj = StrictObject.new(required1: 'a')
+obj.valid?  # => false (only 1 property, needs at least 2)
 ```
 
-#### Per-Property Configuration
-
-You can also enable `$ref` for specific properties using the `ref: true` constraint:
+**Pattern properties:**
 
 ```ruby
-class Person
+class DynamicConfig
   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]
+    # Properties matching /^env_/ must be strings
+    pattern_properties(
+      '^env_' => { type: 'string' }
+    )
   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:
+**Dependent required:**
 
 ```ruby
-EasyTalk.configure do |config|
-  config.use_refs = true
-end
-
-class Person
+class ShippingInfo
   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
-#      },
-#      ...
-#    }
-```
+    property :credit_card, String, optional: true
+    property :billing_address, String, optional: true
 
-### 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"
+    # If credit_card is present, billing_address is required
+    dependent_required(
+      'credit_card' => ['billing_address']
+    )
   end
 end
-
-Person.json_schema["properties"]["address"]
-# => {
-#      "$ref" => "#/$defs/Address",
-#      "description" => "Primary address",
-#      "title" => "Main Address"
-#    }
 ```
 
-### Interaction with `compose`
+### Custom type builders
 
-When using `compose` with `T::AllOf`, `T::AnyOf`, or `T::OneOf`, the composed models are also placed in `$defs`:
+Register custom types with their own schema builders:
 
 ```ruby
-class Employee
-  include EasyTalk::Model
-  define_schema do
-    compose T::AllOf[Person, EmployeeDetails]
-    property :badge_number, String
-  end
+EasyTalk.configure do |config|
+  config.register_type(Money, MoneySchemaBuilder)
 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.
-
-4. **Keep inline for simple, single-use models**: For models used only once, inlining may be more readable.
 
-### Default Behavior
-
-By default, `use_refs` is set to `false`, meaning nested models are inlined. This maintains backward compatibility with previous versions of EasyTalk.
-
-## 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).
-
-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.
-
-### 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.
-
-### Known Limitations
-- Limited support for custom formats
-- Some draft-specific keywords may not be supported
-- Complex composition scenarios may require manual adjustment
+# Or directly:
+EasyTalk::Builders::Registry.register(Money, MoneySchemaBuilder)
+```
 
-## API Reference
+See the [Custom Type Builders documentation](https://rubydoc.info/gems/easy_talk/EasyTalk/Builders/Registry) for details on creating builders.
 
-For complete API documentation, visit [RubyDoc.info](https://rubydoc.info/gems/easy_talk).
+---
 
-### Core Modules
+## Known limitations
 
-| Module | Description | Source |
-|--------|-------------|--------|
-| [`EasyTalk::Model`](https://rubydoc.info/gems/easy_talk/EasyTalk/Model) | Main mixin providing schema definition, validation, and JSON Schema generation | [lib/easy_talk/model.rb](lib/easy_talk/model.rb) |
-| [`EasyTalk::Schema`](https://rubydoc.info/gems/easy_talk/EasyTalk/Schema) | Schema-only mode without ActiveModel validations | [lib/easy_talk/schema.rb](lib/easy_talk/schema.rb) |
-| [`EasyTalk::SchemaDefinition`](https://rubydoc.info/gems/easy_talk/EasyTalk/SchemaDefinition) | DSL for defining properties, titles, and descriptions | [lib/easy_talk/schema_definition.rb](lib/easy_talk/schema_definition.rb) |
-| [`EasyTalk::Property`](https://rubydoc.info/gems/easy_talk/EasyTalk/Property) | Property definition and type dispatching | [lib/easy_talk/property.rb](lib/easy_talk/property.rb) |
+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
 
-### Builders
+---
 
-Type-specific builders that convert Ruby definitions to JSON Schema. See the [builders directory](lib/easy_talk/builders/) for all available builders.
+## Contributing
 
-| Builder | Description |
-|---------|-------------|
-| [`ObjectBuilder`](lib/easy_talk/builders/object_builder.rb) | Handles EasyTalk::Model classes |
-| [`StringBuilder`](lib/easy_talk/builders/string_builder.rb) | String type with format, pattern, length constraints |
-| [`IntegerBuilder`](lib/easy_talk/builders/integer_builder.rb) | Integer type with min/max constraints |
-| [`NumberBuilder`](lib/easy_talk/builders/number_builder.rb) | Float/Number type with numeric constraints |
-| [`BooleanBuilder`](lib/easy_talk/builders/boolean_builder.rb) | Boolean type (T::Boolean) |
-| [`TypedArrayBuilder`](lib/easy_talk/builders/typed_array_builder.rb) | Typed arrays (T::Array[Type]) |
-| [`CompositionBuilder`](lib/easy_talk/builders/composition_builder.rb) | Composition types (T::AnyOf, T::OneOf, T::AllOf) |
-| [`UnionBuilder`](lib/easy_talk/builders/union_builder.rb) | Nilable types (T.nilable) |
-| [`TemporalBuilder`](lib/easy_talk/builders/temporal_builder.rb) | Date and DateTime types |
-| [`BaseBuilder`](lib/easy_talk/builders/base_builder.rb) | Base class for all builders |
-| [`Registry`](lib/easy_talk/builders/registry.rb) | Type-to-builder registration |
+- Run `bin/setup`
+- Run specs: `bundle exec rake spec`
+- Run lint: `bundle exec rubocop`
 
-### Configuration & Utilities
+Bug reports and PRs welcome.
 
-| Class/Module | Description | Source |
-|--------------|-------------|--------|
-| [`EasyTalk::Configuration`](https://rubydoc.info/gems/easy_talk/EasyTalk/Configuration) | Global configuration options | [lib/easy_talk/configuration.rb](lib/easy_talk/configuration.rb) |
-| [`EasyTalk::ValidationBuilder`](https://rubydoc.info/gems/easy_talk/EasyTalk/ValidationBuilder) | Generates ActiveModel validations from constraints | [lib/easy_talk/validation_builder.rb](lib/easy_talk/validation_builder.rb) |
-| [`EasyTalk::ErrorFormatter`](https://rubydoc.info/gems/easy_talk/EasyTalk/ErrorFormatter) | Formats validation errors (flat, JSON Pointer, RFC 7807, JSON:API) | [lib/easy_talk/error_formatter.rb](lib/easy_talk/error_formatter.rb) |
-| [`EasyTalk::TypeIntrospection`](https://rubydoc.info/gems/easy_talk/EasyTalk/TypeIntrospection) | Type detection utilities | [lib/easy_talk/type_introspection.rb](lib/easy_talk/type_introspection.rb) |
-| [`EasyTalk::Tools::FunctionBuilder`](https://rubydoc.info/gems/easy_talk/EasyTalk/Tools/FunctionBuilder) | LLM function specification generator | [lib/easy_talk/tools/function_builder.rb](lib/easy_talk/tools/function_builder.rb) |
+---
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT