action_spec 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9218555ca7d33709a7a5b22528f6900358e36247c123e521f2342d7a36ac02b5
-  data.tar.gz: e771af58669e707ccbcc922b6d9afa726a2b25817ab4836e01ce1154bd22344b
+  metadata.gz: 06b66175d9094e2a53ff6c65cdfd88ad24f91724535ff8e0152341e079d18d0b
+  data.tar.gz: 562f73d96c1f1d57a72ec04e866a14a14fbcf0e12df757ed3b9a334a977450cd
 SHA512:
-  metadata.gz: 7d03ee8f19de7c1c874302344eadf224f9aa3fba2dab228f2f4b44448a2865ba53dd97385587b6b9691308e4a987048b1eab6e5f55a1b03ef93424a643857a0c
-  data.tar.gz: 357fe37dc9a591740079c76dd3e4238a9485cb0d1e57ab020bed09bf737d1937ef22b777f8b062f78473fe497965c2df754ee3858a97f77bdd59674002cdda69
+  metadata.gz: 581a39acd1d534f2c81647d8f9877423bcb53e6ea2ef0deab20c071c88a9fd160351721591e8af4007f2d9543c8375089017247a2a48a1314cb76421d40f08c5
+  data.tar.gz: 8db69ee15a9ac6cf205e8ce40563456f498cb6a2b31ee87104ce1fe524fc33efe46caf11fb151d114380c599ecd3060eaa910185d1915ed6e42e9959186a8af6

data/README.md

