[dinwwwh]

Requested by dinwwwh · project thread

Docs only, no behavior change.

• Adds a one-line JSDoc to downgradeSpecV31ToV30, downgradeSchemaV31ToV30, downgradeSpecV32ToV31, and downgradeSchemaV32ToV31, so editors show what each does on hover. The spec functions name the openapi they set (3.0.4 and 3.1.2, from each finishDocument). The 3.1 to 3.0 schema function notes that local $refs resolve against the schema itself; the 3.2 to 3.1 schema function resolves no schema $refs, so its JSDoc doesn't say so.
• Adds one README sentence in Usage: the output openapi is the latest patch release, 3.1.2 or 3.0.4, and callers who want another patch release set it afterwards, as oRPC does.

pnpm run check and pnpm test (262 tests) pass locally.

---

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-j97oib (78459b5) with main (6a906e9)}

[pullfrog]

✅ No new issues found.

Reviewed changes — docs-only PR, no behavioral surface. I verified every factual claim in the added text against the source, the published OAS versions, and oRPC's source.

• JSDoc on the four converter exports — the two spec functions name the openapi they set (3.0.4 at v3.1-to-v3.0.ts:788, 3.1.2 at v3.2-to-v3.1.ts:300), matching each finishDocument. downgradeSchemaV31ToV30's "local $refs resolve against the schema itself" holds: convertSchemaRef → inline → resolvePointer(ref, ctx) → find(ctx.root, ref) with root = schema. downgradeSchemaV32ToV31 correctly omits any such note, since its convertSchema is a plain convertObject and passes $ref through.
• README output-version sentence (README.md:58) — 3.1.2 (2025-09-19) and 3.0.4 (2024-10-24) are indeed the latest patches of their lines per the spec's version list, and "as oRPC does" checks out: toVersionedOpenAPIDocument in oRPC's openapi-generator.ts downgrades then returns { ...downgraded, openapi: version }.

uncheck on the three touched files passes (oxlint, oxfmt, tsc).

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