We currently advise against OpenAPI 3.1 because it is not yet sufficiently supporting in industry tooling yet.
Once tooling has sufficiently evolved to support it, we should update the guide to support it.
Changes:
The OpenAPI 3.1 Schema Object is a superset of JSON Schema, and thus fully compatible with it e.g. better support for nullable values.
extension of OpenAPI with custom keywords is possible ("vocabularies"); without the need to prefix with x- anymore
format has become non-normative; it does not need to be supported by validators because some formats were underspecified. OAS is planning to re-add some support using new keywords (additional validation "vocabularies").
allows to specify deprecation everywhere within Schema Objects e.g. on properties
Track evolution to support OpenAPI 3.1.
We currently advise against OpenAPI 3.1 because it is not yet sufficiently supporting in industry tooling yet. Once tooling has sufficiently evolved to support it, we should update the guide to support it.
Changes:
x-anymoreformathas become non-normative; it does not need to be supported by validators because some formats were underspecified. OAS is planning to re-add some support using new keywords (additional validation "vocabularies").