Skip to content

Resolve $refs nested inside parameter and response header schemas - #449

Merged
ahx merged 5 commits into
mainfrom
support-nested-refs-in-query-parameters
Aug 13, 2026
Merged

Resolve $refs nested inside parameter and response header schemas#449
ahx merged 5 commits into
mainfrom
support-nested-refs-in-query-parameters

Conversation

@ahx

@ahx ahx commented Feb 25, 2026

Copy link
Copy Markdown
Owner

Fixes ahx/openapi_first#450.

Builder handed Parameters::Parameter (and Header#resolved_schema) a schema that was resolved
only one level deep: RefResolver::Hash#resolved follows a $ref at the top level of a node, but
every $ref below that stayed unresolved. The parameter unpacking and conversion code reads those
plain hashes, so it saw no type, items or properties behind a nested $ref and left the value
alone, while json_schemer — which does follow refs — then rejected it.

So besides the reported deepObject case, values described via items: { $ref: … },
allOf: [{ $ref: … }] or a $ref'd object property were not converted either, for query, path,
header and cookie parameters as well as response headers.

RefResolver::Hash#dereferenced / Array#dereferenced now return a plain, fully dereferenced
Hash/Array, and Builder uses it for parameter and response header schemas. This happens once per
definition, so there is no cost per request, and validation itself is untouched — only unpacking and
type conversion gain the type information they were missing. A $ref that points back to a node on
its own path (a recursive schema) is left unresolved, so loading such a document still terminates
and the result stays JSON-serializable.

Also in here, from the original draft: request examples in spec/test_cases_spec.rb
(valid_request / invalid_request), a few nullable request body cases and a readable
Failure#inspect.

@ahx
ahx force-pushed the support-nested-refs-in-query-parameters branch from 438bf71 to d7a63ca Compare August 13, 2026 12:34
@ahx ahx changed the title Support nested refs in query parameters Resolve $refs nested inside parameter and response header schemas Aug 13, 2026
Only a $ref at the top level of a parameter or response header schema was
resolved before, so the parameter unpacking and conversion code did not see
any type described behind a nested $ref. A deepObject parameter with a $ref'd
array property was not unpacked into an array, and values described via
`items: { $ref: ... }` or `allOf: [{ $ref: ... }]` were left unconverted.

Fixes #450

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@ahx
ahx force-pushed the support-nested-refs-in-query-parameters branch from d7a63ca to 90c8faa Compare August 13, 2026 14:56
@ahx
ahx marked this pull request as ready for review August 13, 2026 17:41
@ahx
ahx merged commit a938408 into main Aug 13, 2026
32 checks passed
@ahx
ahx deleted the support-nested-refs-in-query-parameters branch August 13, 2026 17:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

deepObject paramters with array values do not support nested $refs

1 participant