v3.2: ports from 3.3 (June/July 2026) by karenetheridge · Pull Request #5420 · OAI/OpenAPI-Specification · GitHub

Backports from 3.3 to 3.2 of recent spec edits.

Will continue populating this list until all 3.3 PRs are merged.

v3.3: define a mechanism for preserving value/part order in forms #5403 a5edad7 2026-06-03 encoding headers are not needed for serializing an array
v3.3: define a mechanism for preserving value/part order in forms #5403 ed1d645 2026-06-09 some media-types, e.g. multipart/form-data, define an explicit ordering
v3.3: define a mechanism for preserving value/part order in forms #5403 92e8405 2026-06-24 define a mechanism for preserving value/part order in forms
v3.3: fix error: encoding objects also now apply to array items #5404 2f7b55b 2026-06-03 fix error: encoding objects also now apply to array items
v3.3: set the type here, to ensure the body content is deserialized as an object #5390 3fb284b 2026-05-30 set the type here, to ensure the body content is deserialized as an object
fix error: these keywords deal with items, not properties #5386 03344fc 2026-05-13 fix error: these keywords deal with items, not properties
v3.3: use extra markup to clarify intent #5331 1432e75 2026-05-13 use extra markup to clarify intent
v3.3: include an ABNF for contentType #5324 d1eb6f5 2026-05-12 include an ABNF for contentType (amended)
v3.3: be clear which property we are referring to #5330 7ce1fec 2026-05-13 be clear which property we are referring to
v3.3: remove unnecessary use of "content" #5333 1189d3a 2026-05-13 remove unnecessary use of "content"
v3.3: describe stringified response codes without referencing a specific formaat #5332 f1c2dcf 2026-05-13 describe stringified response codes without referencing a specific format

I think all of these are suitable for inclusion into 3.2.1, as they are all clarifications rather than introducing new capabilities.

no schema changes are needed for this pull request

