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

by

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.

More Related Contents:

  1. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  2. How to specify if a field is optional or required in OpenAPI/Swagger?
  3. How to return an array of objects in SwaggerHub?
  4. How to document dynamic query parameter names in OpenAPI (Swagger)?
  5. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  6. Swagger schema properties ignored when using $ref – why?
  7. How to define mutually exclusive query parameters in Swagger (OpenAPI)?
  8. Swagger 2.0: Multiple Path objects with different paths but same request and response
  9. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  10. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  11. Swagger: wildcard path parameters
  12. How to define an optional parameter in path using swagger
  13. Swagger: “equivalent path already exists” despite different parameters
  14. Re-using model with different required properties
  15. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  16. How not to copy-paste 3 generic error responses in almost all paths?
  17. How to define global parameters in OpenAPI?
  18. Schema object without a type attribute in Swagger 2.0
  19. Swagger: take one or more values from enum
  20. How to export swagger.json (or yaml)
  21. How to add multiple example values in swagger properties?
  22. How can I represent ‘Authorization: Bearer ‘ in a Swagger Spec (swagger.json)
  23. How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?
  24. Post a json body with swagger
  25. Swagger API which is having query string
  26. OpenAPI query string parameter with list of objects
  27. How to add multiple example values for an array in OpenAPI/Swagger?
  28. OpenAPI path/query parameters nested structure serialization
  29. Sending cookie session id with Swagger 3.0
  30. How do I combine multiple OpenAPI 3 specification files together?

Leave a Comment