"must NOT have additional properties": why a request is refused
Last checked and updated
The schema at the place the error names says additionalProperties: false, and the value there has a property the schema does not list under properties. The message is the Ajv validator's wording. Either the payload carries something it should not, or the schema is stricter than intended.
A minimal case
NewUser:
type: object
required: [email]
additionalProperties: false
properties:
email:
type: string
format: email
$ curl -X POST http://127.0.0.1:4621/users -H 'content-type: application/json' \
-d '{"email":"a@example.com","role":"admin"}'
HTTP/1.1 422 Unprocessable Entity
{"errors":[{"in":"body","pointer":"","message":"must NOT have additional properties"}],
"title":"The request does not match the API description","status":422,
"detail":"The request does not match createUser: body : must NOT have additional properties"}
pointer says where: the empty pointer is the body itself, /address would be the object in the address property. The property at fault is the one the schema at that place does not name, here role.
Which side is wrong
| Situation | Fix |
|---|---|
A typo in the payload (emial) | Fix the client |
| The client sends a field the API does not take | Remove it, or add it to the schema if the server really reads it |
| The server returns a new field and a client validates responses against a closed schema | Do not close response schemas; remove additionalProperties: false there |
The schema is combined with allOf | See below |
When no payload can pass: allOf
Admin:
allOf:
- $ref: "#/components/schemas/NewUser" # additionalProperties: false
- type: object
properties:
role:
type: string
additionalProperties only counts the properties (and patternProperties) written in its own schema. NewUser therefore refuses role, and Admin requires both parts to match: every admin with a role fails, with exactly this message.
In OpenAPI 3.1, take additionalProperties: false out of the parts and close the combination with unevaluatedProperties: false, which sees the properties of all parts:
Admin:
allOf:
- $ref: "#/components/schemas/NewUser"
- type: object
properties:
role:
type: string
unevaluatedProperties: false
OpenAPI 3.0 has no unevaluatedProperties: leave the base schema open there. More on the keyword itself: additionalProperties in OpenAPI.