Keep null in OpenAPI 3.1 nullable enums

BA
3d ago
+526-8

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

  • EnumSchemaParser sets nullable on the parsed enum when the schema has nullable: true, "null" in type, or null in enum (new SchemaUtils.hasNullTypeOrValue). The check runs before the existing filter removes null. Inline enums then get | null through the existing inline formatter, the same way 3.0 ones do.
  • With enumStyle: "union", the generated type includes null: export type Color = "red" | "green" | null.
  • With the enum and const styles, a TypeScript enum or const object cannot hold null, so a $ref to a nullable enum is typed Color | null wherever it is used: object properties, array items ((Color | null)[]), oneOf branches and record values. This lives in PrimitiveSchemaParser, where a $ref becomes a type name, via SchemaUtils.isNullableEnumRef. It reads the component's parsed data, or its raw schema when the component is not parsed yet. With union the type already contains null, so nothing is added there.
  • A nullable array-valued enum (enum: [["a", "b"], ["c", "d"], null]) keeps its null too.

Enums without null are unchanged. No existing snapshot changes.

Verification

  • New tests/spec/nullable-enum with a 3.1 fixture (type+enum null, type-only null, enum-only null, array-valued enum, $ref in properties / array items / oneOf / records, a component declared after its user, non-nullable enums) and a separate 3.0 fixture (nullable: true), run with enumStyle enum, union and const: snapshots plus explicit checks. 8 of the 9 tests fail on main and all pass here.
  • bun run test: 318 tests pass. bun run format:check and bun run build pass. bun run lint reports the same 4 errors and 60 warnings as on main (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 null in type or enum as nullable, matching 3.0 nullable: true behavior.
  • Union-style enum types now include null ("red" | "green" | null).
  • With enum and const styles, every reference to a nullable enum—object properties, array items, union branches, and record values—is typed Color | null because a TypeScript enum or const object can't hold null.
  • Adds tests covering inline and $ref uses across all enum styles, including enum-only nullable enums and components referenced before they're parsed.