[dinwwwh]

Requested by dinwwwh · project thread

Problem

Zod writes .nullable() on objects, arrays, integers, and formatted strings as anyOf: [X, { type: "null" }]. In 3.1 to 3.0, that stayed an anyOf with the null-only branch, anyOf: [X, { type: "string", nullable: true, enum: [null] }]. NSwag 14.7 turns it into empty classes, so a .NET client fails at runtime on valid JSON. Kiota and oapi-codegen make wrapper or union types. Zod's own openapi-3.0 target writes X with nullable: true instead.

Change

When a schema's anyOf has exactly two branches, one of them the null-only branch, the other branch now replaces the anyOf with nullable: true. It has to meet these conditions:

• it has a string type
• it has no $ref, enum, allOf, anyOf, oneOf, not, or nullable. Null could still fail any of those beside nullable: true. Wrapping $refs in allOf with nullable broke oapi-codegen and datamodel-codegen, and putting null in an enum breaks openapi-python-client and oapi-codegen, so those cases keep the anyOf.
• it shares no keyword with the schema around it

downgradeSchemaV31ToV30({ anyOf: [{ type: 'object', properties: { a: { type: 'string' } } }, { type: 'null' }] })
// before: { anyOf: [{ type: 'object', properties: { a: { type: 'string' } } }, { type: 'string', nullable: true, enum: [null] }] }
// after:  { type: 'object', properties: { a: { type: 'string' } }, nullable: true }

Merges run once the whole input has been converted. In a cyclic input, such as a dereferenced recursive parent: Node | null, a cycle can reach a branch before that branch finishes converting. Merging at that point would copy a partial schema. Running the merges at the end avoids this without per-schema bookkeeping. A WeakSet of finished schemas made 3.1 to 3.0 about 12% slower. Deferring the merges keeps speed the same as main: on the generated 100-resource API, the corpus, and the oRPC doc, the medians over 300 shuffled runs were within noise.

The README gains a row for the new conversion. It also gains a limitation: datamodel-code-generator reads a required nullable: true property as never null unless --strict-nullable is passed. I checked this with datamodel-codegen. It already applies to type: [X, "null"] output.

Verification

• pnpm test: 255 pass, and coverage stays at 100% statements and branches. One existing expectation changed: anyOf: [string, null] now gives { type: "string", nullable: true }. New tests cover merged shapes, kept shapes, and the cycle case. The cycle test fails if the merge runs inside finishSchema.
• Fuzz against main with Ajv in draft-04 mode, which honors nullable: 2,176 nullable anyOf schemas with varied outer keywords, branch orders, and null spellings. 462 outputs changed, and none of them changed which values are accepted.
• pnpm run check passes.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

✅ 21 untouched benchmarks

---

_{Comparing claude/project-thread-mlwjfb (6ec102b) with main (cfae3e1)}

[pullfrog]

ℹ️ No critical issues — one minor doc gap.

Reviewed changes

• Nullable-union merge — a deferred post-conversion pass (downgradeV30 draining twoBranchAnyOfs into mergeNullable) collapses a two-branch anyOf of one single-type branch and the canonical null branch into that branch plus nullable: true, skipping branches with $ref/allOf/anyOf/enum/not/nullable/oneOf or a key shared with the surrounding schema.
• Tests — new cases for merged shapes, kept shapes (no shared key, unsupported keywords, three branches), and a cyclic parent: Node | null; the existing anyOf: [string, null] expectation now expects { type: 'string', nullable: true }.
• README — new schema-downgrade row for the conversion plus a datamodel-code-generator --strict-nullable limitation note.

The merge is semantically sound: the surviving branch's non-type keywords are type-scoped and do not apply to null, and the branch type is a non-null string, so null still only enters via nullable. The shared-key guard is load-bearing — it stops Object.assign from overwriting an outer keyword (e.g. an inner type: ['object','null'] alongside an anyOf of {type:'integer'} and null, where a merge would wrongly widen acceptance to integers). Deferring to a post-pass correctly avoids copying a partially converted branch in cycles. Verified: 255 tests pass, snapshots unchanged, pnpm run check clean.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}