treaty 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fe35b7cf209d578b34ee7d904bdd146db4a3ac61f022a1f5f02c80bfe21875e
-  data.tar.gz: 4be4a2f29fbfb30115e696baeaf618eaf59fe5c2fc309a0d1ced3eff61713671
+  metadata.gz: a3fcf5acc02ad345e7ff61ba70124596a89be46af035b6ee5d4114de8509f883
+  data.tar.gz: bc5d32074c9cab57438851555fb6849014b52da7f0732517a54db2f48563a198
 SHA512:
-  metadata.gz: d256fd30a7553ebfc015c06049c4fc0edceddaa782b3b0bda807364568009465556e72867324bc4a707d61c52da579f5a40f4324922af4349f1a7553023a9443
-  data.tar.gz: 4d71a4831e946faf207b9c21947531f3bc6263941f07e3a627c2e504a8c471d6aec597fe167090c0d0d49979b3b4dbf2f8e0620cfe9cd12f492286f60b5a3e7a
+  metadata.gz: 3ebb477674d48c4e4e0aafa30eeb9ca3ad20dd96c65f19d38d31b55f6256b7e816768b149720662c9de239242a9aeab78ed038685dd0d82754b005c9e31380c8
+  data.tar.gz: b04b8248df32a42c41b833920cada319fcfb73344a7fa9520867b59fbba60655716f8152342f9a34765c06aa05d99160b7ff9812b826ff7bebca2ccd6a1cda94

data/README.md

@@ -13,7 +13,7 @@
 </div>
 
 > [!WARNING]
-> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.14.0"`) until the 1.0 release.
+> **Development Status**: Treaty is currently under active development in the 0.x version series. Breaking changes may occur between minor versions (0.x) as we refine the API and add new features. The library will stabilize with the 1.0 release. We recommend pinning to specific patch versions in your Gemfile (e.g., `gem "treaty", "~> 0.15.0"`) until the 1.0 release.
 
 ## 📚 Documentation
 
