easy_talk 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce558538c73afc10d98c0c6b5e38e68ce033a79d1c212bb91fede27f10fb3523
-  data.tar.gz: e46a7a67b6c1a3209108a800cefca8659381236c23ce14986e971babd874908d
+  metadata.gz: b091eaff6c33ddcc23f0c5d0147bf28f94a7421c95a0ca47ad917af8e42fad20
+  data.tar.gz: 9a6c0de5afff453a566940b7b1684e2075e70b53379b2bf3b7583a46ca370c58
 SHA512:
-  metadata.gz: b523e6cd50edc0594d98fffdb8a9de0616e5f58a2af435a23e5f4a81ac54b25692cd0bccba71c93eca812022efd298b2a9d654b34e3b8f37301ea8e7b16a4de3
-  data.tar.gz: 7f287df819b0e09ddf5fce9506f045860dea876b0653cf7ede7dfb58e7a1d78e545933946921f0dfb4f1f02709357629f0b071c53e7c4ff945cdcf1908f5c2b6
+  metadata.gz: 32a49bfa38a5279340b6699ff26d8ac415c1574f83da1488d403d422d4b49cd4aea94d5424d858c5ae2326e914c4e83995a97eb67fe4b005543e6f8984d6a60c
+  data.tar.gz: 02ad31d7b34aac67a4777a709ffb286487675f28e6a2c18757dd87e7a006743ab6cd0f75b817fdb6abb23d3f9ef63384fcbd5f063e1eb2d0dc8a06c7107ae0e0

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+## [3.1.0] - 2025-12-18
+
+### Added
+- **JSON Schema `$schema` Keyword Support**: Added ability to declare which JSON Schema draft version schemas conform to
+  - New `schema_version` configuration option supporting Draft-04, Draft-06, Draft-07, Draft 2019-09, and Draft 2020-12
+  - Global configuration via `EasyTalk.configure { |c| c.schema_version = :draft202012 }`
+  - Per-model override using `schema_version` keyword in `define_schema` block
+  - Support for custom schema URIs
+  - `$schema` only appears at root level (not in nested models)
+  - Default is `:none` for backward compatibility
+
+- **JSON Schema `$id` Keyword Support**: Added ability to provide a unique identifier URI for schemas
+  - New `schema_id` configuration option for setting schema identifiers
+  - Global configuration via `EasyTalk.configure { |c| c.schema_id = 'https://example.com/schema.json' }`
+  - Per-model override using `schema_id` keyword in `define_schema` block
+  - Supports absolute URIs, relative URIs, and URN formats
+  - `$id` only appears at root level (not in nested models)
+  - Default is `nil` for backward compatibility
+
+- **JSON Schema `$ref` and `$defs` Support**: Added ability to reference reusable schema definitions for nested models
+  - New `use_refs` configuration option to globally enable `$ref` for nested EasyTalk models
+  - Global configuration via `EasyTalk.configure { |c| c.use_refs = true }`
+  - Per-property override using `ref: true` or `ref: false` constraint
+  - Nested models are automatically added to `$defs` when `$ref` is enabled
+  - Supports direct model properties, `T::Array[Model]`, and `T.nilable(Model)` types
+  - Nilable models with `$ref` use `anyOf` with `$ref` and `null` type
+  - Multiple references to the same model only create one `$defs` entry
+  - Additional constraints (title, description) can be combined with `$ref`
+  - Default is `false` for backward compatibility (nested schemas are inlined)
+
 ## [3.0.0] - 2025-01-03
 
 ### BREAKING CHANGES

data/README.md

@@ -16,6 +16,9 @@ EasyTalk is a Ruby library that simplifies defining and generating JSON Schema.
 * **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.
 
 ### Use Cases
 - API request/response validation
