Keep null in OpenAPI 3.1 nullable enums
Fixes #1847
Problem
OpenAPI 3.1 removed nullable: true. A nullable enum is written as type: ["string", "null"] and/or with null in enum. The generator dropped that null:
status: { type: ["string", "null"], enum: ["active", "pending", null] }
level: { type: ["integer", "null"], enum: [1, 2, null] }
color: { $ref: "#/components/schemas/Color" } # Color: { type: ["string", "null"], enum: ["red", "green", null] }
came out as status?: "active" | "pending", level?: 1 | 2 and color?: Color in every enum style, so code checking for null did not type-check. EnumSchemaParser.parse() filters null out of schema.enum, and the formatters only add null back when the 3.0 nullable flag is set.
A 3.0 nullable: true enum had a related gap: inline it gets | null, but a property that references it through $ref stays color?: Color.
Solution
EnumSchemaParsersetsnullableon the parsed enum when the schema hasnullable: true,"null"intype, ornullinenum(newSchemaUtils.hasNullTypeOrValue). The check runs before the existing filter removesnull. Inline enums then get| nullthrough the existing inline formatter, the same way 3.0 ones do.- With
enumStyle: "union", the generated type includesnull:export type Color = "red" | "green" | null. - With the
enumandconststyles, a TypeScript enum or const object cannot holdnull, so a$refto a nullable enum is typedColor | nullwherever it is used: object properties, array items ((Color | null)[]), oneOf branches and record values. This lives inPrimitiveSchemaParser, where a$refbecomes a type name, viaSchemaUtils.isNullableEnumRef. It reads the component's parsed data, or its raw schema when the component is not parsed yet. Withunionthe type already containsnull, so nothing is added there. - A nullable array-valued enum (
enum: [["a", "b"], ["c", "d"], null]) keeps itsnulltoo.
Enums without null are unchanged. No existing snapshot changes.
Verification
- New
tests/spec/nullable-enumwith a 3.1 fixture (type+enumnull,type-only null,enum-only null, array-valued enum,$refin properties / array items / oneOf / records, a component declared after its user, non-nullable enums) and a separate 3.0 fixture (nullable: true), run withenumStyleenum,unionandconst: snapshots plus explicit checks. 8 of the 9 tests fail onmainand all pass here. bun run test: 318 tests pass.bun run format:checkandbun run buildpass.bun run lintreports the same 4 errors and 60 warnings as onmain(none in changed lines).- A changeset is included.
Summary by cubic
Keeps null in OpenAPI 3.1 nullable enums so generated types match the schema. Previously, nullable enums declared with type: ["string", "null"] or null in enum lost the null, and a $ref to a 3.0 nullable: true enum also dropped null.
Fixes #1847.
- Treats
nullintypeorenumas nullable, matching 3.0nullable: truebehavior. - Union-style enum types now include
null("red" | "green" | null). - With
enumandconststyles, every reference to a nullable enum—object properties, array items, union branches, and record values—is typedColor | nullbecause a TypeScript enum or const object can't holdnull. - Adds tests covering inline and
$refuses across all enum styles, including enum-only nullable enums and components referenced before they're parsed.