fix(fetch): respect OpenAPI default explode: true for array query parameters (#3231) by zeriong · Pull Request #3308 · orval-labs/orval

zeriong · 2026-05-03T12:18:59Z

Summary

Use nullish coalescing (parameterObject.explode ?? true) so that undefined defaults to true per the OpenAPI 3.0/3.1 spec instead of being treated as
falsy.
Previously, array query parameters without an explicit explode field were serialized as comma-separated (?ids=1,2,3) instead of repeated key-value pairs
(?ids=1&ids=2&ids=3).

Breaking Change

Users relying on the implicit comma-separated behavior without setting explode: false will see a change in serialization output. To preserve the old behavior,
explicitly set explode: false on the parameter.

Test plan

bun run build — 12 successful
bun vitest run — 2303 passed (3 pre-existing failures in resolve-version.test.ts, unrelated)
bun run test:snapshots — 3746 passed; 2 snapshot files updated (fetch/parameters, fetch/dateParams)
Verified solid-start package already handled this correctly, no other clients affected

Closes #3231

Summary by CodeRabbit

Bug Fixes
- Fixed query-parameter explode behavior so array-valued query parameters follow style-based defaults (form-style defaults to explode).
- Arrays in query parameters are now serialized as repeated entries when exploded (e.g., q and tag), producing correct URLs and request behavior.

coderabbitai · 2026-05-03T12:19:10Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Array-like query parameter explode logic was refactored into shouldExplodeArrayQueryParameter which resolves style (defaulting by in) and enables explode when style === 'form'; the explode-parameter selection now uses this predicate and snapshots updated to treat q and tag as exploded.

Changes

Query Parameter Explosion Default Compliance

Layer / File(s)	Summary
Explode predicate & helpers `packages/fetch/src/index.ts`	Introduced `getDefaultStyle`, `getDefaultExplode`, and `isArrayLikeSchema` to resolve default `style`/`explode` and detect array-like schemas.
Explode predicate `packages/fetch/src/index.ts`	Added `shouldExplodeArrayQueryParameter` which gates explode to `in === 'query'`, array-like schemas, and `style === 'form'`, using explicit `explode` when present or the style-based default.
Explode filter usage `packages/fetch/src/index.ts`	Replaced inline `parameterObject.explode` check with `shouldExplodeArrayQueryParameter` when building `explodeParameters`.
Test Snapshots `tests/__snapshots__/fetch/dateParams/pets/pets.ts`, `tests/__snapshots__/fetch/parameters/endpoints.ts`	Snapshots updated: `explodeParameters` expanded from `['tag']` to `['q', 'tag']`, so array values for `q` are serialized as repeated query parameters.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

orval-labs/orval#3055 — Related changes to explode-aware query serialization in another client integration.

Suggested reviewers

melloware

Poem

🐇 I nibble code beneath the moon,
I twitch my nose and hum a tune,
Arrays now bloom as keys repeat,
q and tag dance, each value neat.
Hop—serialization tastes like sweet!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: fixing the fetch client to respect OpenAPI's default explode: true for array query parameters.
Linked Issues check	✅ Passed	The PR implementation aligns with issue `#3231` requirements: it treats undefined explode as true for array query parameters in form style, applies style-based gating, and includes appropriate tests.
Out of Scope Changes check	✅ Passed	All changes in the PR are directly scoped to the issue objectives: refactoring explode logic, adding style-based defaulting, and updating test snapshots accordingly.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

soartec-lab · 2026-05-05T02:21:10Z

@zeriong

In v3.1, the default value is false.

https://swagger.io/specification/

idiodoneo-chris · 2026-05-05T10:19:20Z

According to the Swagger spec, for query parameters the default is, in fact, true if style is not specified or is set to form. This is the case when FastAPI produces an api spec (and FastAPI does then require exploded parameters in the query which broke with Orval 8).

Here's a typical example produced by FastAPI:

  {
    "/api/v1/interests": {
      "get": {
        "summary": "List all interests",
        "description": "Lists all available interests with localized names.",
        "operationId": "list_interests_endpoint",
        "parameters": [
          {
            "name": "l",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                {
                  "type": "null"
                }
              ],
              "description": "Language codes to prioritize for text",
              "title": "L"
            },
            "description": "Language codes to prioritize for text"
          }
        ],
      }
    }
  }