@@ -133,4 +133,4 @@ Thank you to all [contributors](https://github.com/servactory/treaty/graphs/cont
 
 ## 📄 License
 
-Treaty is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+Treaty is available as open source under the terms of the [MIT License](./LICENSE).

data/config/locales/en.yml

@@ -45,6 +45,7 @@ en:
       # Attribute options
       options:
         unknown: "Unknown options for attribute '%{attribute}': %{unknown}. Known options: %{known}"
+        message_evaluation_error: "Custom message evaluation failed for attribute '%{attribute}': %{error}"
 
       # Attribute modifiers
       modifiers:
@@ -62,6 +63,18 @@ en:
           conversion_not_supported: "Option 'cast' for attribute '%{attribute}' does not support conversion from '%{from}' to '%{to}'"
           conversion_error: "Cast failed for attribute '%{attribute}' from '%{from}' to '%{to}'. Value: '%{value}'. Error: %{error}"
 
+      # Attribute conditionals
+      conditionals:
+        if:
+          invalid_type: "Option 'if' for attribute '%{attribute}' must be a Proc or Lambda. Got: %{type}"
+          evaluation_error: "Conditional evaluation failed for attribute '%{attribute}': %{error}"
+
+        unless:
+          invalid_type: "Option 'unless' for attribute '%{attribute}' must be a Proc or Lambda. Got: %{type}"
+          evaluation_error: "Conditional evaluation failed for attribute '%{attribute}': %{error}"
+
+        mutual_exclusivity_error: "Attribute '%{attribute}' cannot have both 'if' and 'unless' options. Use only one conditional option."
+
       # Attribute builder DSL
       builder:
         not_implemented: "%{class} must implement #create_attribute"

data/lib/treaty/attribute/option/base.rb

@@ -143,10 +143,12 @@ module Treaty
 
         # Resolves custom message with lambda support
         # If message is a lambda, calls it with provided named arguments
+        # Catches all exceptions from lambda execution and re-raises as Validation errors
         #
         # @param attributes [Hash] Named arguments to pass to lambda
         # @return [String, nil] Resolved message string or nil
-        def resolve_custom_message(**attributes)
+        # @raise [Treaty::Exceptions::Validation] If custom message lambda raises an exception
+        def resolve_custom_message(**attributes) # rubocop:disable Metrics/MethodLength
           message = custom_message
           return nil if message.nil?
 
@@ -155,6 +157,15 @@ module Treaty
           else
             message
           end
+        rescue StandardError => e
+          # Catch all exceptions from custom message lambda execution
+          error_message = I18n.t(
+            "treaty.attributes.options.message_evaluation_error",
+            attribute: @attribute_name,
+            error: e.message
+          )
+
+          raise Treaty::Exceptions::Validation, error_message
         end
 
         # Checks if schema is in advanced mode

data/lib/treaty/attribute/option/conditionals/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Conditionals
+        # Base class for conditional option processors.
+        #
+        # ## Purpose
+        #
+        # Conditionals control whether an attribute should be processed at all.
+        # Unlike validators (which check data) and modifiers (which transform data),
+        # conditionals determine attribute visibility based on runtime conditions.
+        #
+        # ## Key Difference from Validators/Modifiers
+        #
+        # - **Validators**: Check if data is valid
+        # - **Modifiers**: Transform data values
+        # - **Conditionals**: Decide if attribute exists in output
+        #
+        # ## Processing
+        #
+        # Conditionals are evaluated BEFORE validators and modifiers:
+        # 1. If condition evaluates to `false` → attribute is skipped entirely
+        # 2. If condition evaluates to `true` → attribute is processed normally
+        #
+        # ## Mode Support
+        #
+        # Conditionals do NOT support simple/advanced modes.
+        # They only accept lambda/proc directly:
+        #
+        # ```ruby
+        # # Correct
+        # integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+        # array :tags, if: ->(post:) { post[:published_at].present? }
+        #
+        # # Incorrect - no simple/advanced mode
+        # integer :rating, if: true  # Not supported
+        # integer :rating, if: { is: ..., message: ... }  # Not supported
+        # ```
+        #
+        # ## Implementation
+        #
+        # Subclasses must implement:
+        # - `validate_schema!` - Validate the conditional schema at definition time
+        # - `evaluate_condition(data)` - Evaluate condition with runtime data
+        class Base < Treaty::Attribute::Option::Base
+          # Phase 1: Validates conditional schema
+          # Must be overridden in subclasses
+          #
+          # @raise [Treaty::Exceptions::Validation] If schema is invalid
+          # @return [void]
+          def validate_schema!
+            raise Treaty::Exceptions::NotImplemented,
+                  "#{self.class} must implement #validate_schema!"
+          end
+
+          # Evaluates the conditional with runtime data
+          # Must be overridden in subclasses
+          #
+          # @param _data [Hash] Raw data to evaluate condition against
+          # @raise [Treaty::Exceptions::Validation] If evaluation fails
+          # @return [Boolean] True if attribute should be processed, false otherwise
+          def evaluate_condition(_data)
+            raise Treaty::Exceptions::NotImplemented,
+                  "#{self.class} must implement #evaluate_condition"
+          end
+
+          # Conditionals do not validate values
+          # This is a no-op for conditionals
+          #
+          # @param _value [Object] The value (unused)
+          # @return [void]
+          def validate_value!(_value)
+            # No-op: conditionals don't validate values
+          end
+
+          # Conditionals do not transform values
+          # This is a no-op for conditionals
+          #
+          # @param value [Object] The value to pass through
+          # @return [Object] The unchanged value
+          def transform_value(value)
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/option/conditionals/if_conditional.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Conditionals
+        # Conditionally includes attributes based on runtime data evaluation.
+        #
+        # ## Usage Examples
+        #
+        # Basic usage with keyword arguments splat:
+        #   array :tags, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+        #   integer :rating, if: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+        #
+        # Named argument pattern:
+        #   array :tags, if: ->(post:) { post[:published_at].present? }
+        #   integer :views, if: ->(post:) { post[:published_at].present? }
+        #
+        # Complex conditions:
+        #   string :admin_note, if: ->(**attrs) {
+        #     attrs.dig(:user, :role) == "admin" && attrs.dig(:post, :flagged)
+        #   }
+        #
+        # ## Use Cases
+        #
+        # 1. **Show fields only when published**:
+        #    ```ruby
+        #    response 200 do
+        #      object :post do
+        #        string :id
+        #        string :title
+        #        datetime :published_at, :optional
+        #        integer :rating, if: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        #      end
+        #    end
+        #    # If published_at is nil → rating is excluded from response
+        #    # If published_at exists → rating is included
+        #    ```
+        #
+        # 2. **Role-based field visibility**:
+        #    ```ruby
+        #    response 200 do
+        #      object :user do
+        #        string :name
+        #        string :email, if: ->(user:) { user[:role] == "admin" }
+        #      end
+        #    end
+        #    ```
+        #
+        # 3. **Nested attribute conditionals**:
+        #    ```ruby
+        #    object :post do
+        #      string :title
+        #      array :tags, if: ->(post:) { post[:published_at].present? } do
+        #        string :_self
+        #      end
+        #    end
+        #    ```
+        #
+        # ## Important Notes
+        #
+        # - Lambda receives raw data as named arguments
+        # - Lambda MUST return truthy/falsy value
+        # - If condition is false → attribute is completely omitted
+        # - If condition is true → attribute is validated and transformed normally
+        # - All exceptions in lambda are caught and wrapped in Treaty::Exceptions::Validation
+        # - Does NOT support simple mode (if: true) or advanced mode (if: { is: ..., message: ... })
+        #
+        # ## Error Handling
+        #
+        # If the lambda raises any exception, it's caught and converted to a
+        # Treaty::Exceptions::Validation with detailed error message including:
+        # - Attribute name
+        # - Original exception message
+        #
+        # ## Data Access Pattern
+        #
+        # The lambda receives the same data structure that the orchestrator processes.
+        # For nested attributes, you can access parent data using dig:
+        #
+        # ```ruby
+        # # For response with { post: { title: "...", published_at: "..." } }
+        # integer :rating, if: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        #
+        # # Alternative: named argument pattern
+        # integer :rating, if: ->(post:) { post[:published_at].present? }
+        # ```
+        class IfConditional < Treaty::Attribute::Option::Conditionals::Base
+          # Validates that if option is a callable (Proc/Lambda)
+          #
+          # @raise [Treaty::Exceptions::Validation] If if is not a Proc/lambda
+          # @return [void]
+          def validate_schema!
+            conditional_lambda = @option_schema
+
+            return if conditional_lambda.respond_to?(:call)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.conditionals.if.invalid_type",
+                    attribute: @attribute_name,
+                    type: conditional_lambda.class
+                  )
+          end
+
+          # Evaluates the conditional lambda with runtime data
+          # Returns boolean indicating if attribute should be processed
+          #
+          # @param data [Hash] Raw data from request/response/entity
+          # @raise [Treaty::Exceptions::Validation] If lambda execution fails
+          # @return [Boolean] True if attribute should be processed, false to skip it
+          def evaluate_condition(data)
+            conditional_lambda = @option_schema
+
+            # Call lambda with raw data as named arguments
+            # The lambda can use **attributes or specific named args like post:
+            result = conditional_lambda.call(**data)
+
+            # Convert result to boolean
+            !!result
+          rescue StandardError => e
+            # Catch all exceptions from lambda execution
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.conditionals.if.evaluation_error",
+                    attribute: @attribute_name,
+                    error: e.message
+                  )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/option/conditionals/unless_conditional.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Treaty
+  module Attribute
+    module Option
+      module Conditionals
+        # Conditionally excludes attributes based on runtime data evaluation.
+        #
+        # ## Usage Examples
+        #
+        # Basic usage with keyword arguments splat:
+        #   array :tags, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+        #   integer :draft_views, unless: ->(**attributes) { attributes.dig(:post, :published_at).present? }
+        #
+        # Named argument pattern:
+        #   array :draft_notes, unless: ->(post:) { post[:published_at].present? }
+        #   integer :edit_count, unless: ->(post:) { post[:published_at].present? }
+        #
+        # Complex conditions:
+        #   string :internal_note, unless: ->(**attrs) {
+        #     attrs.dig(:user, :role) == "admin" && attrs.dig(:post, :flagged)
+        #   }
+        #
+        # ## Use Cases
+        #
+        # 1. **Hide fields when published**:
+        #    ```ruby
+        #    response 200 do
+        #      object :post do
+        #        string :id
+        #        string :title
+        #        datetime :published_at, :optional
+        #        integer :draft_views, unless: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        #      end
+        #    end
+        #    # If published_at is nil → draft_views is included in response
+        #    # If published_at exists → draft_views is excluded
+        #    ```
+        #
+        # 2. **Role-based field exclusion**:
+        #    ```ruby
+        #    response 200 do
+        #      object :user do
+        #        string :name
+        #        string :internal_id, unless: ->(user:) { user[:role] == "public" }
+        #      end
+        #    end
+        #    ```
+        #
+        # 3. **Nested attribute conditionals**:
+        #    ```ruby
+        #    object :post do
+        #      string :title
+        #      array :draft_notes, unless: ->(post:) { post[:published_at].present? } do
+        #        string :_self
+        #      end
+        #    end
+        #    ```
+        #
+        # ## Important Notes
+        #
+        # - Lambda receives raw data as named arguments
+        # - Lambda MUST return truthy/falsy value
+        # - If condition is true → attribute is completely omitted (OPPOSITE of `if`)
+        # - If condition is false → attribute is validated and transformed normally
+        # - All exceptions in lambda are caught and wrapped in Treaty::Exceptions::Validation
+        # - Does NOT support simple mode (unless: true) or advanced mode (unless: { is: ..., message: ... })
+        #
+        # ## Difference from `if` Option
+        #
+        # `unless` is the logical opposite of `if`:
+        # - `if` includes attribute when condition is TRUE
+        # - `unless` includes attribute when condition is FALSE
+        #
+        # ```ruby
+        # # These are equivalent:
+        # integer :rating, if: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        # integer :rating, unless: ->(**attrs) { attrs.dig(:post, :published_at).blank? }
+        #
+        # # These are also equivalent:
+        # integer :draft_views, unless: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        # integer :draft_views, if: ->(**attrs) { attrs.dig(:post, :published_at).blank? }
+        # ```
+        #
+        # ## Error Handling
+        #
+        # If the lambda raises any exception, it's caught and converted to a
+        # Treaty::Exceptions::Validation with detailed error message including:
+        # - Attribute name
+        # - Original exception message
+        #
+        # ## Data Access Pattern
+        #
+        # The lambda receives the same data structure that the orchestrator processes.
+        # For nested attributes, you can access parent data using dig:
+        #
+        # ```ruby
+        # # For response with { post: { title: "...", published_at: "..." } }
+        # integer :draft_views, unless: ->(**attrs) { attrs.dig(:post, :published_at).present? }
+        #
+        # # Alternative: named argument pattern
+        # integer :draft_views, unless: ->(post:) { post[:published_at].present? }
+        # ```
+        class UnlessConditional < Treaty::Attribute::Option::Conditionals::Base
+          # Validates that unless option is a callable (Proc/Lambda)
+          #
+          # @raise [Treaty::Exceptions::Validation] If unless is not a Proc/lambda
+          # @return [void]
+          def validate_schema!
+            conditional_lambda = @option_schema
+
+            return if conditional_lambda.respond_to?(:call)
+
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.conditionals.unless.invalid_type",
+                    attribute: @attribute_name,
+                    type: conditional_lambda.class
+                  )
+          end
+
+          # Evaluates the conditional lambda with runtime data
+          # Returns boolean indicating if attribute should be processed
+          #
+          # @param data [Hash] Raw data from request/response/entity
+          # @raise [Treaty::Exceptions::Validation] If lambda execution fails
+          # @return [Boolean] True if attribute should be processed (when condition is FALSE), false to skip it
+          def evaluate_condition(data)
+            conditional_lambda = @option_schema
+
+            # Call lambda with raw data as named arguments
+            # The lambda can use **attributes or specific named args like post:
+            result = conditional_lambda.call(**data)
+
+            # Convert result to boolean and NEGATE it (opposite of if)
+            # unless includes attribute when condition is FALSE
+            !result
+          rescue StandardError => e
+            # Catch all exceptions from lambda execution
+            raise Treaty::Exceptions::Validation,
+                  I18n.t(
+                    "treaty.attributes.conditionals.unless.evaluation_error",
+                    attribute: @attribute_name,
+                    error: e.message
+                  )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/treaty/attribute/option/registry.rb

