OpenAPI 3.1 Upgrade

[tfrauenstein]

OpenAPI 3.1.0 was officially released on February 15, 2021. Last minor update OpenAPI 3.1.1 was released on Oct. 24, 2024.

Key changes in OpenAPI 3.1:

• Full support for JSON Schema (Draft 2020-12), with no OpenAPI-specific overrides — schema definitions are now fully compatible with standard JSON Schema.
• Introduction of webhooks as a first-class component.
• Removal of keywords like nullable, discriminator, example, xml, etc., from the schema object if they are not part of JSON Schema.
• The components section was expanded to support more component types, including webhooks.
• The format keyword is still supported, but OpenAPI no longer interprets it — its meaning is now tool-dependent.

Despite these improvements, OpenAPI 3.1 adoption was initially slow among tools, due to the significant shift in schema handling (especially full JSON Schema integration), which required major updates.

Let's update our guideline to use OpenAPI 3.1 -- see e.g. https://opensource.zalando.com/restful-api-guidelines/#101

[ePaul]

Action items:

• [x] check what changes are needed in Zally (@ktsypkina)
• [x] check what changes are needed in Sunrise + API portal (@tkrop)
• [x] Draft guideline update (@tfrauenstein)

[tfrauenstein]

done via https://github.com/zalando/restful-api-guidelines/pull/850