easy_talk 3.0.0 → 3.2.0

data/docs/property-types.markdown

@@ -0,0 +1,212 @@
+---
+layout: page
+title: Property Types
+permalink: /property-types/
+---
+
+# Property Types
+
+EasyTalk supports Ruby's built-in types plus Sorbet-style generic types for more complex schemas.
+
+## Basic Types
+
+### String
+
+```ruby
+property :name, String
+# => { "type": "string" }
+```
+
+**Constraints:**
+
+| Constraint | Description | Example |
+|------------|-------------|---------|
+| `min_length` | Minimum length | `min_length: 1` |
+| `max_length` | Maximum length | `max_length: 100` |
+| `pattern` | Regex pattern | `pattern: /^[a-z]+$/` |
+| `format` | JSON Schema format | `format: "email"` |
+| `enum` | Allowed values | `enum: %w[a b c]` |
+
+**Common formats:** `email`, `uri`, `uuid`, `date`, `date-time`, `time`, `ipv4`, `ipv6`, `hostname`
+
+### Integer
+
+```ruby
+property :age, Integer
+# => { "type": "integer" }
+```
+
+**Constraints:**
+
+| Constraint | Description | Example |
+|------------|-------------|---------|
+| `minimum` | Minimum value (inclusive) | `minimum: 0` |
+| `maximum` | Maximum value (inclusive) | `maximum: 100` |
+| `exclusive_minimum` | Minimum value (exclusive) | `exclusive_minimum: 0` |
+| `exclusive_maximum` | Maximum value (exclusive) | `exclusive_maximum: 100` |
+| `multiple_of` | Must be multiple of | `multiple_of: 5` |
+| `enum` | Allowed values | `enum: [1, 2, 3]` |
+
+### Float / Number
+
+```ruby
+property :price, Float
+# => { "type": "number" }
+```
+
+Supports the same constraints as Integer.
+
+### Boolean
+
+```ruby
+property :active, T::Boolean
+# => { "type": "boolean" }
+```
+
+Note: Use `T::Boolean` (not Ruby's `TrueClass`/`FalseClass`).
+
+## Date and Time Types
+
+### Date
+
+```ruby
+property :birth_date, Date
+# => { "type": "string", "format": "date" }
+```
+
+### DateTime
+
+```ruby
+property :created_at, DateTime
+# => { "type": "string", "format": "date-time" }
+```
+
+### Time
+
+```ruby
+property :start_time, Time
+# => { "type": "string", "format": "time" }
+```
+
+## Generic Types
+
+EasyTalk uses Sorbet-style generics for complex types.
+
+### Arrays
+
+```ruby
+property :tags, T::Array[String]
+# => { "type": "array", "items": { "type": "string" } }
+```
+
+**Array Constraints:**
+
+| Constraint | Description | Example |
+|------------|-------------|---------|
+| `min_items` | Minimum array length | `min_items: 1` |
+| `max_items` | Maximum array length | `max_items: 10` |
+| `unique_items` | All items must be unique | `unique_items: true` |
+
+```ruby
+property :scores, T::Array[Integer], min_items: 1, max_items: 5
+```
+
+### Nullable Types
+
+Use `T.nilable` to allow null values:
+
+```ruby
+property :nickname, T.nilable(String)
+# => { "anyOf": [{ "type": "string" }, { "type": "null" }] }
+```
+
+**Note:** `T.nilable` makes the property nullable but still required. To make it optional as well:
+
+```ruby
+property :nickname, T.nilable(String), optional: true
+```
+
+Or use the helper method:
+
+```ruby
+nullable_optional_property :nickname, String
+```
+
+## Nested Models
+
+Reference other EasyTalk models directly:
+
+```ruby
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :street, String
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address  # Nested model
+  end
+end
+```
+
+Arrays of models:
+
+```ruby
+property :addresses, T::Array[Address]
+```
+
+## Composition Types
+
+### OneOf
+
+Exactly one schema must match:
+
+```ruby
+property :contact, T::OneOf[Email, Phone]
+```
+
+### AnyOf
+
+At least one schema must match:
+
+```ruby
+property :identifier, T::AnyOf[UserId, Email, Username]
+```
+
+### AllOf
+
+All schemas must match (for combining schemas):
+
+```ruby
+property :profile, T::AllOf[BasicInfo, ExtendedInfo]
+```
+
+## Null Type
+
+For explicit null-only values:
+
+```ruby
+property :deprecated_field, NilClass
+# => { "type": "null" }
+```
+
+## Type Summary
+
+| Ruby Type | JSON Schema Type |
+|-----------|------------------|
+| `String` | `"string"` |
+| `Integer` | `"integer"` |
+| `Float` | `"number"` |
+| `T::Boolean` | `"boolean"` |
+| `Date` | `"string"` + `"date"` format |
+| `DateTime` | `"string"` + `"date-time"` format |
+| `Time` | `"string"` + `"time"` format |
+| `T::Array[T]` | `"array"` |
+| `T.nilable(T)` | `anyOf` with null |
+| `NilClass` | `"null"` |
+| Model class | `"object"` (inline or `$ref`) |

data/docs/schema-definition.markdown

@@ -0,0 +1,180 @@
+---
+layout: page
+title: Schema Definition
+permalink: /schema-definition/
+---
+
+# Schema Definition
+
+The `define_schema` block is where you declare your model's structure. It provides a clean DSL for defining JSON Schema properties and metadata.
+
+## Basic Structure
+
+```ruby
+class MyModel
+  include EasyTalk::Model
+
+  define_schema do
+    title "Model Title"
+    description "What this model represents"
+
+    property :field_name, Type, constraints...
+  end
+end
+```
+
+## Schema Metadata
+
+### title
+
+Sets the schema title (appears in JSON Schema output):
+
+```ruby
+define_schema do
+  title "User Account"
+end
+```
+
+### description
+
+Adds a description to the schema:
+
+```ruby
+define_schema do
+  description "Represents a user account in the system"
+end
+```
+
+## Defining Properties
+
+The `property` method defines a schema property:
+
+```ruby
+property :name, Type, option: value, ...
+```
+
+### Required vs Optional
+
+By default, all properties are **required**. Use `optional: true` to make a property optional:
+
+```ruby
+define_schema do
+  property :name, String                    # Required
+  property :nickname, String, optional: true # Optional
+end
+```
+
+### Property Titles and Descriptions
+
+Add metadata to individual properties:
+
+```ruby
+property :email, String,
+  title: "Email Address",
+  description: "The user's primary email"
+```
+
+### Property Renaming
+
+Use `:as` to rename a property in the JSON Schema output:
+
+```ruby
+property :created_at, String, as: :createdAt
+```
+
+This creates a property named `createdAt` in the schema while keeping `created_at` as the Ruby attribute.
+
+## Type Constraints
+
+Different types support different constraints. See [Property Types](property-types) for the full list.
+
+### String Constraints
+
+```ruby
+property :username, String,
+  min_length: 3,
+  max_length: 20,
+  pattern: /^[a-z0-9_]+$/
+```
+
+### Numeric Constraints
+
+```ruby
+property :age, Integer,
+  minimum: 0,
+  maximum: 150
+
+property :price, Float,
+  exclusive_minimum: 0
+```
+
+### Enum Values
+
+```ruby
+property :status, String, enum: %w[active inactive pending]
+```
+
+## Composition
+
+### compose
+
+Use `compose` to include schemas from other models:
+
+```ruby
+class FullProfile
+  include EasyTalk::Model
+
+  define_schema do
+    compose T::AllOf[BasicInfo, ContactInfo, Preferences]
+  end
+end
+```
+
+### Composition Types
+
+- `T::AllOf[A, B]` - Must match all schemas
+- `T::AnyOf[A, B]` - Must match at least one schema
+- `T::OneOf[A, B]` - Must match exactly one schema
+
+## Configuration Options
+
+### Per-Model Validation Control
+
+Disable automatic validations for a specific model:
+
+```ruby
+define_schema(validations: false) do
+  property :data, String
+end
+```
+
+### Per-Property Validation Control
+
+Disable validation for specific properties:
+
+```ruby
+property :legacy_field, String, validate: false
+```
+
+## Example: Complete Model
+
+```ruby
+class Product
+  include EasyTalk::Model
+
+  define_schema do
+    title "Product"
+    description "A product in the catalog"
+
+    property :id, String, format: "uuid"
+    property :name, String, min_length: 1, max_length: 100
+    property :description, String, optional: true
+    property :price, Float, minimum: 0
+    property :currency, String, enum: %w[USD EUR GBP], default: "USD"
+    property :category, String
+    property :tags, T::Array[String], optional: true
+    property :active, T::Boolean, default: true
+    property :created_at, DateTime, as: :createdAt
+  end
+end
+```

data/lib/easy_talk/builders/base_builder.rb

@@ -12,7 +12,9 @@ module EasyTalk
       COMMON_OPTIONS = {
         title: { type: T.nilable(String), key: :title },
         description: { type: T.nilable(String), key: :description },
-        optional: { type: T.nilable(T::Boolean), key: :optional }
+        optional: { type: T.nilable(T::Boolean), key: :optional },
+        as: { type: T.nilable(T.any(String, Symbol)), key: :as },
+        validate: { type: T.nilable(T::Boolean), key: :validate }
       }.freeze
 
       attr_reader :property_name, :schema, :options
@@ -42,7 +44,7 @@ module EasyTalk
       # Builds the schema object based on the provided options.
       sig { returns(T::Hash[Symbol, T.untyped]) }
       def build
-        @valid_options.each_with_object(schema) do |(constraint_name, value), obj|
+        @valid_options.except(:ref).each_with_object(schema) do |(constraint_name, value), obj|
           next if @options[constraint_name].nil?
 
           # Use our centralized validation

data/lib/easy_talk/builders/composition_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'collection_helpers'
+require_relative '../ref_helper'
 
 module EasyTalk
   module Builders
@@ -15,17 +16,18 @@ module EasyTalk
         'OneOfBuilder' => 'oneOf'
       }.freeze
 
