Remove incorrect documentation about combining values and allow_blank

[eriklovmo]

The deleted example was incorrect: you can, in fact, not supply a blank value to the state parameter with such a params block. I don't know the background, maybe it was correct at one point in time.

[eriklovmo]

I did not update the changelog because it seemed like an insignificant patch. Is that OK?

[ericproulx]

@eriklovmo I do confirm the behavior

# frozen_string_literal: true

require 'bundler/inline'

gemfile(true) do
  source 'https://rubygems.org'
  gem 'grape'
  gem 'rack'
  gem 'minitest'
  gem 'rack-test'
end

require 'minitest/autorun'
require 'rack/test'
require 'grape'

class GrapeAPIBugTest < Minitest::Test
  include Rack::Test::Methods

  def setup
    @api = Class.new(Grape::API) do
      prefix :api
      version 'v1', using: :path
  
      params do
        requires :state, type: Symbol, values: [:active, :inactive]
      end
  
      post '/' do
        'hello'
      end
    end.new
  end

  def test_v1_users_via_api
    options = {
      method: Rack::POST,
      params: {
        state: nil
      }
    }
    env = Rack::MockRequest.env_for('/api/v1', options)
    response = Rack::MockResponse[*@api.call(env)]

    assert_equal 'hello', response.body
    assert_equal 201, response.status
  end
end

It fails

[ericproulx]

But #2185, is mentionning something about optional vs requires. Test is passing when updating the test with optional.

[eriklovmo]

@eriklovmo I do confirm the behavior

Thanks!

But #2185, is mentionning something about optional vs requires. Test is passing when updating the test with optional.

OK, this might warrant a clarifying note in the docs. When using optional, validation also passes when given an empty string "", which appears to be coerced into nil. I haven’t looked into the code mechanics yet, but do you think the underlying issue is the ambiguity around "blankness", or is it that we’re conflating optional keys with optional values?

@ericproulx

[ericproulx]

@eriklovmo Verified — your removal is correct. Behavior matrix from a runnable repro:

params block	omitted	nil	""	invalid	valid
requires :state, type: Symbol, values: [...]	400 missing	400 invalid	400 invalid	400 invalid	201
optional :state, type: Symbol, values: [...]	201 absent	201 nil	201 nil	400 invalid	201
optional :state, type: Symbol, values: [...], allow_blank: false	201 absent	400 empty	400 empty	400 invalid	201

To your question — "ambiguity around blankness, or conflating optional keys with optional values?" — it's the latter. Grape::Validations::Validators::ValuesValidator#validate_param! (lib/grape/validations/validators/values_validator.rb:30) short-circuits on nil whenever the param is optional at the root scope:

return if val.nil? && !required_for_root_scope?

This runs before @allow_blank is consulted (line 31), so optional + values: accepts nil regardless of allow_blank setting. @allow_blank itself defaults to nil (lib/grape/validations/validators/base.rb:62), not true — that's the second factual error in the deleted note.

The ""-passes-too observation is the Symbol coercer turning empty strings into nil, which then takes the same line-30 path.

To reject blank values from an optional :values param, the user has to add allow_blank: false. That's handled by a separate AllowBlankValidator (lib/grape/validations/validators/allow_blank_validator.rb) that runs ahead of values validation and rejects nil/empty when the key is present; absent keys still pass, which is the right semantics for optional.

I rolled this into #2700 (the README/docs cleanup PR) with the deletion you proposed plus a clarifying replacement note covering optional + values and the allow_blank: false opt-out. Closing this in favor of that — thanks for catching the bug in the original docs!

[ericproulx]

Superseded by #2700, which incorporates this deletion plus a corrected clarifying note about optional + values semantics. Thanks for catching the bug in the original docs!