-
Notifications
You must be signed in to change notification settings - Fork 9.1k
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
base: main
Are you sure you want to change the base?
Conversation
@lornajane So far looks good to me. |
Co-authored-by: Vincent Biret <[email protected]>
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. |
- 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- 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 |
### 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
### 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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?
### 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[deleted original suggestion due to typo pointed out by Jeremy below — see following comment for updated suggestion]
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Code Generation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
### 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 Generation | |
- 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` |
(thanks @jeremyfiel )
|
||
Version 3.1.2 has no material changes but does contain editorial fixes. | ||
|
||
- Clarification that Example Objects can be used in Header Objects. |
There was a problem hiding this comment.
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
I'd like to propose a slightly different ordering to improve the storytelling around this release:
This would give us a flow more like the following: 3.2 UpdatesTagsData Modeling and RepresentationOAS 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 RegistrySequential and Streaming Media TypesParameters and HeadersMultipart Media TypesXMLCode GenerationExample ObjectAdditional Major AdditionsNote: This subsection ordering within this section makes sense to me, but I do not feel strongly about it. MethodsDocument Identification and Reference ResolutionSecuritySmaller ImprovementsServers, Paths, and Runtime ExpressionsResponsesUpdated to New Versions of Other Standardsetc. |
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 |
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.