-      sig { params(name: Symbol, type: T.untyped, _constraints: Hash).void }
+      sig { params(name: Symbol, type: T.untyped, constraints: Hash).void }
       # Initializes a new instance of the CompositionBuilder class.
       #
       # @param name [Symbol] The name of the composition.
       # @param type [Class] The type of the composition.
-      # @param _constraints [Hash] The constraints for the composition (not used in this method).
-      def initialize(name, type, _constraints)
+      # @param constraints [Hash] The constraints for the composition.
+      def initialize(name, type, constraints)
         @composer_type = self.class.name.split('::').last
         @name = name
         @type = type
         @context = {}
+        @constraints = constraints
       end
 
       # Builds the composed JSON schema.
@@ -50,17 +52,13 @@ module EasyTalk
       # @return [Array<Hash>] The array of schemas.
       def schemas
         items.map do |type|
-          if type.respond_to?(:schema)
+          if EasyTalk::RefHelper.should_use_ref?(type, @constraints)
+            EasyTalk::RefHelper.build_ref_schema(type, @constraints)
+          elsif type.respond_to?(:schema)
             type.schema
           else
-            # Map Float type to 'number' in JSON Schema
-            json_type = case type.to_s
-                       when 'Float', 'BigDecimal'
-                         'number'
-                       else
-                         type.to_s.downcase
-                       end
-            { type: json_type }
+            # Map Ruby type to JSON Schema type
+            { type: TypeIntrospection.json_schema_type(type) }
           end
         end
       end

