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?

Peltz

Related: How to specify a property can be null or a reference with Swagger?. – Mellicent

Answer 1

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.

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.

Mellicent

Would be nice to reference the 3.1 specification that this is stated. Reading on swagger.io/specification it explicitly says Multiple types via an array are not supported – Gupta

Just to add for anyone coming to this later, for 3.0.3 specifically, nullable: true actually allows the type: 'nullable' value to be used. So you want to do nullable: true and type: 'null' together. spec.openapis.org/oas/v3.0.3#fixed-fields-19 – Anesthetist

@Anesthetist there's no type: 'null' keyword in OpenAPI 3.0.x; instead you're supposed to use nullable: true as explained in this answer. The wording in the spec section you linked to is a bit confusing, but the intended meaning is that the value null is considered a valid value for a schema instance if this schema has the nullable: true attribute. – Mellicent

(cont.) type: 'null' and type: [....., 'null'] are valid only is OpenAPI 3.1. – Mellicent

Hey @Mellicent thanks for pointing that out. I had to do a little bit of a deeper dive to try and understand what the schema was trying to say, because I was still finding myself confused. Based on this proposal github.com/OAI/OpenAPI-Specification/blob/main/proposals/… it would seem that adding nullable: true to type: string is equivalent to a JSON schema "type": [ "string", "null" ], but OAS 3.0 doesn't allow type: [ "string", "null" ] explicitly. I'm glad in 3.1 they moved away from nullable because 3.0 is frustratingly confusing and limiting... – Anesthetist

@Gupta I could not find your quote by the link. Instead, the spec says that the schema object "is a superset of the JSON Schema Specification Draft 2020-12", which, if you follow the next link, brings you to a page with examples exactly like in this answer (datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00). – Cissy

I couldn't get nullable: true to work on OpenAPI 3.0.1. It works with oneOf and a list of types string and 'null'. – Stardom