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?
Best Answer
This depends on the OpenAPI version.
OpenAPI 3.1
Your example is valid in OpenAPI 3.1, which is fully compatible with JSON Schema 2020-12.
The above is equivalent to:
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:
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, thenullable
keyword serves as atype
modifier to allownull
values.OpenAPI 2.0
OAS2 does not support
'null'
as the data type, so you are out of luck. You can only usetype: string
. However, some tools supportx-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.