Skip to content

additionalProperties in OpenAPI: closed objects and maps

Last checked and updated

additionalProperties says what to do with properties that a schema does not list under properties. By default they are allowed. Set it to false and the object is closed: any other property is an error. Set it to a schema and the object becomes a map whose values follow that schema.

Both uses in one schema

NewUser:
  type: object
  required: [email]
  additionalProperties: false
  properties:
    email:
      type: string
      format: email
    labels:
      type: object
      additionalProperties:
        type: string

NewUser is closed: only email and labels may appear. labels is a map from any key to a string.

What a mock server answers

A mock generated from this file accepts a correct body:

$ curl -X POST http://127.0.0.1:4621/users -H 'content-type: application/json' \
    -d '{"email":"a@example.com","labels":{"team":"core"}}'
HTTP/1.1 201 Created

{"email":"user@example.com","labels":{"property1":"string","property2":"string"}}

The generated example shows how tools read a map: with invented keys, property1 and property2. Add an example to the schema if the keys should mean something in your documentation.

A property the schema does not name is refused:

$ 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"}],
 "type":"https://apigit.com/mock/problems/invalid-request",
 "title":"The request does not match the API description","status":422, ...}

And a map value of the wrong type is reported with its place:

{"errors":[{"in":"body","pointer":"/labels/team","message":"must be string"}], ...}

Should request bodies be closed?

Closing a request schema catches typing mistakes (emial) and stops clients from sending fields the server silently drops, such as a role they hoped would be honoured. The price: adding a field later means old servers refuse new clients. Leave responses open, so a client that validates responses does not break when the server starts returning one more field.

The allOf trap

additionalProperties: false looks only at the properties (and patternProperties) of the schema it is written in. Combined with allOf, it refuses the other schema's properties:

Admin:
  allOf:
    - $ref: "#/components/schemas/NewUser"   # closed: only email, labels
    - type: object
      properties:
        role:
          type: string

No object with a role can match Admin: the first part forbids it. In OpenAPI 3.1 write unevaluatedProperties: false on the combined schema and remove additionalProperties: false from the parts; it takes the properties of every part into account. OpenAPI 3.0 has no such keyword: leave the base schema open, or repeat the properties.

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