easy_talk 3.1.0 → 3.3.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
@@ -21,7 +23,7 @@ module EasyTalk
         params(
           property_name: Symbol,
           schema: T::Hash[Symbol, T.untyped],
-          options: T::Hash[Symbol, String],
+          options: T::Hash[Symbol, T.untyped],
           valid_options: T::Hash[Symbol, T.untyped]
         ).void
       end
@@ -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
@@ -57,6 +59,7 @@ module EasyTalk
         end
       end
 
+      sig { returns(T::Boolean) }
       def self.collection_type?
         false
       end

data/lib/easy_talk/builders/boolean_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 
@@ -14,7 +15,7 @@ module EasyTalk
         default: { type: T::Boolean, key: :default }
       }.freeze
 
-      sig { params(name: Symbol, constraints: Hash).void }
+      sig { params(name: Symbol, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, constraints = {})
         super(name, { type: 'boolean' }, constraints, VALID_OPTIONS)
       end

data/lib/easy_talk/builders/collection_helpers.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
+# typed: true
 
 module EasyTalk
   module Builders
     # Base builder class for array-type properties.
     module CollectionHelpers
+      extend T::Sig
+
+      sig { returns(T::Boolean) }
       def collection_type?
         true
       end

data/lib/easy_talk/builders/composition_builder.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'collection_helpers'
+require_relative '../ref_helper'
 
 module EasyTalk
   module Builders
@@ -15,22 +17,24 @@ module EasyTalk
         'OneOfBuilder' => 'oneOf'
       }.freeze
 
-      sig { params(name: Symbol, type: T.untyped, _constraints: Hash).void }
+      sig { params(name: Symbol, type: T.untyped, constraints: T::Hash[Symbol, T.untyped]).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.
       #
-      # @return [void]
+      # @return [Hash] The composed JSON schema.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
       def build
         @context[@name.to_sym] = {
           type: 'object',
@@ -41,6 +45,7 @@ module EasyTalk
       # Returns the composer keyword based on the composer type.
       #
       # @return [String] The composer keyword.
+      sig { returns(T.nilable(String)) }
       def composer_keyword
         COMPOSER_TO_KEYWORD[@composer_type]
       end
@@ -48,19 +53,16 @@ module EasyTalk
       # Returns an array of schemas for the composed JSON schema.
       #
       # @return [Array<Hash>] The array of schemas.
+      sig { returns(T::Array[T.untyped]) }
       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
@@ -68,6 +70,7 @@ module EasyTalk
       # Returns the items of the type.
       #
       # @return [T.untyped] The items of the type.
+      sig { returns(T.untyped) }
       def items
         @type.items
       end

data/lib/easy_talk/builders/integer_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 
@@ -20,7 +21,7 @@ module EasyTalk
       }.freeze
 
       # Initializes a new instance of the IntegerBuilder class.
-      sig { params(name: Symbol, constraints: Hash).void }
+      sig { params(name: Symbol, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, constraints = {})
         super(name, { type: 'integer' }, constraints, VALID_OPTIONS)
       end

data/lib/easy_talk/builders/null_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 
@@ -6,8 +7,10 @@ module EasyTalk
   module Builders
     # builder class for Null properties.
     class NullBuilder < BaseBuilder
+      extend T::Sig
+
       # Initializes a new instance of the NullBuilder class.
-      sig { params(name: Symbol, _constraints: Hash).void }
+      sig { params(name: Symbol, _constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, _constraints = {})
         super(name, { type: 'null' }, {}, {})
       end

data/lib/easy_talk/builders/number_builder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 
 require_relative 'base_builder'
 
@@ -6,6 +7,8 @@ module EasyTalk
   module Builders
     # Builder class for number properties.
     class NumberBuilder < BaseBuilder
+      extend T::Sig
+
       VALID_OPTIONS = {
         multiple_of: { type: T.any(Integer, Float), key: :multipleOf },
         minimum: { type: T.any(Integer, Float), key: :minimum },
@@ -18,7 +21,7 @@ module EasyTalk
       }.freeze
 
       # Initializes a new instance of the NumberBuilder class.
-      sig { params(name: Symbol, constraints: Hash).void }
+      sig { params(name: Symbol, constraints: T::Hash[Symbol, T.untyped]).void }
       def initialize(name, constraints = {})
         super(name, { type: 'number' }, constraints, VALID_OPTIONS)
       end