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.