Resolve $refs nested inside parameter and response header schemas - #449
Merged
Conversation
ahx
force-pushed
the
support-nested-refs-in-query-parameters
branch
from
August 13, 2026 12:34
438bf71 to
d7a63ca
Compare
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
force-pushed
the
support-nested-refs-in-query-parameters
branch
from
August 13, 2026 14:56
d7a63ca to
90c8faa
Compare
ahx
marked this pull request as ready for review
August 13, 2026 17:41
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes ahx/openapi_first#450.
BuilderhandedParameters::Parameter(andHeader#resolved_schema) a schema that was resolvedonly one level deep:
RefResolver::Hash#resolvedfollows a$refat the top level of a node, butevery
$refbelow that stayed unresolved. The parameter unpacking and conversion code reads thoseplain hashes, so it saw no
type,itemsorpropertiesbehind a nested$refand left the valuealone, while
json_schemer— which does follow refs — then rejected it.So besides the reported
deepObjectcase, values described viaitems: { $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#dereferencednow return a plain, fully dereferencedHash/Array, and
Builderuses it for parameter and response header schemas. This happens once perdefinition, 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
$refthat points back to a node onits 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 fewnullablerequest body cases and a readableFailure#inspect.