action_spec 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9218555ca7d33709a7a5b22528f6900358e36247c123e521f2342d7a36ac02b5
-  data.tar.gz: e771af58669e707ccbcc922b6d9afa726a2b25817ab4836e01ce1154bd22344b
+  metadata.gz: d4483d08f3dbf8917159d539ee9b064366551409ae646714def0b89595484428
+  data.tar.gz: 065af0d1f835124179afef0a756515b6184598cd35ef217a96615f18b2098cbe
 SHA512:
-  metadata.gz: 7d03ee8f19de7c1c874302344eadf224f9aa3fba2dab228f2f4b44448a2865ba53dd97385587b6b9691308e4a987048b1eab6e5f55a1b03ef93424a643857a0c
-  data.tar.gz: 357fe37dc9a591740079c76dd3e4238a9485cb0d1e57ab020bed09bf737d1937ef22b777f8b062f78473fe497965c2df754ee3858a97f77bdd59674002cdda69
+  metadata.gz: 71ae3fd218312cb0e788f7a5affad8e31da416546e319852509d260490fe261009be24fc51cedfc5948c8c7e9cee04285b50019e613316f3a96605d7cee98b1f
+  data.tar.gz: 7aaee031ed042a3631c952789ccf4ca37db7f7a7f53fcb6a45f1a0e8c4badad005cd4e8774fad58d467c8b2f49d543f4d499407b98cad4dde8fe4e6dbe7cc197

data/README.md

@@ -201,6 +201,16 @@ 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`.
 
+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:`.
+
 If you prefer not to use bang methods, you can also write `required: true`:
 
 ```ruby
@@ -371,7 +381,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 +437,58 @@ 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`.
+- `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 +531,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 +545,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 +583,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 +592,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
@@ -729,6 +805,18 @@ 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_message: -> { "is not allowed for #{current_user}" }
+  json data: {
+    birthday!: { type: Date, error_message: ->(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:

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/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
 

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?
@@ -50,12 +51,25 @@ module ActionSpec
         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
@@ -43,12 +43,16 @@ module ActionSpec
 
       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.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:
         )
@@ -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

@@ -133,7 +133,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:)

data/lib/action_spec/version.rb

@@ -1,3 +1,3 @@
 module ActionSpec
-  VERSION = "1.5.0"
+  VERSION = "1.6.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.6.0
 platform: ruby
 authors:
 - zhandao