soartec-lab · 2026-05-06T00:37:12Z

@idiodoneo-chris
Thank you for your comment. The solution would be to have a process to calculate the value of explode from the values of style and form.

Use nullish coalescing (parameterObject.explode ?? true) so that undefined defaults to true per the OpenAPI 3.0/3.1 spec instead of being treated as falsy. Closes orval-labs#3231 Signed-off-by: zeriong <jaeryong95@gmail.com>

Signed-off-by: zeriong <jaeryong95@gmail.com>

zeriong · 2026-05-10T15:10:35Z

@soartec-lab
Good point on involving!
style. Kept the PR scope but added a guard so default-true only applies when style is form or unspecified — leaves room for future non-form style handling without changing current behavior:

const style = parameterObject.style ?? 'form';

return (
  parameterObject.in === 'query' &&
  isArrayLike &&
  style === 'form' &&
  (parameterObject.explode ?? true)
);

Snapshots unchanged.

soartec-lab · 2026-05-11T10:07:28Z

          | undefined) ?? []
      ).some((s) => resolveSchemaRef(s, context).schema.type === 'array');

+    const style = parameterObject.style ?? 'form';


Note that the default value may change depending on the type of parameter.

Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of in): for "query" - "form"; for "path" - "simple"; for "header" - "simple"; for "cookie" - "form".

https://swagger.io/specification/

@soartec-lab
Thanks for check, please one more review!

…xplode-true-3231

Address review feedback on orval-labs#3308: the OpenAPI spec defines and defaults per value (query/cookie -> form/true, path/header -> simple/false). Extract , , , and so the spec mapping is explicit and array-like schema detection guards against malformed oneOf/anyOf/allOf. No behavior change; snapshots unchanged. Signed-off-by: zeriong <jaeryong95@gmail.com>

Address review feedback on orval-labs#3308: the OpenAPI spec defines style and explode defaults per "in" value (query/cookie -> form/true, path/header -> simple/false). Extract getDefaultStyle, getDefaultExplode, isArrayLikeSchema, and shouldExplodeArrayQueryParameter so the spec mapping is explicit and array-like schema detection guards against malformed oneOf/anyOf/allOf. No behavior change; snapshots unchanged. Signed-off-by: zeriong <jaeryong95@gmail.com>

soartec-lab · 2026-05-12T14:10:29Z

@zeriong
I apologize, but I'm spending too much time on this, so please give me a little more time to review it.
It appears that the AI has made a change of direction midway through the process and is performing unnecessary and redundant processing.

https://github.com/orval-labs/orval/blob/master/CONTRIBUTING.md#a-note-about-ai

zeriong · 2026-05-12T15:16:52Z

@soartec-lab

Apologies — I think I misinterpreted your earlier note about per-in defaults as a hint to refactor further, but rereading it, it was just clarifying the spec. The extra helpers in the latest commit are out of scope for #3231 and don't change behavior.

Shall I revert to the 2nd commit (6cb04e1) with just explode ?? true and the style === 'form' guard?

I'll also be more careful in reviewing AI-assisted output before pushing. Thanks for your patience.

soartec-lab · 2026-05-26T13:53:25Z

-      parameterObject.in === 'query' && isArrayLike && parameterObject.explode
-    );
-  });
+  const explodeParameters = parameterObjects.filter((parameterObject) =>


What is the significance of extracting this function? It just looks like the code has been moved.

Fair point — it's a single-use extraction that just relocates the original inline filter without reducing complexity. I'll fold the logic back into the .filter() callback.

soartec-lab · 2026-05-26T13:54:45Z

+  }
+
+  const style = parameterObject.style ?? getDefaultStyle(parameterObject.in);
+  // Only `form` style supports explode semantics in a way orval currently


/ Only form style supports explode semantics in a way orval currently
// emits (repeated key=value pairs). Other styles (spaceDelimited,
// pipeDelimited, deepObject) are intentionally not exploded here.

