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- and x-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"

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 the enum 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).

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 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 reference Path 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). 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 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.
• format is now not validated by default.

Breaking changes

• The specification versioning no longer follows SemVer.
• The 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).
• Due to the compliance with JSON Schema, there is no longer interaction between 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.

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 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 the version field).
• Changed some hyperlinks from http to https.
• Clarified add the notion of optional security on operations.
• Added an explanation that the 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.
• 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 the Operation Object.
• Clarified how path parameters are being matched.
• Clarified example/examples value(s) in the Parameter Object.
• Fixed example for pipeDelimited object value.
• Fixed Callback Object description.
• Clarified Link Object's operationDef's description.
• Improved ABNF for Runtime Expressions.
• Clarified valid regex for pattern under Schema Object.
• Clarified the behavior of nullable under Schema Object.
• Fixed names of OAuth2 flows in the description of Security Scheme Object.
• Improved description of Security Filtering section.

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's default field.
• Fixed various examples.
• Clarified operationId is case sensitive.
• Clarified the default value of the Parameter Object's deprecated field is false.
• Added recommendation to not use the Parameter Object's allowEmptyValue field as it will be removed in a future version.
• Fixed the description of the Media Type Object's schema field.
• Clarified the description of the Responses Object's response codes field description.
• Clarified that the Schema Object's additionalProperties field has a default value of true.
• 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 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 and examples 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 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 and operationId 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 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 supported oneOf and anyOf. A new Discriminator 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 in cookie.

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 the url 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 and simple types of style.
• Clarified that the Encoding Object applies to both multipart and application/x-www-form-urlencoded and only those.
• Clarified the possible response code wildcards are only 1XX, 2XX, 3XX, 4XX or 5XX.
• 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

OAS 3.0.0-rc1 Change Log

Schema Changes

• url is now required under the Server Object.
• Server Variable Object's 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.
• The 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.
• The deprecated field under the Schema Object now defaults to false.
• The flow field under the Security Scheme Object has been renamed to flows.
• Request Body's required now defaults to false.
• Added allowReserved to the Encoding Property Object.

Descriptive Changes

• termsOfService now MUST be in the form of a URL.
• all description fields now support CommonMark.
• Clarified that specific response codes (200 for example) take precedence over response ranges (2XX for example).
• Clarified that for Parameter Object, either schema or content are required.
• pattern under the Schema Object now specifies the regex flavor.
• Added header restrictions. "Accept", "Content-Type", "Authorization" header paramters and "Content-Type" response headers will now be ignored.
• Referenced a specific version of supported CommonMark.
• Added clarifications to null not being a type (as opposed to a value).

Document Changes

• ToC has been updated to reflect changes.
• Fixed various anchors in the document.
• Various examples have been fixed.

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:

• Changed the versioning scheme of the spec.
• Reusable definitions in the spec has been expanded and reorganized under the Components Object.
• Added support for operation callbacks.
• Added support for a new static linking between responses and operations.
• Reworked parameters - removed formData parameters, added cookie parameters, changed body parameters to Request Body Objects as a separate entity.
• Parameters now support complex types.
• Responses support multiple media type specifications.
• Reworked file support. Dropped file as a type, but provided better handling for file uploads and downloads.
• Reworked security definitions to allow for support for more schemes.
• Improved support for examples throughout the spec.
• Added support for defining multiple servers hosting the API, including URL variables.

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.