@@ -3,7 +3,7 @@
 module Treaty
   module Attribute
     module Option
-      # Central registry for all option processors (validators and modifiers).
+      # Central registry for all option processors (validators, modifiers, and conditionals).
       #
       # ## Purpose
       #
@@ -14,7 +14,7 @@ module Treaty
       #
       # 1. **Registration** - Stores option processor classes
       # 2. **Retrieval** - Provides access to registered processors
-      # 3. **Categorization** - Organizes processors by category (validator/modifier)
+      # 3. **Categorization** - Organizes processors by category (validator/modifier/conditional)
       # 4. **Validation** - Checks if options are registered
       #
       # ## Registered Options
@@ -23,15 +23,23 @@ module Treaty
       # - `:required` → RequiredValidator
       # - `:type` → TypeValidator
       # - `:inclusion` → InclusionValidator
+      # - `:format` → FormatValidator
       #
       # ### Modifiers
       # - `:as` → AsModifier
       # - `:default` → DefaultModifier
+      # - `:transform` → TransformModifier
+      # - `:cast` → CastModifier
+      #
+      # ### Conditionals
+      # - `:if` → IfConditional
+      # - `:unless` → UnlessConditional
       #
       # ## Usage
       #
       # Registration (done in RegistryInitializer):
       #   Registry.register(:required, RequiredValidator, category: :validator)
