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

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

…ecent minor additions

lornajane · 2025-08-17T18:40:32Z

@handrews Could you take a look at the multipart media types section I just added? We had it as **TODO** still!

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]>

karenetheridge · 2025-09-07T22:54:23Z

draft-release-notes.md

+- Other URL/URI handling does not change between 3.1 and 3.2 (but bears a recap in case you're wondering how it all goes together):
+  - Other URLs, such as to external documentation or a license, are resolved against the base URI.
+  - Relative links inside `description` fields are resolved relative to their rendered context, such as your published API documentation page.
+  - API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI.


Suggested change

- API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI.

- API endpoints (such as /paths entries, and authentication URLs) are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI.

draft-release-notes.md

karenetheridge · 2025-09-07T22:58:50Z

draft-release-notes.md

+
+- Support for sequential media types such as `text/event-stream` for server-sent events (SSE) and `multipart/mixed`, `application/jsonl`, `application/json-seq` and others for sequential data.
+- Responses can be a repeating data structure, and are treated as if they are an array of schema objects.
+- Use `itemSchema` in a mediatype entry to describe each item.


Suggested change

- Use `itemSchema` in a mediatype entry to describe each item.

- Use `itemSchema` in a media-type entry to describe each item.

Why hyphenation? AFAICT we don't hyphenate it anywhere in the OAS. I'd go with:

Suggested change

- Use `itemSchema` in a mediatype entry to describe each item.

- Use `itemSchema` in a Media Type Object to describe each item.

to avoid any confusion over what an "entry" is.

We also don't say "mediatype" either.

@karenetheridge agreed

draft-release-notes.md

karenetheridge · 2025-09-07T23:00:46Z

draft-release-notes.md

+#### Describe examples in both structured and serialized forms
+
+- The Example Object (used in `examples` fields) gets two new fields: `dataValue` and `serializedValue`.
+- `dataValue` describes the example in structured format.


Suggested change

- `dataValue` describes the example in structured format.

- `dataValue` describes the example in structured format (deserialized into the JSON document model, suitable for evaluating with a `schema`).

I agree with @karenetheridge , although if this wording is seen as too detailed, "suitable for evaluating with a schema" or "suitable for evaluating with a Schema Object" is the most important part to me.

handrews · 2025-09-07T23:57:02Z

draft-release-notes.md

+
+#### Minor updates that are worth a mention
+
+- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case.


Please let's not include this. No one can remember what "override" meant, and given the widespread incorrect implementation of the thing usually doing the "override", this is hard to even explain. Just let that language quietly disappear. As best we can tell, it had no practical implications but was instead a somewhat philosophical statement about which examples are closest to the wire format.

karenetheridge · 2025-09-07T23:57:04Z

draft-release-notes.md

+
+#### Minor updates that are worth a mention
+
+- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case.


I think this is what is intended? This is like "James while John had had had had had had had had had had had a better effect on the teacher"

Suggested change

- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case.

- Non-Schema `example`s no longer "override" Schema `example`s; tools are free to use the most appropriate `example` for any given use case.

karenetheridge · 2025-09-07T23:58:57Z

summary-release-notes.md

+
+- Additional updates
+
+    - Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case.


Suggested change

- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case.

- Non-Schema `example`s no longer "override" Schema `example`s; tools are free to use the most appropriate `example` for any given use case.

I still say just drop this from the changelog entirely. The suggested change is not quite correct as there are also two different exampleses as well as two different examples. And all of them interact in different ways. This is just removing confusing language that doesn't do anything. It shouldn't be announced any more than announcing we fixed some spelling or something.

@karenetheridge after your Slack comments about an hour or so ago, I re-read this suggestion again, and my comment stands.

Also, why do you object to just dropping this line from the change log? What benefit is there here?

I don't object. I made these comments before you suggested dropping them.

@karenetheridge apologies, it's gotten a little hard to follow it all!

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

handrews · 2025-09-08T19:48:21Z

draft-release-notes.md

+
+- Support the new `query` method alongside the existing `get`/`post`/`put`/`delete`/`options`/`head`/`patch`/`trace`.
+  Query is a new method in the HTTP standard, 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. `LINK`. Do NOT add `HEAD` under this, use the existing sibling `head`.


Suggestion for flow, I do not feel at all strongly about it.

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, 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.

draft-release-notes.md

handrews · 2025-09-08T19:52:46Z

draft-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.
+  If no `$self` field is defined, then the retrieval URI is used - just as it was in previous versions of OpenAPI.


The retrieval URI is not always correct.

Suggested change

If no `$self` field is defined, then the retrieval URI is used - just as it was in previous versions of OpenAPI.

If no `$self` field is defined, then just as in previous versions of the OAS, the base URI according to RFC3986 Section 5.1.2 – 5.1.4 is used. This is most often the retrieval URI, but see the new Appendix G for examples of all possible sources.

draft-release-notes.md

handrews · 2025-09-08T20:18:11Z

draft-release-notes.md

+- `serializedValue` shows how the example will be formatted when it is sent/received by the API.
+- The existing `value` field can still be used, which means that you can safely upgrade to 3.2 and then revisit these fields and update them to use either `dataValue` or `serializedValue` as appropriate.
+  Use the new fields for examples you add after upgrading to 3.2.
+- The existing `externalValue` field can still be used to give a reference to an example, but this is now clearly documented as being a serialized value.
+- There are lots of examples of the examples (ha!) and clear documentation of how the fields can be combined.
+- Summary of what to do: use `examples` over `example`, and use `dataValue` to show a clear, structured example of the data.
+  If your use case could benefit from an example of how the data will look when it's transmitted, use `serializedValue` as well.


I trimmed the "but this is now documented" partially for flow, but partially because it was always clear (Dan's investigation didn't find any examples of incorrect implementations).

Suggested change

- `serializedValue` shows how the example will be formatted when it is sent/received by the API.

- The existing `value` field can still be used, which means that you can safely upgrade to 3.2 and then revisit these fields and update them to use either `dataValue` or `serializedValue` as appropriate.

Use the new fields for examples you add after upgrading to 3.2.

- The existing `externalValue` field can still be used to give a reference to an example, but this is now clearly documented as being a serialized value.

- There are lots of examples of the examples (ha!) and clear documentation of how the fields can be combined.

- Summary of what to do: use `examples` over `example`, and use `dataValue` to show a clear, structured example of the data.

If your use case could benefit from an example of how the data will look when it's transmitted, use `serializedValue` as well.

- For UTF-8 compatible serializations, `serializedValue` shows how the example will be formatted when it is sent/received by the API.

- The existing `externalValue` field supports non-UTF-8-compatible serializations, and can still be used to give a reference to an example.

- The existing `value` field can still be used, which means that you can safely upgrade to 3.2 and then revisit these fields and update them to use either `dataValue` or `serializedValue` as appropriate.

Use the new fields for examples you add after upgrading to 3.2.

- There are lots of examples of the examples (ha!) and clear documentation of how the fields can be combined.

- Summary of what to do: use `examples` over `example`, and use `dataValue` to show a clear, structured example of the schema-ready data.

If your use case could benefit from an example of how the data will look when it's transmitted, use `serializedValue` as well.

handrews · 2025-09-08T20:19:26Z

draft-release-notes.md

+- New field `defaultMapping` to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized.
+- No change from previous versions: use `discriminator` to hint which entry in `anyOf` or `oneOf` is expected.
+- No change from previous versions: use `mapping` to link the discriminator property value to the Schema name if they aren't an exact match.
+- Implementations now SHOULD (rather than MAY) support templates/generics using `$dynamicRef`.


This probably belongs somewhere else, like the miscellaneous section at the end- it's not related to discriminator, and isn't really a polymorphism thing either. Or if it stays here, it should go at the top or bottom and not among the Discriminator-specific things.

handrews · 2025-09-08T20:23:05Z

draft-release-notes.md

+
+#### Editorial changes
+
+- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data.


Suggested change

- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data.

- Re-organization of the top-level sections to group more content with the most relevant Objects and bring the start of the Objects and Fields (formerly Schema) section close to the top of the OAS.

- Substantial streamlining and simplification of document parsing, relative URI-reference resolution, and implicit connection resolution, including examples of base URI determination

- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data.

draft-release-notes.md

handrews · 2025-09-08T20:27:45Z

draft-release-notes.md

+```
+
+#### Minor updates that are worth a mention
+


If PR #4927 is merged (probably needs rewriting as this is my perspective):

Suggested change

- The `openapi` field now only requires the major and minor version (e.g. `openapi: "3.2"`) to emphasize that patch within a minor release line clarify and replace earlier patch releases, and are not distinct versions with their own behavior.

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

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

Open

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

ralfhandl reviewed Aug 4, 2025

View reviewed changes

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

ralfhandl reviewed Aug 4, 2025

View reviewed changes

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

lornajane added 2 commits August 12, 2025 21:28

Add some examples for the smaller features, fix markdown

dcace33

Better opening section for security schemes

947723e

karenetheridge reviewed Aug 15, 2025

View reviewed changes

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

lornajane and others added 3 commits August 17, 2025 16:09

Update draft-release-notes.md

b69d9df

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

Update draft-release-notes.md

5f2ccbb

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

Add multipart media types section, tidy up from other feedback, add r…

a829744

…ecent minor additions

lornajane added 2 commits August 17, 2025 19:41

Correct indentation of sub-bullets

e4ca9a6

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

Open

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

handrews reviewed Sep 7, 2025

View reviewed changes

karenetheridge reviewed Sep 7, 2025

View reviewed changes

handrews requested changes Sep 8, 2025

View reviewed changes

Apply suggestions from code review

5564550

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

	- API endpoints are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI.
	- API endpoints (such as /paths entries, and authentication URLs) are resolved against the URL in the Server Object, which itself might be relative and resolved against the base URI.

	- Use `itemSchema` in a mediatype entry to describe each item.
	- Use `itemSchema` in a media-type entry to describe each item.

	- Use `itemSchema` in a mediatype entry to describe each item.
	- Use `itemSchema` in a Media Type Object to describe each item.

	- `dataValue` describes the example in structured format.
	- `dataValue` describes the example in structured format (deserialized into the JSON document model, suitable for evaluating with a `schema`).


		#### Minor updates that are worth a mention

		- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case.

	- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case.
	- Non-Schema `example`s no longer "override" Schema `example`s; tools are free to use the most appropriate `example` for any given use case.


		- Additional updates

		- Non-Schema examples no longer "override" Schema examples; tools are free to use the most appropriate example for any given use case.

	- 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, 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.

	If no `$self` field is defined, then the retrieval URI is used - just as it was in previous versions of OpenAPI.
	If no `$self` field is defined, then just as in previous versions of the OAS, the base URI according to RFC3986 Section 5.1.2 – 5.1.4 is used. This is most often the retrieval URI, but see the new Appendix G for examples of all possible sources.


		#### Editorial changes

		- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data.



	- The `openapi` field now only requires the major and minor version (e.g. `openapi: "3.2"`) to emphasize that patch within a minor release line clarify and replace earlier patch releases, and are not distinct versions with their own behavior.

Draft release notes for 3.2.0 and 3.1.2 #4600

Are you sure you want to change the base?

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!

Uh oh!

Uh oh!

Uh oh!

lornajane commented Aug 17, 2025

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!

Choose a reason for hiding this comment

Uh oh!

lornajane commented May 16, 2025 •

edited

Loading

handrews commented Jul 5, 2025 •

edited

Loading