Draft release notes for 3.2.0 and 3.1.2 #4600

lornajane · 2025-05-16T15:32:26Z

Opening this as a pull request purely as a good way to collaborate - DO NOT MERGE.

The content will be added to the github release.

miqui · 2025-05-20T00:14:51Z

@lornajane So far looks good to me.

draft-release-notes.md

Co-authored-by: Vincent Biret <[email protected]>

draft-release-notes.md

jeremyfiel · 2025-06-01T05:07:42Z

should add more detailed info on new keywords in MediaType object.

Co-authored-by: Ralf Handl <[email protected]>

lornajane · 2025-06-01T09:34:13Z

@jeremyfiel can you say something about what's missing? (I obviously don't know or it wouldn't be missing ...) I did just update with some of the changes from the last couple of weeks, but I don't think there is anything here that would match what you're asking for.

draft-release-notes.md

handrews · 2025-07-05T20:21:38Z

I'd like to propose a slightly different ordering to improve the storytelling around this release:

Our marquee features are improved tagging and *sequential/streaming support, and the latter of those is part of a pretty comprehensive update to data modeling and representation.
Expanded HTTP method support, self-identifying documents, and expanded OAuth support are our other major changes.
Improving the details and rigor of servers, paths, runtime expressions, and responses are "quality-of-life" improvements, to quote a recent Slack conversation.

This would give us a flow more like the following:

3.2 Updates

Data Modeling and Representation

OAS v3.2 makes significant progress towards more consistent, modular, and extensible media type and parameter support, while also expanding the set of media types supported in response to both emerging and legacy use cases. In addition, we have removed ambiguity regarding how to present examples in a variety of complex scenarios.

Media Type Registry

Sequential and Streaming Media Types

Parameters and Headers

Multipart Media Types

XML

Code Generation

Example Object

Additional Major Additions

Note: This subsection ordering within this section makes sense to me, but I do not feel strongly about it.

Methods

Document Identification and Reference Resolution

Security

Smaller Improvements

Servers, Paths, and Runtime Expressions

Responses

Updated to New Versions of Other Standards

etc.

lornajane · 2025-07-06T11:34:47Z

There's about 50% more spec change since I wrote this draft, re ordering definitely in our future! Thanks for the outline , I'll be trying to catch up this week

Co-authored-by: Henry Andrews <[email protected]>

draft-release-notes.md

ralfhandl

Nice!

Co-authored-by: Henry Andrews <[email protected]>

lornajane · 2025-08-03T21:26:54Z

Started adding the suggested structure (in 3 parts: digestible high level features, the masterpieces of data modeling, and then everything else), but I note that we don't have all the sections you mentioned @handrews , in particular:

media types registry, these are the release notes on the specification and the media types registry isn't in this document so they're not included. Hold that thought for the blog content though
code gen, I'm not sure what should go here
multipart handling, how did I get this far without adding it? I have no idea but I've put a placeholder for now!

draft-release-notes.md

miqui · 2025-08-17T21:07:32Z

@lornajane Nice job!! Looks GREAT to me.

Co-authored-by: Ralf Handl <[email protected]>

lornajane · 2025-08-25T09:33:15Z

This is chaos, I'll be restructuring to make much slimmer release notes, an upgrade guide for the learn site and an announcement blog post (with the option to drill in with blog posts on more topics). I don't have a lot of time for the next week or so but I'll push updates when I can - since I'll mostly be moving content around, feedback on this current version is still very helpful if you have any

ralfhandl

Nice! Only minor suggestions.

summary-release-notes.md

draft-release-notes.md

summary-release-notes.md

Co-authored-by: Ralf Handl <[email protected]>

draft-release-notes.md

summary-release-notes.md

handrews

@lornajane thanks for the continued great work! Here's more suggestions, please feel free to reword them further. I know I tend to include too much detail or make the language too specification-like for this.

draft-release-notes.md

Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Karen Etheridge <[email protected]>

Co-authored-by: Henry Andrews <[email protected]>

lornajane · 2025-09-14T18:37:46Z

Thank for all the brilliant reviews!! Split a bunch of the content out to become some new docs: OAI/learn.openapis.org#137

karenetheridge

That was my final pass!

There were a few places where grammar could be improved, e.g. add missing articles, switch away from passive voice but I'll leave it to the experts for the final polish :)

karenetheridge · 2025-09-18T02:55:04Z

draft-release-notes.md

+- `parent` field to point to the tag that this tag is nested under. If you use `x-tagGroups`, adjust to use a tags hierarchy.
+- `kind` field to allow a tag to be classified into a category such as navigation, or audience.
+   The `kind` field is free-form text, however there are some expected/conventional values such as `nav` (in line with the most common current usage as grouping for documentation output).
+- A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`.


Pulled this out of the bullets as the registry isn't a new field.

Suggested change

- A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`.

And we've added a [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`.

karenetheridge · 2025-09-18T02:56:14Z

draft-release-notes.md

+
+#### Support additional HTTP methods
+
+- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.


Added "field" to distinguish the field name from the actual method name which is QUERY.

Suggested change

- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.

- Support the new `query` method field alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.

karenetheridge · 2025-09-18T02:57:19Z

draft-release-notes.md

+
+- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.
+  QUERY is a [draft standard](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html) new HTTP method nearing final publication, which is designed to allow complex filtering query data to be sent in the body of a request when it doesn't fit in the query string.
+- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. you can add `LINK` under this field, but do NOT add `HEAD`; use the existing Operation Object `head` field.


Suggested change

- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. you can add `LINK` under this field, but do NOT add `HEAD`; use the existing Operation Object `head` field.

- Under an `additionalOperations` entry in a Path Item Object, use any other methods not listed as keys using the correct capitalization, e.g. you can add `LINK` under this field, but do NOT add `HEAD`; use the existing Operation Object `head` field.

karenetheridge · 2025-09-18T02:57:58Z

draft-release-notes.md

+  QUERY is a [draft standard](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-11.html) new HTTP method nearing final publication, which is designed to allow complex filtering query data to be sent in the body of a request when it doesn't fit in the query string.
+- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. you can add `LINK` under this field, but do NOT add `HEAD`; use the existing Operation Object `head` field.
+
+The following example describes both QUERY and LINK methods for the `cakes/` endpoint:


Suggested change

The following example describes both QUERY and LINK methods for the `cakes/` endpoint:

The following example describes both QUERY and LINK methods for the `/cakes` endpoint:

karenetheridge · 2025-09-18T03:13:51Z

summary-release-notes.md

+- Support for additional HTTP methods
+
+    - Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.
+    - Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. `LINK`. Do NOT add `HEAD` under this, use the existing sibling `head`.


as in the main document:

Suggested change

- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. `LINK`. Do NOT add `HEAD` under this, use the existing sibling `head`.

- Under an `additionalOperations` entry in a Path Item Object, use any other methods not listed as keys using the correct capitalization, e.g. you can add `LINK` under this field, but do NOT add `HEAD`; use the existing Operation Object `head` field.

"and use the existing" instead of a
semicolon?

karenetheridge · 2025-09-18T03:15:57Z

summary-release-notes.md

+- Document identity and URL resolution
+
+    - Additional top-level field `$self` is added to allow users to define the base URI of the document, used to resolve relative references.
+    - More explanation and examples regarding URL resolution.


Suggested change

- More explanation and examples regarding URL resolution.

- More explanation and examples regarding URI resolution.

lornajane · 2025-09-20T13:44:22Z

Thanks for all your input, the content became the release notes and also some documentation updates, so the pull requests is no longer needed

Start with a list of changes

607e5d7

lornajane mentioned this pull request May 16, 2025

Release notes for 3.2.0 and 3.1.2 #4596

Closed

Add notes for 3.1, sort out formatting, add updated references

ad61ff8

lornajane mentioned this pull request May 21, 2025

Open Community (TDC) Meeting, Thursday 22 May 2025 #4584

Closed

baywet reviewed May 21, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

lornajane and others added 2 commits May 24, 2025 20:00

Update structure and improve wording

74c7289

Update draft-release-notes.md

4b8e237

Co-authored-by: Vincent Biret <[email protected]>

ralfhandl reviewed May 29, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

lornajane and others added 3 commits June 1, 2025 09:39

Update draft-release-notes.md

6c82362

Co-authored-by: Ralf Handl <[email protected]>

Sort out some formatting and suggested improvements

55b604a

Add some more recent spec additions, use section headings

5b29057

jeremyfiel mentioned this pull request Jun 3, 2025

wip for OAS 3.2 updates Redocly/redocly-cli#2119

Draft

8 tasks

handrews mentioned this pull request Jun 11, 2025

tagGroups functionality zuplo/zudoku#880

Closed

handrews requested changes Jun 14, 2025

View reviewed changes

Apply suggestions from code review

a0323b8

Co-authored-by: Henry Andrews <[email protected]>

lornajane commented Jul 8, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

lornajane added 2 commits July 8, 2025 20:56

Bring up to date, improve titles and formatting

02ad980

Reformat and remove aside

248cfc9

handrews reviewed Jul 13, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

