Repository navigation
fix(parser): default explode to false for non-form parameter styles - #1727
Merged
Merged
Conversation
inferParamExplode picked the default from the parameter location instead of the style, so
every query and cookie parameter without an explicit "explode" got explode: true. For
spaceDelimited and pipeDelimited arrays that is the form serialization, and the declared
style is silently dropped. Three array parameters with styles form, pipeDelimited and
spaceDelimited, none of them setting explode, RawQuery observed on the wire:
before: fm=1&fm=2&fm=3&pd=1&pd=2&pd=3&sp=1&sp=2&sp=3
after: fm=1&fm=2&fm=3&pd=1%7C2%7C3&sp=1+2+3
OpenAPI 3.0.3 and 3.1 both say the default is true only when style is form, which is what
the comment in the function already quoted.
The shorthand dates to 6b48c0f (2022-04-14), which introduced the inference.
pipeDelimited arrays were already supported at that commit — uri/query_encoder.go
implemented the style and gen.isSupportedParamStyle rejected pipeDelimited for objects
only — so pipeDelimited has been serialized as form since v0.26.0, four years.
spaceDelimited returned ErrNotImplemented until ogen-go#1716 enabled it for arrays, extending the
same defect to a second style.
Take the style, not the location. Query and cookie parameters default to style form, so
their default explode is unchanged; path and header parameters default to simple and were
already false. Only an explicitly declared non-form style changes, and only when the spec
does not set explode itself.
The Encoding Object shares the inference, so a urlencoded or multipart body property with
a declared non-form style is corrected the same way. Body observed for an encoding entry
of {tags: {style: pipeDelimited}} over an array of "a", "b", "c":
before: tags=a&tags=b&tags=c
after: tags=a%7Cb%7Cc
deepObject keeps defaulting to true. The style/explode table in validateParamStyle accepts
{deepObject, true} only, so a literal reading of the spec (false for every style but form)
would make a bare "style: deepObject" fail to parse, which three checked-in specs use
(_testdata/positive/parameters.json, _testdata/positive/additionalPropertiesPatternProperties.yml
and the encoding object in _testdata/positive/form.json).
make generate examples produces no diff.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
A query parameter that declares a non-form
stylebut leavesexplodeunset isserialized as
form, silently discarding the declared style. Three array parameters,none of them setting
explode:Generated client called with
["1","2","3"]for each,r.URL.RawQueryas observed by theserver:
fm=1&fm=2&fm=3&pd=1&pd=2&pd=3&sp=1&sp=2&sp=3fm=1&fm=2&fm=3&pd=1%7C2%7C3&sp=1+2+3formis unchanged;pipeDelimitedandspaceDelimitedwere emitting the formserialization.
The Encoding Object is affected the same way. For an
application/x-www-form-urlencodedbody with
encoding: {tags: {style: pipeDelimited}}over["a","b","c"], the requestbody:
tags=a&tags=b&tags=ctags=a%7Cb%7CcBoth tables are measured, not derived — generated a client on each side and captured the
request at an
httptestserver.Cause
inferParamExplode(openapi/parser/parse_parameter.go:241) keys the default off theparameter location instead of the style:
The comment states the OpenAPI 3.0.3/3.1 rule correctly; the code below it never looks at
the style, so every query and cookie parameter defaults to
explode: true.This dates to 6b48c0f (2022-04-14), which introduced the inference.
pipeDelimitedarrays were already supported at that commit —
uri/query_encoder.goimplemented thestyle and
gen.isSupportedParamStylerejectedpipeDelimitedonly for objects — sopipeDelimitedhas been serialized asformsince v0.26.0, four years.spaceDelimitedreturnedErrNotImplementeduntil #1716 enabled it for arrays,extending the same defect to a second style.
Fix
Pass the already-inferred style to
inferParamExplodeinstead of the location. The threecall sites —
parse_parameter.go,parse_header.go,parse_mediatype.go— hoist theirexisting
inferParamStyle(...)call one line so the value can be reused.Blast radius
spaceDelimitedhas zero released users.#1716 merged 2026-07-24;
v1.23.0is dated 2026-07-10 andmainisv1.23.0-15.Nothing tagged has ever emitted
spaceDelimited, so that half of the change cannot breaka released user.
pipeDelimitedand the Encoding Object do change the wire format for released users onupgrade. That is the real compatibility cost of this PR and I would rather state it than
bury it. It is four years of a spec violation rather than a documented behaviour, but a
client whose server was built against the same wrong ogen output will need both sides
upgraded together.
The escape hatch is one line in the user's own spec. Adding
explode: truerestoresthe previous bytes exactly, with no ogen-version pinning, and that direction is covered by
a test.
Everything else is provably unchanged. Defaults by location:
simplesimpleformformOnly an explicitly declared non-form style moves, and only when the spec does not set
explodeitself.make generate examples— 44 integration targets and 22 examples —produces a 0-file diff, so no checked-in spec changes shape and there is no
regenerated code in this PR.
Tests
Three table tests in
openapi/parser/parse_parameter_test.go, 15 subtests:TestParameterExplodeDefault— query parameters: unset,form,spaceDelimited,pipeDelimited,deepObject, plus the override direction (spaceDelimitedandpipeDelimitedwith an explicitexplode: true,formwith an explicitexplode: false).TestEncodingExplodeDefault— the Encoding Object path, which had no coverage.TestHeaderExplodeDefault— response headers.I verified they fail without the fix, by reverting only the three source files to the base
commit and keeping the tests:
Restoring the change makes all 15 pass. To be precise about what that proves: 4 of the
15 subtests catch this bug. The other 11 pin behaviour that must not move — the explicit
explodeoverrides,form,deepObject, and the whole ofTestHeaderExplodeDefault,which passes both with and without the fix and is a regression guard rather than a
reproduction.
Verification
Run locally on macOS/arm64, go1.25.10,
CGO_ENABLED=0, caches cleared first.main@2e755d1 is green on all of these, so these are comparisons against a clean baseline.
go test --timeout 15m ./..../go.test.sh(race)cd examples && go test ./...golangci-lint v2.12.2 run -c .golangci.yml ./...make generate examples && git diff --exit-codeIf this PR shows no check runs at first, that is the workflow-approval gate rather than a
failure — these local runs are the pre-merge evidence until CI reports.
Alternative
The strict reading of the spec is
case openapi.QueryStyleForm:alone —falsefor everyother style, including
deepObject. I did not take it becausevalidateParamStyleaccepts{deepObject, true}only, so a barestyle: deepObjectwould stop parsing. Threechecked-in specs write it bare, and with the strict variant they fail:
Keeping
deepObjectontruealso matches howuriimplements it —query_param_encoder.go:152panics on non-explode deepObject. If you would rather havethe strict reading and treat
{deepObject, false}as an error users must fix explicitly,say so and I will switch: it is a one-line change plus a negative fixture.