…rmat (OAI#5332) In JSON, property keys are always strings; in YAML they may or not be depending on the parser, but other formats may also be in use (TOML, TOON etc). What matters is the resulting type(s) of the decoded data, not the specific formatting used for the serialized form.

Appendix D no longer talks about percent-encoding of headers, as the specification is now clear that percent-encoding of headers is never done (with the exception of the use of style:form in Cookie headers).

closes OAI#4788

We are specifically talking about the "encoding" keyword here, and the multipart/form-data media-type (most other multipart types decode to arrays).

…bject (OAI#5390)

This change is accompanied by an edit to the "Forms" page in the Media-Type Registry.

…ng (OAI#5403)

All the source PRs from v3.3 have been merged now, so this is ready to go. I edited each commit to indicate the original PR it came from.

..and in comparing the diff of this branch vs v3.3-dev, it looks like nothing was missed -- the only differences from 3.3 are in the new security changes, and my two PRs that tweak the handling of multipart messages (#5407 and #5391).

@karenetheridge Were there any merge conflicts when porting these that you had to resolve?

No conflicts.

One thing which might just be me misunderstanding/misremembering.

..and be more specific about what an "array property" and "array schema" are

v3.2: fix whitespace (mistakenly added in #5420)

karenetheridge force-pushed the ether/v3.2-ports-from-3.3-202606 branch from 0a5b864 to a5edad7 Compare July 2, 2026 22:49

karenetheridge changed the base branch from main to v3.2-dev July 2, 2026 22:49

karenetheridge added 10 commits July 8, 2026 13:46

remove unnecessary use of "content" (OAI#5333 )

e922d90

Appendix D no longer talks about percent-encoding of headers, as the specification is now clear that percent-encoding of headers is never done (with the exception of the use of style:form in Cookie headers).

be clear which property we are referring to (OAI#5330 )

2aad412

include an ABNF for contentType (amended) (OAI#5324 )

16734c2

closes OAI#4788

use extra markup to clarify intent (OAI#5331 )

7648160

We are specifically talking about the "encoding" keyword here, and the multipart/form-data media-type (most other multipart types decode to arrays).

fix error: these keywords deal with items, not properties (OAI#5386 )

d8dc438

set the type here, to ensure the body content is deserialized as an o…

084f97e

…bject (OAI#5390)

fix error: encoding objects also now apply to array items (OAI#5404 )

fd245a7

define a mechanism for preserving value/part order in forms (OAI#5403 )

fd1fe2e

This change is accompanied by an edit to the "Forms" page in the Media-Type Registry.

some media-types, e.g. multipart/form-data, define an explicit orderi…

a84af72

…ng (OAI#5403)

karenetheridge force-pushed the ether/v3.2-ports-from-3.3-202606 branch from 71bc187 to e59e3a8 Compare July 8, 2026 23:25

karenetheridge marked this pull request as ready for review July 8, 2026 23:25

karenetheridge requested review from a team as code owners July 8, 2026 23:25

karenetheridge mentioned this pull request Jul 8, 2026

Open Community (TDC) Meeting, Thursday 09 July 2026 #5416

Closed

miqui previously approved these changes Jul 9, 2026

View reviewed changes

karenetheridge mentioned this pull request Jul 15, 2026

Open Community (TDC) Meeting, Thursday 16 July 2026 #5431

Closed

handrews reviewed Jul 16, 2026

View reviewed changes

Comment thread src/oas.md Outdated

karenetheridge added 2 commits July 16, 2026 10:11

replace "array schema" with clearer definition (OAI#5334 )

8d44671

clarify how encoding works for deserialization too (OAI#5422 )

0f44797

..and be more specific about what an "array property" and "array schema" are

karenetheridge dismissed miqui’s stale review via 0f44797 July 16, 2026 17:12

karenetheridge force-pushed the ether/v3.2-ports-from-3.3-202606 branch from e59e3a8 to 0f44797 Compare July 16, 2026 17:12

karenetheridge requested review from handrews and miqui July 16, 2026 17:12

handrews approved these changes Jul 16, 2026

View reviewed changes

miqui approved these changes Jul 16, 2026

View reviewed changes

karenetheridge merged commit f4c6c07 into OAI:v3.2-dev Jul 16, 2026
4 checks passed

karenetheridge deleted the ether/v3.2-ports-from-3.3-202606 branch July 16, 2026 19:54

miqui pushed a commit that referenced this pull request Aug 6, 2026

fix whitespace (mistakenly added in #5420 )

363cb47

miqui added a commit that referenced this pull request Aug 6, 2026

Merge pull request #5462 from karenetheridge/ether/v3.2-fix-whitespace

8c9c9b4

v3.2: fix whitespace (mistakenly added in #5420)

lornajane mentioned this pull request Aug 13, 2026

Create the 3.2.1 release #5491

Closed

v3.2: ports from 3.3 (June/July 2026) by karenetheridge · Pull Request #5420 · OAI/OpenAPI-Specification · GitHub

Uh oh!

v3.2: ports from 3.3 (June/July 2026) - #5420

v3.2: ports from 3.3 (June/July 2026)#5420
karenetheridge merged 12 commits into
OAI:v3.2-devfrom
karenetheridge:ether/v3.2-ports-from-3.3-202606

karenetheridge commented Jul 2, 2026

Uh oh!

karenetheridge commented Jul 8, 2026

Uh oh!

karenetheridge commented Jul 8, 2026

Uh oh!

handrews commented Jul 9, 2026

Uh oh!

karenetheridge commented Jul 9, 2026

Uh oh!

handrews left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

v3.2: ports from 3.3 (June/July 2026) by karenetheridge · Pull Request #5420 · OAI/OpenAPI-Specification · GitHub

Uh oh!

v3.2: ports from 3.3 (June/July 2026) - #5420

v3.2: ports from 3.3 (June/July 2026)#5420karenetheridge merged 12 commits intoOAI:v3.2-devOAI/OpenAPI-Specification:v3.2-devfrom karenetheridge:ether/v3.2-ports-from-3.3-202606karenetheridge/OpenAPI-Specification:ether/v3.2-ports-from-3.3-202606Copy head branch name to clipboard

Conversation

karenetheridge commented Jul 2, 2026

Uh oh!

karenetheridge commented Jul 8, 2026

Uh oh!

karenetheridge commented Jul 8, 2026

Uh oh!

handrews commented Jul 9, 2026

Uh oh!

karenetheridge commented Jul 9, 2026

Uh oh!

handrews left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

v3.2: ports from 3.3 (June/July 2026)#5420
karenetheridge merged 12 commits into
OAI:v3.2-devfrom
karenetheridge:ether/v3.2-ports-from-3.3-202606