data/lib/easy_talk/builders/object_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base_builder'
+require_relative '../model_helper'
 
 module EasyTalk
   module Builders
@@ -33,12 +34,15 @@ module EasyTalk
       def initialize(schema_definition)
         # Keep a reference to the original schema definition
         @schema_definition = schema_definition
-        # Duplicate the raw schema hash so we can mutate it safely
-        @original_schema = schema_definition.schema.dup
+        # Deep duplicate the raw schema hash so we can mutate it safely
+        @original_schema = deep_dup(schema_definition.schema)
 
         # We'll collect required property names in this Set
         @required_properties = Set.new
 
+        # Collect models that are referenced via $ref for $defs generation
+        @ref_models = Set.new
+
         # Usually the name is a string (class name). Fallback to :klass if nil.
         name_for_builder = schema_definition.name ? schema_definition.name.to_sym : :klass
 
@@ -53,6 +57,24 @@ module EasyTalk
 
       private
 
+      ##
+      # Deep duplicates a hash, including nested hashes.
+      # This prevents mutations from leaking back to the original schema.
+      #
+      def deep_dup(obj)
+        case obj
+        when Hash
+          obj.transform_values { |v| deep_dup(v) }
+        when Array
+          obj.map { |v| deep_dup(v) }
+        when Class, Module
+          # Don't duplicate Class or Module objects - they represent types
+          obj
+        else
+          obj.duplicable? ? obj.dup : obj
+        end
+      end
+
       ##
       # Main aggregator: merges the top-level schema keys (like :properties, :subschemas)
       # into a single hash that we'll feed to BaseBuilder.
@@ -60,12 +82,20 @@ module EasyTalk
         # Start with a copy of the raw schema
         merged = @original_schema.dup
 
+        # Remove schema_version and schema_id as they're handled separately in json_schema output
+        merged.delete(:schema_version)
+        merged.delete(:schema_id)
+
         # Extract and build sub-schemas first (handles allOf/anyOf/oneOf references, etc.)
         process_subschemas(merged)
 
         # Build :properties into a final form (and find "required" props)
+        # This also collects models that use $ref into @ref_models
         merged[:properties] = build_properties(merged.delete(:properties))
 
+        # Add $defs for any models that are referenced via $ref
+        add_ref_model_defs(merged) if @ref_models.any?
+
         # Populate the final "required" array from @required_properties
         merged[:required] = @required_properties.to_a if @required_properties.any?
 
