easy_talk 3.0.0 → 3.2.0

data/README.md

@@ -2,20 +2,179 @@
 
 [![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)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/easy_talk)
+
+## Table of Contents
+
+- [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)
 
 ## Introduction
 
 ### What is EasyTalk?
-EasyTalk is a Ruby library that simplifies defining and generating JSON Schema. It provides an intuitive interface for Ruby developers to define structured data models that can be used for validation and documentation.
+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.
 
 ### Key Features
-* **Intuitive Schema Definition**: Use Ruby classes and methods to define JSON Schema documents easily.
-* **Automatic ActiveModel Validations**: Schema constraints automatically generate corresponding ActiveModel validations (configurable).
-* **Works for plain Ruby classes and ActiveModel classes**: Integrate with existing code or build from scratch.
-* **LLM Function Support**: Ideal for integrating with Large Language Models (LLMs) such as OpenAI's GPT series. EasyTalk enables you to effortlessly create JSON Schema documents describing the inputs and outputs of LLM function calls.
-* **Schema Composition**: Define EasyTalk models and reference them in other EasyTalk models to create complex schemas.
-* **Enhanced Model Integration**: Automatic instantiation of nested EasyTalk models from hash attributes.
-* **Flexible Configuration**: Global and per-model configuration options for fine-tuned control.
+* **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.
 
 ### Use Cases
 - API request/response validation
@@ -25,7 +184,7 @@ EasyTalk is a Ruby library that simplifies defining and generating JSON Schema.
 - Configuration schema definitions
 
 ### Inspiration
-Inspired by Python's Pydantic library, EasyTalk brings similar functionality to the Ruby ecosystem, providing a Ruby-friendly approach to JSON Schema operations.
+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.
 
 ## Installation
 
@@ -364,6 +523,27 @@ 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:
+
+```ruby
+EasyTalk.configure do |config|
+  config.property_naming_strategy = :snake_case  # Options: :identity, :snake_case, :camel_case, :pascal_case
+end
+
+define_schema do
+  property_naming_strategy :camel_case  # Overrides global setting for this schema
+  property :name, String
+end
+```
+
+This affects how property names are represented in the generated JSON Schema. 
+Additionally, names can be overridden per property:
+
+```ruby
+property :first_name, String, as: "firstName"  # Overrides global naming strategy
+```
+
 ## Schema Composition
 
 ### Using T::AnyOf
@@ -405,13 +585,67 @@ class VehicleRegistration
 end
 ```
 
+### Array Composition
+Composition types can be combined with arrays to define collections where each item must match one of several schemas:
+
+```ruby
+class ProductA
+  include EasyTalk::Model
+  define_schema do
+    property :sku, String
+    property :weight, Float
+  end
+end
+
+class ProductB
+  include EasyTalk::Model
+  define_schema do
+    property :sku, String
+    property :digital_url, String
+  end
+end
+
+class Order
+  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]]
+  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": {...} }, ... }
+        ]
+      }
+    }
+  }
+}
+```
+
+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
+
 ### Complex Compositions
 You can combine composition types to create complex schemas:
 
 ```ruby
 class ComplexObject
   include EasyTalk::Model
-  
+
   define_schema do
     property :basic_info, BaseInfo
     property :specific_details, T::OneOf[DetailTypeA, DetailTypeB]
@@ -477,6 +711,78 @@ user.errors[:age] # => ["must be greater than 21"] # Custom validation
 user.errors[:height] # => ["must be greater than 0"] # Overridden validation
 ```
 
+### Standardized Error Formatting
+
+EasyTalk provides multiple output formats for validation errors, making it easy to build consistent API responses.
+
+#### Available Formats
+
+| 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:
+
+```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:
+
+```ruby
+EasyTalk::ErrorFormatter.format(user.errors, format: :rfc7807, title: "User Validation Failed")
+```
+
+#### Configuration
+
+Configure error formatting globally:
+
+```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
+end
+```
+
 ### Model Attributes
 EasyTalk models provide getters and setters for all defined properties:
 
@@ -520,6 +826,57 @@ user.address.street # => "123 Main St"
 
 ## Advanced Features
 
