Skip to content

enum in OpenAPI: allowed values, null, and adding one later

Last checked and updated

enum lists the values a field may take; anything else is invalid. The values are compared exactly, so they are case sensitive, and they should be of the schema's type.

status:
  type: string
  enum: [draft, active, archived]

A mock server generated from this refuses another value and names the field:

$ curl -X POST http://127.0.0.1:4632/items -H 'content-type: application/json' \
    -d '{"name":"a","status":"deleted","quantity":2}'
HTTP/1.1 422 Unprocessable Entity

{"errors":[{"in":"body","pointer":"/status","message":"must be equal to one of the allowed values"}],
 "type":"https://apigit.com/mock/problems/invalid-request",
 "title":"The request does not match the API description","status":422, ...}

and uses the first value in generated examples ("status":"draft"), which is a reason to list the most typical value first.

Allowing null

null has to pass two checks, the type and the enum. Both must allow it:

# OpenAPI 3.1
priority:
  type: [string, "null"]
  enum: [low, high, null]
# OpenAPI 3.0
priority:
  type: string
  nullable: true
  enum: [low, high, null]

With this schema, "priority": null is accepted (the mock answers 201 Created). Leave null out of the enum and it is refused even though the type allows it. More on the two spellings: nullable in OpenAPI 3.0 and 3.1.

Describing each value

enum carries no descriptions. Three ways to document the values, from most to least portable:

  1. In the schema's description: a short list, "draft: not visible to customers; ...". Every tool shows it.
  2. In OpenAPI 3.1, oneOf with one const per value, each with its own title and description. It validates like an enum and documentation tools can show the texts.
  3. Extensions such as x-enum-descriptions or x-enum-varnames. They work only in the generators that define them.

One value: enum or const

A field that always has the same value, such as the type of one variant under a discriminator, is const: card in OpenAPI 3.1 and enum: [card] in 3.0.

Adding a value later

Where the enum is usedAdding a valueRemoving a value
Requestsafe: old clients keep sending old valuesbreaking: old clients send what is now refused
Responsecan break clients: generated code can fail on a value it does not knowsafe for clients that handle all values

If a response enum is likely to grow, say so in its description, and tell client authors to handle unknown values. Some teams leave response fields as plain strings with the known values documented, for exactly this reason.

Common mistakes

  • Values of the wrong type: enum: [1, 2] under type: string can never match.
  • YAML reading a value as something else: unquoted no, on or off can become booleans in some YAML parsers. Quote them: enum: ["yes", "no"].
  • An enum and a default that is not one of its values.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish