[dinwwwh]

Requested by dinwwwh · project thread

Problem

#374 fixed $refs into a key that 3.0 renames to an extension, but only under a component schema in a document. downgradeSchemaV31ToV30 renames a root key that no keyword names in the same way, yet left the $ref as written:

downgradeSchemaV31ToV30({
  type: 'object',
  properties: { image: { $ref: '#/CustomTypes/Path' } },
  CustomTypes: { Path: { type: 'string' } },
})
// properties.image stays { $ref: '#/CustomTypes/Path' }, but the key is now x-CustomTypes

The output $ref points at nothing. This happens in real schemas. I ran about 106k standalone schemas from the hunt corpora through downgradeSchemaV31ToV30, and also converted each one as a component of a document. They differ in 7 schemas from 2 projects, and every difference is this case (#/CustomTypes/Path, #/CustomTypes/agentArgument, #/Assets).

Fix

isInlined now gives a $ref's first key the same test when the root being converted is a schema, which is the test #374 gives the key after #/components/schemas/<name>/. That test moves into a small becomesExtension helper. The root is recorded in module state beside the other per-run sets and cleared in the same finally.

What stays the same:

• Refs into keys 3.0 keeps, such as #/properties/a or #/not, stay bare.
• $ref: '#' stays as written.
• Refs in a document, such as #/paths/... or a custom root key of the document, are unaffected.

I updated the README row on keywords 3.0 does not define.

Checks

• Tests: 313 pass, downgrader coverage stays at 100%, and pnpm run check passes.
• All 37,810 corpus documents give byte-identical outputs before and after. Total time was 59.4 s before and 53.8 s after, which is run-order noise.
• Across the 106,149 standalone schemas, the standalone and in-document outputs now differ in 0 schemas (7 before). The in-document outputs had already passed the value oracles in earlier rounds.

---

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

✅ 29 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/project-thread-ttohne (ffcbb96) with main (063278f)}

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]

ℹ️ Minor suggestions only — one stale docs bullet for the newly documented scope.

Reviewed changes

• Root-key extension refs — isInlined now inlines a standalone schema's $ref when the first path key becomes a 3.0 extension, so #/CustomTypes/Path no longer dangles after CustomTypes is renamed to x-CustomTypes.
• Shared helper — the keyword-rename test is factored into becomesExtension and reused by the existing component-schema branch.
• Per-run state — schemaRoot records the schema entry point and is cleared with the other module-level pass state in the same finally.
• Docs and test — the README row is updated and a test pins the new behavior alongside a kept #/properties/... ref and #.

The code path checks out: downgradeSpecV31ToV30 leaves schemaRoot undefined, so document conversion is untouched, and refs into removed keywords (#/prefixItems/0) still dangle as documented. All 313 downgrader tests and uncheck on the touched files pass.

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