Skip to content

Keep null in OpenAPI 3.1 nullable enums - #1848

Open
bardrop wants to merge 3 commits into
acacode:mainfrom
bardrop-oss:fix-nullable-enum-3-1
Open

bardrop wants to merge 3 commits into
acacode:mainfrom
bardrop-oss:fix-nullable-enum-3-1

Conversation

@bardrop

@bardrop bardrop commented Nov 14, 2026 •

Copy link
Copy Markdown

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.

Written for commit 8e6a88f. Summary will update on new commits.

View guided diff

OpenAPI 3.1 writes a nullable enum as type: [T, "null"] and/or with
null in enum. EnumSchemaParser stripped the null value and only kept
3.0 nullable: true, so these enums lost their null. Treat null in type
or enum as nullable, include null in union-style enum types, and add
null to a property that references a nullable enum through $ref when
the enum style cannot hold null (enum, const).

Fixes acacode#1847
@changeset-bot

changeset-bot Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 8e6a88f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
swagger-typescript-api Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 8 files

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

Comment thread tests/spec/nullable-enum/schema.json Resolved
Move the nullable enum $ref check into the primitive parser so array
items, union branches and record values get `| null` too, not only
object properties. Read the raw component when it is not parsed yet.
Keep null for nullable array-valued enums. Split the OpenAPI 3.0 cases
into their own fixture.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 9 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

Comment thread src/schema-parser/schema-utils.ts Resolved

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

OpenAPI 3.1 nullable enums (type: [T, "null"]) drop null from generated types

1 participant