Migrating from OpenAPI 3.0 to 3.1

If you think the OpenAPI 3.0 and 3.1 specifications are fully compatible, think again.

A few days ago, I was chatting with someone who asked me why some tools don't yet support the OpenAPI 3.1 specification. I mean, OpenAPI 3.1 was released in 2021, four years ago. Shouldn't we have already upgraded our tools to support it? Yes and no. While it sounds like a simple upgrade, there are risks associated with it. Let's find out why.

---

This article is brought to you with the help of our supporter, Scalar.

Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.

---

Everyone knows that using OpenAPI as the source of truth for your API definitions makes everything easier. You get access to numerous tools that let you do things like generating documentation, SDKs, tests, and mock servers. Each one of those tools can support one or more versions of the OpenAPI specification. In many cases, it supports the version with the most users. And, if you're building and maintaining one of those tools yourself, you try to avoid supporting new OpenAPI versions at all costs. What's so different between OpenAPI 3.0 and 3.1?

OpenAPI version 3.0.0 was first released in July 2017, more than seven years ago. Since then there have been four minor releases leading to the release of OpenAPI v3.0.4 in October 2024, last year. The differences between each minor version are, well, minor. Altogether, compared to v3.0.0, v3.0.4 introduces changes related to terminology and language with the goal of eliminating ambiguities as much as possible. One example is the change from using the word "definition" to using "description" when referring to OpenAPI documents. Another example is the additional guidelines surrounding the usage of the example and examples fields. Overall, none of these changes required any modification of the code of existing tools. In other words, if a tool supports OpenAPI v3.0.0 it also supports v3.0.4. What about v3.1.0 and beyond?

The first big change that 3.1 introduces is the full compatibility with JSON Schema. What this means is that from now on you can use any JSON Schema tool to parse and validate your OpenAPI document. According to the v3.1.1 specification "OAS 3.1 inherits the parsing requirements of JSON Schema Specification Draft 2020-12." It also means, according to the same document that it's now a "requirement to parse complete documents before deeming a Schema Object reference to be unresolvable." Another interesting change was the removable of the nullable keyword in favor of adding the null data type. While before you could have an attribute defined as a string but nullable, with 3.1 you can't. You can either have a string or a null data type but not both at the same time. Depending on how you were using data types this change might make some impact in the way you use tools. Another change that might generate problems is the change of the exclusiveMinimum and exclusiveMaximum from boolean to integer. Now the exclusive minimum and maximum follow the JSON Schema range specification. One final change that might create some issues is the change in the usage of examples. While you could use the example attribute to define a single example in 3.0, in 3.1 you have to use the examples attribute which defines an array of examples. So, even if you just have one single example you should define it as an array of one element. The v.3.1.1 specification document states that "example is retained purely for compatibility with older versions of the OpenAPI Specification."

To illustrate how the changes can affect your OpenAPI documents, here's a simple example schema defining a person on OAS 3.0:

Person:
  type: object
  properties:
    name:
      type: string
    age:
      type: integer
      format: int32
      minimum: 0
      exclusiveMinimum: true
    required:
      - name
    example:
      name: Julie
      age: 30

Here's the same schema written for OAS 3.1:

Person:
  type: object
  properties:
    name:
      type: string
    age:
      type: integer
      format: int32
      exclusiveMinimum: 0
    required:
      - name
    examples:
      - name: Julie
        age: 30

These are, in my opinion, the most important changes that might affect the behavior of tools that support only OAS 3.1 because they're not backward compatible with 3.0. If, for example, you have a document using the exclusiveMinimum as an integer, it won't validate on a tool designed for OAS 3.0. There are, however, other changes that you should pay attention to such as the support for webhooks, and the ability to use sophisticated JSON Schema logic.

While making changes to one or even a handful of OpenAPI documents doesn't feel manageable, things can get complicated when you need to handle hundreds of API descriptions. That's why some tool maintainers choose not to support OpenAPI 3.1. At least not until all the tools being used also support it. Otherwise, the risk of having API descriptions that have features only available on OpenAPI 3.1 is too high to cope with.

---