Draft release notes for 3.2.0 and 3.1.2 #4600
Draft
+101
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@lornajane So far looks good to me. |
baywet
reviewed
May 21, 2025
Co-authored-by: Vincent Biret <[email protected]>
ralfhandl
reviewed
May 29, 2025
|
should add more detailed info on new keywords in MediaType object. |
|
@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. |
8 tasks
handrews
requested changes
Jun 14, 2025
Comment on lines
+47
to
+48
| - XML namespaces can be IRIs (rather than URIs) | ||
| - Explanation and example on how to handle `null` in XML |
There was a problem hiding this comment.
Suggested change
| - XML namespaces can be IRIs (rather than URIs) | |
| - Explanation and example on how to handle `null` in XML | |
| - New `nodeType` field allows maping schemas to all common XML node types (elements, attributes, text, or cdata) or to nothing | |
| - `attribute: true` deprecated in favor of `nodeType: attribute` | |
| - `wrapped: true` deprecated in favor of `nodeType: element` (as `nodeType` defaults to `none` for arrays to preserve compatibility) | |
| - The `xml` keyword can be used in any Schema Object | |
| - XML namespaces can be IRIs (rather than URIs) | |
| - Explanation and example on how to handle `null` in XML |
Comment on lines
+59
to
+63
| ### Parameters | ||
|
|
||
| - 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 with any value of `in` (however this many not be a Good Idea (TM) in some scenarios) |
There was a problem hiding this comment.
Suggested change
| ### Parameters | |
| - 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 with any value of `in` (however this many not be a Good Idea (TM) in some scenarios) | |
| ### Parameters and Headers | |
| - 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) |
| ### Minor edits that are worth a mention: | ||
|
|
||
| - Streamlined to YAML examples (unless something specific to another format) to try to make it easier to follow | ||
| - `allowReserved` is now supported for any parameter or header, regardless of `in` location |
There was a problem hiding this comment.
This is now covered under "Parameters and Headers"
| ### 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. |
There was a problem hiding this comment.
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?
Comment on lines
+32
to
+37
| ### Discriminator | ||
|
|
||
| - 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. | ||
| - the discriminator `propertyName` can now be an optional field. | ||
| - additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. |
There was a problem hiding this comment.
Suggested change
| ### Discriminator | |
| - 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. | |
| - the discriminator `propertyName` can now be an optional field. | |
| - additional `defaultMapping` field to indicate which schema to use if the `propertyName` is not set, or if the value is unrecognized. | |
| ### Code Generatoin | |
| - the discriminator `propertyName` can now be an optional field. | |
| - additional `defaultMapping` field 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` |
|
|
||
| Version 3.1.2 has no material changes but does contain editorial fixes. | ||
|
|
||
| - Clarification that Example Objects can be used in Header Objects. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.