Skip to content

"must be equal to one of the allowed values": an enum mismatch

Last checked and updated

The schema at the pointer has an enum, and the value is not one of its entries. The message is the Ajv validator's wording. The comparison is exact: same type, same case.

A minimal case

status:
  type: string
  enum: [draft, active, archived]
$ 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, ...}

pointer names the field, /status. For an item of a list it includes the position: /items/2/status.

The usual reasons

CauseExampleFix
The API gained a value and the description was not updatedthe server returns "paused", the enum has three valuesAdd it to the enum. If this is a response validated by a client, the client breaks until its copy of the description is updated
Case"Active" against activeSend the exact spelling
null"priority": null with enum: [low, high]List null in the enum as well as in the type
Type"2" against enum: [1, 2, 3]Send a number; a query parameter is converted by its declared type, a JSON body is not
YAML changed the valuesenum: [yes, no] read as booleansQuote them in the description: ["yes", "no"]

In a request or in a response

In a request, the client is sending something the API does not accept: fix the client, or widen the enum if the server really takes the value.

In a response, the server returned something its own description does not allow. That is a bug in the description or in the server, and it is what breaks generated clients: one that maps an enum to a closed type can fail on a value it does not know. Checking the description against the running API (a contract test, or a mock compared with the real responses) finds these before a client does.

How to write an enum, allow null in it and extend it safely: enum in OpenAPI.

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