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?

API Specification Transformation

API Portal and SDK Generation

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.

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

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.

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

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

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

requestBody: 
  content: 
    text/plain:
      schema: 
        enum: 
          - 1
        type: integer
      example: 1
  required: true

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

requestBody:
  content:
    application/octet-stream: {}

requestBody:
content:
  multipart/form-data:
    schema:
      type: object
      properties:
        userId:
          type: integer
        fileName:
          type: string
          format: binary

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          userId:
            type: integer
          fileName:
            type: string
            contentMediaType: application/octet-stream

requestBody:
  content:
    image/png:
      schema:
        type: string
        format: base64

requestBody:
  content:
    image/png:
      schema:
        type: string
        format: base64

Other Components of OpenAPI 3.0

Additional Changes in OpenAPI 3.1

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

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

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.

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