Improvements Added to Support for Nullable Types in API Transformer

We have added some improvements to our existing support for nullable types in API Transformer, in particular when arrays are also involved. These improvements target transformations involving the OpenAPI (v3.0), RAML (v0.8 ,v1.0), Postman (v1.0, v2.0), and Insomnia formats and will ensure reduced loss of information and improved overall quality of the output.

Details

Nullable types or schemas are those that allow null as a value in the data. In API description formats, when dealing with arrays, it is possible to mark the array schema or the array items schema as nullable. Until now, API Transformer only supported the first case (nullable arrays) but not the latter (nullable array items).

OpenAPI, RAML

API description formats like OpenAPI and RAML both allow you to define nullable schemas using the nullable and nil keywords respectively. You can use these keywords to mark array items as nullable as well, as shown below:

Example OpenAPI v3.0 Using Nullable:

{
  "type": "array",
  "items":{
    "type": "string",
    "nullable": true
  }
}

Example RAML v1.0 Using Nil Type:

type: array
items:
  type: string | nil

With the improvements under discussion, you will now be able to transform your specs without losing this information.

Comparison of Before vs Now Output

For an input RAML 1.0 schema:

type: array | nil
items:
  type: string | nil

Here is what the OpenAPI schema looked like (with information loss) when transformed from above RAML, using API Transformer:

{
    "type": "array",
    "items": {
        "type": "string"
    },
    "nullable": true
}

Here is what the OpenAPI schema looks like now (without information loss) when transformed from above RAML, using API Transformer. Note, the presence of nullable in the array items schema which was not present in the previous case:

{
    "type": "array",
    "items": {
        "type": "string",
        "nullable": true
    },
    "nullable": true
}

Moreover, for complex cases involving $ref for items type, we now export nullable info using the oneOf construct.

{
  .......
  "components": {
    "schemas": {
      "MySchema": {
        "type": "array",
        "items": {
          "oneOf": [
            {
              "nullable": true
            },
            {
              "$ref": "#/components/schemas/GlobalSchema"
            }
          ]
        }
      },
      "GlobalSchema": {
        "type": "object"
      }
    }
  }
}

Postman Collections, Insomnia

In API description formats that lack a proper type system e.g. Postman Collections and Insomnia files, APIMatic auto-generates types using the example requests and responses data. Support for nullable array items has been added in such cases as well.