OpenAPI Initiative announced specification versions 3.0.4 and 3.1.1

[rartych]

Problem description
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.
https://spec.openapis.org/oas/v3.0.4.html

Expected action
OpenAPI Initiative states that:

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.

but recommends updating where possible.
API Design Guidelines should reference to the latest release 3.0.4 and it should be used by sub-projects in Spring25 meta-release.

Additional context
https://www.openapis.org/blog/2024/10/25/announcing-openapi-specification-patch-releases

[rartych]

Release Notes

https://github.com/OAI/OpenAPI-Specification/releases/tag/3.0.4

While the 3.0.4 release makes no changes to requirements of the OpenAPI 3.0.3 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
• Declares that the HTML specifications at 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.

Tooling maintainers should expect minimal work to support 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.

References

Additional guidance for resolving references and parsing documents was added, resolving component names, tags, and operationIds are clarified.
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.

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.

[eric-murray]

The Swagger editor does not yet support 3.0.4. We should delay any requirement to use 3.0.4 until that is in place, otherwise none of our APIs will render when displayed using that tool.

[rartych]

Good point! Let's wait for the tool support then.