ralfhandl reviewed Jul 18, 2025

View reviewed changes

lornajane and others added 3 commits August 3, 2025 20:32

Apply suggestions from code review

2e9fcc2

Co-authored-by: Henry Andrews <[email protected]>

Catch up on the added features

3b1d2eb

Refactor into sections

ffb4bbb

ralfhandl reviewed Aug 4, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

draft-release-notes.md Outdated Show resolved Hide resolved

draft-release-notes.md Outdated Show resolved Hide resolved

Add some more examples

9a9c498

ralfhandl linked an issue Aug 18, 2025 that may be closed by this pull request

Release notes for 3.2.0 and 3.1.2 #4596

Closed

Update draft-release-notes.md

403a010

Co-authored-by: Ralf Handl <[email protected]>

lornajane requested a review from handrews August 23, 2025 11:14

Add style: cookie and other recent changes

e8cc875

Add a much slimmer list of changes for the release notes

ca5f9f2

ralfhandl reviewed Sep 2, 2025

View reviewed changes

Apply suggestions from code review

a1e8818

Co-authored-by: Ralf Handl <[email protected]>

karenetheridge reviewed Sep 7, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

karenetheridge reviewed Sep 7, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

karenetheridge reviewed Sep 7, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

karenetheridge reviewed Sep 7, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

karenetheridge reviewed Sep 7, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

handrews reviewed Sep 7, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

karenetheridge reviewed Sep 7, 2025

View reviewed changes

draft-release-notes.md Outdated Show resolved Hide resolved

karenetheridge reviewed Sep 7, 2025

View reviewed changes

summary-release-notes.md Outdated Show resolved Hide resolved

handrews requested changes Sep 8, 2025

View reviewed changes

lornajane and others added 4 commits September 9, 2025 08:04

Apply suggestions from code review

5564550

Co-authored-by: Henry Andrews <[email protected]> Co-authored-by: Karen Etheridge <[email protected]>

Apply suggestions from code review

4c02500

Co-authored-by: Henry Andrews <[email protected]>

More updates from feedback, thanks everyone

de6cf5f

Fix formatting

540c9bf

karenetheridge reviewed Sep 18, 2025

View reviewed changes

This was referenced Sep 18, 2025

Official 3.1.2 release branch #4969

Merged

Official 3.2.0 release branch #4970

Merged

baywet mentioned this pull request Sep 19, 2025

Add support for OpenAPI 3.2 main issue BinkyLabs/OpenAPI.NET#1

Open

lornajane closed this Sep 20, 2025

	- A [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`.

	And we've added a [registry](https://spec.openapis.org/registry/tag-kind/index.html) to establish conventions for values used in `kind`.


		#### Support additional HTTP methods

		- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.

	- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.
	- Support the new `query` method field alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.

	- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization, e.g. you can add `LINK` under this field, but do NOT add `HEAD`; use the existing Operation Object `head` field.
	- Under an `additionalOperations` entry in a Path Item Object, use any other methods not listed as keys using the correct capitalization, e.g. you can add `LINK` under this field, but do NOT add `HEAD`; use the existing Operation Object `head` field.

	The following example describes both QUERY and LINK methods for the `cakes/` endpoint:
	The following example describes both QUERY and LINK methods for the `/cakes` endpoint:

	- More explanation and examples regarding URL resolution.
	- More explanation and examples regarding URI resolution.

Draft release notes for 3.2.0 and 3.1.2 #4600

Draft release notes for 3.2.0 and 3.1.2 #4600

Uh oh!

Conversation

lornajane commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

miqui commented May 20, 2025

Uh oh!

Uh oh!

Uh oh!

jeremyfiel commented Jun 1, 2025

Uh oh!

lornajane commented Jun 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

handrews commented Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

3.2 Updates

Tags

Data Modeling and Representation

Media Type Registry

Sequential and Streaming Media Types

Parameters and Headers

Multipart Media Types

XML

Code Generation

Example Object

Additional Major Additions

Methods

Document Identification and Reference Resolution

Security

Smaller Improvements

Servers, Paths, and Runtime Expressions

Responses

Updated to New Versions of Other Standards

etc.

Uh oh!

lornajane commented Jul 6, 2025

Uh oh!

Uh oh!

Uh oh!

ralfhandl left a comment

Choose a reason for hiding this comment

Uh oh!

lornajane commented Aug 3, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

miqui commented Aug 17, 2025

Uh oh!

lornajane commented Aug 25, 2025

Uh oh!

ralfhandl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lornajane commented May 16, 2025 •

edited

Loading

handrews commented Jul 5, 2025 •

edited

Loading