Raising exception when loading schema with a JSON parameter (i.e. with schema under `parameters[0][:content]["application/json"][:schema]`)

[Drowze]

OpenAPI 3.0+ supports nesting parameters schema under a content property - that allows for defining json-formatted parameter schemas. See:

• https://swagger.io/docs/specification/v3_0/describing-parameters/#schema-vs-content
• https://spec.openapis.org/oas/v3.0.4#fixed-fields-for-use-with-content

We're getting errors though when attempting to load a parameter defined that way.

Reproducing:

# schema.yaml
---
openapi: 3.0.3
info:
  title: Test API
  version: '1.0'
servers:
- url: http://localhost:3000
paths:
  /users/search:
    get:
      parameters:
        - name: filters
          in: query
          content:
            application/json:
              schema:
                type: object
                properties:
                  from_date:
                    type: string
                  to_date:
                    type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  created_at:
                    type: string

$ ruby -r'openapi_first' -e 'OpenapiFirst.load("schema.yaml")'
/Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/builder.rb:113:in 'block in OpenapiFirst::Builder#resolve_parameters': undefined method 'resolved' for nil (NoMethodError)

        result['schema'] = parameter['schema'].resolved
                                              ^^^^^^^^^
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/builder.rb:111:in 'Array#map'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/builder.rb:111:in 'OpenapiFirst::Builder#resolve_parameters'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/builder.rb:99:in 'OpenapiFirst::Builder#parse_parameters'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/builder.rb:70:in 'block (2 levels) in OpenapiFirst::Builder#router'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/builder.rb:67:in 'Array#map'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/builder.rb:67:in 'block in OpenapiFirst::Builder#router'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/ref_resolver.rb:141:in 'block in OpenapiFirst::RefResolver::Hash#each'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/ref_resolver.rb:140:in 'Hash#each_key'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/ref_resolver.rb:140:in 'OpenapiFirst::RefResolver::Hash#each'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/builder.rb:65:in 'OpenapiFirst::Builder#router'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/builder.rb:23:in 'OpenapiFirst::Builder.build_router'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first/definition.rb:32:in 'OpenapiFirst::Definition#initialize'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first.rb:79:in 'Class#new'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first.rb:79:in 'OpenapiFirst.parse'
	from /Users/Drowze/.gems/4.0.0/gems/openapi_first-3.3.1/lib/openapi_first.rb:70:in 'OpenapiFirst.load'

My environment:

Ruby version: ruby 4.0.2 (2026-03-17 revision d3da9fec82) +PRISM [arm64-darwin25]
openapi_first version: 3.3.1

[ahx]

Hi @Drowze thanks for the report! I have not looked at the reported exception yet, because I am on vacation. Will take a closer look next week.

What I can say right now is that parameter parsing is currently implemented in openapi parameters. I have referenced this issue there: ahx/openapi_parameters#23

It should not be possible to add support there.
Do you want to take a stab at this?

Thanks again for the report.

[ahx]

Hey @Drowze support for 'content' was added in openapi_parameters 0.12.0. Updating that version (bundle update openapi_parameters) should solve this issue.

The dependency was updated in openapi_first 3.4.0 3.4.1, which comes with a few more new features as well https://github.com/ahx/openapi_first/blob/main/CHANGELOG.md#340

Does that work for you?

[Drowze]

Hey @ahx 👋

Apologies for the delay! I just now tested the latest version 3.4.1 but it didn't seem to fix the issue - attempting to parse a spec containing parameters with application/json content still raises an error (unless they also have a root-level schema, in addition to the content-nested schema; but when doing this workaround the request validation fails, so it's not really useful)

I've came up with this minimal reproduction test - hope it makes things a bit more clear :)

require 'bundler/inline'

gemfile do
  source 'https://rubygems.org'
  gem 'openapi_first', '3.4.1'
  gem 'minitest'
  gem 'rack-test'
end

require 'openapi_parameters/version'
require 'minitest/autorun'

puts "Ruby version: #{Ruby::VERSION}"
puts "OpenapiFirst version: #{OpenapiFirst::VERSION}"
puts "OpenapiParameters version: #{OpenapiParameters::VERSION}"

