Ali Raza September 21, 2021

OpenAPI 3.1 - What's New and How to Migrate to/from Other API Specs?

The OpenAPI Initiative announced the latest API specification format OpenAPI 3.1 earlier this year. OpenAPI 3.1 introduces multiple new functionalities and improvements compared to the previous OpenAPI versions, which is why this upgrade is expected to have a higher adoption rate.

We are excited to announce the support for OpenAPI 3.1 as APIMatic’s latest supported API specification format, which can be used throughout APIMatic’s solutions like API transformation, API Portal generation, and SDK generation.

How Does APIMatic Support OpenAPI 3.1?

OpenAPI 3.1 can be used in APIMatic to perform any API transformation or to generate API portals and SDKs.

API Specification Transformation

APIMatic supports transformations between different API specification formats. If you haven’t jumped on the OpenAPI 3.1 bandwagon yet, you can transform your existing API definition file into OAS 3.1, or convert an OpenAPI 3.1 file to any supported format.

API Portal and SDK Generation

APIMatic’s Code Generator and Docs Generator also support OpenAPI 3.1 definition files. You can import your OpenAPI 3.1 file so as to generate the developer-friendly API Portal or to generate feature-rich SDKs in any language supported by APIMatic.

Behind the Scenes of Mapping OpenAPI 3.0 to OpenAPI 3.1 in APIMatic

Let’s dive in to see the process of how each component of OpenAPI 3.0 is actually mapped to the corresponding component in OpenAPI 3.1 with APIMatic Transformer.

The major difference between both formats is related to the Schema Object. Previously, the OpenAPI 3.0 Schema Object was an extended subset of JSON Schema Specification Wright Draft 00, however, the OpenAPI 3.1 Schema Object is a superset of JSON Schema Specification Draft 2020-12 by default.

Having said that, you can also use any valid JSON Schema as a Schema Object in OpenAPI 3.1 with JSON Schema Dialect declared in either JSON Schema or in jsonSchemaDialect field in the root OpenAPI 3.1 specification, for that matter.

Now let’s start looking into the mapping of some of the most widely used components of OpenAPI 3.0 to OpenAPI 3.1 one by one:

Root Object

OpenAPI 3.1 has two additional root components jsonSchemaDialect and webhooks as shown in the diagram below.

APIMatic Transformer sets jsonSchemaDialect  to “ https://json-schema.org/draft/2020-12/schema” in the exported OpenAPI 3.1 file since the exported file always contains Schema Objects which conform to JSON Schema Specification Draft 2020-12.

Difference between Root Objects of OpenAPI 3.0 and OpenAPI 3.1
Difference between Root Objects of OpenAPI 3.0 and OpenAPI 3.1

Info Object

The Info Object in OpenAPI 3.1 is a superset of the Info Object in OpenAPI 3.0 having an additional summary field. The APIMatic Transformer maps the Info Object’s data from OpenAPI 3.0 to OpenAPI 3.1.

Difference between Info Objects of OpenAPI 3.0 and OpenAPI 3.1

Difference between Info Objects of OpenAPI 3.0 and OpenAPI 3.1
Difference between License Objects of OpenAPI 3.0 and OpenAPI 3.1

Difference between Info Objects of OpenAPI 3.0 and OpenAPI 3.1

Components Object

Components Object in OpenAPI 3.1 is also a superset of the one in OpenAPI 3.0, which contains an additional pathItemsobject. However, there is a major difference between both formats in terms of Schema Objects inside Schemas, Responses, Parameters, and RequestBodies Objects.

Difference between Component Objects of OpenAPI 3.0 and OpenAPI 3.1
Difference between Component Objects of OpenAPI 3.0 and OpenAPI 3.1

Schema objects

As described above, the Schema Object in OpenAPI 3.0 is an extended subset of JSON Schema Specification Wright Draft 00 that made it confusing for users as some things could follow JSON schema standards while others had to be done in OpenAPI's style. However, the Schema Object of OpenAPI 3.1 (exported from APIMatic) is a superset of JSON Schema Specification Draft 2020-12.

The new JSON Schema Draft 2020-12 has some major changes with respect to the old JSON Schema Draft 00. Thus, APIMatic Transformer converts this Schema Object from old to new JSON Schema Draft while mapping OpenAPI 3.0 to OpenAPI 3.1.

Mappings of some widely used components from Json Schema Draft 00 to Draft 2020-12 are explained further:

Nullable flag

If your OpenAPI 3.0 Schema Object contains a nullable field, it will be mapped to the “null” type in the list of types in OpenAPI 3.1’s Schema Object since the nullable field is no longer allowed in JSON Schema Draft 2020-12 and must be declared as follows:

OpenAPI 3.0

requestBody: 
  content: 
    text/plain: 
      example: 3
      schema: 
        nullable: true
        type: integer
  required: true
OpenAPI 3.1
requestBody:
  content:
    text/plain:
      schema:
        type:
        - integer
        - 'null'
        contentEncoding: int32
        contentMediaType: text/plain
      example: 3
  required: true

 

ExclusiveMinimum and ExclusiveMaximum

