easy_talk 3.1.0 → 3.2.0

data/README.md

@@ -2,23 +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.
-* **JSON Schema Version Support**: Configure the `$schema` keyword to declare which JSON Schema draft version your schemas conform to (Draft-04 through Draft 2020-12).
-* **Schema Identification**: Configure the `$id` keyword to provide a unique identifier URI for your schemas.
-* **Schema References**: Use `$ref` and `$defs` for reusable schema definitions, reducing duplication when models are used in multiple places.
+* **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
@@ -28,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
 
@@ -367,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
@@ -408,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]
@@ -480,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:
 
@@ -523,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:
 
@@ -569,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
@@ -591,11 +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.auto_validations = true               # Automatically generate ActiveModel validations
   config.schema_version = :none                # JSON Schema version for $schema keyword
                                                # Options: :none, :draft202012, :draft201909, :draft7, :draft6, :draft4
   config.schema_id = nil                       # Base URI for $id keyword (nil = no $id)
   config.use_refs = false                      # Use $ref for nested models instead of inlining
+  config.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
 ```
 
@@ -628,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
@@ -638,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)
@@ -878,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:
 
@@ -915,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:
 
@@ -941,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:
 
@@ -968,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:
 
@@ -980,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
@@ -1011,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.
 
@@ -1035,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 |
 |--------------------|----------|----------|------------------------|
@@ -1828,6 +2368,47 @@ To learn about current capabilities, see the [spec/easy_talk/examples](https://g
 - 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
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).