+      #   Registry.register(:if, IfConditional, category: :conditional)
       #
       # Retrieval (done in OptionOrchestrator):
       #   processor_class = Registry.processor_for(:required)
@@ -111,6 +119,14 @@ module Treaty
                     .transform_values { |info| info.fetch(:processor_class) }
           end
 
+          # Get all conditionals
+          #
+          # @return [Hash] Hash of option_name => processor_class for conditionals
+          def conditionals
+            registry.select { |_, info| info.fetch(:category) == :conditional }
+                    .transform_values { |info| info.fetch(:processor_class) }
+          end
+
           # Reset registry (mainly for testing)
           def reset!
             @registry = nil

data/lib/treaty/attribute/option/registry_initializer.rb

@@ -7,14 +7,15 @@ module Treaty
       #
       # ## Purpose
       #
-      # Centralized registration point for all option processors (validators and modifiers).
+      # Centralized registration point for all option processors (validators, modifiers, and conditionals).
       # Automatically registers all built-in options when loaded.
       #
       # ## Responsibilities
       #
       # 1. **Validator Registration** - Registers all built-in validators
       # 2. **Modifier Registration** - Registers all built-in modifiers
-      # 3. **Auto-Loading** - Executes automatically when file is loaded
+      # 3. **Conditional Registration** - Registers all built-in conditionals
+      # 4. **Auto-Loading** - Executes automatically when file is loaded
       #
       # ## Built-in Validators
       #
