[dinwwwh]

Requested by dinwwwh · project thread

What

Adds one line to the 3.1 → 3.0 Spec Limitations in packages/downgrader/README.md:

A 3.1 document that already uses 3.2 fields, as FastAPI writes itemSchema for streaming responses, keeps them as written, and the schemas inside them are not converted. Run downgradeSpecV32ToV31 on it first.

Why

FastAPI 0.162.0 writes openapi: 3.1.0 but uses the 3.2 Media Type itemSchema for JSONL and SSE routes. downgradeSpecV31ToV30 keeps itemSchema (and the 3.1 keywords inside it, such as contentSchema and type lists) as written, so the 3.0 output is invalid. Running downgradeSpecV32ToV31 first turns each itemSchema into schema: { type: "array", items: … }, and the result downgrades cleanly.

Probe on main, with a FastAPI-shaped SSE route and a JSONL route:

path	3.0 content
downgradeSpecV31ToV30 only	itemSchema kept, contentMediaType/contentSchema and type: ["string", "null"] kept inside it
downgradeSpecV32ToV31 then downgradeSpecV31ToV30	schema: { type: "array", items: … }, with data as { type: "string" }

oRPC builds 3.2 and runs both steps, so its output never has this shape; a README note is the simple fit.

---

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-ocwmac (be1112c) with main (e324f29)²}

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. ↩

2. No successful run was found on main (f9f255f) during the generation of this report, so e324f29 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[pullfrog]

✅ No new issues found.

Reviewed changes

• Downgrader 3.1→3.0 limitation note — adds one bullet to packages/downgrader/README.md's ### Spec (downgradeSpecV31ToV30) → #### Limitations documenting that a 3.1 document already carrying 3.2 fields (FastAPI's streaming itemSchema) keeps them as written, with the schemas inside left unconverted, and pointing to running downgradeSpecV32ToV31 first.

I verified the claim against the code rather than taking it on faith: v3.1→3.0 MEDIA_TYPE_FIELDS lists only encoding/examples/schema, so itemSchema is deep-cloned through convertObject untouched and its inner schemas never reach convertSchema; and v3.2→3.1 defines itemSchema: DROP plus finishMediaType rewriting it to schema: { type: 'array', items: convertSchema(itemSchema) }. I also confirmed the FastAPI example against current fastapi/fastapi: openapi_version defaults to "3.1.0" while JSONL/SSE streaming routes emit itemSchema (SSE additionally carrying contentSchema/contentMediaType inside it). Placement in the 3.1→3.0 spec limitations is correct, and uncheck packages/downgrader/README.md passes (oxlint + oxfmt).

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