Skip to content

"must be string", "must be integer": a value of the wrong type

Last checked and updated

The schema at the pointer declares a type, and the value has another JSON type. The message (the Ajv validator's wording) names the type that was expected: "must be string", "must be integer", "must be number", "must be boolean", "must be array", "must be object", "must be null".

A minimal case

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

{"errors":[
  {"in":"body","pointer":"/name","message":"must be string"},
  {"in":"body","pointer":"/quantity","message":"must be integer"}],
 "type":"https://apigit.com/mock/problems/invalid-request",
 "title":"The request does not match the API description","status":422, ...}

The pointer names the field. "2" in quotes is a string, so it is refused for an integer; 7 without quotes is a number, so it is refused for a string.

integer against number

integer is a number without a fractional part. 1.5 is refused with the same message:

-d '{"name":"a","status":"draft","quantity":1.5}'
{"errors":[{"in":"body","pointer":"/quantity","message":"must be integer"}], ...}

A value of the right type that breaks a limit is a different error: 0 against minimum: 1 gives "must be >= 1". format: int32 or int64 describes the range for generators; whether a validator checks it depends on the tool.

A JSON body is not converted, a query parameter is

Everything in a URL is text, so a validator converts a query or path parameter to its declared type before checking it. ?limit=20 passes as an integer, and text that is not an integer (ten, 1.5, an empty value) fails:

$ curl -i 'http://127.0.0.1:4641/orders?limit=ten'
HTTP/1.1 422 Unprocessable Entity

{"errors":[{"in":"query","name":"limit","message":"must be integer"}], ...}

A JSON body already has types, and no conversion happens. This is why the same value can pass as a query parameter and fail in a body.

The usual reasons

CauseFix
A number sent in quotes, often from a form field or an environment variableConvert it before serialising
A float for an integer (1.5, or a calculated 2.0000001)Round it in the client, or declare type: number
null for a field that does not allow it ("must be string")Leave the field out, or allow null: nullable in 3.0 and 3.1
A single value where a list is expected ("must be array")Wrap it: ["a"]
The description is wrong: ids declared as integer while the API returns stringsFix the schema; large ids are safer as strings anyway: integers beyond 2^53 are outside the range JSON implementations agree on (RFC 8259) and lose precision in parsers that read numbers as doubles, JavaScript's among them

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