[tatomyr]

What/Why/How?

OpenAPI 3.2 adds an optional description field to the Media Type Object (OAI/OpenAPI-Specification#5584), and lint reports it in OpenAPI 3.2 descriptions as "Property description is not expected here".

The OpenAPI 3.2 types now hold the field, so lint accepts it.

Before merge

The field is in the OpenAPI 3.2 draft and waits for the next patch release. Merge this PR after that release.

Reference

OAI/OpenAPI-Specification#5584

Testing

Locally, e2e tests.

Screenshots (optional)

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

---

Note

Low Risk
Schema-only addition to OpenAPI 3.2 type definitions with e2e coverage; no runtime auth, data, or security behavior changes.

Overview
OpenAPI 3.2.1 adds an optional description on Media Type Objects. Redocly’s OpenAPI 3.2 struct types did not include it, so lint reported Property description is not expected here under content entries.

This change extends the MediaType node in oas3_2.ts with a string description (CommonMark allowed, per spec). lint now accepts the field on 3.2 documents. An e2e fixture covers application/json under a request body, and the lint snapshot reflects the extra line.

^{Reviewed by Cursor Bugbot for commit c7cc6d2. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: e59d45d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@redocly/openapi-core	Patch
@redocly/cli	Patch
@redocly/client-generator	Patch
@redocly/recheck	Patch
@redocly/respect-core	Patch
@redocly/reunite-integration	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

📝 Recheck Summary

ℹ️ No Markdown files changed under docs/ or cookbook/.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	82.63% (🎯 80%)	21953 / 26565
🔵	Statements	82.19% (🎯 80%)	23825 / 28987
🔵	Functions	84.4% (🎯 80%)	4258 / 5045
🔵	Branches	75.57% (🎯 75%)	16271 / 21529

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/core/src/types/oas3_2.ts	72.72%	28.57%	100%	72.72%	70-84, 88-123, 138-155

Generated in workflow #13272 for commit e59d45d by the Vitest Coverage Report Action

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
latest	▓░░░░░░░░░░ 1.01x ± 0	▓░░░░░░░░░░ 1.00x	▓░░░░░░░░░░ 1.00x
next	▓░░░░░░░░░░ 1.00x	▓░░░░░░░░░░ 1.00x ± 0.02	▓░░░░░░░░░░ 1.00x ± 0.01