Add oneof: option for polymorphic Hash parameters (#2385)

[ericproulx]

Resolves #2385. Adds an oneof: option for requires/optional so a Hash parameter can accept one of several variant schemas without the optional + mutually_exclusive + given workaround the issue describes.

API

params do
  requires :value, type: Hash, oneof: [
    proc { requires :fixed_price, type: Float },
    proc do
      requires :time_unit, type: String
      requires :rate, type: Float
    end
  ]
end
post '/pricing' do
  params[:value]
end

Both {"value":{"fixed_price":100.0}} and {"value":{"time_unit":"hour","rate":50.0}} succeed. A request that doesn't match any variant returns 400 with value does not match any of the allowed schemas.

Each variant is a Proc that uses the normal Grape params DSL — so requires, optional, regexp:, values:, allow_blank:, nested Hash/Array, Grape::API::Boolean, custom types, etc. all work inside variants without re-implementation. Coercion through the winning variant is applied to the parent params (e.g. "150.5" → 150.5).

Variants are tried in declaration order; the first variant whose validators raise no exceptions wins (deterministic).

Why a separate oneof: and not types: [hash_schema {...}]

I considered overloading types: per @dblock's note in the issue thread, but kept oneof: distinct because:

• types: already drives MultipleTypeCoercer for primitive variants (types: [Integer, String]).
• Mixing primitives and hash schemas in one array — types: [Integer, hash_schema { ... }] — produces a non-obvious dispatch.
• oneof: aligns with JSON Schema vocabulary and makes the user's intent explicit.

If the maintainers prefer the types: overload, the validator and collector machinery in this PR are reusable — only infer_coercion/process_oneof! would need to change.

Implementation

File	What
lib/grape/validations/oneof_collector.rb	Minimal @api-compatible shim. Exposes OneofCollector.collect(block) which evaluates the variant block in a fresh ParamsScope and returns the captured validators.
lib/grape/validations/validators/oneof_validator.rb	OneofValidator < Base. At request time deep-dups the candidate hash, runs each variant's validators against the dup, takes the first variant that produces no exceptions, and replaces params[attr_name] with the (possibly coerced) result. Raises Validation with i18n key oneof if no variant matches.
lib/grape/validations/params_scope.rb	validates calls process_oneof! when :oneof is in the validations hash; the helper validates shape (non-empty Array of Procs, type: Hash) and replaces each Proc with its OneofCollector.collect-built validator list before the standard validate loop instantiates OneofValidator.
lib/grape/locale/en.yml	New oneof: 'does not match any of the allowed schemas' key.
README.md	New §"Multiple Hash Schemas with oneof" between "Multiple Allowed Types" and "Validation of Nested Parameters".
CHANGELOG.md	Features entry referencing #2385.

Definition-time guards

• oneof: requires type: Hash (raises ArgumentError)
• Variants array must be non-empty (raises ArgumentError)
• Every entry must be a Proc (raises ArgumentError)

Tests

19 new examples in spec/grape/validations/validators/oneof_validator_spec.rb:

• Definition-time errors (4 cases)
• Two-flat-variants matching/coercion/rejection (6 cases)
• optional :value with missing/invalid (2 cases)
• Full DSL inside variants — values:, regexp: (4 cases)
• Deeply nested Hash inside variants (3 cases)

Test plan

• bundle exec rspec spec/grape/validations/validators/oneof_validator_spec.rb — 19 examples, 0 failures
• bundle exec rspec — full suite green (2,273 examples, up from 2,254)
• bundle exec rubocop lib/ spec/ — clean

Credits

Same feature requested as in #2661 by @jcagarcia and @mia-n. This PR re-implements from scratch using the existing ParamsScope infrastructure (instead of a parallel mini-DSL) so all Grape validators work inside variants by design.

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run

[dblock]

I like oneof with the use of proc very much, nice solution! Merge at will after we hear from @jcagarcia and @mia-n?

[dblock]

Haven't heard from @jcagarcia or @mia-n - should we merge this @ericproulx? I'm good with it.

[ericproulx]

Haven't heard from @jcagarcia or @mia-n - should we merge this @ericproulx? I'm good with it.

I'm good with it.

[dblock]

Squash it.