How to define a property that can be string or null in OpenAPI (Swagger)?

Question

I have JSON schema file where one of the properties is defined as either string or null:

"type":["string", "null"]

When converted to YAML (for use with OpenAPI/Swagger), it becomes:

type:
  - 'null'
  - string

but the Swagger Editor shows an error:

Schema "type" key must be a string

What is the correct way to define a nullable property in OpenAPI?

Answer 1

This depends on the OpenAPI version.

OpenAPI 3.1 (upcoming version)

Your example will be valid in OpenAPI 3.1 (once the final version is released and tools are updated to support it). This new OAS version will be compatible with JSON Schema draft 2019-09.

type:
  - 'null'   # Note the quotes around 'null'
  - string

# same as
type: ['null', string]

The above is equivalent to:

oneOf:
  - type: 'null'   # Note the quotes around 'null'
  - type: string

The nullable keyword used in OAS 3.0.x (see below) does not exist in OAS 3.1, it was removed in favor of the 'null' type.

OpenAPI 3.0.x

Nullable strings are defined as follows:

type: string
nullable: true

This is different from JSON Schema syntax because OpenAPI versions up to 3.0.x use their own flavor of JSON Schema ("extended subset"). One of the differences is that the type must be a single type and cannot be a list of types. Also there's no 'null' type; instead, the nullable keyword serves as a type modifier to allow null values.

OpenAPI 2.0

OAS2 does not support 'null' as the data type, so you are out of luck. You can only use type: string. However, some tools support x-nullable: true as a vendor extension, even though nulls are not part of the OpenAPI 2.0 Specification.

Consider migrating to OpenAPI v. 3 to get proper support for nulls.