@@ -88,16 +118,18 @@ module EasyTalk
         # Cache with a key based on property name and its full configuration
         @properties_cache ||= {}
 
-        properties_hash.each_with_object({}) do |(prop_name, prop_options), result|
-          cache_key = [prop_name, prop_options].hash
+        properties_hash.each_with_object({}) do |(original_name, prop_options), result|
+          # Use :as constraint for property name without mutating original constraints
+          property_name = (prop_options[:constraints][:as] || original_name).to_sym
+          cache_key = [property_name, prop_options].hash
 
           # Use cache if the exact property and configuration have been processed before
           @properties_cache[cache_key] ||= begin
-            mark_required_unless_optional(prop_name, prop_options)
-            build_property(prop_name, prop_options)
+            mark_required_unless_optional(property_name, prop_options)
+            build_property(property_name, prop_options)
           end
 
-          result[prop_name] = @properties_cache[cache_key]
+          result[property_name] = @properties_cache[cache_key]
         end
       end
 
@@ -127,17 +159,94 @@ module EasyTalk
       ##
       # Builds a single property. Could be a nested schema if it has sub-properties,
       # or a standard scalar property (String, Integer, etc.).
+      # Also tracks EasyTalk models that should be added to $defs when using $ref.
       #
       def build_property(prop_name, prop_options)
         @property_cache ||= {}
 
         # Memoize so we only build each property once
         @property_cache[prop_name] ||= begin
-          # Remove optional constraints from the property
-          constraints = prop_options[:constraints].except(:optional)
+          # Remove internal constraints that shouldn't be passed to Property
+          constraints = prop_options[:constraints].except(:optional, :as)
+          prop_type = prop_options[:type]
+
+          # Track models that will use $ref for later $defs generation
+          collect_ref_models(prop_type, constraints)
+
           # Normal property: e.g. { type: String, constraints: {...} }
-          Property.new(prop_name, prop_options[:type], constraints)
+          Property.new(prop_name, prop_type, constraints)
+        end
+      end
+
+      ##
+      # Collects EasyTalk models that will be referenced via $ref.
+      # These models need to be added to $defs in the final schema.
+      #
+      def collect_ref_models(prop_type, constraints)
+        # Check if this type should use $ref
+        if should_collect_ref?(prop_type, constraints)
+          @ref_models.add(prop_type)
+        elsif prop_type.is_a?(EasyTalk::Types::Composer)
+          collect_ref_models(prop_type.items, constraints)
+        # Handle typed arrays with EasyTalk model items
+        elsif typed_array?(prop_type)
+          extract_inner_types(prop_type).each { |inner_type| collect_ref_models(inner_type, constraints) }
+        # Handle nilable types
+        elsif nilable_with_model?(prop_type)
+          actual_type = T::Utils::Nilable.get_underlying_type(prop_type)
+          @ref_models.add(actual_type) if should_collect_ref?(actual_type, constraints)
+        end
+      end
+
+      ##
+      # Determines if a type should be collected for $ref based on config and constraints.
+      #
+      def should_collect_ref?(check_type, constraints)
+        return false unless ModelHelper.easytalk_model?(check_type)
+
+        # Per-property constraint takes precedence
+        return constraints[:ref] if constraints.key?(:ref)
+
+        # Fall back to global configuration
+        EasyTalk.configuration.use_refs
+      end
+
+      def typed_array?(prop_type)
+        prop_type.is_a?(T::Types::TypedArray)
+      end
+
+      def extract_inner_types(prop_type)
+        return [] unless typed_array?(prop_type)
+
+        if prop_type.type.is_a?(EasyTalk::Types::Composer)
+          prop_type.type.items
+        else
+          [prop_type.type.raw_type]
+        end
+      end
+
+      ##
+      # Checks if type is nilable and contains an EasyTalk model.
+      #
+      def nilable_with_model?(prop_type)
+        return false unless prop_type.respond_to?(:types)
+        return false unless prop_type.types.all? { |t| t.respond_to?(:raw_type) }
+        return false unless prop_type.types.any? { |t| t.raw_type == NilClass }
+
+        actual_type = T::Utils::Nilable.get_underlying_type(prop_type)
+        ModelHelper.easytalk_model?(actual_type)
+      end
+
+      ##
+      # Adds $defs entries for all collected ref models.
+      #
+      def add_ref_model_defs(schema_hash)
+        definitions = @ref_models.each_with_object({}) do |model, acc|
+          acc[model.name] = model.schema
         end
+
+        existing_defs = schema_hash[:defs] || {}
+        schema_hash[:defs] = existing_defs.merge(definitions)
       end
 
       ##