[dinwwwh]

Requested by dinwwwh · project thread

Fixes a regression from #87/#88. The nullable merge removes an anyOf of a branch and null (or #88 turns it into oneOf), but a $ref such as #/components/schemas/User/properties/home/anyOf/0 was kept as written and dangled, making the 3.0 document invalid.

Real producers of such refs: zod-to-json-schema 3.25 with its default $refStrategy: "root" (z.object({ home: Addr.nullable(), work: Addr.nullable() }) gives work: { anyOf: [{ $ref: "#/properties/home/anyOf/0" }, { type: "null" }] }, and a recursive Node.nullable() refs #/anyOf/0), and @apidevtools/swagger-parser bundle() with an external schema used nullable twice.

Changes

• convertSchemaRef marks, for a $ref kept as written, each input schema whose anyOf the $ref passes through. The deferred nullable merge skips those, so the pair stays an anyOf and the $ref still resolves. The marks are cleared per call. No copies are made, so a recursive $ref can't create a cycle.
• The first commit inlined such $refs instead, but a recursive one then reused the in-progress conversion of an ancestor, so the output held a JS cycle and JSON.stringify threw. The second commit replaces that.
• Tests: the zod-to-json-schema pair keeps home's anyOf and work's $ref, and a recursive $ref into #/anyOf/0 keeps the anyOf and serializes. Both fail on main.
• README limitations: such a pair stays an anyOf; $refs into a keyword 3.0 removes (prefixItems/0, propertyNames) or into a oneOf that becomes anyOf still dangle (pre-existing, rarer).

pnpm run check and all 258 tests pass; corpus snapshots are unchanged. A spec-level check of the self-referencing oneOf, the recursive anyOf, and the nullable pair gives valid 3.0 with no dangling refs.

🤖 Generated with Claude Code

https://claude.ai/code/session_013DHN6pxmaQMB2i4Rv3Kx35

[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-gd6r1r (4cabe65) with main (c716716)}

[pullfrog]

✅ No new issues found.

Reviewed changes

Reviewed the 3-file, single-commit fix for dangling $refs into anyOf/oneOf branches during 3.1→3.0 conversion.

• Inlining heuristic — isInlined now treats refs containing /anyOf/ or /oneOf/ as inline targets, so refs into those branches are converted to their targets instead of being left dangling when 3.0 merges or renames those keywords.
• Regression coverage — the new test covers a Zod-style nullable anyOf whose second branch refs the first, plus a $ref into a surviving oneOf; verified it fails without the source change.
• Documentation — README now describes the new inlining behavior and the remaining limitation for refs into removed keywords such as prefixItems/0 and propertyNames.

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