{"id":19791438,"url":"https://github.com/sergiobayona/easy_talk","last_synced_at":"2025-04-24T05:04:57.380Z","repository":{"id":226099563,"uuid":"767708206","full_name":"sergiobayona/easy_talk","owner":"sergiobayona","description":"Ruby gem for defining and generating JSON Schema","archived":false,"fork":false,"pushed_at":"2025-04-10T15:19:46.000Z","size":377,"stargazers_count":40,"open_issues_count":4,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-24T05:04:35.940Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sergiobayona.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-05T18:57:36.000Z","updated_at":"2025-04-21T19:28:41.000Z","dependencies_parsed_at":"2024-03-18T22:27:54.849Z","dependency_job_id":"464f8648-2a40-490b-bcaa-e7c1baa8cecf","html_url":"https://github.com/sergiobayona/easy_talk","commit_stats":null,"previous_names":["sergiobayona/easy_talk"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergiobayona%2Feasy_talk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergiobayona%2Feasy_talk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergiobayona%2Feasy_talk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergiobayona%2Feasy_talk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sergiobayona","download_url":"https://codeload.github.com/sergiobayona/easy_talk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250566458,"owners_count":21451231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T07:02:12.657Z","updated_at":"2025-04-24T05:04:57.369Z","avatar_url":"https://github.com/sergiobayona.png","language":"Ruby","funding_links":[],"categories":["Ruby","API Builder and Discovery"],"sub_categories":[],"readme":"# EasyTalk\n\n## Introduction\n\n### What is EasyTalk?\nEasyTalk 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.\n\n### Key Features\n* **Intuitive Schema Definition**: Use Ruby classes and methods to define JSON Schema documents easily.\n* **Works for plain Ruby classes and ActiveRecord models**: Integrate with existing code or build from scratch.\n* **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.\n* **Schema Composition**: Define EasyTalk models and reference them in other EasyTalk models to create complex schemas.\n* **Validation**: Write validations using ActiveModel's validations.\n\n### Use Cases\n- API request/response validation\n- LLM function definitions\n- Object structure documentation\n- Data validation and transformation\n- Configuration schema definitions\n\n### Inspiration\nInspired by Python's Pydantic library, EasyTalk brings similar functionality to the Ruby ecosystem, providing a Ruby-friendly approach to JSON Schema operations.\n\n## Installation\n\n### Requirements\n- Ruby 3.2 or higher\n\n### Installation Steps\nAdd EasyTalk to your application's Gemfile:\n\n```ruby\ngem 'easy_talk'\n```\n\nOr install it directly:\n\n```bash\n$ gem install easy_talk\n```\n\n### Verification\nAfter installation, you can verify it's working by creating a simple model:\n\n```ruby\nrequire 'easy_talk'\n\nclass Test\n  include EasyTalk::Model\n  \n  define_schema do\n    property :name, String\n  end\nend\n\nputs Test.json_schema\n```\n\n## Quick Start\n\n### Minimal Example\nHere's a basic example to get you started with EasyTalk:\n\n```ruby\nclass User\n  include EasyTalk::Model\n\n  define_schema do\n    title \"User\"\n    description \"A user of the system\"\n    property :name, String, description: \"The user's name\"\n    property :email, String, format: \"email\"\n    property :age, Integer, minimum: 18\n  end\nend\n```\n\n### Generated JSON Schema\nCalling `User.json_schema` will generate:\n\n```ruby\n{\n  \"type\" =\u003e \"object\",\n  \"title\" =\u003e \"User\",\n  \"description\" =\u003e \"A user of the system\",\n  \"properties\" =\u003e {\n    \"name\" =\u003e {\n      \"type\" =\u003e \"string\", \n      \"description\" =\u003e \"The user's name\"\n    },\n    \"email\" =\u003e {\n      \"type\" =\u003e \"string\", \n      \"format\" =\u003e \"email\"\n    },\n    \"age\" =\u003e {\n      \"type\" =\u003e \"integer\", \n      \"minimum\" =\u003e 18\n    }\n  },\n  \"required\" =\u003e [\"name\", \"email\", \"age\"]\n}\n```\n\n### Basic Usage\nCreating and validating an instance of your model:\n\n```ruby\nuser = User.new(name: \"John Doe\", email: \"john@example.com\", age: 25)\nuser.valid? # =\u003e true\n\nuser.age = 17\nuser.valid? # =\u003e false\n```\n\n## Core Concepts\n\n### Schema Definition\nIn EasyTalk, you define your schema by including the `EasyTalk::Model` module and using the `define_schema` method. This method takes a block where you can define the properties and constraints of your schema.\n\n```ruby\nclass MyModel\n  include EasyTalk::Model\n\n  define_schema do\n    title \"My Model\"\n    description \"Description of my model\"\n    property :some_property, String\n    property :another_property, Integer\n  end\nend\n```\n\n### Property Types\n\n#### Ruby Types\nEasyTalk supports standard Ruby types directly:\n\n- `String`: String values\n- `Integer`: Integer values\n- `Float`: Floating-point numbers\n- `Date`: Date values\n- `DateTime`: Date and time values\n- `Hash`: Object/dictionary values\n\n#### Sorbet-Style Types\nFor complex types, EasyTalk uses Sorbet-style type notation:\n\n- `T::Boolean`: Boolean values (true/false)\n- `T::Array[Type]`: Arrays with items of a specific type\n- `T.nilable(Type)`: Type that can also be nil\n\n#### Custom Types\nEasyTalk supports special composition types:\n\n- `T::AnyOf[Type1, Type2, ...]`: Value can match any of the specified schemas\n- `T::OneOf[Type1, Type2, ...]`: Value must match exactly one of the specified schemas\n- `T::AllOf[Type1, Type2, ...]`: Value must match all of the specified schemas\n\n### Property Constraints\nProperty constraints depend on the type of property. Some common constraints include:\n\n- `description`: A description of the property\n- `title`: A title for the property\n- `format`: A format hint for the property (e.g., \"email\", \"date\")\n- `enum`: A list of allowed values\n- `minimum`/`maximum`: Minimum/maximum values for numbers\n- `min_length`/`max_length`: Minimum/maximum length for strings\n- `pattern`: A regular expression pattern for strings\n- `min_items`/`max_items`: Minimum/maximum number of items for arrays\n- `unique_items`: Whether array items must be unique\n\n### Required vs Optional Properties\nBy default, all properties defined in an EasyTalk model are required. You can make a property optional by specifying `optional: true`:\n\n```ruby\ndefine_schema do\n  property :name, String\n  property :middle_name, String, optional: true\nend\n```\n\nIn this example, `name` is required but `middle_name` is optional.\n\n### Schema Validation\nEasyTalk models include ActiveModel validations. You can validate your models using the standard ActiveModel validation methods:\n\n```ruby\nclass User\n  include EasyTalk::Model\n  \n  validates :name, presence: true\n  validates :age, numericality: { greater_than_or_equal_to: 18 }\n  \n  define_schema do\n    property :name, String\n    property :age, Integer, minimum: 18\n  end\nend\n\nuser = User.new(name: \"John\", age: 17)\nuser.valid? # =\u003e false\nuser.errors.full_messages # =\u003e [\"Age must be greater than or equal to 18\"]\n```\n\n## Defining Schemas\n\n### Basic Schema Structure\nA schema definition consists of a class that includes `EasyTalk::Model` and a `define_schema` block:\n\n```ruby\nclass Person\n  include EasyTalk::Model\n\n  define_schema do\n    title \"Person\"\n    property :name, String\n    property :age, Integer\n  end\nend\n```\n\n### Property Definitions\nProperties are defined using the `property` method, which takes a name, a type, and optional constraints:\n\n```ruby\nproperty :name, String, description: \"The person's name\", title: \"Full Name\"\nproperty :age, Integer, minimum: 0, maximum: 120, description: \"The person's age\"\n```\n\n### Arrays and Collections\nArrays can be defined using the `T::Array` type:\n\n```ruby\nproperty :tags, T::Array[String], min_items: 1, unique_items: true\nproperty :scores, T::Array[Integer], description: \"List of scores\"\n```\n\nYou can also define arrays of complex types:\n\n```ruby\nproperty :addresses, T::Array[Address], description: \"List of addresses\"\n```\n\n### Constraints and Validations\nConstraints can be added to properties and are used for schema generation:\n\n```ruby\nproperty :name, String, min_length: 2, max_length: 50\nproperty :email, String, format: \"email\"\nproperty :category, String, enum: [\"A\", \"B\", \"C\"], default: \"A\"\n```\n\nFor validation, you can use ActiveModel validations:\n\n```ruby\nvalidates :name, presence: true, length: { minimum: 2, maximum: 50 }\nvalidates :email, format: { with: URI::MailTo::EMAIL_REGEXP }\nvalidates :category, inclusion: { in: [\"A\", \"B\", \"C\"] }\n```\n\n### Additional Properties\nBy default, EasyTalk models do not allow additional properties beyond those defined in the schema. You can change this behavior using the `additional_properties` keyword:\n\n```ruby\ndefine_schema do\n  property :name, String\n  additional_properties true\nend\n```\n\nWith `additional_properties true`, you can add arbitrary properties to your model instances:\n\n```ruby\ncompany = Company.new\ncompany.name = \"Acme Corp\"        # Defined property\ncompany.location = \"New York\"     # Additional property\ncompany.employee_count = 100      # Additional property\n```\n\n## Schema Composition\n\n### Using T::AnyOf\nThe `T::AnyOf` type allows a property to match any of the specified schemas:\n\n```ruby\nclass Payment\n  include EasyTalk::Model\n\n  define_schema do\n    property :details, T::AnyOf[CreditCard, Paypal, BankTransfer]\n  end\nend\n```\n\n### Using T::OneOf\nThe `T::OneOf` type requires a property to match exactly one of the specified schemas:\n\n```ruby\nclass Contact\n  include EasyTalk::Model\n\n  define_schema do\n    property :contact, T::OneOf[PhoneContact, EmailContact]\n  end\nend\n```\n\n### Using T::AllOf\nThe `T::AllOf` type requires a property to match all of the specified schemas:\n\n```ruby\nclass VehicleRegistration\n  include EasyTalk::Model\n  \n  define_schema do\n    compose T::AllOf[VehicleIdentification, OwnerInfo, RegistrationDetails]\n  end\nend\n```\n\n### Complex Compositions\nYou can combine composition types to create complex schemas:\n\n```ruby\nclass ComplexObject\n  include EasyTalk::Model\n  \n  define_schema do\n    property :basic_info, BaseInfo\n    property :specific_details, T::OneOf[DetailTypeA, DetailTypeB]\n    property :metadata, T::AnyOf[AdminMetadata, UserMetadata, nil]\n  end\nend\n```\n\n### Reusing Models\nModels can reference other models to create hierarchical schemas:\n\n```ruby\nclass Address\n  include EasyTalk::Model\n  \n  define_schema do\n    property :street, String\n    property :city, String\n    property :state, String\n    property :zip, String\n  end\nend\n\nclass User\n  include EasyTalk::Model\n  \n  define_schema do\n    property :name, String\n    property :address, Address\n  end\nend\n```\n\n## ActiveModel Integration\n\n### Validations\nEasyTalk models include ActiveModel validations:\n\n```ruby\nclass User\n  include EasyTalk::Model\n  \n  validates :age, comparison: { greater_than: 21 }\n  validates :height, presence: true, numericality: { greater_than: 0 }\n  \n  define_schema do\n    property :name, String\n    property :age, Integer\n    property :height, Float\n  end\nend\n```\n\n### Error Handling\nYou can access validation errors using the standard ActiveModel methods:\n\n```ruby\nuser = User.new(name: \"Jim\", age: 18, height: -5.9)\nuser.valid? # =\u003e false\nuser.errors[:age] # =\u003e [\"must be greater than 21\"]\nuser.errors[:height] # =\u003e [\"must be greater than 0\"]\n```\n\n### Model Attributes\nEasyTalk models provide getters and setters for all defined properties:\n\n```ruby\nuser = User.new\nuser.name = \"John\"\nuser.age = 30\nputs user.name # =\u003e \"John\"\n```\n\nYou can also initialize a model with a hash of attributes:\n\n```ruby\nuser = User.new(name: \"John\", age: 30, height: 5.9)\n```\n\n## ActiveRecord Integration\n\n### Automatic Schema Generation\nFor ActiveRecord models, EasyTalk automatically generates a schema based on the database columns:\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  include EasyTalk::Model\nend\n```\n\nThis will create a schema with properties for each column in the `products` table.\n\n### Enhancing Generated Schemas\nYou can enhance the auto-generated schema with the `enhance_schema` method:\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  include EasyTalk::Model\n  \n  enhance_schema({\n    title: \"Retail Product\",\n    description: \"A product available for purchase\",\n    properties: {\n      name: {\n        description: \"Product display name\",\n        title: \"Product Name\"\n      },\n      price: {\n        description: \"Retail price in USD\"\n      }\n    }\n  })\nend\n```\n\n### Column Exclusion Options\nEasyTalk provides several ways to exclude columns from your JSON schema:\n\n#### 1. Global Configuration\n\n```ruby\nEasyTalk.configure do |config|\n  # Exclude specific columns by name from all models\n  config.excluded_columns = [:created_at, :updated_at, :deleted_at]\n  \n  # Exclude all foreign key columns (columns ending with '_id')\n  config.exclude_foreign_keys = true   # Default: false\n  \n  # Exclude all primary key columns ('id')\n  config.exclude_primary_key = true    # Default: true\n  \n  # Exclude timestamp columns ('created_at', 'updated_at')\n  config.exclude_timestamps = true     # Default: true\n  \n  # Exclude all association properties\n  config.exclude_associations = true   # Default: false\nend\n```\n\n#### 2. Model-Specific Column Ignoring\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  include EasyTalk::Model\n  \n  enhance_schema({\n    ignore: [:internal_ref_id, :legacy_code]  # Model-specific exclusions\n  })\nend\n```\n\n### Virtual Properties\nYou can add properties that don't exist as database columns:\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  include EasyTalk::Model\n  \n  enhance_schema({\n    properties: {\n      full_details: {\n        virtual: true,\n        type: :string,\n        description: \"Complete product information\"\n      }\n    }\n  })\nend\n```\n\n### Associations and Foreign Keys\nBy default, EasyTalk includes your model's associations in the schema:\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  include EasyTalk::Model\n  belongs_to :category\n  has_many :reviews\nend\n```\n\nThis will include `category` (as an object) and `reviews` (as an array) in the schema.\n\nYou can control this behavior with configuration:\n\n```ruby\nEasyTalk.configure do |config|\n  config.exclude_associations = true    # Don't include associations  \n  config.exclude_foreign_keys = true    # Don't include foreign key columns\nend\n```\n\n## Advanced Features\n\n### LLM Function Generation\nEasyTalk provides a helper method for generating OpenAI function specifications:\n\n```ruby\nclass Weather\n  include EasyTalk::Model\n  \n  define_schema do\n    title \"GetWeather\"\n    description \"Get the current weather in a given location\"\n    property :location, String, description: \"The city and state, e.g. San Francisco, CA\"\n    property :unit, String, enum: [\"celsius\", \"fahrenheit\"], default: \"fahrenheit\"\n  end\nend\n\nfunction_spec = EasyTalk::Tools::FunctionBuilder.new(Weather)\n```\n\nThis generates a function specification compatible with OpenAI's function calling API.\n\n### Schema Transformation\nYou can transform EasyTalk schemas into various formats:\n\n```ruby\n# Get Ruby hash representation\nschema_hash = User.schema\n\n# Get JSON Schema representation\njson_schema = User.json_schema\n\n# Convert to JSON string\njson_string = User.json_schema.to_json\n```\n\n### Type Checking and Validation\nEasyTalk performs basic type checking during schema definition:\n\n```ruby\n# This will raise an error because \"minimum\" should be used with numeric types\nproperty :name, String, minimum: 1  # Error!\n\n# This will raise an error because enum values must match the property type\nproperty :age, Integer, enum: [\"young\", \"old\"]  # Error!\n```\n\n### Custom Type Builders\nFor advanced use cases, you can create custom type builders:\n\n```ruby\nmodule EasyTalk\n  module Builders\n    class MyCustomTypeBuilder \u003c BaseBuilder\n      # Custom implementation\n    end\n  end\nend\n```\n\n## Configuration\n\n### Global Settings\nYou can configure EasyTalk globally:\n\n```ruby\nEasyTalk.configure do |config|\n  config.excluded_columns = [:created_at, :updated_at, :deleted_at]\n  config.exclude_foreign_keys = true\n  config.exclude_primary_key = true\n  config.exclude_timestamps = true\n  config.exclude_associations = false\n  config.default_additional_properties = false\nend\n```\n\n### Per-Model Configuration\nSome settings can be configured per model:\n\n```ruby\nclass Product \u003c ActiveRecord::Base\n  include EasyTalk::Model\n  \n  enhance_schema({\n    additionalProperties: true,\n    ignore: [:internal_ref_id, :legacy_code]\n  })\nend\n```\n\n### Exclusion Rules\nColumns are excluded based on the following rules (in order of precedence):\n\n1. Explicitly listed in `excluded_columns` global setting\n2. Listed in the model's `schema_enhancements[:ignore]` array\n3. Is a primary key when `exclude_primary_key` is true (default)\n4. Is a timestamp column when `exclude_timestamps` is true (default)\n5. Matches a foreign key pattern when `exclude_foreign_keys` is true\n\n### Customizing Output\nYou can customize the JSON Schema output by enhancing the schema:\n\n```ruby\nclass User \u003c ActiveRecord::Base\n  include EasyTalk::Model\n  \n  enhance_schema({\n    title: \"User Account\",\n    description: \"User account information\",\n    properties: {\n      name: {\n        title: \"Full Name\",\n        description: \"User's full name\"\n      }\n    }\n  })\nend\n```\n\n## Examples\n\n### User Registration\n\n```ruby\nclass User\n  include EasyTalk::Model\n\n  validates :name, :email, :password, presence: true\n  validates :password, length: { minimum: 8 }\n  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }\n\n  define_schema do\n    title \"User Registration\"\n    description \"User registration information\"\n    property :name, String, description: \"User's full name\"\n    property :email, String, format: \"email\", description: \"User's email address\"\n    property :password, String, min_length: 8, description: \"User's password\"\n    property :notify, T::Boolean, default: true, description: \"Whether to send notifications\"\n  end\nend\n```\n\n### Payment Processing\n\n```ruby\nclass CreditCard\n  include EasyTalk::Model\n\n  define_schema do\n    property :CardNumber, String\n    property :CardType, String, enum: %w[Visa MasterCard AmericanExpress]\n    property :CardExpMonth, Integer, minimum: 1, maximum: 12\n    property :CardExpYear, Integer, minimum: Date.today.year, maximum: Date.today.year + 10\n    property :CardCVV, String, pattern: '^[0-9]{3,4}$'\n    additional_properties false\n  end\nend\n\nclass Paypal\n  include EasyTalk::Model\n\n  define_schema do\n    property :PaypalEmail, String, format: 'email'\n    property :PaypalPasswordEncrypted, String\n    additional_properties false\n  end\nend\n\nclass BankTransfer\n  include EasyTalk::Model\n\n  define_schema do\n    property :BankName, String\n    property :AccountNumber, String\n    property :RoutingNumber, String\n    property :AccountType, String, enum: %w[Checking Savings]\n    additional_properties false\n  end\nend\n\nclass Payment\n  include EasyTalk::Model\n\n  define_schema do\n    title 'Payment'\n    description 'Payment info'\n    property :PaymentMethod, String, enum: %w[CreditCard Paypal BankTransfer]\n    property :Details, T::AnyOf[CreditCard, Paypal, BankTransfer]\n  end\nend\n```\n\n### Complex Object Hierarchies\n\n```ruby\nclass Address\n  include EasyTalk::Model\n\n  define_schema do\n    property :street, String\n    property :city, String\n    property :state, String\n    property :zip, String, pattern: '^[0-9]{5}(?:-[0-9]{4})?$'\n  end\nend\n\nclass Employee\n  include EasyTalk::Model\n\n  define_schema do\n    title 'Employee'\n    description 'Company employee'\n    property :name, String, title: 'Full Name'\n    property :gender, String, enum: %w[male female other]\n    property :department, T.nilable(String)\n    property :hire_date, Date\n    property :active, T::Boolean, default: true\n    property :addresses, T.nilable(T::Array[Address])\n  end\nend\n\nclass Company\n  include EasyTalk::Model\n\n  define_schema do\n    title 'Company'\n    property :name, String\n    property :employees, T::Array[Employee], title: 'Company Employees', description: 'A list of company employees'\n  end\nend\n```\n\n### API Integration\n\n```ruby\n# app/controllers/api/users_controller.rb\nclass Api::UsersController \u003c ApplicationController\n  def create\n    schema = User.json_schema\n    \n    # Validate incoming request against the schema\n    validation_result = JSONSchemer.schema(schema).valid?(params.to_json)\n    \n    if validation_result\n      user = User.new(user_params)\n      if user.save\n        render json: user, status: :created\n      else\n        render json: { errors: user.errors }, status: :unprocessable_entity\n      end\n    else\n      render json: { errors: \"Invalid request\" }, status: :bad_request\n    end\n  end\n  \n  private\n  \n  def user_params\n    params.require(:user).permit(:name, :email, :password)\n  end\nend\n```\n\n## Troubleshooting\n\n### Common Errors\n\n#### \"Invalid property name\"\nProperty names must start with a letter or underscore and can only contain letters, numbers, and underscores:\n\n```ruby\n# Invalid\nproperty \"1name\", String  # Starts with a number\nproperty \"name!\", String  # Contains a special character\n\n# Valid\nproperty :name, String\nproperty :user_name, String\n```\n\n#### \"Property type is missing\"\nYou must specify a type for each property:\n\n```ruby\n# Invalid\nproperty :name\n\n# Valid\nproperty :name, String\n```\n\n#### \"Unknown option\"\nYou specified an option that is not valid for the property type:\n\n```ruby\n# Invalid (min_length is for strings, not integers)\nproperty :age, Integer, min_length: 2\n\n# Valid\nproperty :age, Integer, minimum: 18\n```\n\n### Schema Validation Issues\nIf you're having issues with validation:\n\n1. Make sure you've defined ActiveModel validations for your model\n2. Check for mismatches between schema constraints and validations\n3. Verify that required properties are present\n\n### Type Errors\nType errors usually occur when there's a mismatch between a property type and its constraints:\n\n```ruby\n# Error: enum values must be strings for a string property\nproperty :status, String, enum: [1, 2, 3]\n\n# Correct\nproperty :status, String, enum: [\"active\", \"inactive\", \"pending\"]\n```\n\n### Best Practices\n\n1. Define clear property names and descriptions\n2. Use appropriate types for each property\n3. Add validations for important business rules\n4. Keep schemas focused and modular\n5. Reuse models when appropriate\n6. Use explicit types instead of relying on inference\n7. Test your schemas with sample data\n\n# Nullable vs Optional Properties in EasyTalk\n\nOne 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.\n\n## Key Concepts\n\n| Concept | Description | JSON Schema Effect | EasyTalk Syntax |\n|---------|-------------|-------------------|-----------------|\n| **Nullable** | Property can have a `null` value | Adds `\"null\"` to the type array | `T.nilable(Type)` |\n| **Optional** | Property doesn't have to exist | Omits property from `\"required\"` array | `optional: true` constraint |\n\n## Nullable Properties\n\nA **nullable** property can contain a `null` value, but the property itself must still be present in the object:\n\n```ruby\nproperty :age, T.nilable(Integer)\n```\n\nThis produces the following JSON Schema:\n\n```json\n{\n  \"properties\": {\n    \"age\": { \"type\": [\"integer\", \"null\"] }\n  },\n  \"required\": [\"age\"]\n}\n```\n\nIn this case, the following data would be valid:\n- `{ \"age\": 25 }`\n- `{ \"age\": null }`\n\nBut this would be invalid:\n- `{ }` (missing the age property entirely)\n\n## Optional Properties\n\nAn **optional** property doesn't have to be present in the object at all:\n\n```ruby\nproperty :nickname, String, optional: true\n```\n\nThis produces:\n\n```json\n{\n  \"properties\": {\n    \"nickname\": { \"type\": \"string\" }\n  }\n  // Note: \"nickname\" is not in the \"required\" array\n}\n```\n\nIn this case, the following data would be valid:\n- `{ \"nickname\": \"Joe\" }`\n- `{ }` (omitting nickname entirely)\n\nBut this would be invalid:\n- `{ \"nickname\": null }` (null is not allowed because the property isn't nullable)\n\n## Nullable AND Optional Properties\n\nFor properties that should be both nullable and optional (can be omitted or null), you need to combine both approaches:\n\n```ruby\nproperty :bio, T.nilable(String), optional: true\n```\n\nThis produces:\n\n```json\n{\n  \"properties\": {\n    \"bio\": { \"type\": [\"string\", \"null\"] }\n  }\n  // Note: \"bio\" is not in the \"required\" array\n}\n```\n\nFor convenience, EasyTalk also provides a helper method:\n\n```ruby\nnullable_optional_property :bio, String\n```\n\nWhich is equivalent to the above.\n\n## Configuration Options\n\nBy default, nullable properties are still required. You can change this global behavior:\n\n```ruby\nEasyTalk.configure do |config|\n  config.nilable_is_optional = true # Makes all T.nilable properties also optional\nend\n```\n\nWith this configuration, any property defined with `T.nilable(Type)` will be treated as both nullable and optional.\n\n## Practical Examples\n\n### User Profile Schema\n\n```ruby\nclass UserProfile\n  include EasyTalk::Model\n  \n  define_schema do\n    # Required properties (must exist, cannot be null)\n    property :id, String\n    property :name, String\n    \n    # Required but nullable (must exist, can be null)\n    property :age, T.nilable(Integer)\n    \n    # Optional but not nullable (can be omitted, cannot be null if present)\n    property :email, String, optional: true\n    \n    # Optional and nullable (can be omitted, can be null if present)\n    nullable_optional_property :bio, String\n  end\nend\n```\n\nThis creates clear expectations for data validation:\n- `id` and `name` must be present and cannot be null\n- `age` must be present but can be null\n- `email` doesn't have to be present, but if it is, it cannot be null\n- `bio` doesn't have to be present, and if it is, it can be null\n\n## Common Gotchas\n\n### Misconception: Nullable Implies Optional\n\nA 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.\n\n### Misconception: Optional Properties Accept Null\n\nAn 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)`.\n\n## Migration from Earlier Versions\n\nIf 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.\n\nTo maintain backward compatibility with your existing code, you can use:\n\n```ruby\nEasyTalk.configure do |config|\n  config.nilable_is_optional = true # Makes T.nilable properties behave as they did before\nend\n```\n\nWe recommend updating your schema definitions to explicitly declare which properties are optional using the `optional: true` constraint, as this makes your intent clearer.\n\n## Best Practices\n\n1. **Be explicit about intent**: Always clarify whether properties should be nullable, optional, or both\n2. **Use the helper method**: For properties that are both nullable and optional, use `nullable_optional_property`\n3. **Document expectations**: Use comments to clarify validation requirements for complex schemas\n4. **Consider validation implications**: Remember that ActiveModel validations operate independently of the schema definition\n\n## JSON Schema Comparison\n\n| EasyTalk Definition | Required | Nullable | JSON Schema Equivalent |\n|--------------------|----------|----------|------------------------|\n| `property :p, String` | Yes | No | `{ \"properties\": { \"p\": { \"type\": \"string\" } }, \"required\": [\"p\"] }` |\n| `property :p, T.nilable(String)` | Yes | Yes | `{ \"properties\": { \"p\": { \"type\": [\"string\", \"null\"] } }, \"required\": [\"p\"] }` |\n| `property :p, String, optional: true` | No | No | `{ \"properties\": { \"p\": { \"type\": \"string\" } } }` |\n| `nullable_optional_property :p, String` | No | Yes | `{ \"properties\": { \"p\": { \"type\": [\"string\", \"null\"] } } }` |\n\n## Development and Contributing\n\n### Setting Up the Development Environment\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that lets you experiment.\n\nTo install this gem onto your local machine, run:\n\n```bash\nbundle exec rake install\n```\n\n### Running Tests\nRun the test suite with:\n\n```bash\nbundle exec rake spec\n```\n\n### Contributing Guidelines\nBug reports and pull requests are welcome on GitHub at https://github.com/sergiobayona/easy_talk.\n\n## JSON Schema Compatibility\n\n### Supported Versions\nEasyTalk 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.\n\n### Specification Compliance\nTo 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.\n\n### Known Limitations\n- Limited support for custom formats\n- No direct support for JSON Schema draft 2020-12 features\n- Complex composition scenarios may require manual adjustment\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergiobayona%2Feasy_talk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsergiobayona%2Feasy_talk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergiobayona%2Feasy_talk/lists"}