Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

OpenApi: optional query and header parameters are documented as nullable

Open
  • Is something wrong?
#9,461 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@Marve10s is already working on this.

Since Oct 17, 2026.

  • #9464 by @Marve10s — open

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
57/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
api

Research direction

Start in OpenApi.ts at processParameters, the entry point named in the issue, and trace how optional query and header parameter schemas pass through the representation pipeline. Compare those parameter schemas with the body handling described in the issue, then inspect or add focused tests for OpenApi.fromApi query and header output. Done means optional parameters omit JSON null while preserving the documented string forms, with body behavior unchanged.

Written by the indexing model from the issue text.

Description

What version of Effect is running?

4.0.5. Also seen on 4.0.0. OpenApi.ts on main is the same as in 4.0.5.

What steps can reproduce the bug?

OpenApi.fromApi documents a query parameter declared with Schema.optional as anyOf: [T, null]. A query string has no way to send null, and the server's query decoder doesn't accept one.

import { Schema } from "effect"
import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api"

const Query = Schema.Struct({
  limit: Schema.optional(Schema.FiniteFromString),
  cursor: Schema.optional(Schema.NullOr(Schema.String))
})

const Api = HttpApi.make("api").add(
  HttpApiGroup.make("items").add(
    HttpApiEndpoint.get("list", "/items", { query: Query, success: Schema.String })
  )
)

console.log(JSON.stringify(OpenApi.fromApi(Api).paths["/items"].get.parameters, null, 2))

// What the server does with the `null` the document allows
const decodeQuery = Schema.decodeUnknownExit(Schema.toCodecStringTree(Query))
console.log(decodeQuery({ limit: "null" })._tag) // "Failure"
What is the expected behavior?

limit documented as { "type": "string" } with required: false. required: false already says the parameter can be left out, so the undefined that Schema.optional adds has nothing left to describe.

cursor documented with only the string form of its NullOr, anyOf: [{ "type": "string", "enum": ["null"] }, { "type": "string" }], and no JSON null around it.

What do you see instead?
[
  {
    "name": "limit",
    "in": "query",
    "schema": { "anyOf": [{ "type": "string" }, { "type": "null" }] },
    "required": false
  },
  {
    "name": "cursor",
    "in": "query",
    "schema": {
      "anyOf": [
        { "anyOf": [{ "type": "string", "enum": ["null"] }, { "type": "string" }] },
        { "type": "null" }
      ]
    },
    "required": false
  }
]

cursor shows the mismatch most clearly. Its NullOr gets the query codec's representation, the string "null". The undefined from Schema.optional gets the JSON codec's, where Undefined encodes as null. One parameter ends up described by two codecs.

Additional information
  • Headers have the same problem: headers: Schema.Struct({ "x-trace": Schema.optional(Schema.String) }) comes out as anyOf: [{ "type": "string" }, { "type": "null" }].
  • Bodies are fine. A JSON body does decode null to undefined, so T | null is the right description there.
  • Effect's own HttpApiClient is unaffected, since it drops undefined before building the URL. Clients generated from the document are the ones that break. We generate ours with orval, which types limit as string | null and sends ?limit=null when given null. The service then rejects the request, or, for a plain Schema.String, reads "null" as a real value.
  • Switching to Schema.optionalKey fixes the document. It also makes { limit: undefined } fail to encode, so every caller that builds a query from a possibly-undefined value has to leave the key out by hand, which is what Schema.optional exists to avoid.
  • A possible workaround until it's fixed: an OpenApi.Transform that drops the null member from every parameter where required is false.
  • My guess at the cause, from reading the source: processParameters queues parameter schemas as "properties" ops, and those go through the same representation pipeline as bodies, so an optional property's undefined gets the JSON rule.
Dominant language
TypeScript
Stars
16.7k
Forks
808
Avg merge
10h 12m
Merged PRs (30d)
813

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Effect-TS/effect

All issues in Effect-TS/effect

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.