In OpenAPI 3.0, exclusiveMinimum and exclusiveMaximum are of Boolean type and are used in conjunction with minimum and maximum respectively. However, in OpenAPI 3.1, exclusiveMinimum and exclusiveMaximum are of type Number and will convey the same meaning as exclusiveMinimum does in conjunction with minimum or exclusiveMaximum with maximum respectively.

OpenAPI 3.0

 requestBody: 
  content: 
    application/json: 
      schema: 
        exclusiveMaximum: true
        exclusiveMinimum: true
        maximum: 50
        minimum: 1.22
        type: number
      example: 3
  required: true
OpenAPI 3.1
requestBody:
  content:
    text/plain:
      schema:
        exclusiveMaximum: 50
        exclusiveMinimum: 1.22
        type: number
        contentEncoding: double
        contentMediaType: text/plain
      example: 3
  required: true

Single-valued Enum and Const

If you have a single-valued enum in your OpenAPI 3.0 file, the APIMatic Transformer maps this to a field called const since in OpenAPI 3.1, you have the const field to store the value for a single-valued enum. OpenAPI 3.0
requestBody: 
  content: 
    text/plain:
      schema: 
        enum: 
          - 1
        type: integer
      example: 1
  required: true
OpenAPI 3.1
requestBody:
  content:
    text/plain:
      schema:
        const: 1
        type: integer
  required: true

File Upload

In OpenAPI 3.0, you describe a file upload using type set to string and format set to binary or base64 depending on how the file contents will be encoded. However, in OpenAPI 3.1, JSON Schema’s keywords contentEncoding and contentMediaType take care of how the contents will be encoded.

Moreover, you don’t even need to use the Schema Object for a binary file in a POST request.

Binary File Upload in OpenAPI 3.0

requestBody:
  content:
    application/octet-stream:
      schema:
        type: string
        format: binary
Binary File Upload in OpenAPI 3.1
requestBody:
  content:
    application/octet-stream: {}
Upload via Multipart Request in OpenAPI 3.0
requestBody:
content:
  multipart/form-data:
    schema:
      type: object
      properties:
        userId:
          type: integer
        fileName:
          type: string
          format: binary
Upload via Multipart Request in OpenAPI 3.1
requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          userId:
            type: integer
          fileName:
            type: string
            contentMediaType: application/octet-stream
Upload Image with base64 encoding in OpenAPI 3.0
requestBody:
  content:
    image/png:
      schema:
        type: string
        format: base64
Upload Image with base64 encoding in OpenAPI 3.1
requestBody:
  content:
    image/png:
      schema:
        type: string
        format: base64

Other Components of OpenAPI 3.0

All other components of OpenAPI 3.0 are mapped to OpenAPI 3.1 in APIMatic without any change in them.

Additional Changes in OpenAPI 3.1

OpenAPI 3.1 also offers additional updates like multiple examples and reference objects:

Multiple Examples inside Schema Object

OpenAPI 3.0 allows multiple examples alongside Schema Object (i.e. as a sibling to Schema Object) but does not allow multiple examples inside Schema Object. Fortunately, the support for multiple examples inside Schema Object has been added in OpenAPI 3.1. But the structure of these multiple examples would be different from what we use for the examples alongside the Schema Object.

Multiple examples can be defined as a list of examples as shown below, it is recommended to use examples rather than a single example in Schema Object for OpenAPI 3.1.

Example inside Schema Object for OpenAPI 3.0

requestBody:
  content:
    text/plain:
      schema:
        type: integer
        example: 2
Multiple Examples inside Schema Object for OpenAPI 3.1
requestBody:
  content:
    text/plain:
      schema:
        type: integer
        examples:
        - 1
        - 2
        - 3

Reference Object

In OpenAPI 3.1, summary and description keywords have been introduced in Reference Object. These summary and description fields by default should override the summary and description fields of the referenced component respectively and if the referenced component does not allow summary or description, the corresponding field will have no effect.

For additional changes in OpenAPI 3.1, you can visit the official OpenAPI 3.1 specification.

Transforming OpenAPI 3.0 Files to OpenAPI 3.1 via APIMatic

APIMatic takes care of all of these mappings behind the scenes. To actually transform a file to OpenAPI 3.1, is just a matter of a few steps. We will be using a sample Customer API in OpenAPI 3.0 format for this example.
  1. Go to the APIMatic Dashboard and click on Transform API.
  2. Import the OpenAPI 3.0 specification linked above.
  3. Select the export format as OpenAPI 3.1.
  4. Click on Convert.
Transforming a OpenAPI 3.0 file to OpenAPI 3.1 in APIMatic
Transforming a OpenAPI 3.0 file to OpenAPI 3.1 in APIMatic

Yay! Great, you have successfully transformed an OpenAPI 3.0 file to the latest OpenAPI 3.1 format. You can look at the exported OpenAPI v3.1 specification here.

To Summarize

The features and improvements offered in OpenAPI 3.1 can open many avenues for API developers in the future as more products and services will move to support OAS 3.1. APIMatic offers a quick solution with API Transformer to convert any API definition into OpenAPI 3.1 format within seconds so you can fully utilize all tools supporting this format, and eliminate the time spent on rewriting API definitions in new formats.