JSON Schema "additionalProperties" Errors, Explained
By default, JSON Schema allows any extra keys on an object beyond what's listed in properties. This error only appears when a schema explicitly opts out of that with additionalProperties: false.
What triggers it
{
"type": "object",
"properties": { "name": { "type": "string" } },
"additionalProperties": false
}Against that schema, {"name": "Ada", "role": "admin"} fails — role isn't declared in properties, and the schema forbids anything not declared. Without additionalProperties: false, the same data would pass; JSON Schema is permissive by default and only strict where you tell it to be.
Why this trips people up
It's easy to assume listing properties is itself a whitelist — it isn't. properties only describes the shape of keys if present; it doesn't restrict what else can be there unless paired with additionalProperties: false. This surprises people validating API responses: an upstream service adding a new field is entirely valid JSON Schema-wise unless you locked the schema down, which is often the point — loose validation tolerates additive, backward-compatible API changes.
When to use additionalProperties: false
- Use it for strict internal contracts — config files, request bodies you fully control — where an unexpected key likely indicates a typo or a bug.
- Avoid it for schemas validating third-party or evolving API responses, where it turns a harmless new field into a hard validation failure.
Debug the schema location, not only the property name
The same key may be allowed at one level and rejected at another. Read the validator's instance path and schema path together: the instance path identifies the input object, while the schema path identifies the rule that denied it. A common mistake is adding a property to the root schema when the failure occurred inside user.address.
Composition keywords can also change the result. With allOf, a strict branch may not see properties declared in a sibling branch, depending on the JSON Schema draft and validator behavior. Test the complete composed schema with representative valid and invalid fixtures. Do not “fix” the error by making every object permissive; that hides typos and weakens the contract.
Frequently Asked Questions
What does additionalProperties: false do?
It rejects keys not permitted by the applicable object schema.
Does it automatically apply to nested objects?
No. Each nested object schema needs its own explicit policy.
How do I model a string dictionary?
Set additionalProperties to {"type":"string"}.