The OpenAPI Specification Repository
The OAI is pleased to announce the official release of the OpenAPI Specification 3.1.0!
See 3.1.0-rc1 for previous changes in 3.1.0, including the explanation of why there are breaking changes.
jsonSchemaDialect
top-level field to allow the definition of a default $schema value for Schema Objects.x-oai-
and x-oas-
prefixes for Specification Extensions are now reserved to be defined by the OpenAPI Initiative./
, ?
or #
.$ref
to take into account reference and component changes.See 3.1.0-rc0 for previous changes in 3.1.0, including the explanation of why there are breaking changes.
enum
now MUST not be empty (changed from SHOULD).default
now MUST exist in the enum
values, if such values are defined (changed from SHOULD).responses
are no longer required to be defined under the Operation Object.$schema
keyword (implicitly and explicitly).As part of this release, we have decided to not follow SemVer anymore, and as such introduce breaking changes. These changes are documented as part of the release notes.
webhooks
. This allows describing out-of-band webhooks that are available as part of the API.summary
field.identifier
field for SPDX licenses.pathItems
, to allow for reusable Path Item Object
s to be defined within a valid OpenAPI document.null
.object
type
for spaceDelimited
and pipeDelimited
style
values.style
, explode
and allowReserved
for multipart/form-data
media type as well.webhooks
support, expressions in the Callback Object
can now also reference Path Item Object
s.summary
and description
fields can now be overridden.Breaking Changes
mutualTLS
) as a security scheme.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.$ref
is inherently part of the Schema Object
and has its own defined behavior.x-oas-
are now reserved for the OpenAPI Initiative.format
is now not validated by default.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).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.The OAI is pleased to announce the official release of the OpenAPI Specification 3.0.3!
As a patch release, the following changes were made to improve the specification in terms of readability and accuracy. None of these modifications change the behavior of the spec.
openapi
field, not the version
field).http
to https
.Server Variable Object
's enum
should not be empty. This is not a breaking change but should be considered as guidance for a more explicit restriction in the next major version.Paths Object
should start with a forward slash.Path Item Object
's $ref
behavior with sibling fields.callbacks
under the Operation Object
.example
/examples
value(s) in the Parameter Object
.pipeDelimited
object
value.Callback Object
description.Link Object
's operationDef
's description.Runtime Expressions
.pattern
under Schema Object
.nullable
under Schema Object
.Security Scheme Object
.Security Filtering
section.The OAI is pleased to announce the official release of the OpenAPI Specification 3.0.2!
As a patch release, the following changes were made to improve the specification in terms of readability and accuracy. None of these modifications change the behavior of the spec.
Common Name
to reduce potential confusion.Server Variable Object
's default
field.operationId
is case sensitive.Parameter Object
's deprecated
field is false
.Parameter Object
's allowEmptyValue
field as it will be removed in a future version.Media Type Object
's schema
field.Responses Object
's response codes field description.Schema Object
's additionalProperties
field has a default value of true
.Discriminator Object
description.Security Scheme Object
description to include reference to the use of API Keys in cookies.Security Requirement Object
.The OAI is pleased to announce the official release of the OpenAPI Specification 3.0.1!
This our first patch release since 3.0.0, containing the following updates:
example
and examples
fields descriptions were updated to reference them as 'fields' and not 'objects'.The OAI is pleased to announce the official release of the OpenAPI Specification 3.0.0!
The list below reflect the changes since the last release candidate.
headers
map under the Encoding Object can now also reference headers.operationRef
and operationId
under the Link Object. Also clarified that a Link MUST contain one of them.Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md
Map
construct being effectively what they are. Clarifies that specification extensions are not allowed, as they did not make sense.headers
as a map of Header Objects.Components Object
can now either be defined inline or referenced.content
, now only one media type can be used at most.headers
property under the Link Object has been removed.requestBody
property to allow passing a request body.discriminator
property has been completely reworked to utilize the newly supported oneOf
and anyOf
. A new Discriminator Object
has been added to support these changes.namespace
now MUST be an absolute URI.apiKey
security scheme can now also be in cookie
.Rich Text Formatting
section has been reworded to ease the requirements.servers
would default to a single Server with the url
value of /
.enum
's description has been fixed to state it can only be a string (the type was correct).Paths Object
.summary
field under the Operation Object.form
and simple
types of style
.multipart
and application/x-www-form-urlencoded
and only those.1XX
, 2XX
, 3XX
, 4XX
or 5XX
.parameters
now defines how to deal with cases of parameter name ambiguity.Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md
url
is now required under the Server Object.enum
and default
values are now string
only (were any primitive
).servers
under the Path Item Object and Operation Object has been fixed to be an array of Server Objects and not a single one.example
and examples
fields have been reworked, alongside the Example Object. There is no longer examples
field under the Schema Object. Where examples
exist, they are now a map of named examples with additional metadata for each example. The Example Object now has defined fields and is not free-form.content
is now required under the Request Body Object.href
under the Link Object has been renamed to operationRef
, its description is clarified as well.deprecated
field under the Schema Object now defaults to false
.flow
field under the Security Scheme Object has been renamed to flows
.required
now defaults to false
.allowReserved
to the Encoding Property Object.termsOfService
now MUST be in the form of a URL.description
fields now support CommonMark.200
for example) take precedence over response ranges (2XX
for example).schema
or content
are required.pattern
under the Schema Object now specifies the regex flavor.null
not being a type (as opposed to a value).Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc1/versions/3.0.md
We're happy to announce the release of the first Implementer's Draft of OAS 3.0.0, known as 3.0.0-rc0.
A lot of changes in this release, as a first one goes, so expect the change log to be updated. An initial list of changes, in no particular order:
file
as a type, but provided better handling for file uploads and downloads.Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc0/versions/3.0.md
Our blog post contains more details of the process and next steps.