[dinwwwh]

Summary

This PR updates the downgrader documentation to clarify the handling of OpenAPI 3.2 parameters and JSON Schema type inference during downgrade operations.

Changes Made

• Split parameter downgrade rule: Separated the rule for example/examples beside content from the rule for style/explode/allowReserved beside content into two distinct rows for clarity, as they have different rationales (3.1 allows examples only beside schema vs. these properties are disallowed in both versions)
• Added schema type inference note: Documented that untyped schemas gaining a format from contentEncoding or contentMediaType will also gain type: "string" during downgrade, explaining this is necessary for 3.0 compatibility with binary strings and file upload detection

Notable Details

• The parameter rule split improves documentation clarity by distinguishing between properties that have version-specific locations (example/examples) versus those that are invalid in both versions (style/explode/allowReserved beside content)
• The schema type inference behavior is important for users to understand as it represents a semantic change: schemas that previously accepted non-string values will now reject them in 3.0, but this is required for proper 3.0 tooling support of file uploads

https://claude.ai/code/session_011fEwBizWTNSA9LBukUskYJ

[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

✅ 20 untouched benchmarks

---

_{Comparing claude/sleepy-volta-rpou39 (d0cec43) with main (308cb29)¹}

Footnotes

1. No successful run was found on main (cda4e92) during the generation of this report, so 308cb29 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

• Split the "parameter properties beside content" row — the 3.2→3.1 table now separates example/examples (removed because 3.1 allows them only beside schema) from style/explode/allowReserved (schema-scoped fields, allowed by neither version beside content). Matches finishParameter in packages/downgrader/src/v3.2-to-v3.1.ts:220, which drops the same five keys whenever parameter.content is present.
• Added a 3.1→3.0 limitations note — an untyped schema that gains a format from contentEncoding/contentMediaType also gains type: "string". Matches finishSchema (packages/downgrader/src/v3.1-to-v3.0.ts:505) and the marks binary strings with format test, whose untyped { contentMediaType: "image/png" } case yields { type: "string", format: "binary" }.

Also verified the 3.2 spec places example/examples at the Parameter Object top level (usable beside content) while style/explode/allowReserved sit under "Fixed Fields for use with schema", so the new rationale is accurate. uncheck packages/downgrader/README.md passes (oxlint + oxfmt).

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