Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

OpenAPI Specification 3.1-RC0 Changelog #2223

Closed
webron opened this issue May 6, 2020 · 7 comments
Closed

OpenAPI Specification 3.1-RC0 Changelog #2223

webron opened this issue May 6, 2020 · 7 comments

Comments

@webron
Copy link
Member

webron commented May 6, 2020

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 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 referencePath 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).
  • 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.

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.
@earth2marsh
Copy link
Member

out-of-bound webhooks should perhaps be out-of-band webhooks?

@webron
Copy link
Member Author

webron commented May 7, 2020

I'm telling you, those damn foreigners...

@handrews
Copy link
Member

handrews commented May 7, 2020

Probably should call out these specifically (the first two need PRs which I can do today/tomorrow if needed, the last two are covered by PR #2200):

  • exclusiveMinimum / exclusiveMaximum as booleans
  • no more interaction between required, readOnly/writeOnly, and request/response direction
  • format no longer validates by default
  • byte and binary

Also, for the RC, probably worth noting that the final release will correspond to the next JSON Schema draft, including these changes which are not breaking relative to OAS 3 even though they are breaking relative to draft 2019-09:

@handrews
Copy link
Member

handrews commented May 7, 2020

Also if we go to 4.0, do we want to drop nullable entirely so there's only one way to do null values?

@m-mohr
Copy link

m-mohr commented May 12, 2020

Also if we go to 4.0, do we want to drop nullable entirely so there's only one way to do null values?

Wouldn't you usually deprecate nullable in 3.1 and then remove it in 4.0?

@handrews
Copy link
Member

@m-mohr there's some question over whether this release should be 3.1 or 4.0. See #2219 for details.

@webron webron changed the title OpenAPI Specification 3.1-RC0 (???) Changelog OpenAPI Specification 3.1-RC0 Changelog Jun 10, 2020
@MikeRalphson
Copy link
Member

Closing as 3.1-rc0 has been released.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants