Skip to content

fix(parser): default explode to false for non-form parameter styles - #1727

Merged
ernado merged 1 commit into
ogen-go:mainfrom
shuvamk:fix/param-explode-default
Aug 7, 2026
Merged

ernado merged 1 commit into
ogen-go:mainfrom
shuvamk:fix/param-explode-default

Conversation

@shuvamk

@shuvamk shuvamk commented Aug 2, 2026

Copy link
Copy Markdown
Contributor

A query parameter that declares a non-form style but leaves explode unset is
serialized as form, silently discarding the declared style. Three array parameters,
none of them setting explode:

parameters:
  - {name: fm, in: query, required: true, style: form,           schema: {type: array, items: {type: string}}}
  - {name: pd, in: query, required: true, style: pipeDelimited,  schema: {type: array, items: {type: string}}}
  - {name: sp, in: query, required: true, style: spaceDelimited, schema: {type: array, items: {type: string}}}

Generated client called with ["1","2","3"] for each, r.URL.RawQuery as observed by the
server:

RawQuery
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

form is unchanged; pipeDelimited and spaceDelimited were emitting the form
serialization.

The Encoding Object is affected the same way. For an application/x-www-form-urlencoded
body with encoding: {tags: {style: pipeDelimited}} over ["a","b","c"], the request
body:

body
before tags=a&tags=b&tags=c
after tags=a%7Cb%7Cc

Both tables are measured, not derived — generated a client on each side and captured the
request at an httptest server.

Cause

inferParamExplode (openapi/parser/parse_parameter.go:241) keys the default off the
parameter location instead of the style:

// When style is form, the default value is true.
// For all other styles, the default value is false.
if locatedIn.Query() || locatedIn.Cookie() {
	return true
}

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. pipeDelimited
arrays were already supported at that commit — uri/query_encoder.go implemented the
style and gen.isSupportedParamStyle rejected pipeDelimited only for objects — so
pipeDelimited has been serialized as form since v0.26.0, four years.
spaceDelimited returned ErrNotImplemented until #1716 enabled it for arrays,
extending the same defect to a second style.

Fix

Pass the already-inferred style to inferParamExplode instead of the location. The three
call sites — parse_parameter.go, parse_header.go, parse_mediatype.go — hoist their
existing inferParamStyle(...) call one line so the value can be reused.

Blast radius

spaceDelimited has zero released users.

$ git merge-base --is-ancestor defc9127 v1.23.0; echo $?
1
$ git tag --contains defc9127
$

#1716 merged 2026-07-24; v1.23.0 is dated 2026-07-10 and main is v1.23.0-15.
Nothing tagged has ever emitted spaceDelimited, so that half of the change cannot break
a released user.

pipeDelimited and the Encoding Object do change the wire format for released users on
upgrade.
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: true restores
the previous bytes exactly, with no ogen-version pinning, and that direction is covered by
a test.

Everything else is provably unchanged. Defaults by location:

location default style explode before after
path simple false false
header simple false false
query form true true
cookie form true true

Only an explicitly declared non-form style moves, and only when the spec does not set
explode itself. 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 (spaceDelimited and
    pipeDelimited with an explicit explode: true, form with an explicit
    explode: 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:

--- FAIL: TestParameterExplodeDefault
    --- FAIL: /SpaceDelimited   Not equal: expected: false, actual: true
    --- FAIL: /PipeDelimited    Not equal: expected: false, actual: true
--- FAIL: TestEncodingExplodeDefault
    --- FAIL: /SpaceDelimited   Not equal: expected: false, actual: true
    --- FAIL: /PipeDelimited    Not equal: expected: false, actual: true

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
explode overrides, form, deepObject, and the whole of TestHeaderExplodeDefault,
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.

Gate Result
go test --timeout 15m ./... PASS, 0 failures
./go.test.sh (race) PASS, 0 races
cd examples && go test ./... PASS
golangci-lint v2.12.2 run -c .golangci.yml ./... 0 issues
make generate examples && git diff --exit-code exit 0, 0 files changed

If 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 — false for every
other style, including deepObject. I did not take it because validateParamStyle accepts
{deepObject, true} only, so a bare style: deepObject would stop parsing. Three
checked-in specs write it bare, and with the strict variant they fail:

--- FAIL: TestGenerate/Positive/parameters/Gen
      - parse parameter "deepObject":
      - invalid style explode combination "deepObject", explode:false
--- FAIL: TestGenerate/Positive/additionalPropertiesPatternProperties/Gen
--- FAIL: TestGenerate/Positive/form/Gen
      - encoding property "deepObject":

Keeping deepObject on true also matches how uri implements it —
query_param_encoder.go:152 panics on non-explode deepObject. If you would rather have
the 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.

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>
@ernado
ernado merged commit de2a3e6 into ogen-go:main Aug 7, 2026
15 checks passed
@shuvamk
shuvamk deleted the fix/param-explode-default branch August 8, 2026 09:45
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.

2 participants