- 
                Notifications
    You must be signed in to change notification settings 
- Fork 9.2k
Closed
Description
This ticket gives everyone the opportunity to look at the changelog for the upcoming release. Please review the content and add anything you think might be missing.
The part about the JSON Schema draft is a bit lacking as we might push in some different changes before the release. Anyone who wants to add a summary for it is more than welcome.
Changelog
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 Objecthas a newsummaryfield.
- The License Objectnow has a newidentifierfield for SPDX licenses.
- Components Objectnow 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 Bodyonly 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 objecttypeforspaceDelimitedandpipeDelimitedstylevalues.
- The Encoding Objectnow supportsstyle,explodeandallowReservedformultipart/form-datamedia type as well.
- To enable better webhookssupport, expressions in theCallback Objectcan now also referencePath Item Objects.
- When using the Reference Object,summaryanddescriptionfields can now be overridden.
- The Schema Objectis now fully compliant with JSON Schema draft 2019-09 (see JSON Schema Core and JSON Schema Validation).
- The Discriminator Objectcan 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,componentsorwebhooksto exist at the top level. While previous versions requiredpaths, 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, $refis inherently part of theSchema Objectand has its own defined behavior.
- Extensions prefixed with x-oas-are now reserved for the OpenAPI Initiative.
Clarifications
- Reworded the definition of OpenAPI Documentto 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.
Metadata
Metadata
Assignees
Labels
No labels