@@ -589,6 +592,10 @@ EasyTalk.configure do |config|
   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
 end
 ```
 
@@ -1168,17 +1175,657 @@ bundle exec rubocop
 ### Contributing Guidelines
 Bug reports and pull requests are welcome on GitHub at https://github.com/sergiobayona/easy_talk.
 
+## JSON Schema Version (`$schema` Keyword)
+
+The `$schema` keyword declares which JSON Schema dialect (draft version) a schema conforms to. EasyTalk supports configuring this at both the global and per-model level.
+
+### Why Use `$schema`?
+
+The `$schema` keyword:
+- Declares the JSON Schema version your schema is written against
+- Helps validators understand which specification to use
+- Enables tooling to provide appropriate validation and autocomplete
+- Documents the schema dialect for consumers of your API
+
+### Supported Draft Versions
+
+EasyTalk supports the following JSON Schema draft versions:
+
+| Symbol | JSON Schema Version | URI |
+|--------|---------------------|-----|
+| `:draft202012` | Draft 2020-12 (latest) | `https://json-schema.org/draft/2020-12/schema` |
+| `:draft201909` | Draft 2019-09 | `https://json-schema.org/draft/2019-09/schema` |
+| `:draft7` | Draft-07 | `http://json-schema.org/draft-07/schema#` |
+| `:draft6` | Draft-06 | `http://json-schema.org/draft-06/schema#` |
+| `:draft4` | Draft-04 | `http://json-schema.org/draft-04/schema#` |
+| `:none` | No `$schema` output (default) | N/A |
+
+### Global Configuration
+
+Configure the schema version globally to apply to all models:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_version = :draft202012  # Use JSON Schema Draft 2020-12
+end
+```
+
+With this configuration, all models will include `$schema` in their output:
+
+```ruby
+class User
+  include EasyTalk::Model
+
+  define_schema do
+    property :name, String
+  end
+end
+
+User.json_schema
+# => {
+#      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+#      "type" => "object",
+#      "properties" => { "name" => { "type" => "string" } },
+#      "required" => ["name"],
+#      "additionalProperties" => false
+#    }
+```
+
+### Per-Model Configuration
+
+Override the global setting for individual models using the `schema_version` keyword in the schema definition:
+
+```ruby
+class LegacyModel
+  include EasyTalk::Model
+
+  define_schema do
+    schema_version :draft7  # Use Draft-07 for this specific model
+    property :name, String
+  end
+end
+
+LegacyModel.json_schema
+# => {
+#      "$schema" => "http://json-schema.org/draft-07/schema#",
+#      "type" => "object",
+#      ...
+#    }
+```
+
+### Disabling `$schema` for Specific Models
+
+If you have a global schema version configured but want to exclude `$schema` from a specific model, use `:none`:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_version = :draft202012  # Global default
+end
+
+class InternalModel
+  include EasyTalk::Model
+
+  define_schema do
+    schema_version :none  # No $schema for this model
+    property :data, String
+  end
+end
+
+InternalModel.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => { "data" => { "type" => "string" } },
+#      ...
+#    }
+# Note: No "$schema" key present
+```
+
+### Custom Schema URIs
+
+You can also specify a custom URI if you're using a custom meta-schema or a different schema registry:
+
+```ruby
+class CustomModel
+  include EasyTalk::Model
+
+  define_schema do
+    schema_version 'https://my-company.com/schemas/v1/meta-schema.json'
+    property :id, String
+  end
+end
+```
+
+### Nested Models
+
+The `$schema` keyword only appears at the root level of the schema. When you have nested EasyTalk models, only the top-level model's `json_schema` output will include `$schema`:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_version = :draft202012
+end
+
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address
+  end
+end
+
+User.json_schema
+# => {
+#      "$schema" => "https://json-schema.org/draft/2020-12/schema",  # Only at root
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => {
+#          "type" => "object",  # No $schema here
+#          "properties" => { "city" => { "type" => "string" } },
+#          ...
+#        }
+#      },
+#      ...
+#    }
+```
+
+### Default Behavior
+
+By default, `schema_version` is set to `:none`, meaning no `$schema` keyword is included in the generated schemas. This maintains backward compatibility with previous versions of EasyTalk.
+
+### Best Practices
+
+1. **Choose a version appropriate for your validators**: If you're using a specific JSON Schema validator, check which drafts it supports.
+
+2. **Use Draft 2020-12 for new projects**: It's the latest stable version with the most features.
+
+3. **Be consistent**: Use global configuration for consistency across your application, and only override per-model when necessary.
+
+4. **Consider your consumers**: If your schemas are consumed by external systems, ensure they support the draft version you're using.
+
+## Schema Identifier (`$id` Keyword)
+
+The `$id` keyword provides a unique identifier for your JSON Schema document. EasyTalk supports configuring this at both the global and per-model level.
+
+### Why Use `$id`?
+
+The `$id` keyword:
+- Establishes a unique URI identifier for the schema
+- Enables referencing schemas from other documents via `$ref`
+- Provides a base URI for resolving relative references within the schema
+- Documents the canonical location of the schema
+
+### Global Configuration
+
+Configure the schema ID globally to apply to all models:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_id = 'https://example.com/schemas/base.json'
+end
+```
+
+With this configuration, all models will include `$id` in their output:
+
+```ruby
+class User
+  include EasyTalk::Model
+
+  define_schema do
+    property :name, String
+  end
+end
+
+User.json_schema
+# => {
+#      "$id" => "https://example.com/schemas/base.json",
+#      "type" => "object",
+#      "properties" => { "name" => { "type" => "string" } },
+#      "required" => ["name"],
+#      "additionalProperties" => false
+#    }
+```
+
+### Per-Model Configuration
+
+Override the global setting for individual models using the `schema_id` keyword in the schema definition:
+
+```ruby
+class User
+  include EasyTalk::Model
+
+  define_schema do
+    schema_id 'https://example.com/schemas/user.schema.json'
+    property :name, String
+    property :email, String
+  end
+end
+
+User.json_schema
+# => {
+#      "$id" => "https://example.com/schemas/user.schema.json",
+#      "type" => "object",
+#      ...
+#    }
+```
+
+### Disabling `$id` for Specific Models
+
+If you have a global schema ID configured but want to exclude `$id` from a specific model, use `:none`:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_id = 'https://example.com/schemas/default.json'
+end
+
+class InternalModel
+  include EasyTalk::Model
+
+  define_schema do
+    schema_id :none  # No $id for this model
+    property :data, String
+  end
+end
+
+InternalModel.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => { "data" => { "type" => "string" } },
+#      ...
+#    }
+# Note: No "$id" key present
+```
+
+### Combining `$schema` and `$id`
+
+When both `$schema` and `$id` are configured, they appear in the standard order (`$schema` first, then `$id`):
+
+```ruby
+class Product
+  include EasyTalk::Model
+
+  define_schema do
+    schema_version :draft202012
+    schema_id 'https://example.com/schemas/product.schema.json'
+    property :name, String
+    property :price, Float
+  end
+end
+
+Product.json_schema
+# => {
+#      "$schema" => "https://json-schema.org/draft/2020-12/schema",
+#      "$id" => "https://example.com/schemas/product.schema.json",
+#      "type" => "object",
+#      ...
+#    }
+```
+
+### Nested Models
+
+The `$id` keyword only appears at the root level of the schema. When you have nested EasyTalk models, only the top-level model's `json_schema` output will include `$id`:
+
+```ruby
+EasyTalk.configure do |config|
+  config.schema_id = 'https://example.com/schemas/user.json'
+end
+
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :city, String
+  end
+end
+
+class User
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address
+  end
+end
+
+User.json_schema
+# => {
+#      "$id" => "https://example.com/schemas/user.json",  # Only at root
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => {
+#          "type" => "object",  # No $id here
+#          "properties" => { "city" => { "type" => "string" } },
+#          ...
+#        }
+#      },
+#      ...
+#    }
+```
+
+### URI Formats
+
+The `$id` accepts various URI formats:
+
+```ruby
+# Absolute URI (recommended for published schemas)
+schema_id 'https://example.com/schemas/user.schema.json'
+
+# Relative URI
+schema_id 'user.schema.json'
+
+# URN format
+schema_id 'urn:example:user-schema'
+```
+
+### Default Behavior
+
+By default, `schema_id` is set to `nil`, meaning no `$id` keyword is included in the generated schemas. This maintains backward compatibility with previous versions of EasyTalk.
+
+### Best Practices
+
+1. **Use absolute URIs for published schemas**: This ensures global uniqueness and enables external references.
+
+2. **Follow a consistent naming convention**: For example, `https://yourdomain.com/schemas/{model-name}.schema.json`.
+
+3. **Keep IDs stable**: Once published, avoid changing schema IDs as external systems may reference them.
+
+4. **Combine with `$schema`**: When publishing schemas, include both `$schema` (for validation) and `$id` (for identification).
+
+## Schema References (`$ref` and `$defs`)
+
+The `$ref` keyword allows you to reference reusable schema definitions, reducing duplication when the same model is used in multiple places. EasyTalk supports automatic `$ref` generation for nested models.
+
+### Why Use `$ref`?
+
+The `$ref` keyword:
+- Reduces schema duplication when the same model appears multiple times
+- Produces cleaner, more organized schemas
+- Improves schema readability and maintainability
+- Aligns with JSON Schema best practices for reusable definitions
+
+### Default Behavior (Inline Schemas)
+
+By default, EasyTalk inlines nested model schemas directly:
+
+```ruby
+class Address
+  include EasyTalk::Model
+  define_schema do
+    property :street, String
+    property :city, String
+  end
+end
+
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address
+  end
+end
+
+Person.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => {
+#          "type" => "object",
+#          "properties" => {
+#            "street" => { "type" => "string" },
+#            "city" => { "type" => "string" }
+#          },
+#          ...
+#        }
+#      },
+#      ...
+#    }
+```
+
+### Enabling `$ref` References
+
+#### Global Configuration
+
+Enable `$ref` generation for all nested models:
+
+```ruby
+EasyTalk.configure do |config|
+  config.use_refs = true
+end
+```
+
+With this configuration, nested models are referenced via `$ref` and their definitions are placed in `$defs`:
+
+```ruby
+Person.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => { "$ref" => "#/$defs/Address" }
+#      },
+#      "$defs" => {
+#        "Address" => {
+#          "type" => "object",
+#          "properties" => {
+#            "street" => { "type" => "string" },
+#            "city" => { "type" => "string" }
+#          },
+#          ...
+#        }
+#      },
+#      ...
+#    }
+```
+
+#### Per-Property Configuration
+
+You can also enable `$ref` for specific properties using the `ref: true` constraint:
+
+```ruby
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address, ref: true  # Use $ref for this property
+  end
+end
+```
+
+Or disable `$ref` for specific properties when it's enabled globally:
+
+```ruby
+EasyTalk.configure do |config|
+  config.use_refs = true
+end
+
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, Address, ref: false  # Inline this property despite global setting
+  end
+end
+```
+
+### Arrays of Models
+
+When using `$ref` with arrays of models, the `$ref` applies to the array items:
+
+```ruby
+EasyTalk.configure do |config|
+  config.use_refs = true
+end
+
+class Company
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :addresses, T::Array[Address]
+  end
+end
+
+Company.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "addresses" => {
+#          "type" => "array",
+#          "items" => { "$ref" => "#/$defs/Address" }
+#        }
+#      },
+#      "$defs" => {
+#        "Address" => { ... }
+#      },
+#      ...
+#    }
+```
+
+You can also use the per-property `ref` constraint with arrays:
+
+```ruby
+property :addresses, T::Array[Address], ref: true
+```
+
+### Nilable Models with `$ref`
+
+When using `$ref` with nilable model types, EasyTalk uses `anyOf` to combine the reference with the null type:
+
+```ruby
+EasyTalk.configure do |config|
+  config.use_refs = true
+end
+
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :address, T.nilable(Address)
+  end
+end
+
+Person.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "address" => {
+#          "anyOf" => [
+#            { "$ref" => "#/$defs/Address" },
+#            { "type" => "null" }
+#          ]
+#        }
+#      },
+#      "$defs" => {
+#        "Address" => { ... }
+#      },
+#      ...
+#    }
+```
+
+### Multiple References to the Same Model
+
+When the same model is used multiple times, it only appears once in `$defs`:
+
+```ruby
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :name, String
+    property :home_address, Address, ref: true
+    property :work_address, Address, ref: true
+    property :shipping_addresses, T::Array[Address], ref: true
+  end
+end
+
+Person.json_schema
+# => {
+#      "type" => "object",
+#      "properties" => {
+#        "name" => { "type" => "string" },
+#        "home_address" => { "$ref" => "#/$defs/Address" },
+#        "work_address" => { "$ref" => "#/$defs/Address" },
+#        "shipping_addresses" => {
+#          "type" => "array",
+#          "items" => { "$ref" => "#/$defs/Address" }
+#        }
+#      },
+#      "$defs" => {
+#        "Address" => { ... }  # Only defined once
+#      },
+#      ...
+#    }
+```
+
+### Combining `$ref` with Other Constraints
+
+You can add additional constraints alongside `$ref`:
+
+```ruby
+class Person
+  include EasyTalk::Model
+  define_schema do
+    property :address, Address, ref: true, description: "Primary address", title: "Main Address"
+  end
+end
+
+Person.json_schema["properties"]["address"]
+# => {
+#      "$ref" => "#/$defs/Address",
+#      "description" => "Primary address",
+#      "title" => "Main Address"
+#    }
+```
+
+### Interaction with `compose`
+
+When using `compose` with `T::AllOf`, `T::AnyOf`, or `T::OneOf`, the composed models are also placed in `$defs`:
+
+```ruby
+class Employee
+  include EasyTalk::Model
+  define_schema do
+    compose T::AllOf[Person, EmployeeDetails]
+    property :badge_number, String
+  end
+end
+```
+
+If you also have properties using `$ref`, both the composed models and property models will appear in `$defs`.
+
+### Best Practices
+
+1. **Use global configuration for consistency**: If you prefer `$ref` style, enable it globally rather than per-property.
+
+2. **Consider schema consumers**: Some JSON Schema validators and tools work better with inlined schemas, while others prefer `$ref`. Choose based on your use case.
+
+3. **Use `$ref` for frequently reused models**: If a model appears in many places, `$ref` reduces schema size and improves maintainability.
+
+4. **Keep inline for simple, single-use models**: For models used only once, inlining may be more readable.
+
+### Default Behavior
+
+By default, `use_refs` is set to `false`, meaning nested models are inlined. This maintains backward compatibility with previous versions of EasyTalk.
+
 ## JSON Schema Compatibility
 
 ### Supported Versions
-EasyTalk 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.
+EasyTalk supports generating schemas compatible with JSON Schema Draft-04 through Draft 2020-12. Use the `schema_version` configuration option to declare which version your schemas conform to (see [JSON Schema Version](#json-schema-version-schema-keyword) above).
+
+While EasyTalk allows you to specify any draft version via the `$schema` keyword, the generated schema structure is generally compatible across versions. Some newer draft features may require manual adjustment.
 
 ### Specification Compliance
 To learn about current capabilities, see the [spec/easy_talk/examples](https://github.com/sergiobayona/easy_talk/tree/main/spec/easy_talk/examples) folder. The examples illustrate how EasyTalk generates JSON Schema in different scenarios.
 
 ### Known Limitations
 - Limited support for custom formats
-- No direct support for JSON Schema draft 2020-12 features
+- Some draft-specific keywords may not be supported
 - Complex composition scenarios may require manual adjustment
 
 ## License

data/lib/easy_talk/builders/object_builder.rb

@@ -39,6 +39,9 @@ module EasyTalk
         # 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
 
@@ -60,12 +63,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?
 
@@ -127,6 +138,7 @@ 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 ||= {}
@@ -135,9 +147,91 @@ module EasyTalk
         @property_cache[prop_name] ||= begin
           # Remove optional constraints from the property
           constraints = prop_options[:constraints].except(:optional)
+          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)
+        # Handle typed arrays with EasyTalk model items
+        elsif typed_array_with_model?(prop_type)
+          inner_type = prop_type.type.raw_type
+          @ref_models.add(inner_type) if should_collect_ref?(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 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
+
+      ##
+      # Checks if a type is an EasyTalk model.
+      #
+      def easytalk_model?(check_type)
+        check_type.is_a?(Class) &&
+          check_type.respond_to?(:schema) &&
+          check_type.respond_to?(:ref_template) &&
+          defined?(EasyTalk::Model) &&
+          check_type.include?(EasyTalk::Model)
+      end
+
+      ##
+      # Checks if type is a typed array containing an EasyTalk model.
+      #
+      def typed_array_with_model?(prop_type)
+        return false unless prop_type.is_a?(T::Types::TypedArray)
+
+        inner_type = prop_type.type.raw_type
+        easytalk_model?(inner_type)
+      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)
+        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
 
       ##

data/lib/easy_talk/builders/typed_array_builder.rb

@@ -14,7 +14,8 @@ module EasyTalk
         max_items: { type: Integer, key: :maxItems },
         unique_items: { type: T::Boolean, key: :uniqueItems },
         enum: { type: T::Array[T.untyped], key: :enum },
-        const: { type: T::Array[T.untyped], key: :const }
+        const: { type: T::Array[T.untyped], key: :const },
+        ref: { type: T::Boolean, key: :ref }
       }.freeze
 
       attr_reader :type
@@ -35,7 +36,9 @@ module EasyTalk
       sig { returns(T::Hash[Symbol, T.untyped]) }
       def schema
         super.tap do |schema|
-          schema[:items] = Property.new(@name, inner_type, {}).build
+          # Pass ref constraint to items if present (for nested model references)
+          item_constraints = @options&.slice(:ref) || {}
+          schema[:items] = Property.new(@name, inner_type, item_constraints).build
         end
       end
 

data/lib/easy_talk/configuration.rb

@@ -2,12 +2,32 @@
 
 module EasyTalk
   class Configuration
-    attr_accessor :default_additional_properties, :nilable_is_optional, :auto_validations
+    # JSON Schema draft version URIs
+    SCHEMA_VERSIONS = {
+      draft202012: 'https://json-schema.org/draft/2020-12/schema',
+      draft201909: 'https://json-schema.org/draft/2019-09/schema',
+      draft7: 'http://json-schema.org/draft-07/schema#',
+      draft6: 'http://json-schema.org/draft-06/schema#',
+      draft4: 'http://json-schema.org/draft-04/schema#'
+    }.freeze
+
+    attr_accessor :default_additional_properties, :nilable_is_optional, :auto_validations, :schema_version, :schema_id,
+                  :use_refs
 
     def initialize
       @default_additional_properties = false
       @nilable_is_optional = false
       @auto_validations = true
+      @schema_version = :none
+      @schema_id = nil
+      @use_refs = false
+    end
+
+    # Returns the URI for the configured schema version, or nil if :none
+    def schema_uri
+      return nil if @schema_version == :none
+
+      SCHEMA_VERSIONS[@schema_version] || @schema_version.to_s
     end
   end
 

data/lib/easy_talk/keywords.rb

@@ -2,6 +2,8 @@
 
 module EasyTalk
   KEYWORDS = %i[
+    schema_id
+    schema_version
     description
     type
     title

data/lib/easy_talk/model.rb

@@ -155,12 +155,63 @@ module EasyTalk
       end
 
       # Returns the JSON schema for the model.
+      # This is the final output that includes the $schema keyword if configured.
       #
       # @return [Hash] The JSON schema for the model.
       def json_schema
-        @json_schema ||= schema.as_json
+        @json_schema ||= build_json_schema
       end
 
+      private
+
+      # Builds the final JSON schema with optional $schema and $id keywords.
+      def build_json_schema
+        result = schema.as_json
+        schema_uri = resolve_schema_uri
+        id_uri = resolve_schema_id
+
+        # Build prefix hash with $schema and $id (in that order per JSON Schema convention)
+        prefix = {}
+        prefix['$schema'] = schema_uri if schema_uri
+        prefix['$id'] = id_uri if id_uri
+
+        return result if prefix.empty?
+
+        prefix.merge(result)
+      end
+
+      # Resolves the schema URI from per-model setting or global config.
+      def resolve_schema_uri
+        model_version = @schema_definition&.schema&.dig(:schema_version)
+
+        if model_version
+          # Per-model override - :none means explicitly no $schema
+          return nil if model_version == :none
+
+          Configuration::SCHEMA_VERSIONS[model_version] || model_version.to_s
+        else
+          # Fall back to global configuration
+          EasyTalk.configuration.schema_uri
+        end
+      end
+
+      # Resolves the schema ID from per-model setting or global config.
+      def resolve_schema_id
+        model_id = @schema_definition&.schema&.dig(:schema_id)
+
+        if model_id
+          # Per-model override - :none means explicitly no $id
+          return nil if model_id == :none
+
+          model_id.to_s
+        else
+          # Fall back to global configuration
+          EasyTalk.configuration.schema_id
+        end
+      end
+
+      public
+
       # Define the schema for the model using the provided block.
       #
       # @yield The block to define the schema.

data/lib/easy_talk/property.rb

@@ -101,22 +101,31 @@ module EasyTalk
     # This method handles different types of properties:
     # - Nilable types (can be null)
     # - Types with dedicated builders
-    # - Types that implement their own schema method
+    # - Types that implement their own schema method (EasyTalk models)
     # - Default fallback to 'object' type
     #
+    # When use_refs is enabled (globally or per-property), EasyTalk models
+    # are referenced via $ref instead of being inlined.
+    #
     # @return [Hash] The complete JSON Schema property definition
     #
     # @example Simple string property
     #   property = Property.new(:name, 'String')
     #   property.build  # => {"type"=>"string"}
     #
-    # @example Complex nested schema
+    # @example Complex nested schema (inlined)
     #   address = Address.new  # A class with a .schema method
     #   property = Property.new(:shipping_address, address, description: "Shipping address")
     #   property.build  # => Address schema merged with the description constraint
+    #
+    # @example Nested schema with $ref
+    #   property = Property.new(:shipping_address, Address, ref: true)
+    #   property.build  # => {"$ref"=>"#/$defs/Address", ...constraints}
     def build
       if nilable_type?
         build_nilable_schema
+      elsif should_use_ref?
+        build_ref_schema
       elsif builder
         args = builder.collection_type? ? [name, type, constraints] : [name, constraints]
         builder.new(*args).build
@@ -193,6 +202,14 @@ module EasyTalk
 
       return { type: 'null' } unless actual_type
 
+      # Check if the underlying type is an EasyTalk model that should use $ref
+      if easytalk_model?(actual_type) && should_use_ref_for_type?(actual_type)
+        # Use anyOf with $ref and null type
+        ref_constraints = constraints.except(:ref, :optional)
+        schema = { anyOf: [{ '$ref': actual_type.ref_template }, { type: 'null' }] }
+        return ref_constraints.empty? ? schema : schema.merge(ref_constraints)
+      end
+
       # Create a property with the actual type
       non_nil_schema = Property.new(name, actual_type, constraints).build
 
@@ -201,5 +218,54 @@ module EasyTalk
         type: [non_nil_schema[:type], 'null'].compact
       )
     end
+
+    # Determines if $ref should be used for the current type.
+    #
+    # @return [Boolean] true if $ref should be used, false otherwise
+    # @api private
+    def should_use_ref?
+      return false unless easytalk_model?(type)
+
+      should_use_ref_for_type?(type)
+    end
+
+    # Determines if $ref should be used for a given type based on constraints and config.
+    #
+    # @param check_type [Class] The type to check
+    # @return [Boolean] true if $ref should be used, false otherwise
+    # @api private
+    def should_use_ref_for_type?(check_type)
+      return false unless 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
+
+    # Checks if a type is an EasyTalk model.
+    #
+    # @param check_type [Object] The type to check
+    # @return [Boolean] true if the type is an EasyTalk model
+    # @api private
+    def easytalk_model?(check_type)
+      check_type.is_a?(Class) &&
+        check_type.respond_to?(:schema) &&
+        check_type.respond_to?(:ref_template) &&
+        defined?(EasyTalk::Model) &&
+        check_type.include?(EasyTalk::Model)
+    end
+
+    # Builds a $ref schema for an EasyTalk model.
+    #
+    # @return [Hash] A schema with $ref pointing to the model's definition
+    # @api private
+    def build_ref_schema
+      # Remove ref and optional from constraints as they're not JSON Schema keywords
+      ref_constraints = constraints.except(:ref, :optional)
+      schema = { '$ref': type.ref_template }
+      ref_constraints.empty? ? schema : schema.merge(ref_constraints)
+    end
   end
 end

data/lib/easy_talk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EasyTalk
-  VERSION = '3.0.0'
+  VERSION = '3.1.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: easy_talk
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Sergio Bayona
 bindir: bin
 cert_chain: []
-date: 2025-09-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -147,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.7.2
 specification_version: 4
 summary: Generate json-schema from Ruby classes with ActiveModel integration.
 test_files: []