Skip to content

Draft release notes for 3.2.0 and 3.1.2 #4600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 10 commits into
base: main
Choose a base branch
from

Conversation

lornajane
Copy link
Contributor

@lornajane lornajane commented May 16, 2025

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
Copy link
Contributor

miqui commented May 20, 2025

@lornajane So far looks good to me.

lornajane and others added 2 commits May 24, 2025 20:00
Co-authored-by: Vincent Biret <vincentbiret@hotmail.com>
@jeremyfiel
Copy link
Contributor

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

@lornajane
Copy link
Contributor Author

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

### Editorial changes:

- Extensive additions around media types, encoding, sequential media types, SSE examples, working with binary data,
- Clarification that Example Objects can be used in Header Objects.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we changed anything here? PR #4648 allows additional use of example/examples for both Parameter and Header fields, but that has not merged yet?


Version 3.1.2 has no material changes but does contain editorial fixes.

- Clarification that Example Objects can be used in Header Objects.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as under 3.2

@handrews
Copy link
Member

handrews commented Jul 5, 2025

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

  1. 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.
  2. Expanded HTTP method support, self-identifying documents, and expanded OAuth support are our other major changes.
  3. 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

Tags

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
Copy link
Contributor Author

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>

- additional parameter location `querystring`, to allow parsing the entire query string as a single field similar to the way a request body is handled, using the `content` field. Useful for complex or unconventional query data. Mutually exclusive with the `query` field.
- parameters can therefore be `in` the `querystring` as an alternative to the existing `header`, `cookie`, `query` and `path` values.
- `allowReserved` field is now permitted on parameters and headers with any value of `in` (however this many not be a Good Idea (TM) in some scenarios)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you suggest some situations where it might be unwise? I'm not sure what's implied.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lornajane let me make a suggestion without that line. It's addressed in the spec- it's more that percent-encoding (which is mandated by schema+style and is reduced but not eliminated by allowReserved) is not suitable for all parameter types. I'm not sure why I thought it should be mentioned in the notes.

Suggested change
- `allowReserved` field is now permitted on parameters and headers with any value of `in` (however this many not be a Good Idea (TM) in some scenarios)
- `allowReserved` field is now permitted on parameters and headers with any value of `in`

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants