Skip to content

"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

SituationFix
A typo in the payload (emial)Fix the client
The client sends a field the API does not takeRemove 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 schemaDo not close response schemas; remove additionalProperties: false there
The schema is combined with allOfSee 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.

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