@@ -30,6 +31,11 @@ module Treaty
       # - `:transform` → TransformModifier - Transforms values using custom lambdas
       # - `:cast` → CastModifier - Converts values between types automatically
       #
+      # ## Built-in Conditionals
+      #
+      # - `:if` → IfConditional - Conditionally includes attributes based on runtime data
+      # - `:unless` → UnlessConditional - Conditionally excludes attributes based on runtime data
+      #
       # ## Auto-Registration
       #
       # This file calls `register_all!` when loaded, ensuring all processors
@@ -63,6 +69,7 @@ module Treaty
           def register_all!
             register_validators!
             register_modifiers!
+            register_conditionals!
           end
 
           private
@@ -86,6 +93,14 @@ module Treaty
             Registry.register(:transform, Modifiers::TransformModifier, category: :modifier)
             Registry.register(:cast, Modifiers::CastModifier, category: :modifier)
           end
+
+          # Registers all built-in conditionals
+          #
+          # @return [void]
+          def register_conditionals!
+            Registry.register(:if, Conditionals::IfConditional, category: :conditional)
+            Registry.register(:unless, Conditionals::UnlessConditional, category: :conditional)
+          end
         end
       end
     end

data/lib/treaty/attribute/validation/nested_transformer.rb

@@ -79,6 +79,9 @@ module Treaty
             transformed = {}
 
             attribute.collection_of_attributes.each do |nested_attribute|
+              # Check if conditional (if/unless option) - skip attribute if condition evaluates to skip
+              next unless should_process_attribute?(nested_attribute, value)
+
               process_attribute(nested_attribute, value, transformed)
             end
 