class OpenapiFirstTest < Minitest::Test
  def setup
    @parameter = {
      name: 'filters',
      in: 'query',
      schema: { type: 'string' },
      content: {
        'application/json': {
          schema: {
            type: 'object',
            properties: { name: { type: 'string' } }
          }
        }
      }
    }
    @spec = {
      openapi: '3.0.3',
      info: { title: 'Test API', version: '1.0' },
      servers: [{ url: 'http://localhost' }],
      paths: {
        '/users': {
          get: {
            parameters: [@parameter],
            responses: {
              '200': {
                content: {
                  'application/json': {
                    schema: {
                      type: 'object',
                      properties: { id: { type: 'integer' }, name: { type: 'string' } }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  end

  # When parsing a spec with a parameter that has both `schema` and
  #   `content["application/json"].schema`, the parsing doesn't raise an error,
  #   but the request parameter validation doesn't work as expected (see last test)
  def test_parse_with_schema_and_content
    definition = OpenapiFirst.parse(@spec, filepath: 'spec.json')
    assert_instance_of OpenapiFirst::Definition, definition
  end

  # When parsing a spec with a parameter that has only
  #   `content["application/json"].schema` and no root `schema`, the parsing
  #   raises an error
  def test_parse_with_content_only
    @parameter.delete(:schema)
    OpenapiFirst.parse(@spec, filepath: 'spec.json')
  end

  # When validating a request with a parameter that has both `schema` and
  #   `content["application/json"].schema` the validation doesn't work as
  #   expected, i.e.: the parameter is treated as a string (serialized JSON) and
  #   validated against the un-serialized JSON schema.
  def test_request_validation
    definition = OpenapiFirst.parse(@spec, filepath: 'spec.json')
    env = Rack::MockRequest.env_for(
      '/users',
      params: { filters: { name: 'John' }.to_json }
    )
    request = Rack::Request.new(env)

    validated = definition.validate_request(request)

    error_msg = if validated.error
                  <<~ERROR
                    #{validated.error.message}
                    expected schema: #{validated.error.errors[0].schema}
                    actual type: #{validated.error.errors[0].type}
                    actual value: #{validated.error.errors[0].value}
                    raw request query params: #{request.query_string}
                  ERROR
                end
    assert validated.valid?, error_msg
  end
end

Running the repro script:

$ ruby repro.rb -v
Ruby version: 4.0.2
OpenapiFirst version: 3.4.1
OpenapiParameters version: 0.12.0
Run options: -v --seed 65025

# Running:

OpenapiFirstTest#test_request_validation = 0.00 s = F
OpenapiFirstTest#test_parse_with_schema_and_content = 0.00 s = .
OpenapiFirstTest#test_parse_with_content_only = 0.00 s = E

Finished in 0.005001s, 599.8800 runs/s, 399.9200 assertions/s.

  1) Failure:
OpenapiFirstTest#test_request_validation [repro.rb:100]:
Query parameter is invalid: value at `/filters` is not a string
expected schema: {"type" => "string"}
actual type: string
actual value: {"name" => "John"}
raw request query params: filters=%7B%22name%22%3A%22John%22%7D


  2) Error:
OpenapiFirstTest#test_parse_with_content_only:
NoMethodError: undefined method 'resolved' for nil
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/builder.rb:113:in 'block in OpenapiFirst::Builder#resolve_parameters'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/builder.rb:111:in 'Array#map'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/builder.rb:111:in 'OpenapiFirst::Builder#resolve_parameters'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/builder.rb:99:in 'OpenapiFirst::Builder#parse_parameters'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/builder.rb:70:in 'block (2 levels) in OpenapiFirst::Builder#router'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/builder.rb:67:in 'Array#map'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/builder.rb:67:in 'block in OpenapiFirst::Builder#router'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/ref_resolver.rb:141:in 'block in OpenapiFirst::RefResolver::Hash#each'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/ref_resolver.rb:140:in 'Hash#each_key'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/ref_resolver.rb:140:in 'OpenapiFirst::RefResolver::Hash#each'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/builder.rb:65:in 'OpenapiFirst::Builder#router'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/builder.rb:23:in 'OpenapiFirst::Builder.build_router'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first/definition.rb:32:in 'OpenapiFirst::Definition#initialize'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first.rb:87:in 'Class#new'
    /Users/Drowze/.gems/openapi_first-3.4.1/lib/openapi_first.rb:87:in 'OpenapiFirst.parse'
    repro.rb:73:in 'OpenapiFirstTest#test_parse_with_content_only'

3 runs, 2 assertions, 1 failures, 1 errors, 0 skips

[Drowze]

Just investigated a bit and the fix looked simple - opened a PR for it 😄 #477

[ahx]

Thanks for the fix! This was just released in 3.4.2 🚀