Objects in query params are not being exploded

[pgraug]

Description

When generating types for an endpoint with query parameters that contain an object, the default behaviour (style: 'form' and explode: true) should be to "explode" or "spread" the object.

That doesn't seem to be happening in the generated types.

style and explode are added to the IR.ParameterObject in packages/shared/src/openApi/3.0.x/parser/parameter.ts but they don't seem to be used for anything.

Reproducible example or configuration

I've made a small example of the bug here: https://stackblitz.com/edit/hey-api-example-hbrngrmq?file=src%2Fclient%2Ftypes.gen.ts

I currently get this:

export type PostFooData = {
  body?: never;
  path?: never;
  query: {
    externalId: number;
    pagination?: Pagination;
  };
  url: '/foo';
};

But it should output this:

export type PostFooData = {
  body?: never;
  path?: never;
  query: Pagination & {
    externalId: number;
  };
  url: '/foo';
};

Where the Pagination object is exploded which it should be by default for the default style (form).

OpenAPI specification (optional)

{
  "openapi": "3.0.0",
  "info": {
    "title": "OpenAPI 3.0.0 parameter explode object example",
    "version": "1"
  },
  "paths": {
    "/foo": {
      "post": {
        "parameters": [
          {
            "name": "externalId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "pagination",
            "in": "query",
            "schema": {
              "$ref": "#/components/schemas/Pagination"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "OK"
          }
        }
      }
    },
    "/bar": {
      "get": {
        "parameters": [
          {
            "name": "pagination",
            "in": "query",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Pagination"
            }
          }
        ],
        "responses": {
          "default": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      }
    }
  }
}

System information (optional)

No response

[bolt-new-by-stackblitz]

Start a new pull request in StackBlitz Codeflow.

• hey-api-example-hbrngrmq (Open reproduction)

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔ ｜ pullfrog.com}

[mrlubos]

@pgraug Can you show me where you interpret the spec describing this behavior?

[pgraug]

@mrlubos I found it here: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.4.md#fixed-fields-for-use-with-schema

In the table it says

style | [...] Default values (based on value of in): for "query" - "form" [...]

explode | [...] When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map. [...] When style is "form", the default value is true [...]

It's also described in this guide: https://swagger.io/docs/specification/v3_0/serialization/. In the first row of the table.

[mrlubos]

@pgraug from LLM:

The author is misunderstanding the spec.

The style: 'form' + explode: true settings are serialization directives, not type structure directives. They control how the SDK serializes the object into the URL query string at runtime, not how the types should be shaped.

The spec says: “When you serialize this pagination object to the wire, explode it into individual query params (?page=1&pageSize=10 instead of ?pagination=page,1,pageSize,10).”

The spec does not say: “Pretend this parameter doesn’t exist and merge its properties into the parent.”

Why the requested change is wrong:
1. Name collisions — If Pagination had an externalId property, the intersection type Pagination & { externalId: number } would silently conflict
2. Lost semantics — The SDK needs to know which properties belong to which parameter to serialize correctly. Flattening the types loses this grouping
3. Optionality confusion — pagination is optional, but if Pagination had required properties, flattening would incorrectly make them required at the top level
4. The parameter has a name — OpenAPI explicitly defines a parameter called pagination. That’s the contract

What Hey API should do (and likely already does):
∙ Accept { pagination?: Pagination; externalId: number } from the user
∙ Serialize to ?page=1&pageSize=10&externalId=123 at runtime using the style/explode metadata

However — there’s a valid sub-question here: is Hey API actually using those style/explode values during serialization? The author notes they’re parsed into the IR but “don’t seem to be used for anything.” That could be a legitimate runtime bug worth verifying.​​​​​​​​​​​​​​​​