@@ -87,6 +90,87 @@ module Treaty
 
           private
 
+          # Returns the conditional option name if present (:if or :unless)
+          # Raises error if both are present (mutual exclusivity)
+          #
+          # @param nested_attribute [Attribute::Base] The attribute to check
+          # @raise [Treaty::Exceptions::Validation] If both :if and :unless are present
+          # @return [Symbol, nil] :if, :unless, or nil
+          def conditional_option_for(nested_attribute) # rubocop:disable Metrics/MethodLength
+            has_if = nested_attribute.options.key?(:if)
+            has_unless = nested_attribute.options.key?(:unless)
+
+            if has_if && has_unless
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.mutual_exclusivity_error",
+                      attribute: nested_attribute.name
+                    )
+            end
+
+            return :if if has_if
+            return :unless if has_unless
+
+            nil
+          end
+
+          # Gets cached conditional processors for attributes or builds them
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def conditionals_for_attributes
+            @conditionals_for_attributes ||= build_conditionals_for_attributes
+          end
+
+          # Builds conditional processors for attributes with :if or :unless option
+          # Validates schema at definition time for performance
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def build_conditionals_for_attributes # rubocop:disable Metrics/MethodLength
+            attribute.collection_of_attributes.each_with_object({}) do |nested_attribute, cache|
+              # Get conditional option name (:if or :unless)
+              conditional_type = conditional_option_for(nested_attribute)
+              next if conditional_type.nil?
+
+              processor_class = Option::Registry.processor_for(conditional_type)
+              next if processor_class.nil?
+
+              # Create processor instance
+              conditional = processor_class.new(
+                attribute_name: nested_attribute.name,
+                attribute_type: nested_attribute.type,
+                option_schema: nested_attribute.options.fetch(conditional_type)
+              )
+
+              # Validate schema at definition time (not runtime)
+              conditional.validate_schema!
+
+              cache[nested_attribute] = conditional
+            end
+          end
+
+          # Checks if an attribute should be processed based on its conditional (if/unless option)
+          # Returns true if no conditional is defined or if conditional evaluates appropriately
+          #
+          # @param nested_attribute [Attribute::Base] The attribute to check
+          # @param source_hash [Hash] Source data to pass to conditional
+          # @return [Boolean] True if attribute should be processed, false to skip it
+          def should_process_attribute?(nested_attribute, source_hash)
+            # Check if attribute has a conditional option
+            conditional_type = conditional_option_for(nested_attribute)
+            return true if conditional_type.nil?
+
+            # Get cached conditional processor
+            conditional = conditionals_for_attributes[nested_attribute]
+            return true if conditional.nil?
+
+            # Evaluate condition with source hash data wrapped with parent object name
+            wrapped_data = { attribute.name => source_hash }
+            conditional.evaluate_condition(wrapped_data)
+          rescue StandardError
+            # If conditional evaluation fails, skip the attribute
+            false
+          end
+
           # Processes a single nested attribute
           # Validates, transforms, and adds to target hash
           #
@@ -117,7 +201,7 @@ module Treaty
         end
 
         # Transforms array with nested attributes
-        class ArrayTransformer
+        class ArrayTransformer # rubocop:disable Metrics/ClassLength
           SELF_OBJECT = :_self
           private_constant :SELF_OBJECT
 
@@ -147,6 +231,87 @@ module Treaty
 
           private
 