+### 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:
+
+- 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
+
+```ruby
+class ApiContract
+  include EasyTalk::Schema  # Not EasyTalk::Model
+
+  define_schema do
+    title 'API Contract'
+    description 'A schema-only contract'
+    property :name, String, min_length: 2
+    property :age, Integer, minimum: 0
+  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'
+
+# But no validation methods are available
+contract.valid?  # => NoMethodError
+contract.errors  # => NoMethodError
+```
+
+#### Key Differences from EasyTalk::Model
+
+| 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:
 
@@ -566,16 +923,125 @@ property :age, Integer, enum: ["young", "old"]  # Error!
 ```
 
 ### Custom Type Builders
-For advanced use cases, you can create custom type builders:
+
+EasyTalk provides a type registry that allows you to register custom types with their corresponding schema builders.
+
+#### Registering Custom Types
+
+Register types in your configuration:
 
 ```ruby
-module EasyTalk
-  module Builders
-    class MyCustomTypeBuilder < BaseBuilder
-      # Custom implementation
-    end
+EasyTalk.configure do |config|
+  config.register_type(Money, MoneySchemaBuilder)
+end
+```
+
+Or register directly with the registry:
+
+```ruby
+EasyTalk::Builders::Registry.register(Money, MoneySchemaBuilder)
+```
+
+#### Creating a Custom Builder
+
+Custom builders extend `BaseBuilder` and implement the schema generation logic:
+
+```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
+end
+
+# Register and use
+EasyTalk::Builders::Registry.register(Money, MoneySchemaBuilder)
+
+class Order
+  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
@@ -588,7 +1054,20 @@ 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
 ```
 
@@ -621,7 +1100,7 @@ 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
@@ -631,6 +1110,74 @@ class User
 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)
@@ -871,18 +1418,18 @@ property :status, String, enum: ["active", "inactive", "pending"]
 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
+## 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
+### 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
+### Nullable Properties
 
 A **nullable** property can contain a `null` value, but the property itself must still be present in the object:
 
@@ -908,7 +1455,7 @@ In this case, the following data would be valid:
 But this would be invalid:
 - `{ }` (missing the age property entirely)
 
-## Optional Properties
+### Optional Properties
 
 An **optional** property doesn't have to be present in the object at all:
 
@@ -934,7 +1481,7 @@ In this case, the following data would be valid:
 But this would be invalid:
 - `{ "nickname": null }` (null is not allowed because the property isn't nullable)
 
-## Nullable AND Optional Properties
+### Nullable AND Optional Properties
 
 For properties that should be both nullable and optional (can be omitted or null), you need to combine both approaches:
 
@@ -961,7 +1508,7 @@ nullable_optional_property :bio, String
 
 Which is equivalent to the above.
 
-## Configuration Options
+### Configuration Options
 
 By default, nullable properties are still required. You can change this global behavior:
 
@@ -973,9 +1520,9 @@ end
 
 With this configuration, any property defined with `T.nilable(Type)` will be treated as both nullable and optional.
 
-## Practical Examples
+### Practical Examples
 
-### User Profile Schema
+#### User Profile Schema
 
 ```ruby
 class UserProfile
