OpenAPI Specification - 3.1.0-rc0

[R4wizard]

OAS 3.1.0-rc0 Released!

view OAI changelog on GitHub

Additions

• Introduced a new top-level field - webhooks. This allows describing out-of-band webhooks that are available as part of the API.
• The Info Object has a new summary field.
• The License Object now has a new identifier field for SPDX licenses.
• Components Object now has a new entry pathItems, to allow for reusable Path Item Objects to be defined within a valid OpenAPI document.

Extended Functionality

• Updated primitive types to be based on JSON Schema Specification Draft 2019-09. This now includes type null.
• Lifted the restriction of allowing Request Body only in HTTP methods where the HTTP 1.1 specification RFC7231 has explicitly defined semantics for. While allowed in other methods, it is not recommended.
• Added support to object type for spaceDelimited and pipeDelimited style values.
• The Encoding Object now supports style, explode and allowReserved for multipart/form-data media type as well.
• To enable better webhooks support, expressions in the Callback Object can now also reference Path Item Objects.
• When using the Reference Object, summary and description fields can now be overridden.
• The Schema Object is now fully compliant with JSON Schema draft 2019-09 (see JSON Schema Core and JSON Schema Validation). See also, Breaking Changes.
• The Discriminator Object can now be extended with Specification Extensions.
• Added support for mutual TLS (mutualTLS) as a security scheme.
• Used security requirements can now define an array of roles that are required for execution (and not only scopes for OAuth 2.0 security schemes).

Changes

• An OpenAPI Document now requires at least one of paths, components or webhooks to exist at the top level. While previous versions required paths, now a valid OpenAPI Document can describe only webhooks, or even only reusable components. Thus, an OpenAPI Document no longer necessarily describes an API.
• Anywhere in the 3.0.0 Specification that had a type of Schema Object | Reference Object has been replaced to be Schema Object only. With the move to full JSON Schema support, $ref is inherently part of the Schema Object and has its own defined behavior.
• Extensions prefixed with x-oas- are now reserved for the OpenAPI Initiative.
• format is now not validated by default.

Breaking changes

• The specification versioning no longer follows SemVer.
• The nullable keyword has been removed from the Schema Object (null can be used as a type value).
• exclusiveMaximum and exclusiveMinimum cannot accept boolean values (following JSON Schema).
• Due to the compliance with JSON Schema, there is no longer interaction between required and readOnly/writeOnly in relation to requests and responses.
• format (whether byte, binary, or base64) is no longer used to describe file payloads. As part of JSON Schema compliance, now contentEncoding and contentMediaType can be used for such specification.

Clarifications

• Reworded the definition of OpenAPI Document to reflect that a document no longer must describe paths, but can describe either paths, webhooks, components or any combination of them.
• Dropped the term RESTful APIs in favor of HTTP APIs
• Resolution of relative references has been redefined and clarified. Note there's a difference in resolution between Schema Object References and all others.
• Modification of examples to improve them and provide context for new fields/objects.

[philsturgeon]

Hey @R4wizard it's great to see you've started on this! Is there anything blocking your progress that I can help with?

I've got a few handy links here which might help, for example some articles showing off the differences between OpenAPI v3.0 and v3.1.

• https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
• https://www.apimatic.io/blog/2021/09/migrating-to-and-from-openapi-3-1/
• https://nordicapis.com/whats-new-in-openapi-3-1-0/

Here are some example files which can make for handy pass/fail test cases:

https://github.com/Mermade/openapi3-examples/tree/master/3.1

If you're looking for the JSON Schema that defines a valid OpenAPI document, that'll be right over here:

https://github.com/OAI/OpenAPI-Specification/tree/main/schemas/v3.1

Lmk if there's anything else. 👍🏻