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 <vincentbiret@hotmail.com>

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 <ralf.handl@sap.com>

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 <andrews_henry@yahoo.com>

draft-release-notes.md

ralfhandl

Nice!

Co-authored-by: Henry Andrews <andrews_henry@yahoo.com>

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!

ralfhandl · 2025-08-04T09:37:59Z

draft-release-notes.md

+
+- New `summary` field to allow short descriptions, used when displaying lists of tags. If you use the `x-displayName` extension, you can now use `summary` instead.
+- `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` to allow multiple categories of tag. 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).


Suggested change

- `kind` to allow multiple categories of tag. 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).

- `kind` to allow multiple categories of tags. 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).

ralfhandl · 2025-08-04T09:42:20Z

draft-release-notes.md

+#### Support 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. do NOT add HEAD under this, use the existing sibling `head`.


Suggested change

- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization. e.g. 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. `COPY`. Do NOT add `HEAD` under this, use the existing sibling `head`.

ralfhandl · 2025-08-04T09:47:06Z

draft-release-notes.md

+- Explanation and examples for many use cases including handling `null`, handling arrays, replacing the name, and handling ordered elements.
+- Clarify that the root schema of an XML object should use the component name.
+
+#### Show examples in both structure and serialized forms


Suggested change

#### Show examples in both structure and serialized forms

#### Show examples in both structured and serialized forms

ralfhandl · 2025-08-04T10:55:37Z

draft-release-notes.md

+- How to more clearly indicate that responses will not have a body.
+- Explanation and examples of headers including `Link` and `Set-Cookie`.
+- No change but extensive additional notes on parsing and serializing JSON and non-JSON data formats.
+  Particularly if you are buildling OpenAPI tooling, this section gives much better guidance on some of those tricky edge cases.


Suggested change

Particularly if you are buildling OpenAPI tooling, this section gives much better guidance on some of those tricky edge cases.

Particularly if you are building OpenAPI tooling, this section gives much better guidance on some of those tricky edge cases.

ralfhandl · 2025-08-04T10:57:39Z

draft-release-notes.md

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

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

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

To satisfy our markdown-lint rules

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 <vincentbiret@hotmail.com>

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 <ralf.handl@sap.com>

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 <andrews_henry@yahoo.com>

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 <andrews_henry@yahoo.com>

Catch up on the added features

3b1d2eb

Refactor into sections

ffb4bbb

ralfhandl reviewed Aug 4, 2025

View reviewed changes

	- `kind` to allow multiple categories of tag. 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).
	- `kind` to allow multiple categories of tags. 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).

	- Under an `additionalOperations` entry in a Path, use any other methods not listed as keys using the correct capitalization. e.g. 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. `COPY`. Do NOT add `HEAD` under this, use the existing sibling `head`.

	#### Show examples in both structure and serialized forms
	#### Show examples in both structured and serialized forms

	Particularly if you are buildling OpenAPI tooling, this section gives much better guidance on some of those tricky edge cases.
	Particularly if you are building OpenAPI tooling, this section gives much better guidance on some of those tricky edge cases.

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!

ralfhandl Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

ralfhandl Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

ralfhandl Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

ralfhandl Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

ralfhandl Aug 4, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lornajane commented May 16, 2025 •

edited

Loading

handrews commented Jul 5, 2025 •

edited

Loading