OpenAPI 3.1 - The Gnarly Bits
Tags: openapi, oas, api
Published: 2023-04-03 13:08:00

---
title: OpenAPI 3.1 - The Gnarly Bits
published: true
description: An in-depth look at the differences between OpenAPI 3.0 and 3.1
tags: openapi, oas, api, apis
cover_image: https://user-images.githubusercontent.com/21603/229518009-ea09c9ba-764c-439f-8f21-5f31f84470e1.jpeg
# Use a ratio of 100:42 for best results.
published_at: 2023-04-03 13:08 +0000
---
Though obviously support in [tooling](https://tools.openapis.org/) has taken a little while to begin to appear, both for commercial and Open-Source offerings, there are already a number of resources available to help you get to grips with the latest version of the OpenAPI specification (OAS), whether you are entirely new to it, or an older hand looking to focus on the new features.

[Lorna Mitchell](https://twitter.com/lornajane), who championed the new `webhooks` feature, has a range of information available: a [blog post](https://lornajane.net/posts/2020/whats-new-in-openapi-3-1), a [video](https://www.youtube.com/watch?v=49XpXD-HP0U) and associated [slides](https://noti.st/lornajane/YRdDlZ/whats-new-in-openapi-specification-3-1).

[Phil Sturgeon](https://twitter.com/philsturgeon), who along with [Ben Hutton](https://twitter.com/relequestual) and [Henry Andrews](https://twitter.com/ixat_totep) from the [JSON Schema](https://json-schema.org/) community, helped drive the push to full JSON Schema [Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00) compliance, has written a [blog post](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) for the official [OpenAPIs.org](https://openapis.org/) website on how to transition your OAS documents from v3.0.x to v3.1.0.

My fellow OpenAPI Initiative TSC members [Ron Ratovsky](https://twitter.com/webron) and [Darrel Miller](https://twitter.com/darrel_miller) presented a webinar on [what's new in v3.1](https://www.youtube.com/watch?v=Sflpzh_cAcA).

My fellow [Postman](https://postman.com/) colleague [Arnaud Lauret](https://twitter.com/apihandyman) (the API Handyman) gave a talk at the [API Specifications Conference](https://events.linuxfoundation.org/openapi-asc/) (ASC) in 2022 entitled [OpenAPI 3.x Does What Swagger 2.0 Don’t](https://www.youtube.com/watch?v=WePbF4_7RkY).

Last but not least, the OpenAPI Initiative now has an official [getting started guide](https://oai.github.io/Documentation).

So, with all that going on, is there anything much else to add?

Indeed there is, so let's take a top-down stroll through the OpenAPI specification, to focus on the details of what has changed.

### Top-Level changes

As part of this release, we have decided to not follow SemVer anymore, and as such allow ourselves to introduce minor, but breaking changes. These changes are documented as part of the [release notes](https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0).

### Additions

*   Introduced a new top-level field - `webhooks`. This allows describing out-of-band registered 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](https://spdx.dev/) license codes.
*   The Components Object now has a new entry `pathItems`, to allow for reusable Path Item Objects to be defined within a OpenAPI document.

#### Extended Functionality

*    Updated primitive types to be based on JSON Schema Specification Draft 2020-12. This now includes type `"null"`.
*    Lifted the restriction of allowing Request Body only in HTTP methods where the HTTP 1.1 specification [RFC9110](https://www.rfc-editor.org/rfc/rfc9110) has explicitly defined semantics. While now allowed for other methods, this use is still not recommended.
*    Added support for the object type for `spaceDelimited` and `pipeDelimited` style values.
*    The Encoding Object now supports `style`, `explode` and `allowReserved` for the `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. This is the default behaviour, tooling may optionally allow merging or appending the text.
*    The Schema Object is now fully compliant with JSON Schema draft 2020-12 (see [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core.html) and [JSON Schema Validation](https://json-schema.org/draft/2020-12/json-schema-validation.html)). See also, Breaking Changes.
*    The `$ref` keyword within Schema Objects can now contain [relative JSON Pointers](https://json-schema.org/draft/2020-12/relative-json-pointer.html). 
*    The Discriminator Object can now be extended with Specification Extensions, correcting an oversight in version 3.0.
*    Added support for mutual TLS (`mutualTLS`) as a security scheme type.
*    Security requirements (such as for API keys) can now define an array of roles that are required for execution (and not only scopes for OAuth 2.0 security schemes).
*    Added the `jsonSchemaDialect` top-level field to allow the definition of a default `$schema` value for Schema Objects. This allows any past or future version of JSON Schema to be used in your OAS documents, provided that tools support them.

#### 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 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-` and `x-oai-` are now reserved for the OpenAPI Initiative.
*    The `format` keyword is now not validated by default. It is treated as an annotation. Tooling may allow opt-in validation on a best-case basis.
*    The `allowEmpty` property on `parameters` is now deprecated as it had confusing and less-than-useful behaviour.

#### 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` do not accept boolean values (following JSON Schema). They are independent keywords which take a `number`.
*    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 to control this.
*    The Server Object Variable's `enum` array now MUST not be empty (changed from SHOULD).
*    The Server Object Variable's `default` property 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

*    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 these.
*    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 and objects.
*    It is now clarified what happens when path template expressions do not have a corresponding path parameter.
*    Data types (and just primitive data types) now correspond to JSON Schema.
*    A new section was added to address how to handle the `$schema` keyword (implicitly and explicitly).
*    Updated some inline links to more accurate or secure locations.
*    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.
*    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"

## Conclusion

I hope this guide proves helpful to those considering using OAS 3.1, and those migrating from earlier versions. As ever, let me know in the comments if anything is wrong, unclear or missing.

Why not get involved in the [discussions](https://github.com/OAI/moonwalk/discussions) around a tentative OpenAPI 4.0, codename 'Moonwalk'?