[dinwwwh]

Requested by dinwwwh · project thread

What

#113 writes anyOf [{ $ref: T }, { type: "null" }] as the bare $ref when nothing else sits beside it and T already admits null. Its check, acceptsNull(target), only sees a type that names "null", as GitHub writes.

Zod, Pydantic and OpenAI write a nullable schema as anyOf [X, { type: "null" }] instead. Another nullable use of it then stays an anyOf in 3.0, and null matches both branches, so it can't become a oneOf either. NSwag reads that anyOf as an empty class:

Source	3.1	3.0 on main	3.0 here
oRPC + Zod N.nullable() / N.nullish(), N nullable with an id	anyOf [$ref N, null]	anyOf [$ref N, onlyNull]	$ref N
Pydantic Optional[Metadata] (Metadata is anyOf [X, null])	same	same, NSwag: empty Metadata2	$ref Metadata
OpenAI RealtimeSession.prompt	same	same	$ref Prompt
$ref JsonValue with JsonValue: {}	same	same	$ref JsonValue

N itself becomes nullable: true (or keeps its null pair) in 3.0, so the bare $ref still admits null.

How

A new admitsNull(target) replaces acceptsNull(target) in that branch. It is true for a target that acceptsNull, or one whose keywords are all annotations except an anyOf with a branch that acceptsNull, or one with only annotations, such as {}. README row on the null pair says so; the rest of the README diff is oxfmt re-padding the table.

Tests

New test "keeps only the $ref of an anyOf with null when the target is a nullable anyOf, as Zod and Pydantic write it" (fails on main): the Zod form, with a Pydantic title beside it, {} and a description-only target become the bare $ref; an anyOf with no null branch, an enum beside the target's anyOf, and a description beside the pair keep the anyOf. pnpm run check and pnpm test (364) pass, downgrader coverage 100%.

Corpus check from the issue hunt (19,775 docs): 32 docs change at 77 sites, every one this pair becoming the bare $ref; validator and value-oracle results match main.

Known edge: a component that is a nullable $ref to itself, N: anyOf [$ref N, null], now becomes N: $ref N. That schema matches only null in 3.1 and no library writes it, so it's left alone.

---

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

1 warning

⚠️ 1 benchmark is dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

✅ 29 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/project-thread-3272xh (52ca954) with main (8a0d645)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[pullfrog]

✅ No new issues found.

Reviewed changes

• admitsNull(target) replaces acceptsNull(target) — packages/downgrader/src/v3.1-to-v3.0.ts:795, used at :946. Widens the nullable-$ref collapse to targets that admit null via annotations + an anyOf with an acceptsNull branch (Zod/Pydantic nullable form), or via annotations only (e.g. {}).
• Comment updated at :947 to name the new Zod/Pydantic case; the old comment only mentioned the GitHub form.
• Test added — packages/downgrader/tests/v3.1-to-v3.0.test.ts:1129: the Zod/Pydantic nullable target collapses to the bare $ref, while three negative cases (no null branch, enum beside the target's anyOf, description beside the outer pair) correctly keep the anyOf.
• README null-pair row updated to describe the new target shapes; the rest of the README diff is oxfmt re-padding.

The collapse is sound only if the target still accepts null after conversion, since the outer Owner already accepts null through its own branch. I verified this independently with Ajv 2020-12 differentials across ~2400 generated targets that pass admitsNull: every one produced a converted target that still accepts null, with no unsound collapse. Full suite (364) and uncheck (oxlint/oxfmt/tsc) pass on the changed files.

The disclosed self-referential edge (N: anyOf [$ref N, null] → N: $ref N) is pathological, absent from real docs, and called out in the PR — not worth special handling.

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