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.

Related Tools