[dinwwwh]

Requested by dinwwwh · project thread

OpenAPI 3.2.1 (2026-09-10) adds or removes no fields; it only rewords some descriptions. This PR updates the JSDoc in packages/types/src/v3.2.ts that quotes the changed sentences. It touches comments and READMEs only, so the types and the downgrader behave exactly as before.

I compared against the official versions/3.2.1.md diffed with 3.2.0.md.

Reworded to 3.2.1

• jsonSchemaDialect: adds "See JSON Schema Keywords to determine the default value."
• Path Item query: now "as defined in RFC10008" instead of the IETF draft.
• Parameter allowReserved: names the percent-encoding cases (in: path, in: query, and in: cookie with style: form).
• Parameter schema: "the type and other constraints".
• Media Type encoding: the key must exist in the data instance as a property, not the schema (3.2.1 Encoding By Name). The old JSDoc used the 3.1 wording.
• Encoding contentType: "media type range" instead of "wildcard media type".
• Responses status code: "MUST be represented by a string (for example, "200" enclosed in quotes in YAML)".
• Schema Object and $schema: the OAS dialect schema id is now a URI of the form https://spec.openapis.org/oas/3.2/dialect/YYYY-MM-DD, not the 3.1 base dialect. The Schema Object is a superset of Draft 2020-12 "by default". (Pullfrog caught this one.)

Already in line with 3.2.1, left unchanged

• Encoding style, explode, and allowReserved already said "value" rather than "property value" or "parameter values".
• Media Type prefixEncoding and itemEncoding, and Example externalValue: 3.2.1 changes only sentences that this JSDoc never quoted ("If no Encoding Object is provided for an item…", "Otherwise, the value SHOULD identify…"). Their sibling fields (encoding, serializedValue) leave those sentences out too.

Links

• All 34 v3.2.0.html links in v3.2.ts, and the 3.2 links in the downgrader README, now point at v3.2.1.html. I checked that every anchor exists in 3.2.1.
• The types README lists OpenAPI 3.2.1.

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

🤖 Generated with Claude Code

https://claude.ai/code/session_01VDwPS1PbWZQngTvm2ZRgSq

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[macroscopeapp]

Approvability

Verdict: Would Approve

Macroscope's review found this PR approvable — This PR updates OpenAPI 3.2 documentation links and JSDoc descriptions across two READMEs and a type-definition file. It does not change executable code, exported type shapes, or runtime behavior.

Needs human approval because:

• Insufficient credits. Approvability relies on correctness review in order to determine eligibility

^{Review your spending limits in Billing settings. You can add or adjust custom eligibility rules. Learn more.}

[codspeed]

Merging this PR will not alter performance

✅ 21 untouched benchmarks

---

_{Comparing claude/project-thread-aanwbs (e8f0cbb) with main (70e28ec)}

[pullfrog]

ℹ️ No critical issues — the rewordings and links check out; one 3.2.1 reword appears to have been missed, noted below.

Reviewed changes

• JSDoc reworded to 3.2.1 — seven sentences in packages/types/src/v3.2.ts now match versions/3.2.1.md verbatim (I diffed against the official 3.2.0/3.2.1 sources): jsonSchemaDialect, Path Item query (RFC10008), Parameter allowReserved and schema, Media Type encoding ("data instance as a property"), Encoding contentType ("media type range"), and the Responses status-code wording.
• Spec links retargeted — every v3.2.0.html link in v3.2.ts and packages/downgrader/README.md now points at v3.2.1.html; all 27 v3.2.ts anchors and all README anchors resolve on the published page (parameter-locations and style-values are heading-derived ids, not name= anchors, and do resolve).
• README version bump — packages/types/README.md lists OpenAPI 3.2.1; no v3.2.0 links remain anywhere in the repo, and the openapi: '3.2.0' test fixtures are version values correctly left alone.
• Docs-only: no type or downgrader behavior changes. uncheck passes on both READMEs.

ℹ️ Schema dialect URI still quotes the 3.2.0 value

Both the $schema field JSDoc and the SchemaObject JSDoc still hardcode https://spec.openapis.org/oas/3.1/dialect/base as the OAS dialect schema id. 3.2.0 did say exactly that (so it matched the old spec), but 3.2.1 reworded that sentence to the URI form https://spec.openapis.org/oas/3.2/dialect/YYYY-MM-DD, and the published 3.2 dialect is https://spec.openapis.org/oas/3.2/dialect/2025-09-17. Since this PR is precisely the 3.2.0→3.2.1 JSDoc sync, this looks like the one changed sentence that was overlooked.

Technical details

# 3.2 dialect URI in JSDoc is stale

## Affected sites
- `packages/types/src/v3.2.ts:1118` — `$schema` JSDoc: "Tooling MUST support the OAS dialect schema id `https://spec.openapis.org/oas/3.1/dialect/base`"
- `packages/types/src/v3.2.ts:1492` — `SchemaObject` JSDoc: "dialect is identified by the URI `https://spec.openapis.org/oas/3.1/dialect/base`"

## Evidence
- `versions/3.2.0.md:2979` — "... is identified by the URI `https://spec.openapis.org/oas/3.1/dialect/base`"
- `versions/3.2.1.md:3004` — "The default OpenAPI Schema Object dialect ... is identified by the URI of the form `https://spec.openapis.org/oas/3.2/dialect/YYYY-MM-DD`"
- Published 3.2 dialect `$id`: `https://spec.openapis.org/oas/3.2/dialect/2025-09-17`

## Required outcome
- The 3.2 JSDoc should name the 3.2 dialect (URI form), not the 3.1 one. The `3.1/dialect/base` literal remains correct in `v3.1.ts`.

## Suggested approach (optional)
- Mirror the 3.2.1 phrasing ("URI of the form `https://spec.openapis.org/oas/3.2/dialect/YYYY-MM-DD`"), consistent with the `jsonSchemaDialect` note added in this PR.

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

[pullfrog]

✅ No new issues found.

Reviewed changes

• 3.2 dialect schema id corrected — the $schema and SchemaObject JSDoc in packages/types/src/v3.2.ts now name the 3.2 dialect (https://spec.openapis.org/oas/3.2/dialect/YYYY-MM-DD) instead of the stale .../oas/3.1/dialect/base, and the SchemaObject prose now reads "by default" a superset of Draft 2020-12. Both match versions/3.2.1.md (§ JSON Schema Keywords). This addresses the one omission flagged in the prior review.
• Docs-only, single file, comment text only — no type or downgrader behavior changes.

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