+          # Returns the conditional option name if present (:if or :unless)
+          # Raises error if both are present (mutual exclusivity)
+          #
+          # @param nested_attribute [Attribute::Base] The attribute to check
+          # @raise [Treaty::Exceptions::Validation] If both :if and :unless are present
+          # @return [Symbol, nil] :if, :unless, or nil
+          def conditional_option_for(nested_attribute) # rubocop:disable Metrics/MethodLength
+            has_if = nested_attribute.options.key?(:if)
+            has_unless = nested_attribute.options.key?(:unless)
+
+            if has_if && has_unless
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.mutual_exclusivity_error",
+                      attribute: nested_attribute.name
+                    )
+            end
+
+            return :if if has_if
+            return :unless if has_unless
+
+            nil
+          end
+
+          # Gets cached conditional processors for attributes or builds them
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def conditionals_for_attributes
+            @conditionals_for_attributes ||= build_conditionals_for_attributes
+          end
+
+          # Builds conditional processors for attributes with :if or :unless option
+          # Validates schema at definition time for performance
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def build_conditionals_for_attributes # rubocop:disable Metrics/MethodLength
+            attribute.collection_of_attributes.each_with_object({}) do |nested_attribute, cache|
+              # Get conditional option name (:if or :unless)
+              conditional_type = conditional_option_for(nested_attribute)
+              next if conditional_type.nil?
+
+              processor_class = Option::Registry.processor_for(conditional_type)
+              next if processor_class.nil?
+
+              # Create processor instance
+              conditional = processor_class.new(
+                attribute_name: nested_attribute.name,
+                attribute_type: nested_attribute.type,
+                option_schema: nested_attribute.options.fetch(conditional_type)
+              )
+
+              # Validate schema at definition time (not runtime)
+              conditional.validate_schema!
+
+              cache[nested_attribute] = conditional
+            end
+          end
+
+          # Checks if an attribute should be processed based on its conditional (if/unless option)
+          # Returns true if no conditional is defined or if conditional evaluates appropriately
+          #
+          # @param nested_attribute [Attribute::Base] The attribute to check
+          # @param source_hash [Hash] Source data to pass to conditional
+          # @return [Boolean] True if attribute should be processed, false to skip it
+          def should_process_attribute?(nested_attribute, source_hash)
+            # Check if attribute has a conditional option
+            conditional_type = conditional_option_for(nested_attribute)
+            return true if conditional_type.nil?
+
+            # Get cached conditional processor
+            conditional = conditionals_for_attributes[nested_attribute]
+            return true if conditional.nil?
+
+            # Evaluate condition with source hash data wrapped with parent array attribute name
+            wrapped_data = { attribute.name => source_hash }
+            conditional.evaluate_condition(wrapped_data)
+          rescue StandardError
+            # If conditional evaluation fails, skip the attribute
+            false
+          end
+
           # Checks if this is a simple array (primitive values)
           #
           # @return [Boolean] True if array contains primitive values with :_self attribute
@@ -163,8 +328,8 @@ module Treaty
           # @raise [Treaty::Exceptions::Validation] If validation fails
           # @return [Object] Transformed element value
           def transform_simple_element(item, index) # rubocop:disable Metrics/MethodLength
-            self_attr = attribute.collection_of_attributes.first
-            validator = AttributeValidator.new(self_attr)
+            self_attribute = attribute.collection_of_attributes.first
+            validator = AttributeValidator.new(self_attribute)
             validator.validate_schema!
 
             begin
@@ -201,6 +366,9 @@ module Treaty
             transformed = {}
 
             attribute.collection_of_attributes.each do |nested_attribute|
+              # Check if conditional (if/unless option) - skip attribute if condition evaluates to skip
+              next unless should_process_attribute?(nested_attribute, item)
+
               process_attribute(nested_attribute, item, transformed, index)
             end
 

data/lib/treaty/attribute/validation/orchestrator/base.rb

@@ -70,12 +70,16 @@ module Treaty
 
           # Validates and transforms all attributes
           # Iterates through attributes, processes them, handles :_self objects
+          # Skips attributes with false conditional (if/unless option)
           #
           # @return [Hash] Transformed data with all attributes processed
-          def validate!
+          def validate! # rubocop:disable Metrics/MethodLength
             transformed_data = {}
 
             collection_of_attributes.each do |attribute|
+              # Check if conditional (if/unless option) - skip attribute if condition evaluates to skip
+              next unless should_process_attribute?(attribute)
+
               transformed_value = validate_and_transform_attribute!(attribute)
 
               if attribute.name == SELF_OBJECT && attribute.type == :object
@@ -91,6 +95,49 @@ module Treaty
 
           private
 