@@ -1004,17 +1551,17 @@ This creates clear expectations for data validation:
 - `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
+### Common Gotchas
 
-### Misconception: Nullable Implies Optional
+#### 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
+#### 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
+### 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.
 
@@ -1028,14 +1575,14 @@ 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
+### 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
+### JSON Schema Comparison
 
 | EasyTalk Definition | Required | Nullable | JSON Schema Equivalent |
 |--------------------|----------|----------|------------------------|
@@ -1168,18 +1715,699 @@ bundle exec rubocop
 ### Contributing Guidelines
 Bug reports and pull requests are welcome on GitHub at https://github.com/sergiobayona/easy_talk.
 
-## JSON Schema Compatibility
+## JSON Schema Version (`$schema` Keyword)
 
-### Supported Versions
-EasyTalk is currently loose about JSON Schema versions. It doesn't strictly enforce or adhere to any particular version of the specification. The goal is to add more robust support for the latest JSON Schema specs in the future.
+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.
 
-### 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.
+### Why Use `$schema`?
 
-### Known Limitations
-- Limited support for custom formats
-- No direct support for JSON Schema draft 2020-12 features
-- Complex composition scenarios may require manual adjustment
+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
+  end
+end
+
+User.json_schema
+# => {
+#      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+#      "type" => "object",
+#      "properties" => { "name" => { "type" => "string" } },
+#      "required" => ["name"],
+#      "additionalProperties" => false
+#    }
+```
+
+### Per-Model Configuration
+
+Override the global setting for individual models using the `schema_version` keyword in the schema definition:
+
+```ruby
+class LegacyModel
+  include EasyTalk::Model
+
+  define_schema do
+    schema_version :draft7  # Use Draft-07 for this specific model
+    property :name, String
+  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
+```
+
+### Custom Schema URIs
+
+You can also specify a custom URI if you're using a custom meta-schema or a different schema registry:
+
+```ruby
+class CustomModel
+  include EasyTalk::Model
+
+  define_schema do
+    schema_version 'https://my-company.com/schemas/v1/meta-schema.json'
+    property :id, String
+  end
+end
+```
+
+### Nested Models
+
+The `$schema` keyword only appears at the root level of the schema. When you have nested EasyTalk models, only the top-level model's `json_schema` output will include `$schema`:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_version = :draft202012
+end
+
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address
+  end
+end
+
+User.json_schema
+# => {
+#      "$schema" => "https://json-schema.org/draft/2020-12/schema",  # Only at root
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => {
+#          "type" => "object",  # No $schema here
+#          "properties" => { "city" => { "type" => "string" } },
+#          ...
+#        }
+#      },
+#      ...
+#    }
+```
+
+### Default Behavior
+
+By default, `schema_version` is set to `:none`, meaning no `$schema` keyword is included in the generated schemas. This maintains backward compatibility with previous versions of EasyTalk.
+
+### Best Practices
+
+1. **Choose a version appropriate for your validators**: If you're using a specific JSON Schema validator, check which drafts it supports.
+
+2. **Use Draft 2020-12 for new projects**: It's the latest stable version with the most features.
+
+3. **Be consistent**: Use global configuration for consistency across your application, and only override per-model when necessary.
+
+4. **Consider your consumers**: If your schemas are consumed by external systems, ensure they support the draft version you're using.
+
+## Schema Identifier (`$id` Keyword)
+
+The `$id` keyword provides a unique identifier for your JSON Schema document. EasyTalk supports configuring this at both the global and per-model level.
+
+### Why Use `$id`?
+
+The `$id` keyword:
+- Establishes a unique URI identifier for the schema
+- Enables referencing schemas from other documents via `$ref`
+- Provides a base URI for resolving relative references within the schema
+- Documents the canonical location of the schema
+
+### Global Configuration
+
+Configure the schema ID globally to apply to all models:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_id = 'https://example.com/schemas/base.json'
+end
+```
+
+With this configuration, all models will include `$id` in their output:
+
+```ruby
+class User
+  include EasyTalk::Model
+
+  define_schema do
+    property :name, String
+  end
+end
+
+User.json_schema
+# => {
+#      "$id" => "https://example.com/schemas/base.json",
+#      "type" => "object",
+#      "properties" => { "name" => { "type" => "string" } },
+#      "required" => ["name"],
+#      "additionalProperties" => false
+#    }
+```
+
+### Per-Model Configuration
+
+Override the global setting for individual models using the `schema_id` keyword in the schema definition:
+
+```ruby
+class User
+  include EasyTalk::Model
+
+  define_schema do
+    schema_id 'https://example.com/schemas/user.schema.json'
+    property :name, String
+    property :email, String
+  end
+end
+
+User.json_schema
+# => {
+#      "$id" => "https://example.com/schemas/user.schema.json",
+#      "type" => "object",
+#      ...
+#    }
+```
+
+### Disabling `$id` for Specific Models
+
+If you have a global schema ID configured but want to exclude `$id` from a specific model, use `:none`:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_id = 'https://example.com/schemas/default.json'
+end
+
+class InternalModel
+  include EasyTalk::Model
+
+  define_schema do
+    schema_id :none  # No $id for this model
+    property :data, String
+  end
+end
+
+InternalModel.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => { "data" => { "type" => "string" } },
+#      ...
+#    }
+# Note: No "$id" key present
+```
+
+### Combining `$schema` and `$id`
+
+When both `$schema` and `$id` are configured, they appear in the standard order (`$schema` first, then `$id`):
+
+```ruby
+class Product
+  include EasyTalk::Model
+
+  define_schema do
+    schema_version :draft202012
+    schema_id 'https://example.com/schemas/product.schema.json'
+    property :name, String
+    property :price, Float
+  end
+end
+
+Product.json_schema
+# => {
+#      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+#      "$id" => "https://example.com/schemas/product.schema.json",
+#      "type" => "object",
+#      ...
+#    }
+```
+
+### Nested Models
+
+The `$id` keyword only appears at the root level of the schema. When you have nested EasyTalk models, only the top-level model's `json_schema` output will include `$id`:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_id = 'https://example.com/schemas/user.json'
+end
+
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address
+  end
+end
+
+User.json_schema
+# => {
+#      "$id" => "https://example.com/schemas/user.json",  # Only at root
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => {
+#          "type" => "object",  # No $id here
+#          "properties" => { "city" => { "type" => "string" } },
+#          ...
+#        }
+#      },
+#      ...
+#    }
+```
+
+### URI Formats
+
+The `$id` accepts various URI formats:
+
+```ruby
+# Absolute URI (recommended for published schemas)
+schema_id 'https://example.com/schemas/user.schema.json'
+
+# Relative URI
+schema_id 'user.schema.json'
+
+# URN format
+schema_id 'urn:example:user-schema'
+```
+
+### Default Behavior
+
+By default, `schema_id` is set to `nil`, meaning no `$id` keyword is included in the generated schemas. This maintains backward compatibility with previous versions of EasyTalk.
+
+### Best Practices
+
+1. **Use absolute URIs for published schemas**: This ensures global uniqueness and enables external references.
+
+2. **Follow a consistent naming convention**: For example, `https://yourdomain.com/schemas/{model-name}.schema.json`.
+
+3. **Keep IDs stable**: Once published, avoid changing schema IDs as external systems may reference them.
+
+4. **Combine with `$schema`**: When publishing schemas, include both `$schema` (for validation) and `$id` (for identification).
+
+## Schema References (`$ref` and `$defs`)
+
+The `$ref` keyword allows you to reference reusable schema definitions, reducing duplication when the same model is used in multiple places. EasyTalk supports automatic `$ref` generation for nested models.
+
+### Why Use `$ref`?
+
+The `$ref` keyword:
+- Reduces schema duplication when the same model appears multiple times
+- Produces cleaner, more organized schemas
+- Improves schema readability and maintainability
+- Aligns with JSON Schema best practices for reusable definitions
+
+### Default Behavior (Inline Schemas)
+
+By default, EasyTalk inlines nested model schemas directly:
+
+```ruby
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :street, String
+    property :city, String
+  end
+end
+
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address
+  end
+end
+
+Person.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => {
+#          "type" => "object",
+#          "properties" => {
+#            "street" => { "type" => "string" },
+#            "city" => { "type" => "string" }
+#          },
+#          ...
+#        }
+#      },
+#      ...
+#    }
+```
+
+### Enabling `$ref` References
+
+#### Global Configuration
+
+Enable `$ref` generation for all nested models:
+
+```ruby
+EasyTalk.configure do |config|
+  config.use_refs = true
+end
+```
+
+With this configuration, nested models are referenced via `$ref` and their definitions are placed in `$defs`:
+
+```ruby
+Person.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => { "$ref" => "#/$defs/Address" }
+#      },
+#      "$defs" => {
+#        "Address" => {
+#          "type" => "object",
+#          "properties" => {
+#            "street" => { "type" => "string" },
+#            "city" => { "type" => "string" }
+#          },
+#          ...
+#        }
+#      },
+#      ...
+#    }
+```
+
+#### Per-Property Configuration
+
+You can also enable `$ref` for specific properties using the `ref: true` constraint:
+
+```ruby
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address, ref: true  # Use $ref for this property
+  end
+end
+```
+
+Or disable `$ref` for specific properties when it's enabled globally:
+
+```ruby
+EasyTalk.configure do |config|
+  config.use_refs = true
+end
+
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address, ref: false  # Inline this property despite global setting
+  end
+end
+```
+
+### Arrays of Models
+
+When using `$ref` with arrays of models, the `$ref` applies to the array items:
+
+```ruby
+EasyTalk.configure do |config|
+  config.use_refs = true
+end
+
+class Company
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :addresses, T::Array[Address]
+  end
+end
+
+Company.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "addresses" => {
+#          "type" => "array",
+#          "items" => { "$ref" => "#/$defs/Address" }
+#        }
+#      },
+#      "$defs" => {
+#        "Address" => { ... }
+#      },
+#      ...
+#    }
+```
+
+You can also use the per-property `ref` constraint with arrays:
+
+```ruby
+property :addresses, T::Array[Address], ref: true
+```
+
+### Nilable Models with `$ref`
+
+When using `$ref` with nilable model types, EasyTalk uses `anyOf` to combine the reference with the null type:
+
+```ruby
+EasyTalk.configure do |config|
+  config.use_refs = true
+end
+
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, T.nilable(Address)
+  end
+end
+
+Person.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => {
+#          "anyOf" => [
+#            { "$ref" => "#/$defs/Address" },
+#            { "type" => "null" }
+#          ]
+#        }
+#      },
+#      "$defs" => {
+#        "Address" => { ... }
+#      },
+#      ...
+#    }
+```
+
+### Multiple References to the Same Model
+
+When the same model is used multiple times, it only appears once in `$defs`:
+
+```ruby
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :home_address, Address, ref: true
+    property :work_address, Address, ref: true
+    property :shipping_addresses, T::Array[Address], ref: true
+  end
+end
+
+Person.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "home_address" => { "$ref" => "#/$defs/Address" },
+#        "work_address" => { "$ref" => "#/$defs/Address" },
+#        "shipping_addresses" => {
+#          "type" => "array",
+#          "items" => { "$ref" => "#/$defs/Address" }
+#        }
+#      },
+#      "$defs" => {
+#        "Address" => { ... }  # Only defined once
+#      },
+#      ...
+#    }
+```
+
+### Combining `$ref` with Other Constraints
+
+You can add additional constraints alongside `$ref`:
+
+```ruby
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :address, Address, ref: true, description: "Primary address", title: "Main Address"
+  end
+end
+
+Person.json_schema["properties"]["address"]
+# => {
+#      "$ref" => "#/$defs/Address",
+#      "description" => "Primary address",
+#      "title" => "Main Address"
+#    }
+```
+
+### Interaction with `compose`
+
+When using `compose` with `T::AllOf`, `T::AnyOf`, or `T::OneOf`, the composed models are also placed in `$defs`:
+
+```ruby
+class Employee
+  include EasyTalk::Model
+  define_schema do
+    compose T::AllOf[Person, EmployeeDetails]
+    property :badge_number, String
+  end
+end
+```
+
+If you also have properties using `$ref`, both the composed models and property models will appear in `$defs`.
+
+### Best Practices
+
+1. **Use global configuration for consistency**: If you prefer `$ref` style, enable it globally rather than per-property.
+
+2. **Consider schema consumers**: Some JSON Schema validators and tools work better with inlined schemas, while others prefer `$ref`. Choose based on your use case.
+
+3. **Use `$ref` for frequently reused models**: If a model appears in many places, `$ref` reduces schema size and improves maintainability.
+
+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
+
+## API Reference
+
+For complete API documentation, visit [RubyDoc.info](https://rubydoc.info/gems/easy_talk).
+
+### Core Modules
+
+| 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) |
+
+### Builders
+
+Type-specific builders that convert Ruby definitions to JSON Schema. See the [builders directory](lib/easy_talk/builders/) for all available builders.
+
+| 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 |
+
+### Configuration & Utilities
+
+| 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