[ericproulx]

Fixes #2241. Refs #2416.

Adds Grape.config.allow_undeclared_params. Set to false, a request carrying a param its endpoint did not declare is answered 400. It defaults to true, which keeps today's behaviour, and Grape 5.0 makes false the default.

Grape.config.allow_undeclared_params = false

params do
  requires :name, type: String
  optional :address, type: Hash do
    requires :street, type: String
  end
end
post '/users' do
  # ...
end

POST /users {"name":"Bob","admin":true,"address":{"street":"Main","zip":"1"}}
=> 400 {"error":"admin is not allowed, address[zip] is not allowed"}

Behaviour

• Undeclared params are raised in the same Grape::Exceptions::ValidationErrors as the other validation errors, so rescue_from and error formatting work unchanged. The message is "is not allowed" (grape.errors.messages.undeclared), the same wording dry-schema uses for unknown keys.
• Rejected rather than dropped. Dropping them would change what params returns in every endpoint, and it would hide client typos (Fail on (or get list of) unknown parameters #2241).
• What counts as declared:
  • The names in the endpoint's params blocks, its own and its namespaces'. That includes given blocks; a param renamed with as: counts by the name the client sends.
  • A contract's keys.
  • The route's path params.
  • format.
• Hash, Array and JSON params are checked key by key, and an undeclared key is named by its path, e.g. items[1][price].
  • A param declared without a block, such as type: Hash or Array[String], takes anything.
  • A param declared in several given blocks accepts the keys of every declaration.
• The check runs after the validators, so a JSON param sent as a String is checked as the Hash it is coerced to.
• A mounted API's endpoints are checked. A mounted Rack app is not.

Implementation

• Grape::Validations::UndeclaredParams builds the declared names into a frozen tree at compile!. The sources are route_declared_params, each contract's key_map.dump, and the route regexp's capture names. The tree is held in Endpoint::State#undeclared_params, which is nil while the setting is true.
• Endpoint#run_validators adds its errors to the validators' errors.
• Request#params_sent? lets a request with no query string and no body through without building params.

Performance

These are paired medians. "true" compares this branch with master; "false" compares the setting false with it true on this branch.

	bare GET	POST, 4 params
true, interpreter	1.000	0.991
true, YJIT	1.004	1.013
false, interpreter	0.930	0.953
false, YJIT	0.934	0.938

With the setting true, there is no measurable cost.

Putting path params into the tree at compile time matters for speed. Checking routing args per request sent every :id route down the slow path, at about +2.8 µs.

Known limits (documented in the README)

• The contents of a oneof: param, and of a Hash, JSON or File param declared without a block, are not checked. declared(params) treats them the same way.
• A contract that passes replaces each Array of Hashes with its own output. An undeclared key inside one is therefore dropped rather than reported.
• With version ..., using: :param, the version param counts as undeclared when it reaches an unversioned endpoint.
• With the setting false, a malformed query string gets a 400 even on an endpoint that never reads params, because the check has to parse it.

Towards 5.0

Setting it to false across this repo's suite gives 90 failures. All of them are specs that send params they never declare. A common case is a params block written for a get whose sibling put declares nothing.

Apps will hit the same thing, especially with tokens that only before filters read. The UPGRADING entry tells users to set it to false in their test suite now and to declare such params. In 5.0 they can set it to true to keep today's behaviour.

Tests

• spec/grape/validations/undeclared_params_spec.rb: 19 examples.
• A dry-validation contract context in spec/integration/dry_validation/dry_validation_spec.rb.
• bundle exec rake is green. The dry_validation gemfile suite is green too.

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run

[dblock]

I’m an AI posting on behalf of @dblock. Could we use a positively phrased option? @dblock prefers positive options. allow_undeclared_params would read naturally, with true preserving the current behavior and false rejecting undeclared params (the planned Grape 5.0 default).