@@ -10,8 +10,9 @@ Concise and Powerful API Documentation Solution for Rails. [中文](README_zh.md
 
 ## Table Of Contents
 
-1. [OpenAPI Generation](#openapi-generation)
-2. [Doc DSL](#doc-dsl)
+1. [AI Agent Quick Reference](#ai-agent-quick-reference)
+2. [OpenAPI Generation](#openapi-generation)
+3. [Doc DSL](#doc-dsl)
    1. [`doc`](#doc)
    2. [`doc_dry`](#doc_dry)
    3. [DSL Inside `doc`](#dsl-inside-doc)
@@ -20,21 +21,21 @@ Concise and Powerful API Documentation Solution for Rails. [中文](README_zh.md
       3. [`openapi false`](#openapi-false)
       4. [Scope](#scope)
       5. [Response](#response)
-3. [Schemas](#schemas)
+4. [Schemas](#schemas)
    1. [Declare A Required Field](#declare-a-required-field)
    2. [Field Types](#field-types)
    3. [Field Options](#field-options)
    4. [Schemas From ActiveRecord](#schemas-from-activerecord)
    5. [Type And Boundary Matrix](#type-and-boundary-matrix)
-4. [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
+5. [Parameter Validation And Type Coercion](#parameter-validation-and-type-coercion)
    1. [Validation Flow](#validation-flow)
    2. [Reading Processed Values With `px`](#reading-processed-values-with-px)
    3. [`px` is Whitelist Extraction](#px-is-whitelist-extraction)
    4. [Errors](#errors)
-5. [Configuration And I18n](#configuration-and-i18n)
+6. [Configuration And I18n](#configuration-and-i18n)
    1. [Configuration](#configuration)
    2. [I18n](#i18n)
-6. [AI Generation Style Guide](#ai-generation-style-guide)
+7. [AI Generation Style Guide](#ai-generation-style-guide)
 
 ## Example
 
@@ -71,6 +72,18 @@ class UsersController < ApplicationController
 end
 ```
 
+## AI Agent Quick Reference
+
+When generating Rails controller code with ActionSpec, use these as the canonical choices:
+
+- put `doc { }` or `doc("Summary") { }` immediately above the action method and let ActionSpec infer the action name
+- use `{ }` blocks inside `doc`
+- prefer bang required syntax, such as `query! :id, Integer` and `name!: String`; keep `required: true` for compatibility or generated schemas
+- fold simple nested hash fields, `data: { }`, or `in_xxx(...)` declarations into one line when they have 2 fields or fewer and no complex nesting, such as `json data: { name: String, age: Integer }` or `in_query(name: String, value: String)`
+- declare body fields as `json data: { name!: String }` or `form data: { avatar!: File }`
+- use `doc_dry`, `scope`, `transform`, `px` / `px_key`, `.schemas`, and `px.slice` to keep controller actions small
+- rely on ActionSpec for parameter validation, type coercion, defaults, and similar contracts instead of rewriting the same parameter handling by hand
+
 ## Installation
 
 ```ruby
@@ -142,7 +155,7 @@ def create
 end
 ```
 
-You can also bind it explicitly when you want the action name declared in place:
+Escape hatch: bind the action explicitly when the inferred next method is not the intended action:
 
 ```ruby
 doc(:create, "Create user") {
@@ -201,7 +214,17 @@ cookie! :remember_token, String
 
 Bang methods mark the field as required. For example, `query! :page, Integer` means the request must include `page`, and the value must not be `nil`. Blank values are still allowed unless you set `blank: false`.
 
-If you prefer not to use bang methods, you can also write `required: true`:
+You can also change that default globally:
+
+```ruby
+ActionSpec.configure do |config|
+  config.required_allow_blank = false
+end
+```
+
+With `required_allow_blank = false`, required fields reject blank strings unless that field explicitly sets `blank:` or `allow_blank:`.
+
+Compatibility alternative: if you prefer not to use bang methods, you can also write `required: true`:
 
 ```ruby
 query :page, Integer, required: true
@@ -275,7 +298,16 @@ Notes:
 You can also opt an action out of OpenAPI generation from either `doc` or `doc_dry`:
 
 ```ruby
-openapi false
+doc(openapi: false) { }
+doc_dry(:index, openapi: false)
+```
+
+Or inside the block:
+
+```ruby
+doc {
+  openapi false
+}
 ```
 
 #### Scope
@@ -371,7 +403,9 @@ Meaning of `!`:
 
 You can also use `required: true` instead of bang syntax for parameters, nested fields, and the root request body.
 
-`required` in ActionSpec means "present and not `nil`". It does not reject blank strings by itself. If you want to reject blank values, use `blank: false` or `allow_blank: false`.
+`required` in ActionSpec means "present and not `nil`". By default it does not reject blank strings. You can keep that default, change it globally with `config.required_allow_blank`, or override it per field with `blank:` / `allow_blank:`.
+
+When blank values are allowed, type coercion does not fail just because the input is an empty string. If the field can still carry a meaningful blank value, such as `String`, the original blank string stays in `px`. Otherwise, ActionSpec stores `nil` for that field. For example, `""` stays `""` for `String`, but becomes `nil` for `Date`.
 
 #### Field Types
 
@@ -425,21 +459,59 @@ query :today, Date, default: -> { Time.current.to_date }
 query :status, String, enum: %w[draft published]
 query :score, Integer, range: { ge: 1, le: 5 }
 query :slug, String, pattern: /\A[a-z\-]+\z/
-query :title, String, blank: false # or allow_blank: false
+query :title, String, blank: false
 
 query :nickname, String, transform: :downcase
 query :page, Integer, transform: -> { it + 1 }, px: :page_number
-query :request_id, String, px_key: :trace_id
-query :end_at, Integer, validate: -> { it >= px[:start_at] }
+query :end_at, Integer, validate: -> { current_user && it >= px[:start_at] }
+query :birthday, Date, error: "birthday error"
 ```
 
-Notes:
-
-- `transform` accepts a `Symbol` or a `Proc` and runs **after coercion**, before the value is written into `px`
-- `px` and `px_key` customize the key name written into `px`; `px` is the short form of `px_key`
-- `validate` accepts a `Proc` and runs **after all parameters have been resolved, coerced, transformed, and written into `px`**
-- `validate` runs in the current controller context, so it can read `px` and call methods such as `current_user`
-- when `validate` returns `false` or `nil`, the field adds an `invalid` error
+- `required`
+  - Marks the field as required.
+  - Can replace bang syntax when you do not use `name!:`.
+- `default`
+  - Default value used when the field is missing.
+  - Can be a literal or `-> { }`.
+- `enum`
+  - Restricts the field to values from a fixed set.
+- `range`
+  - Numeric range constraints.
+  - Available: `ge` / `gt` / `le` / `lt`
+- `pattern`
+  - Regex constraint.
+- `length`
+  - Length constraints.
+  - Available: `minimum` / `maximum` / `is`
+- `blank` / `allow_blank`
+  - Controls whether blank values are allowed.
+  - For fields such as `Date`, if blank is allowed, no type coercion is applied and the value becomes `nil`.
+
+- `desc`
+  - Used only for OpenAPI description generation.
+- `example`
+  - Used only for generating a single OpenAPI example.
+- `examples`
+  - Used only for generating multiple OpenAPI examples.
+
+- `transform`
+  - Applies one more custom transformation to the **already-coerced value**.
+  - Accepts a `Symbol` or a `Proc`.
+  - `transform` does not run when the field does not successfully resolve to a value, such as when it is missing, `nil`, or already rejected by an earlier validation step.
+- `px` / `px_key`
+  - Customize the key name used when the parameter is written into `px`.
+- `validate`
+  - Accepts a `Proc`.
+  - Runs **after all parameters have finished resolving, coercion, transform, and writing into `px`**.
+  - Runs in the current controller context, so it can read `px` and directly call controller methods such as `current_user`.
+  - When `validate` returns `false` or `nil`, the field adds an `invalid` error.
+- `error` / `error_message`
+  - Override the error message used when that field fails validation or coercion.
+  - Supported forms:
+    - `String`
+    - `-> { }`
+    - `->(error, value) { }`
+  - Field-level `error` / `error_message` have higher priority than global `config.error_messages`.
 
 About nested object fields
 
@@ -482,7 +554,7 @@ class UsersController < ApplicationController
 end
 ```
 
-`User.schemas` returns a hash that can be passed directly into `form data:`, `json data:`, or `body`.
+`User.schemas` returns a symbol-keyed hash that can be passed directly into `form data:`, `json data:`, or `body`.
 
 By default, it includes all model fields:
 
@@ -496,7 +568,36 @@ You can also limit the exported fields:
 User.schemas(only: %i[name phone role])
 ```
 
-`bang:` defaults to `true`, so required fields are emitted as bang keys such as `"name!"`. If you prefer plain keys, you can pass `bang: false`, and required fields will be emitted as `required: true` instead:
+Or exclude specific fields:
+
+```ruby
+User.schemas(except: %i[phone role])
+```
+
+When `only:` and `except:` are used together, ActionSpec applies `except:` after `only:`.
+
+You can also extract validators for a specific validation context:
+
+```ruby
+User.schemas(on: :create)
+```
+
+You can also override requiredness in the exported schema:  
+When `required:` is an array, only the listed fields are treated as required, and every other exported field is treated as non-required.
+
+```ruby
+User.schemas(required: true)
+User.schemas(required: false)
+User.schemas(required: %i[name role])
+```
+
+You can also merge custom schema fragments into the exported fields:
+
+```ruby
+User.schemas(merge: { name: { required: false, desc: "nickname" } })
+```
+
+`bang:` defaults to `true`, so required fields are emitted as bang keys such as `name!:`. `only:` and `except:` both accept plain names or bang-style names such as `phone!`. If you prefer plain keys, you can pass `bang: false`, and required fields will be emitted as `required: true` instead:
 
 ```ruby
 User.schemas(bang: false)
@@ -505,7 +606,8 @@ User.schemas(bang: false)
 ActionSpec extracts schema-relevant information from ActiveRecord / ActiveModel when available, including:
 
 - field type
-- requiredness, rendered either as bang keys such as `"name!"` or as `required: true` when `bang: false`
+- requiredness, rendered either as bang keys such as `name!:` or as `required: true` when `bang: false`
+- `allow_blank: false` from presence validators unless that validator explicitly allows blank
 - enum values from `enum`
 - `default`
 - `desc` from column comments
@@ -513,22 +615,19 @@ ActionSpec extracts schema-relevant information from ActiveRecord / ActiveModel
 - `range` from numericality validators
 - `length` from length validators and string column limits
 
+Conditional validators with `if:` or `unless:` are skipped during schema extraction, because they cannot be represented as unconditional static schema rules. Validators with `on:` / `except_on:` are skipped by default, but can be extracted by passing `schemas(on: ...)`. The `required:` option overrides the requiredness of exported fields only; it does not remove other extracted constraints such as `allow_blank: false`. The `merge:` option deep-merges custom fragments into each extracted field definition.
+
 Example output:
 
 ```ruby
 User.schemas
 # {
-#   "name!" => { type: String, desc: "user name", length: { maximum: 20 } },
-#   "phone!" => { type: String, length: { maximum: 13 }, pattern: /\A1\d{10}\z/ },
-#   "role" => { type: String, enum: %w[admin member visitor] }
+#   name!: { type: String, desc: "user name", length: { maximum: 20 } },
+#   phone!: { type: String, allow_blank: false, length: { maximum: 13 }, pattern: /\A1\d{10}\z/ },
+#   role: { type: String, enum: %w[admin member visitor] }
 # }
-
 User.schemas(bang: false)
-# {
-#   "name" => { type: String, required: true, desc: "user name", length: { maximum: 20 } },
-#   "phone" => { type: String, required: true, length: { maximum: 13 }, pattern: /\A1\d{10}\z/ },
-#   "role" => { type: String, enum: %w[admin member visitor] }
-# }
+# { name: { type: String, required: true, desc: "user name", length: { maximum: 20 } }, ... }
 ```
 
 #### Type And Boundary Matrix
@@ -544,7 +643,7 @@ User.schemas(bang: false)
 | `DateTime` | `"2025-10-17T12:30:00Z"` | Rejects invalid datetimes such as `"2025-10-17 25:00:00"` |
 | `Time` | `"2025-10-17T12:30:00Z"` | Follows `ActiveModel::Type::Time`, so the date part becomes `2000-01-01` |
 | `File` | `ActionDispatch::Http::UploadedFile`, `Tempfile`, file-like IO objects | Keeps the object as-is and does not read file contents into memory |
-| `Object` | `Hash`, `ActionController::Parameters`, arbitrary Ruby objects | Passed through for scalar `Object`; nested hashes use object schema resolution |
+| `Object` | `Hash`, `ActionController::Parameters` | Scalar `Object` behaves like `Hash` and rejects non-hash values; nested hashes use object schema resolution |
 | `[Type]` | arrays such as `%w[1 2 3]` for `[Integer]` | Rejects non-array values, and reports item errors like `tags.1` |
 | nested object | `{ profile: { nickname: "neo" } }` | Rejects non-hash values, and reports nested paths like `profile.nickname` |
 
@@ -729,18 +828,23 @@ ActionSpec.configure { |config|
 }
 ```
 
+If you want to override one specific field directly in the DSL, use `error` or `error_message` on that field:
+
+```ruby
+doc {
+  query! :page, Integer, error: "choose a page first"
+  query :role, String, validate: -> { false }, error: -> { "is not allowed for #{current_user}" }
+  json data: {
+    birthday!: { type: Date, error: ->(error, value) { "#{error}: #{value.inspect}" } }
+  }
+}
+```
+
 ## AI Generation Style Guide
 
-When using AI tools to generate Rails controller code, and the change involves parameter validation, type coercion, default values, or similar parameter contracts, these conventions work well with ActionSpec:
+When using AI tools to generate Rails controller code, treat the [AI Agent Quick Reference](#ai-agent-quick-reference) as the source of truth.
 
-- use `doc { }` or `doc("Summary") { }`; do not add the action name, and do not leave a blank line between the `doc` block and the action method
-- use `{ }` blocks inside `doc` as well; prefer them over `do ... end`
-- when a batch has 3 fields or fewer and does not contain nested hashes, prefer a single-line style, for example:
-  - `json data: { type: String, required: true }`
-  - `in_query(name: String, value: String)` (prefer `in_xxx(...)` batch declarations over multiple `xx` DSL lines when possible)
-- use `!` but not `required: true`
-- use `doc_dry`, `scope`, and `transform`、`px(px_key)`、`px.slice` to keep controller concise
-- when request parameters match model declarations, prefer `.schemas` to keep `doc` concise
+The rest of this README documents all supported forms, including compatibility alternatives such as `doc(:action, ...)` and `required: true`, but generated code should follow the quick reference unless the existing application style requires otherwise.
 
 ## What Is Not Implemented Yet
 

data/lib/action_spec/configuration.rb

@@ -3,7 +3,7 @@
 module ActionSpec
   class Configuration
     attr_accessor :invalid_parameters_exception_class, :open_api_output, :open_api_title, :open_api_version,
-                  :open_api_server_url, :default_response_media_type
+                  :open_api_server_url, :default_response_media_type, :required_allow_blank
     attr_reader :error_messages
 
     def initialize
@@ -13,6 +13,7 @@ module ActionSpec
       @open_api_version = nil
       @open_api_server_url = nil
       @default_response_media_type = :json
+      @required_allow_blank = true
       @error_messages = ActiveSupport::HashWithIndifferentAccess.new
     end
 
@@ -35,6 +36,7 @@ module ActionSpec
         copy.open_api_version = open_api_version
         copy.open_api_server_url = open_api_server_url
         copy.default_response_media_type = default_response_media_type
+        copy.required_allow_blank = required_allow_blank
         copy.error_messages = error_messages.deep_dup
       end
     end

data/lib/action_spec/doc/endpoint.rb

@@ -57,11 +57,13 @@ module ActionSpec
 
       def add_param(location_name, field)
         location(location_name).add(field)
+        clear_custom_validation_cache!
       end
 
       def add_body(media_type, field)
         body.add(field)
         (@body_media_types[media_type.to_sym] ||= Location.new(media_type.to_sym)).add(field.copy)
+        clear_custom_validation_cache!
       end
 
       def register_scope(name, compact: nil, compact_blank: nil)
@@ -91,6 +93,7 @@ module ActionSpec
         @body_media_types = other.body_media_types
         @scope_options = other.scope_options
         @body_required = other.body_required?
+        clear_custom_validation_cache!
       end
 
       def copy
@@ -110,8 +113,18 @@ module ActionSpec
       end
 
       def custom_validation?
-        [header, path, query, cookie, body].any?(&:custom_validation?)
+        custom_validation_locations.any?
       end
+
+      def custom_validation_locations
+        @custom_validation_locations ||= [header, path, query, cookie, body].select(&:custom_validation?).freeze
+      end
+
+      private
+
+        def clear_custom_validation_cache!
+          remove_instance_variable(:@custom_validation_locations) if instance_variable_defined?(:@custom_validation_locations)
+        end
     end
 
     class Location
@@ -126,6 +139,7 @@ module ActionSpec
 
       def add(field)
         @fields[field.name] = field
+        clear_custom_validation_cache!
       end
 
       def field(name)
@@ -151,7 +165,17 @@ module ActionSpec
       end
 
       def custom_validation?
-        fields.any?(&:custom_validation?)
+        custom_validation_fields.any?
+      end
+
+      def custom_validation_fields
+        @custom_validation_fields ||= fields.select(&:custom_validation?).freeze
+      end
+
+      private
+
+        def clear_custom_validation_cache!
+          remove_instance_variable(:@custom_validation_fields) if instance_variable_defined?(:@custom_validation_fields)
       end
     end
 

data/lib/action_spec/schema/active_record.rb

@@ -6,32 +6,53 @@ module ActionSpec
       extend ActiveSupport::Concern
 
       class_methods do
-        def schemas(only: nil, bang: true)
-          names = selected_column_names(only)
+        def schemas(only: nil, except: nil, on: nil, required: nil, merge: nil, bang: true)
+          names = selected_column_names(only:, except:)
           @action_spec_validator_index = build_validator_index
+          @action_spec_validation_context = normalize_validation_context(on)
+          @action_spec_required_override = normalize_required_override(required)
+          @action_spec_schema_merge = normalize_schema_merge(merge)
 
           names.each_with_object(ActiveSupport::OrderedHash.new) do |name, hash|
-            hash[output_name(name, bang:)] = schema_definition_for(name, bang:)
+            base_required = required_output?(name)
+            definition = schema_definition_for(name, bang:, required: base_required)
+            definition = merge_definition_for(name, definition)
+            output_required = output_required_for(definition, bang:, fallback: base_required)
+            definition = normalize_required_in_definition(definition, bang:, required: output_required)
+            hash[output_name(name, bang:, required: output_required)] = definition
           end
         ensure
           remove_instance_variable(:@action_spec_validator_index) if instance_variable_defined?(:@action_spec_validator_index)
+          remove_instance_variable(:@action_spec_validation_context) if instance_variable_defined?(:@action_spec_validation_context)
+          remove_instance_variable(:@action_spec_required_override) if instance_variable_defined?(:@action_spec_required_override)
+          remove_instance_variable(:@action_spec_schema_merge) if instance_variable_defined?(:@action_spec_schema_merge)
         end
 
         private
 
-          def selected_column_names(only)
-            selected = Array(only).presence&.map { |name| normalize_name(name) } || column_names
+          def selected_column_names(only:, except:)
+            selected = selected_names(only)
+            excluded = excluded_names(except)
 
-            column_names.select { |name| selected.include?(name) }
+            column_names.select { |name| selected.include?(name) && !excluded.include?(name) }
           end
 
-          def output_name(name, bang:)
-            bang && required_attribute?(name) ? "#{name}!" : name
+          def selected_names(only)
+            Array(only).presence&.map { |name| normalize_name(name) } || column_names
           end
 
-          def schema_definition_for(name, bang:)
+          def excluded_names(except)
+            Array(except).map { |name| normalize_name(name) }
+          end
+
+          def output_name(name, bang:, required:)
+            (bang && required ? "#{name}!" : name).to_sym
+          end
+
+          def schema_definition_for(name, bang:, required:)
             definition = { type: schema_type_for(name) }
-            definition[:required] = true if required_attribute?(name) && !bang
+            definition[:required] = true if required && !bang
+            definition[:allow_blank] = false if blank_disallowed_by_validation?(name)
             definition[:default] = column_default_for(name) unless column_default_for(name).nil?
             definition[:desc] = column_comment_for(name) if column_comment_for(name).present?
             definition[:enum] = resolved_enum_for(name) if resolved_enum_for(name).present?
@@ -59,7 +80,11 @@ module ActionSpec
           end
 
           def required_attribute?(name)
-            (!column_nullable?(name) && column_default_for(name).nil?) || presence_validated?(name)
+            database_required?(name) || presence_requires_value?(name)
+          end
+
+          def database_required?(name)
+            !column_nullable?(name) && column_default_for(name).nil?
           end
 
           def column_nullable?(name)
@@ -91,10 +116,8 @@ module ActionSpec
           end
 
           def range_for(name)
-            options = validator_for(name, ActiveModel::Validations::NumericalityValidator)&.options
-            return if options.blank?
-
-            {}.tap do |range|
+            validators_for(name, ActiveModel::Validations::NumericalityValidator).each_with_object({}) do |validator, range|
+              options = validator.options
               range[:gt] = options[:greater_than] if options.key?(:greater_than)
               range[:ge] = options[:greater_than_or_equal_to] if options.key?(:greater_than_or_equal_to)
               range[:lt] = options[:less_than] if options.key?(:less_than)
@@ -107,13 +130,15 @@ module ActionSpec
               limit = string_limit_for(name)
               length[:maximum] = limit if limit
 
-              options = validator_for(name, ActiveModel::Validations::LengthValidator)&.options || {}
-              length[:minimum] = options[:minimum] if options.key?(:minimum)
-              length[:maximum] = options[:maximum] if options.key?(:maximum)
+              validators_for(name, ActiveModel::Validations::LengthValidator).each do |validator|
+                options = validator.options
+                length[:minimum] = options[:minimum] if options.key?(:minimum)
+                length[:maximum] = options[:maximum] if options.key?(:maximum)
 
-              if options.key?(:is)
-                length[:minimum] = options[:is]
-                length[:maximum] = options[:is]
+                if options.key?(:is)
+                  length[:minimum] = options[:is]
+                  length[:maximum] = options[:is]
+                end
               end
             end
 
@@ -127,12 +152,122 @@ module ActionSpec
             column.limit
           end
 
-          def presence_validated?(name)
-            validator_for(name, ActiveModel::Validations::PresenceValidator).present?
+          def blank_disallowed_by_validation?(name)
+            validator = presence_validator_for(name)
+            validator.present? && !validator_allows_blank?(validator)
+          end
+
+          def presence_requires_value?(name)
+            validator = presence_validator_for(name)
+            validator.present? && !validator_allows_blank?(validator) && !validator_allows_nil?(validator)
+          end
+
+          def presence_validator_for(name)
+            validator_for(name, ActiveModel::Validations::PresenceValidator)
+          end
+
+          def validator_allows_blank?(validator)
+            validator.options[:allow_blank] == true
+          end
+
+          def validator_allows_nil?(validator)
+            validator.options[:allow_nil] == true
           end
 
           def validator_for(name, klass)
-            validator_index.fetch(name.to_s, []).find { |validator| validator.is_a?(klass) }
+            validators_for(name, klass).first
+          end
+
+          def validators_for(name, klass)
+            validator_index.fetch(name.to_s, []).select do |validator|
+              validator.is_a?(klass) && static_validator?(validator)
+            end
+          end
+
+          def static_validator?(validator)
+            %i[if unless].none? { |option| validator.options.key?(option) } &&
+              validation_context_matches?(validator)
+          end
+
+          def validation_context_matches?(validator)
+            return false if requested_validation_context.nil? && validator.options.key?(:on)
+            return false if requested_validation_context.nil? && validator.options.key?(:except_on)
+
+            matches_validation_context?(validator) && allowed_by_except_on?(validator)
+          end
+
+          def matches_validation_context?(validator)
+            return true unless validator.options.key?(:on)
+
+            validator_contexts_for(validator.options[:on]).include?(requested_validation_context)
+          end
+
+          def allowed_by_except_on?(validator)
+            return true unless validator.options.key?(:except_on)
+
+            !validator_contexts_for(validator.options[:except_on]).include?(requested_validation_context)
+          end
+
+          def validator_contexts_for(value)
+            Array(value).filter_map { |entry| normalize_validation_context(entry) }
+          end
+
+          def normalize_validation_context(value)
+            value.present? ? value.to_sym : nil
+          end
+
+          def requested_validation_context
+            @action_spec_validation_context
+          end
+
+          def required_output?(name)
+            override = @action_spec_required_override
+            return required_attribute?(name) if override.nil?
+            return override if override == true || override == false
+
+            override.include?(name.to_s)
+          end
+
+          def normalize_required_override(value)
+            return if value.nil?
+            return value if value == true || value == false
+
+            Array(value).map { |name| normalize_name(name) }
+          end
+
+          def merge_definition_for(name, definition)
+            fragment = @action_spec_schema_merge.fetch(name.to_s, nil)
+            return definition unless fragment
+
+            definition.deep_merge(fragment)
+          end
+
+          def output_required_for(definition, bang:, fallback:)
+            return fallback if bang && !definition.key?(:required)
+
+            definition.fetch(:required, fallback) == true
+          end
+
+          def normalize_required_in_definition(definition, bang:, required:)
+            definition = definition.deep_dup
+            if bang
+              definition.delete(:required)
+            else
+              required ? definition[:required] = true : definition.delete(:required)
+            end
+            definition
+          end
+
+          def normalize_schema_merge(value)
+            return {} if value.nil?
+
+            value.to_h.each_with_object({}) do |(name, fragment), hash|
+              hash[normalize_name(name)] = normalize_schema_fragment(fragment)
+            end
+          end
+
+          def normalize_schema_fragment(fragment)
+            fragment.to_h.deep_symbolize_keys
           end
 
           def normalize_name(name)

data/lib/action_spec/schema/array_of.rb

@@ -10,16 +10,20 @@ module ActionSpec
         @item = item
       end
 
-      def cast(value, context:, coerce:, result:, path:)
+      def cast(value, context:, coerce:, result:, path:, field: nil)
         unless value.is_a?(Array)
-          result.add_error(path.join("."), :invalid)
+          if field
+            field.add_error(result, path:, type: :invalid, value:, context:)
+          else
+            result.add_error(path.join("."), :invalid)
+          end
           return []
         end
 
         output = value.each_with_index.map do |entry, index|
-          item.cast(entry, context:, coerce:, result:, path: [*path, index])
+          item.cast(entry, context:, coerce:, result:, path: [*path, index], field: nil)
         end
-        validate_constraints(output, result:, path:)
+        validate_constraints(output, result:, path:, field:, context:)
         output
       end
 
@@ -28,7 +32,7 @@ module ActionSpec
       end
 
       def custom_validation?
-        item.custom_validation?
+        @custom_validation ||= item.custom_validation?
       end
     end
   end

data/lib/action_spec/schema/base.rb

@@ -24,16 +24,20 @@ module ActionSpec
         Schema::Missing
       end
 
+      def blank_value(_value)
+        nil
+      end
+
       def blank_allowed?
         blank != false
       end
 
-      def validate_constraints(value, result:, path:)
+      def validate_constraints(value, result:, path:, field: nil, context: nil)
         return if value.nil?
 
-        validate_enum(value, result:, path:)
-        validate_range(value, result:, path:)
-        validate_pattern(value, result:, path:)
+        validate_enum(value, result:, path:, field:, context:)
+        validate_range(value, result:, path:, field:, context:)
+        validate_pattern(value, result:, path:, field:, context:)
       end
 
       def copy
@@ -46,34 +50,36 @@ module ActionSpec
 
       private
 
-        def add_error(result, path, type, **options)
+        def add_error(result, path, type, field: nil, value: nil, context: nil, **options)
+          return field.add_error(result, path:, type:, value:, context:, **options) if field
+
           result.add_error(path.join("."), type, **options)
         end
 
-        def validate_enum(value, result:, path:)
+        def validate_enum(value, result:, path:, field:, context:)
           return if enum.blank?
           return if Array(enum).include?(value)
 
-          add_error(result, path, :inclusion)
+          add_error(result, path, :inclusion, field:, value:, context:)
         end
 
-        def validate_range(value, result:, path:)
+        def validate_range(value, result:, path:, field:, context:)
           return if range.blank?
 
           rules = range.symbolize_keys
-          add_error(result, path, :greater_than_or_equal_to, count: rules[:ge]) if rules.key?(:ge) && value < rules[:ge]
-          add_error(result, path, :greater_than, count: rules[:gt]) if rules.key?(:gt) && value <= rules[:gt]
-          add_error(result, path, :less_than_or_equal_to, count: rules[:le]) if rules.key?(:le) && value > rules[:le]
-          add_error(result, path, :less_than, count: rules[:lt]) if rules.key?(:lt) && value >= rules[:lt]
+          add_error(result, path, :greater_than_or_equal_to, field:, value:, context:, count: rules[:ge]) if rules.key?(:ge) && value < rules[:ge]
+          add_error(result, path, :greater_than, field:, value:, context:, count: rules[:gt]) if rules.key?(:gt) && value <= rules[:gt]
+          add_error(result, path, :less_than_or_equal_to, field:, value:, context:, count: rules[:le]) if rules.key?(:le) && value > rules[:le]
+          add_error(result, path, :less_than, field:, value:, context:, count: rules[:lt]) if rules.key?(:lt) && value >= rules[:lt]
         end
 
-        def validate_pattern(value, result:, path:)
+        def validate_pattern(value, result:, path:, field:, context:)
           return if pattern.blank?
 
           matcher = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern.to_s)
           return if value.to_s.match?(matcher)
 
-          add_error(result, path, :invalid)
+          add_error(result, path, :invalid, field:, value:, context:)
         end
     end
   end

data/lib/action_spec/schema/field.rb

@@ -3,9 +3,9 @@
 module ActionSpec
   module Schema
     class Field
-      attr_reader :name, :schema, :transform, :validate, :px_key, :scopes
+      attr_reader :name, :schema, :transform, :validate, :px_key, :scopes, :error_message
 
-      def initialize(name:, required:, schema:, transform: nil, validate: nil, px_key: nil, scopes: [])
+      def initialize(name:, required:, schema:, transform: nil, validate: nil, px_key: nil, scopes: [], error_message: nil)
         @name = name.to_sym
         @required = required
         @schema = schema
@@ -13,6 +13,7 @@ module ActionSpec
         @validate = validate
         @px_key = px_key&.to_sym
         @scopes = Array(scopes).map(&:to_sym).freeze
+        @error_message = error_message
       end
 
       def required?
@@ -47,15 +48,28 @@ module ActionSpec
       end
 
       def custom_validation?
-        validate.present? || schema.custom_validation?
+        @custom_validation ||= validate.present? || schema.custom_validation?
+      end
+
+      def add_error(result, path:, type:, value:, context: nil, **options)
+        result.add_error(path.join("."), type, message: resolve_error_message(type, value, context:), **options)
       end
 
       def copy
-        self.class.new(name:, required: required?, schema: schema.copy, transform:, validate:, px_key:, scopes:)
+        self.class.new(name:, required: required?, schema: schema.copy, transform:, validate:, px_key:, scopes:, error_message:)
       end
 
       private
 
+        def resolve_error_message(type, value, context:)
+          case error_message
+          when nil then nil
+          when String then error_message
+          when Proc then apply_error_proc(type, value, context:)
+          else error_message.to_s
+          end
+        end
+
         def apply_symbol_transform(value, context:)
           symbol = transform.to_sym
           return value.public_send(symbol) if value.respond_to?(symbol)
@@ -80,6 +94,16 @@ module ActionSpec
           validate.call(value)
         end
 
+        def apply_error_proc(type, value, context:)
+          return context.instance_exec(&error_message) if context && error_message.arity.zero?
+          return context.instance_exec(type, &error_message) if context && error_message.arity == 1
+          return context.instance_exec(type, value, &error_message) if context && (error_message.arity == 2 || error_message.arity.negative?)
+          return error_message.call if error_message.arity.zero?
+          return error_message.call(type) if error_message.arity == 1
+
+          error_message.call(type, value)
+        end
+
         def invoke_context_transform(context, symbol, value)
           method = context.method(symbol)
           return context.public_send(symbol) if method.arity.zero?

data/lib/action_spec/schema/object_of.rb

@@ -10,8 +10,8 @@ module ActionSpec
         @fields = fields
       end
 
-      def cast(value, context:, coerce:, result:, path:)
-        source = normalize_source(value, result:, path:)
+      def cast(value, context:, coerce:, result:, path:, field: nil)
+        source = normalize_source(value, result:, path:, field:, context:, invalid_value: value)
         return Schema::Missing if source.equal?(Schema::Missing)
 
         output = ActiveSupport::HashWithIndifferentAccess.new
@@ -30,7 +30,7 @@ module ActionSpec
       end
 
       def materialize_missing(context:, coerce:, result:, path:)
-        cast({}, context:, coerce:, result:, path:)
+        cast({}, context:, coerce:, result:, path:, field: nil)
       end
 
       def copy
@@ -38,17 +38,25 @@ module ActionSpec
       end
 
       def custom_validation?
-        fields.any? { |_name, field| field.custom_validation? }
+        custom_validation_fields.any?
+      end
+
+      def custom_validation_fields
+        @custom_validation_fields ||= fields.each_value.select(&:custom_validation?).freeze
       end
 
       private
 
-        def normalize_source(value, result:, path:)
+        def normalize_source(value, result:, path:, field:, context:, invalid_value:)
           return {} if value.nil?
           return value.to_unsafe_h.with_indifferent_access if value.is_a?(ActionController::Parameters)
           return value.with_indifferent_access if value.is_a?(Hash)
 
-          result.add_error(path.join("."), :invalid)
+          if field
+            field.add_error(result, path:, type: :invalid, value: invalid_value, context:)
+          else
+            result.add_error(path.join("."), :invalid)
+          end
           Schema::Missing
         end
     end

data/lib/action_spec/schema/resolver.rb

@@ -12,13 +12,14 @@ module ActionSpec
         @path = [*path, field.name]
       end
 
-      def resolve
-        return resolve_missing unless present?
+        def resolve
+          return resolve_missing unless present?
 
-        return resolve_nil if value.nil?
-        return resolve_blank if blank_disallowed?
+          return resolve_nil if value.nil?
+          return finalize(schema.blank_value(value)) if blank_string_allowed?
+          return resolve_blank if blank_disallowed?
 
-        finalize(schema.cast(value, context:, coerce:, result:, path:))
+        finalize(schema.cast(value, context:, coerce:, result:, path:, field:))
       end
 
       private
@@ -39,22 +40,22 @@ module ActionSpec
 
         def resolve_missing
           if schema.default.respond_to?(:call)
-            return finalize(schema.cast(evaluate_default(schema.default), context:, coerce:, result:, path:))
+            return finalize(schema.cast(evaluate_default(schema.default), context:, coerce:, result:, path:, field:))
           end
-          return finalize(schema.cast(schema.default, context:, coerce:, result:, path:)) unless schema.default.nil?
+          return finalize(schema.cast(schema.default, context:, coerce:, result:, path:, field:)) unless schema.default.nil?
           return finalize(schema.materialize_missing(context:, coerce:, result:, path:)) unless field.required?
 
-          result.add_error(path.join("."), :required)
+          field.add_error(result, path:, type: :required, value: nil, context:)
           Schema::Missing
         end
 
         def resolve_nil
-          result.add_error(path.join("."), field.required? ? :required : :blank)
+          field.add_error(result, path:, type: field.required? ? :required : :blank, value:, context:)
           Schema::Missing
         end
 
         def resolve_blank
-          result.add_error(path.join("."), :blank)
+          field.add_error(result, path:, type: :blank, value:, context:)
           Schema::Missing
         end
 
@@ -62,6 +63,12 @@ module ActionSpec
           !schema.blank_allowed? && value.respond_to?(:blank?) && value.blank?
         end
 
+        def blank_string_allowed?
+          # Keep blank-string semantics explicit: preserve only values that the schema
+          # can meaningfully carry as blank, and normalize the rest to nil.
+          schema.blank_allowed? && value.is_a?(String) && value.blank?
+        end
+
         def finalize(resolved)
           return resolved if resolved.equal?(Schema::Missing)
 

data/lib/action_spec/schema/scalar.rb

@@ -10,21 +10,29 @@ module ActionSpec
         @type = type
       end
 
-      def cast(value, context: nil, coerce:, result:, path:)
+      def cast(value, context: nil, coerce:, result:, path:, field: nil)
         candidate = TypeCaster.cast(type, value)
       rescue TypeCaster::CastError => error
-        result.add_error(path.join("."), :invalid_type, expected: error.expected)
+        if field
+          field.add_error(result, path:, type: :invalid_type, value:, context:, expected: error.expected)
+        else
+          result.add_error(path.join("."), :invalid_type, expected: error.expected)
+        end
         Schema::Missing
       else
         return candidate if candidate.nil?
 
-        validate_constraints(candidate, result:, path:)
+        validate_constraints(candidate, result:, path:, field:, context:)
         coerce ? candidate : value
       end
 
       def copy
         self.class.new(type, default:, enum:, range:, pattern:, length:, blank:, desc: description, example:, examples:)
       end
+
+      def blank_value(value)
+        TypeCaster.normalize(type) == :string ? value : nil
+      end
     end
   end
 end

data/lib/action_spec/schema/type_caster.rb

@@ -17,7 +17,7 @@ module ActionSpec
           return value if value.nil?
 
           normalized = normalize(type)
-          return value if normalized == :object
+          return cast_object(value) if normalized == :object
           return cast_file(value) if normalized == :file
           return cast_boolean(value) if normalized == :boolean
           return cast_integer(value) if normalized == :integer
@@ -67,6 +67,12 @@ module ActionSpec
             raise CastError, :file
           end
 
+          def cast_object(value)
+            return value if value.is_a?(Hash) || value.is_a?(ActionController::Parameters)
+
+            raise CastError, :object
+          end
+
           def cast_integer(value)
             return value if value.is_a?(Integer)
             raise CastError, :integer unless value.is_a?(String) && value.match?(/\A[+-]?\d+\z/)

data/lib/action_spec/schema.rb

@@ -13,7 +13,7 @@ module ActionSpec
   module Schema
     Missing = Object.new.freeze
     OPTION_KEYS = %i[default desc enum range pattern length blank allow_blank example examples].freeze
-    FIELD_OPTION_KEYS = (OPTION_KEYS + %i[required transform px px_key validate]).freeze
+    FIELD_OPTION_KEYS = (OPTION_KEYS + %i[required transform px px_key validate error error_message]).freeze
 
     class << self
       def build(type = nil, **options)
@@ -23,12 +23,15 @@ module ActionSpec
       end
 
       def build_field(name, definition = nil, required: false, scopes: [])
+        field_required = required_key?(name) || required || explicit_required?(definition)
+
         Field.new(
           name: field_name(name),
-          required: required_key?(name) || required || explicit_required?(definition),
-          schema: build_field_schema(strip_field_options(definition)),
+          required: field_required,
+          schema: build_field_schema(schema_definition_for_field(definition, required: field_required)),
           transform: explicit_transform(definition),
           validate: explicit_validate(definition),
+          error_message: explicit_error_message(definition),
           px_key: explicit_px_key(definition),
           scopes:
         )
@@ -36,7 +39,7 @@ module ActionSpec
 
       def from_definition(definition)
         return Scalar.new(String) if definition.blank?
-        return ArrayOf.new(from_definition(type: definition.first)) if definition.is_a?(Array) && definition.one?
+        return ArrayOf.new(from_definition(definition.first)) if definition.is_a?(Array) && definition.one?
         return ArrayOf.new(from_definition(type: nil)) if definition == []
         return Scalar.new(definition) unless definition.is_a?(Hash)
 
@@ -44,7 +47,7 @@ module ActionSpec
         if definition.key?(:type)
           type = definition[:type]
           options = definition.slice(*OPTION_KEYS)
-          return ArrayOf.new(from_definition(type: type.first), options) if type.is_a?(Array) && type.one?
+          return ArrayOf.new(from_definition(type.first), options) if type.is_a?(Array) && type.one?
           return ArrayOf.new(from_definition(type: nil), options) if type == []
           if type.is_a?(Hash)
             return Scalar.new(Object, options) if type.empty?
@@ -76,8 +79,8 @@ module ActionSpec
         name.to_s.end_with?("!")
       end
 
-      def build_field_schema(definition)
-        return from_definition(type: definition) unless definition.is_a?(Hash)
+        def build_field_schema(definition)
+          return from_definition(type: definition) unless definition.is_a?(Hash)
 
         definition = definition.symbolize_keys
         return from_definition(definition.except(:required)) if definition.key?(:type)
@@ -128,6 +131,13 @@ module ActionSpec
           normalize_px_key(options[:px_key] || options[:px])
         end
 
+        def explicit_error_message(definition)
+          return unless definition.is_a?(Hash)
+
+          options = definition.symbolize_keys
+          options[:error_message] || options[:error]
+        end
+
         def normalize_px_key(value)
           return if value.nil? || value == true || value == false
 
@@ -137,7 +147,23 @@ module ActionSpec
         def strip_field_options(definition)
           return definition unless definition.is_a?(Hash)
 
-          definition.symbolize_keys.except(:required, :transform, :px, :px_key, :validate)
+          definition.symbolize_keys.except(:required, :transform, :px, :px_key, :validate, :error, :error_message)
+        end
+
+        def schema_definition_for_field(definition, required:)
+          definition = strip_field_options(definition)
+          return definition unless required
+          return definition if explicit_blank_option?(definition)
+
+          if definition.is_a?(Hash)
+            definition.symbolize_keys.merge(allow_blank: ActionSpec.config.required_allow_blank)
+          else
+            { type: definition.nil? ? String : definition, allow_blank: ActionSpec.config.required_allow_blank }
+          end
+        end
+
+        def explicit_blank_option?(definition)
+          definition.is_a?(Hash) && definition.symbolize_keys.slice(:blank, :allow_blank).present?
         end
     end
   end

data/lib/action_spec/validation_result.rb

@@ -40,7 +40,9 @@ module ActionSpec
       end
     end
 
-    def add_error(attribute, type, **options)
+    def add_error(attribute, type, message: nil, **options)
+      return errors.add(attribute, message) if message
+
       if (message = ActionSpec.config.message_for(attribute, type, options))
         errors.add(attribute, message)
       else

data/lib/action_spec/validator/runner.rb

@@ -25,14 +25,6 @@ module ActionSpec
 
         attr_reader :endpoint, :controller, :coerce
 
-        BUILT_IN_GROUPS = {
-          path: ->(request) { request.path },
-          query: ->(request) { request.query },
-          body: ->(request) { request.body },
-          headers: ->(request) { request.header },
-          cookies: ->(request) { request.cookie }
-        }.freeze
-
         def merge_body!(result)
           if endpoint.request.body_required? && body_source.blank?
             result.add_error("body", :required)
@@ -101,14 +93,15 @@ module ActionSpec
           field.name
         end
 
-      def apply_custom_validations!(result)
-        return unless endpoint.request.custom_validation?
+        def apply_custom_validations!(result)
+          return unless endpoint.request.custom_validation?
 
-        with_controller_px(result.px) do
-          BUILT_IN_GROUPS.each do |location, group_reader|
-            validate_group!(
+          with_controller_px(result.px) do
+            endpoint.request.custom_validation_locations.each do |group|
+              location = group.name
+              validate_group!(
                 result,
-                group_reader.call(endpoint.request),
+                group,
                 values: result.px.scope.fetch(location),
                 location:
               )
@@ -119,9 +112,7 @@ module ActionSpec
         def validate_group!(result, group, values:, location:)
           return unless group.custom_validation?
 
-          group.fields.each do |field|
-            next unless field.custom_validation?
-
+          group.custom_validation_fields.each do |field|
             key = storage_key(field, location)
             next unless values.key?(key)
 
@@ -133,7 +124,7 @@ module ActionSpec
           validate_nested_schema!(field.schema, value, result:, path:)
           return if field.validate_value(value, context: controller)
 
-          result.add_error(path.join("."), :invalid)
+          field.add_error(result, path:, type: :invalid, value:, context: controller)
         end
 
         def validate_nested_schema!(schema, value, result:, path:)
@@ -144,8 +135,7 @@ module ActionSpec
             return unless value.is_a?(Hash)
 
             source = value.with_indifferent_access
-            schema.fields.each_value do |field|
-              next unless field.custom_validation?
+            schema.custom_validation_fields.each do |field|
               next unless source.key?(field.output_name)
 
               validate_field!(field, source[field.output_name], result:, path: [*path, field.name])
@@ -167,8 +157,7 @@ module ActionSpec
             return unless value.is_a?(Hash)
 
             source = value.with_indifferent_access
-            schema.fields.each_value do |field|
-              next unless field.custom_validation?
+            schema.custom_validation_fields.each do |field|
               next unless source.key?(field.output_name)
 
               validate_field!(field, source[field.output_name], result:, path: [*path, field.name])

data/lib/action_spec/version.rb

@@ -1,3 +1,3 @@
 module ActionSpec
-  VERSION = "1.5.0"
+  VERSION = "1.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_spec
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.7.0
 platform: ruby
 authors:
 - zhandao