-
Notifications
You must be signed in to change notification settings - Fork 9.1k
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
[REVIEW ONLY] Add written-word drafts since a PR is a good way to review #4095
base: main
Are you sure you want to change the base?
Changes from all commits
b2d8fa9
7c3faf6
31bae9b
05687b5
5a57fb0
501362d
55e533e
ef767d6
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,71 @@ | ||
The OpenAPI Initiative is pleased to announce a patch release of the 3.0 and 3.1 OpenAPI specifications. | ||
In patch releases, no changes are made to the way that APIs are described, but the specification wording itself contains many updates, expansions, and clarifications where previously the points may have been unclear or not covered. | ||
Tooling that supports 3.1.0 is expected to work without problems on 3.1.1 since the patch releases don't contain structure changes. | ||
|
||
Think of this release as the "Words Mean Things" edition. | ||
|
||
## Released versions | ||
|
||
3.1.1 is the newest and recommended version of the OpenAPI Specification. | ||
If you are starting a new project today, or have the option to upgrade, this is your target version. | ||
|
||
3.0.4 is an additional release on the 3.0 branch to incorporate the improved wording to the 3.0 branch of the specification where the changes applied there. | ||
It is expected that 3.0.4 will be the final release in the 3.0.x line. | ||
|
||
## Summary of changes | ||
|
||
The releases include as many explanations, clarifications and expanded sections as we could manage, driven mostly by the questions and comments we get from the users and tools creators of the OpenAPI Specification. | ||
The highlights include a lot of new content to expand on existing content and reduce ambiguity. | ||
The sections regarding parameters, encoding and schemas have had significant updates and expansion to cover more cases. | ||
You will also find some security clarifications and a whole new "Security Considerations" section has been added. | ||
|
||
Look out for additional appendices with some great explanations that support the additions to the main body of the specification. | ||
We added a great collection of new content sections and appendix entries about handling data including data types, serialization and encoding. | ||
In 3.1, there is more information about parsing documents and resolving references since the adoption of full JSON Schema compatibility. | ||
|
||
The updates also strayed into distinctly "meta" areas, so we've also got: | ||
|
||
- examples of using the `example(s)` fields | ||
- reference to a JSON Schema to represent the OpenAPI Specification schema | ||
- we have clearly defined when something was undefined or implementation dependent | ||
|
||
## Beyond the specification | ||
|
||
In addition to the main specifications that you can always find at [spec.openapis.org](https://spec.openapis.org), there are a number of other resources that you may find helpful: | ||
|
||
- OpenAPI's documentation and examples is available at [learn.openapis.org](https://learn.openapis.org). | ||
This site holds all the examples used in the main OpenAPI specification, and much more additional information besides. | ||
- A [non-authoritative JSON Schema representation of the OpenAPI specification](https://spec.openapis.org/#non-normative-json-schemas) is available. | ||
This representation should not require changes between 3.1.0 and 3.1.1 since patch releases don't change the structure. | ||
- The [formats registry](https://spec.openapis.org/registry/format/index.html) and the [extensions registry](https://spec.openapis.org/registry/extension/index.html) list some common patterns in specification use. | ||
|
||
ralfhandl marked this conversation as resolved.
Show resolved
Hide resolved
ralfhandl marked this conversation as resolved.
Show resolved
Hide resolved
|
||
All of these resources are now linked from the relevant parts of the OpenAPI Specification. | ||
|
||
We also updated the tooling that publishes the specification, changed the GitHub repository structure, cleaned up and reformatted all the Markdown content, and improved our workflow automation. | ||
Which doesn't affect the specification but does make it a nicer place to be and hopefully makes the next release easier too. | ||
|
||
## Upgrade process | ||
|
||
Most users and tool vendors should have no action to take, since the patch releases contain only wording changes or clarifications and no structure changes. | ||
That said, especially if you publish OpenAPI tools, take a look at the release notes on GitHub to check that there are no surprises! | ||
Comment on lines
+47
to
+50
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Since (if we move the sentence I mentioned earlier) we will have said that users don't need to make changes, should we re-focus this part on implementation? I also feel like maybe avoid "upgrade" because there technically shouldn't be a difference. I'm thinking something like the following: Implementation ConsiderationsAll clarifications in 3.0.4 and 3.1.1 apply to the entire 3.0 and 3.1 release lines, respectively, and there is no need for tools to check the patch version number in the That said, these patch releases are unusually substantial, and tool developers may find details to implement that were not previously clear. In 3.1.1, the additional guidance around modeling generic data types and also around parsing documents and resolving references may (I don't know what words to use here... "be surprising?") There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Isn't this what I wrote? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @lornajane I'm fine with leabing the text as-is, particularly if you don't see a distinction. TBH I wrote this review several days ago and then forgot to hit send so I don't quite recall why I was concerned. My obsessions over wording are often helpful in specification text, and much less so elsewhere 😅 |
||
|
||
## Acknowledgements | ||
|
||
So many contributors have contributed to this release, it's not possible to name them all. | ||
If you suggested an idea, joined our regular calls to discuss the changes, opened or reviewed a pull request, or participated in any of the discussions about the changes, then we thank you! | ||
We had a LOT of help, and the new releases are very much improved for it (also the previous release was quite some time ago, a lot of people added to the project in the meantime). | ||
|
||
Particular thanks goes to the Technical Steering Committee members who teamed up and shepherded the whole thing through, and to Henry Andrews whose counsel and hands-on help were a very welcome addition to the process. | ||
|
||
## Get involved | ||
|
||
There are lots of ways to get involved with OpenAPI, and we like to hear from everyone who uses OpenAPI (or wants to)! | ||
|
||
- Start with [the OpenAPI Initiative website](https://openapis.org) to find out more about all our activities. | ||
- Your organization can [become an OpenAPI Initiative member](https://www.openapis.org/membership/join). | ||
- All the standards and resources are developed in the open on GitHub. | ||
Try one of these projects [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification), the new [Arazzo specification](https://github.com/OAI/Arazzo-Specification), the upcoming [Overlay specification](https://github.com/OAI/Overlay-Specification), or the [learn.openapis.org site](https://github.com/OAI/learn.openapis.org). | ||
All the projects have open issues/discussions and welcome new contributors. | ||
- Join one of our [regular open meetings](https://www.openapis.org/calendar) to find out what's coming up and to get involved. | ||
- We have a Slack group that you can also [get an invitation to join](https://communityinviter.com/apps/open-api/openapi). | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,56 @@ | ||
# Release Notes | ||
|
||
While the 3.1.1 release makes no changes to requirements of the OpenAPI 3.1.0 specification, it does introduce a number of notable improvements, including: | ||
- Expands and clarifies a number of explanations, including several new appendices with supplementary details | ||
- Focuses on technical specifics by moving examples and additional documentation now published at [learn.openapis.org](https://learn.openapis.org) | ||
- Declares that the HTML specifications at [spec.openapis.org](https://spec.openapis.org) are now the authoritative versions (formerly it was the Markdown source on GitHub) | ||
|
||
OpenAPI Description writers should mark their OpenAPI Descriptions with the version of the OpenAPI specification they used to write their specification, updating where possible. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @earth2marsh commented that we needed to expand on this, but his remarks were lost in some of the reformatting. I'm not sure this belongs here in the release notes, should probably be in the announcement post instead. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @lornajane agree on any expansion being more suitable for the announcement post. |
||
|
||
Tooling maintainers should expect minimal work to support 3.1.1/3.0.4; however, we recommend checking the list of changes below. | ||
|
||
## Clearer Definitions | ||
|
||
Introduce consistent language around OpenAPI Document/Description/Definition: | ||
- OpenAPI Description means the OpenAPI description of an API, whether it is in one or many files. | ||
- A document means a single file. | ||
- An "entry document" is where the OpenAPI Description for an API starts; it may reference other documents. | ||
|
||
Improved language regarding schemas, explaining the difference between the OpenAPI schema, the schemas used within the OpenAPI schema, and the use of a non-authoritative JSON Schema to supplement the written spec. | ||
|
||
[3.1.1]Added guidance around use of schema dialects. | ||
|
||
## References | ||
|
||
Additional guidance for resolving references and parsing documents was added, resolving component names, tags, and operationIds are clarified. | ||
[3.1.1]The adoption of JSON Schema in 3.1.x changed the parsing and referencing, and a new section was added to cover the changes in more depth than in 3.1.0. | ||
|
||
[3.1.1]Improved explanation of URLs and URIs, and made clear which to use for each URL/URI field. | ||
Clarified that Markdown links are resolved in relation to their rendered context. | ||
|
||
## Data Types | ||
|
||
Extensive clarifications on data types and encoding. | ||
|
||
Added a section on handling binary data. | ||
|
||
## Security | ||
|
||
Added a note that a `security` array that is empty or missing does not indicate that no security arrangements exist for this API. | ||
|
||
Updated references to other standards where newer versions are available, and added more explanation for OpenIDConnect. | ||
|
||
Added a "Security Concerns" section containing advice for implementers and users of OpenAPI. | ||
|
||
## Request Data | ||
|
||
Extensive refactoring of the parameters section | ||
Examples were updated, improved, and explanations added. | ||
|
||
Headers have their own section with examples and specific information. | ||
ralfhandl marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Improves and expands on OpenAPI `example` and `examples` and adds a "Working with Examples" section with a clearer description and examples. | ||
|
||
Clarifies and expands on file uploads, form-urlencoded request bodies, and multipart content, and moves them to a refactored `Encoding Object` section to provide better coverage of edge cases and more examples. | ||
|
||
|
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.
❤️ 🤣