+          # Returns the conditional option name if present (:if or :unless)
+          # Raises error if both are present (mutual exclusivity)
+          #
+          # @param attribute [Attribute::Base] The attribute to check
+          # @raise [Treaty::Exceptions::Validation] If both :if and :unless are present
+          # @return [Symbol, nil] :if, :unless, or nil
+          def conditional_option_for(attribute) # rubocop:disable Metrics/MethodLength
+            has_if = attribute.options.key?(:if)
+            has_unless = attribute.options.key?(:unless)
+
+            if has_if && has_unless
+              raise Treaty::Exceptions::Validation,
+                    I18n.t(
+                      "treaty.attributes.conditionals.mutual_exclusivity_error",
+                      attribute: attribute.name
+                    )
+            end
+
+            return :if if has_if
+            return :unless if has_unless
+
+            nil
+          end
+
+          # Checks if an attribute should be processed based on its conditional (if/unless option)
+          # Returns true if no conditional is defined or if conditional evaluates appropriately
+          #
+          # @param attribute [Attribute::Base] The attribute to check
+          # @return [Boolean] True if attribute should be processed, false to skip it
+          def should_process_attribute?(attribute)
+            # Check if attribute has a conditional option
+            conditional_type = conditional_option_for(attribute)
+            return true if conditional_type.nil?
+
+            # Get cached conditional processor
+            conditional = conditionals_for_attributes[attribute]
+            return true if conditional.nil?
+
+            # Evaluate condition with raw data
+            # The processor's evaluate_condition already handles if/unless logic
+            conditional.evaluate_condition(data)
+          end
+
           # Returns collection of attributes for this context
           # Must be implemented in subclasses
           #
@@ -119,6 +166,40 @@ module Treaty
             end
           end
 
+          # Gets cached conditional processors for attributes or builds them
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def conditionals_for_attributes
+            @conditionals_for_attributes ||= build_conditionals_for_attributes
+          end
+
+          # Builds conditional processors for attributes with :if or :unless option
+          # Validates schema at definition time for performance
+          #
+          # @return [Hash] Hash of attribute => conditional processor
+          def build_conditionals_for_attributes # rubocop:disable Metrics/MethodLength
+            collection_of_attributes.each_with_object({}) do |attribute, cache|
+              # Get conditional option name (:if or :unless)
+              conditional_type = conditional_option_for(attribute)
+              next if conditional_type.nil?
+
+              processor_class = Option::Registry.processor_for(conditional_type)
+              next if processor_class.nil?
+
+              # Create processor instance
+              conditional = processor_class.new(
+                attribute_name: attribute.name,
+                attribute_type: attribute.type,
+                option_schema: attribute.options.fetch(conditional_type)
+              )
+
+              # Validate schema at definition time (not runtime)
+              conditional.validate_schema!
+
+              cache[attribute] = conditional
+            end
+          end
+
           # Validates and transforms a single attribute
           # Handles both nested and regular attributes
           #

data/lib/treaty/result.rb

@@ -2,11 +2,12 @@
 
 module Treaty
   class Result
-    attr_reader :data, :status
+    attr_reader :data, :status, :version
 
-    def initialize(data:, status:)
+    def initialize(data:, status:, version:)
       @data = data
       @status = status
+      @version = version
     end
 
     def inspect
@@ -16,7 +17,7 @@ module Treaty
     private
 
     def draw_result
-      "@data=#{@data.inspect}, @status=#{@status.inspect}"
+      "@data=#{@data.inspect}, @status=#{@status.inspect}, @version=#{@version.inspect}"
     end
   end
 end

data/lib/treaty/version.rb

@@ -3,7 +3,7 @@
 module Treaty
   module VERSION
     MAJOR = 0
-    MINOR = 14
+    MINOR = 15
     PATCH = 0
     PRE = nil
 

data/lib/treaty/versions/workspace.rb

@@ -34,7 +34,8 @@ module Treaty
 
         Treaty::Result.new(
           data: validated_response,
-          status:
+          status:,
+          version: version_factory.version.version
         )
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: treaty
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Anton Sokolov
@@ -155,6 +155,9 @@ files:
 - lib/treaty/attribute/entity/builder.rb
 - lib/treaty/attribute/helper_mapper.rb
 - lib/treaty/attribute/option/base.rb
+- lib/treaty/attribute/option/conditionals/base.rb
+- lib/treaty/attribute/option/conditionals/if_conditional.rb
+- lib/treaty/attribute/option/conditionals/unless_conditional.rb
 - lib/treaty/attribute/option/modifiers/as_modifier.rb
 - lib/treaty/attribute/option/modifiers/cast_modifier.rb
 - lib/treaty/attribute/option/modifiers/default_modifier.rb