Releases: OAI/OpenAPI-Specification
OAS 3.1.1 Released!
Release Notes
While the 3.1.1 release makes no changes to requirements of the OpenAPI 3.1.0 specification, it does introduce a number of notable improvements, including:
- Expands and clarifies a number of explanations, including several new appendices with supplementary details
- Focuses on technical specifics by moving examples and additional documentation now published at learn.openapis.org
- Declares that the HTML specifications at spec.openapis.org are now the authoritative versions (formerly it was the Markdown source on GitHub)
OpenAPI Description writers should mark their OpenAPI Descriptions with the version of the OpenAPI specification they used to write their specification, updating where possible.
Tooling maintainers should expect minimal work to support 3.1.1; however, we recommend checking the list of changes below.
Clearer Definitions
Introduce consistent language around OpenAPI Document/Description/Definition:
- OpenAPI Description means the OpenAPI description of an API, whether it is in one or many files.
- A document means a single file.
- An "entry document" is where the OpenAPI Description for an API starts; it may reference other documents.
Improved language regarding schemas, explaining the difference between the OpenAPI schema, the schemas used within the OpenAPI schema, and the use of a non-authoritative JSON Schema to supplement the written spec.
Added guidance around use of schema dialects.
References
Additional guidance for resolving references and parsing documents was added, resolving component names, tags, and operationIds are clarified.
The adoption of JSON Schema in 3.1.x changed the parsing and referencing, and a new section was added to cover the changes in more depth than in 3.1.0.
Improved explanation of URLs and URIs, and made clear which to use for each URL/URI field.
Clarified that Markdown links are resolved in relation to their rendered context.
Data Types
Extensive clarifications on data types and encoding.
Added a section on handling binary data.
Security
Added a note that a security
array that is empty or missing does not indicate that no security arrangements exist for this API.
Updated references to other standards where newer versions are available, and added more explanation for OpenIDConnect.
Added a "Security Concerns" section containing advice for implementers and users of OpenAPI.
Request Data
Extensive refactoring of the parameters section
Examples were updated, improved, and explanations added.
Headers have their own section with examples and specific information.
Improves and expands on OpenAPI example
and examples
and adds a "Working with Examples" section with a clearer description and examples.
Clarifies and expands on file uploads, form-urlencoded request bodies, and multipart content, and moves them to a refactored Encoding Object
section to provide better coverage of edge cases and more examples.
OAS 3.0.4 Released!
Release Notes
While the 3.0.4 release makes no changes to requirements of the OpenAPI 3.0.3 specification, it does introduce a number of notable improvements, including:
- Expands and clarifies a number of explanations, including several new appendices with supplementary details
- Focuses on technical specifics by moving examples and additional documentation now published at learn.openapis.org
- Declares that the HTML specifications at spec.openapis.org are now the authoritative versions (formerly it was the Markdown source on GitHub)
OpenAPI Description writers should mark their OpenAPI Descriptions with the version of the OpenAPI specification they used to write their specification, updating where possible.
Tooling maintainers should expect minimal work to support 3.0.4; however, we recommend checking the list of changes below.
Clearer Definitions
Introduce consistent language around OpenAPI Document/Description/Definition:
- OpenAPI Description means the OpenAPI description of an API, whether it is in one or many files.
- A document means a single file.
- An "entry document" is where the OpenAPI Description for an API starts; it may reference other documents.
Improved language regarding schemas, explaining the difference between the OpenAPI schema, the schemas used within the OpenAPI schema, and the use of a non-authoritative JSON Schema to supplement the written spec.
References
Additional guidance for resolving references and parsing documents was added, resolving component names, tags, and operationIds are clarified.
Clarified that Markdown links are resolved in relation to their rendered context.
Data Types
Extensive clarifications on data types and encoding.
Added a section on handling binary data.
Security
Added a note that a security
array that is empty or missing does not indicate that no security arrangements exist for this API.
Updated references to other standards where newer versions are available, and added more explanation for OpenIDConnect.
Added a "Security Concerns" section containing advice for implementers and users of OpenAPI.
Request Data
Extensive refactoring of the parameters section
Examples were updated, improved, and explanations added.
Headers have their own section with examples and specific information.
Improves and expands on OpenAPI example
and examples
and adds a "Working with Examples" section with a clearer description and examples.
Clarifies and expands on file uploads, form-urlencoded request bodies, and multipart content, and moves them to a refactored Encoding Object
section to provide better coverage of edge cases and more examples.
OAS 3.1.0 Released!
The OAI is pleased to announce the official release of the OpenAPI Specification 3.1.0!
Changelog
See 3.1.0-rc1 for previous changes in 3.1.0, including the explanation of why there are breaking changes.
Additions
- Added the
jsonSchemaDialect
top-level field to allow the definition of a default $schema value for Schema Objects.
Updates
- Updated some links to more accurate locations.
- Updates JSON Schema support to the latest 2020-12 draft.
- Revamped relative reference resolution under both URIs and URLs.
- Reworked file upload description to take into account new JSON Schema capabilities. This contains breaking changes.
- Both
x-oai-
andx-oas-
prefixes for Specification Extensions are now reserved to be defined by the OpenAPI Initiative.
Clarifications
- Path parameter values cannot contain the unescaped characters
/
,?
or#
. - Further explanation of where Reference Object and JSON Schema's reference should be used.
- Unified wording when values are URLs/URIs.
- Reworded Path Item's
$ref
to take into account reference and component changes. - Fixed some examples.
- Minor text changes to improve consistency and readability.
- The description of the Reference Object has been updated to further clarify its behavior.
- Further updated Schema Object's description to take into account the latest draft, and the default use of https://spec.openapis.org/oas/3.1/dialect/base as the default OAS dialect.
- Reworded "Schema Vocabularies" to "Schema dialects"
OAS 3.1.0-rc1 Released!
Changelog
See 3.1.0-rc0 for previous changes in 3.1.0, including the explanation of why there are breaking changes.
Breaking changes
- Server Variable's
enum
now MUST not be empty (changed from SHOULD). - Server Variable's
default
now MUST exist in theenum
values, if such values are defined (changed from SHOULD). responses
are no longer required to be defined under the Operation Object.
Clarifications
- It is now clarified when path template expression may not have a corresponding path parameter.
- Data types (and just primitive data types) now correspond to JSON Schema.
- Various cosmetic fixes.
- A new section was added to address how to handle the
$schema
keyword (implicitly and explicitly).
OAS 3.1.0-rc0 Released!
Changelog
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.
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 reusablePath Item Object
s 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
forspaceDelimited
andpipeDelimited
style
values. - The Encoding Object now supports
style
,explode
andallowReserved
formultipart/form-data
media type as well. - To enable better
webhooks
support, expressions in theCallback Object
can now also referencePath Item Object
s. - When using the Reference Object,
summary
anddescription
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). See also,
Breaking Changes
- 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
orwebhooks
to 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,
$ref
is inherently part of theSchema Object
and has its own defined behavior. - Extensions prefixed with
x-oas-
are now reserved for the OpenAPI Initiative. format
is now not validated by default.
Breaking changes
- The specification versioning no longer follows SemVer.
- The
nullable
keyword has been removed from theSchema Object
(null
can be used as a type value). exclusiveMaximum
andexclusiveMinimum
cannot acceptboolean
values (following JSON Schema).- Due to the compliance with JSON Schema, there is no longer interaction between
required
andreadOnly
/writeOnly
in relation to requests and responses. format
(whetherbyte
,binary
, orbase64
) is no longer used to describe file payloads. As part of JSON Schema compliance, nowcontentEncoding
andcontentMediaType
can be used for such specification.
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.
OAS 3.0.3 Released!
OAS 3.0.3 Change Log
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.
- Clarified how Path Templating works.
- Clarified the meaning of Semantic Versioning as it applies to the OpenAPI Specification (note, this is the
openapi
field, not theversion
field). - Changed some hyperlinks from
http
tohttps
. - Clarified add the notion of optional security on operations.
- Added an explanation that the
Server Variable Object
'senum
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. - Clarified paths under the
Paths Object
should start with a forward slash. - Clarified
Path Item Object
's$ref
behavior with sibling fields. - Fixed a few examples.
- Clarified the map structure of
callbacks
under theOperation Object
. - Clarified how path parameters are being matched.
- Clarified
example
/examples
value(s) in theParameter Object
. - Fixed example for
pipeDelimited
object
value. - Fixed
Callback Object
description. - Clarified
Link Object
'soperationDef
's description. - Improved ABNF for
Runtime Expressions
. - Clarified valid regex for
pattern
underSchema Object
. - Clarified the behavior of
nullable
underSchema Object
. - Fixed names of OAuth2 flows in the description of
Security Scheme Object
. - Improved description of
Security Filtering
section.
OAS 3.0.2 Released!
OAS 3.0.2 Change Log
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.
- Added clarification to case sensitivity of keys in maps.
- Reworked the Data Type table, removing the
Common Name
to reduce potential confusion. - Clarified the description of the
Server Variable Object
'sdefault
field. - Fixed various examples.
- Clarified
operationId
is case sensitive. - Clarified the default value of the
Parameter Object
'sdeprecated
field isfalse
. - Added recommendation to not use the
Parameter Object
'sallowEmptyValue
field as it will be removed in a future version. - Fixed the description of the
Media Type Object
'sschema
field. - Clarified the description of the
Responses Object
's response codes field description. - Clarified that the
Schema Object
'sadditionalProperties
field has a default value oftrue
. - Fixed a small wording issue in the
Discriminator Object
description. - Fixed the
Security Scheme Object
description to include reference to the use of API Keys in cookies. - Fixed the description of the
Security Requirement Object
.
OAS 3.0.1 Released!
OAS 3.0.1 Change Log
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:
Specification Changes
- Updated document links to HTTPS where applicable.
example
andexamples
fields descriptions were updated to reference them as 'fields' and not 'objects'.- Fixed various examples (indentation, field names, comments).
- Removed the Examples Object as it was left over during editing of v3.0.0. It was not used or referenced to by any other object in the specification.
- Various typo fixes.
Additional Changes
- Clarified the roles and processes in the Technical Steering Committee (TSC, formerly the TDC).
- Improvements to the development guidelines.
OAS 3.0.0 Released!
OAS 3.0.0 Change Log
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.
Schema Changes
- The
headers
map under the Encoding Object can now also reference headers.
Descriptive Changes
- Reworded descriptions for clearer intent (no change of meaning).
- The OpenAPI Definition File has been renamed as the OpenAPI Document.
- Changes to better conform to RFC 2119.
- Elaborated Request Body's and Response's content field support media type ranges.
- Fixed descriptions of
operationRef
andoperationId
under the Link Object. Also clarified that a Link MUST contain one of them. - Added links to OAuth2's and OpenID Connect's specifications.
Document Changes
- Some example fixes.
Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md
OAS 3.0.0-rc2 Released!
OAS 3.0.0-rc2 Change Log
Schema Changes
- The following objects have been removed from the specification: Server Variables, Content, Encoding, Callbacks, Headers, Links, Link Parameters, Scopes. They have all been replaced by the
Map
construct being effectively what they are. Clarifies that specification extensions are not allowed, as they did not make sense. - The Encoding Property Object has been renamed to the Encoding Object. This is a result of the above change.
- The Encoding Object now specifies to which media type each property is applicable.
- The Encoding Object now defines
headers
as a map of Header Objects. - The different components under the
Components Object
can now either be defined inline or referenced. - For parameters using
content
, now only one media type can be used at most. - The
headers
property under the Link Object has been removed. - Link Object has a new
requestBody
property to allow passing a request body. - The Schema Object's
discriminator
property has been completely reworked to utilize the newly supportedoneOf
andanyOf
. A newDiscriminator Object
has been added to support these changes. - The XML Object's
namespace
now MUST be an absolute URI. - The
apiKey
security scheme can now also be incookie
.
Descriptive Changes
- The
Rich Text Formatting
section has been reworded to ease the requirements. - Added OpenAPI Definition File definition.
- Clarified that an empty or nonexisting
servers
would default to a single Server with theurl
value of/
. - Reworded the section explaining the specification's versioning scheme.
- Server Variable
enum
's description has been fixed to state it can only be a string (the type was correct). - Added clarification + examples how path matching works for paths defined under the
Paths Object
. - Removed recommendation for a 120 character limit for the
summary
field under the Operation Object. - Further details added to the
form
andsimple
types ofstyle
. - Clarified that the Encoding Object applies to both
multipart
andapplication/x-www-form-urlencoded
and only those. - Clarified the possible response code wildcards are only
1XX
,2XX
,3XX
,4XX
or5XX
. - Variable Expressions have been renamed to Runtime Expressions. They have been unified between Links and Callbacks, and have a dedicated section. Various examples have been moved and removed as a result.
- Runtime expressions now use curly braces when found inside strings.
- Link Object's
parameters
now defines how to deal with cases of parameter name ambiguity.
Document Changes
- ToC has been updated to reflect changes.
- Fixed various anchors in the document.
- Various examples have been fixed.
- Various editorial changes were made to make the document more readable.
Check it out! https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md