@soartec-lab
I think the annotation is simply copied, is there any other meaning?

soartec-lab · 2026-05-26T13:55:34Z

+
+// Per OpenAPI 3.0/3.1, the default `explode` is `true` when `style` is `form`,
+// otherwise `false`. https://swagger.io/specification/
+const getDefaultExplode = (style: string): boolean => style === 'form';


Similarly, what is the significance of extracting this variable?

Agreed. By the time this is reached, style === 'form' is already guaranteed by the guard above, so getDefaultExplode(style) always returns true. The extraction adds nothing — I'll inline it to parameterObject.explode ?? true.

soartec-lab · 2026-05-26T13:56:14Z

+// Per OpenAPI 3.0/3.1, the default `style` depends on `in`:
+// query, cookie -> "form"; path, header -> "simple".
+// https://swagger.io/specification/
+const getDefaultStyle = (parameterIn: string | undefined): string => {


It seems unlikely that the default value will be reached. I thought a ternary operator would suffice.

You're right. getDefaultStyle is only ever called from shouldExplodeArrayQueryParameter, which already returns early when in !== 'query'. So it's always called with 'query' and always returns 'form' — the cookie/path/header/default branches are unreachable here. I'll drop the switch entirely and just default style to 'form'.

zeriong · 2026-05-27T11:47:01Z

@soartec-lab
Thanks for the thorough review — you're right on all four points, and I want to be transparent about how this happened. After you cited the spec's per-in style/explode defaults on May 11, I read it as a request to encode that full table explicitly, and added getDefaultStyle / getDefaultExplode / a named predicate to do so. The intent was spec fidelity, but I missed that this code path is query- and form-only by construction (orval's explodeParameters mechanism only emits repeated key=value, which is form-style query behavior). So the per-in and non-form branches I added are not just unused — they're unreachable and untestable through the actual generation path, which makes them a liability rather than future-proofing. I'll collapse these back to the minimal form from 6cb04e1 (inline array-like check, a style ?? 'form' / style === 'form' guard, and explode ?? true); behavior and snapshots are identical. I'll keep isArrayLikeSchema since it dedups the three repeated oneOf/anyOf/allOf blocks, but happy to inline that too if you'd prefer the PR to stay strictly at 6cb04e1.

melloware requested a review from soartec-lab May 3, 2026 12:20

melloware assigned soartec-lab May 3, 2026

melloware added the fetch Fetch client related issue label May 3, 2026

zeriong added 2 commits May 10, 2026 23:52

fix(fetch): gate explode default on style === 'form' (orval-labs#3231)

6cb04e1

Signed-off-by: zeriong <jaeryong95@gmail.com>

zeriong force-pushed the fix/fetch-default-explode-true-3231 branch from 97ac3f4 to 6cb04e1 Compare May 10, 2026 14:52

soartec-lab reviewed May 11, 2026

View reviewed changes

Merge remote-tracking branch 'origin/master' into fix/fetch-default-e…

78de9b4

…xplode-true-3231

zeriong force-pushed the fix/fetch-default-explode-true-3231 branch from 6812509 to 0b338b7 Compare May 11, 2026 11:45

zeriong requested a review from soartec-lab May 12, 2026 11:57

zeriong added 3 commits May 14, 2026 11:31

Merge branch 'master' into fix/fetch-default-explode-true-3231

c197b9f

Merge branch 'master' into fix/fetch-default-explode-true-3231

84dc056

Merge branch 'master' into fix/fetch-default-explode-true-3231

d6a20ae

soartec-lab reviewed May 26, 2026

View reviewed changes

Merge branch 'master' into fix/fetch-default-explode-true-3231

6d35e93

Uh oh!

Conversation

zeriong commented May 3, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking Change

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

soartec-lab commented May 5, 2026

Uh oh!

idiodoneo-chris commented May 5, 2026

Uh oh!

soartec-lab commented May 6, 2026

Uh oh!

zeriong commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soartec-lab commented May 12, 2026

Uh oh!

zeriong commented May 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zeriong commented May 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

zeriong commented May 3, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 3, 2026 •

edited

Loading

zeriong commented May 10, 2026 •

edited

Loading