Skip to content
Owais Khan Software Reviews
How-To Guides

json schema additionalproperties not working

Fix every reason additionalProperties silently fails in JSON Schema, with worked examples and root-cause explanations.

By Owais Khan

The most common reason additionalProperties appears to do nothing is that it is placed at the wrong schema level, combined incorrectly with $ref, or the validator is simply not configured to enforce it. Fix the scope and the combination pattern and the keyword works exactly as specified.

What additionalProperties Is Actually Supposed to Do

The additionalProperties keyword controls properties whose names are not listed in properties and do not match any pattern in patternProperties. By default, any additional properties are allowed. Setting additionalProperties to false means zero extra properties are permitted. Setting it to a schema object means extra properties are allowed but must validate against that sub-schema.

Critically, additionalProperties only “sees” properties that were not already claimed by properties or patternProperties in the same schema object. This single scoping rule is the root cause of almost every bug report.

The Broken Schema — Input as People Usually Write It

Imagine you are modelling a product record. You want only sku and price to be allowed.

{
 "type": "object",
 "additionalProperties": false,
 "properties": {
 "sku": { "type": "string" },
 "price": { "type": "number" }
 }
}

Test data that should be rejected:

{ "sku": "ABC-01", "price": 9.99, "discount": 0.1 }

Many developers report that discount slips through without an error. The three most common reasons are explored below.

The Fixed Schema — After Applying Every Correction

{
 "type": "object",
 "properties": {
 "sku": { "type": "string" },
 "price": { "type": "number" }
 },
 "additionalProperties": false
}

Test data that is now correctly rejected:

{ "sku": "ABC-01", "price": 9.99, "discount": 0.1 }

Test data that is correctly accepted:

{ "sku": "ABC-01", "price": 9.99 }

The schema content is identical to the broken version — the difference lies in the three root causes described next.

Each Root Cause, Explained

Root Cause 1 — additionalProperties on a nested object instead of the root

The keyword only restricts the object it lives in. If you write it inside a child property’s schema, it has no effect on the parent object’s extra keys.

Wrong placement:

{
 "type": "object",
 "properties": {
 "sku": {
 "type": "string",
 "additionalProperties": false
 },
 "price": { "type": "number" }
 }
}

Here additionalProperties: false is scoped to the sku string schema, which is not an object, so it has no practical effect. The parent object still accepts discount.

Correct placement: additionalProperties must sit at the same level as properties, directly inside the object schema you want to restrict.

Root Cause 2 — Combining additionalProperties with $ref

A very common pattern is to extend a base schema using $ref and then add additionalProperties: false alongside it:

{
 "type": "object",
 "$ref": "#/$defs/BaseProduct",
 "additionalProperties": false
}

This does not work as intended. The $ref is resolved independently; the properties declared inside BaseProduct are invisible to the additionalProperties keyword in the referencing schema because they live in a different schema object. The result is that every property — including the ones from the base — is treated as “additional” and rejected.

The correct fix is to use allOf so that both the referenced schema and the local constraints are applied together, and then list the locally-known properties explicitly:

{
 "type": "object",
 "allOf": [
 { "$ref": "#/$defs/BaseProduct" }
 ],
 "properties": {
 "discount": { "type": "number" }
 },
 "additionalProperties": false
}

Even here, additionalProperties only sees discount (the local properties). The properties defined in BaseProduct are still invisible to it. The safest approach when you need strict closure across a $ref boundary is to list all expected properties explicitly in the same schema object that carries additionalProperties: false.

Root Cause 3 — The validator is not enforcing the schema

Some libraries require you to opt in to strict validation. For example, Ajv (a popular JavaScript validator) has a removeAdditional option that silently strips extra properties instead of rejecting them, which can mask the fact that they were present. If you expect a validation error but get none, check that your validator is set to error on additional properties rather than strip or ignore them.

Also verify you are passing the schema to the validator correctly. A common Python mistake is calling validate(instance, schema) with the arguments reversed, or importing a draft-specific validator that does not match the $schema declared in your document.

Worked Example — Step by Step

Goal: Allow only eventId (string) and timestamp (integer) on an event object.

Step 1 — Write the schema:

{
 "type": "object",
 "properties": {
 "eventId": { "type": "string" },
 "timestamp": { "type": "integer" }
 },
 "additionalProperties": false
}

Step 2 — Test with a valid payload:

{ "eventId": "EVT-99", "timestamp": 1718000000 }

Result: valid — both properties are listed in properties, so neither is “additional”.

Step 3 — Test with an extra property:

{ "eventId": "EVT-99", "timestamp": 1718000000, "source": "mobile" }

Result: invalid — source is not in properties and additionalProperties is false, so the object fails validation.

Step 4 — Test with a missing property:

{ "eventId": "EVT-99" }

Result: valid — additionalProperties says nothing about required fields. Omitting timestamp is fine unless you also add "required": ["eventId", "timestamp"].

If you are generating schemas from an existing type definition, the OpenAI Structured Outputs JSON Schema Converter can produce a correctly scoped schema automatically, saving you from manual placement errors.

Allowing Extra Properties of a Specific Type

additionalProperties does not have to be false. You can set it to a schema, which allows extra properties but constrains their values:

{
 "type": "object",
 "properties": {
 "eventId": { "type": "string" }
 },
 "additionalProperties": { "type": "number" }
}

Now { "eventId": "EVT-1", "score": 42 } is valid, but { "eventId": "EVT-1", "score": "high" } is invalid because score is additional and its value is not a number.

Applying This to Your Own Schema

  1. Locate every object schema (any node with "type": "object") that you want to close.
  2. Confirm additionalProperties is a sibling of properties inside that same node.
  3. If you use $ref, list all expected properties explicitly in the same object that carries additionalProperties: false, or restructure with allOf.
  4. Check your validator’s configuration — ensure it is set to report errors rather than silently remove or ignore extra properties.
  5. Add a test payload with a deliberately unknown property and confirm the validator rejects it before shipping.

Open the OpenAI Structured Outputs JSON Schema Converter

Frequently asked questions

Does additionalProperties apply to nested objects automatically?
No. The keyword only restricts the object schema it is written in. Each nested object needs its own `additionalProperties` keyword if you want to close it too.
Why does additionalProperties: false reject all properties when I use $ref?
Because `additionalProperties` can only see properties declared in the same schema object's `properties` or `patternProperties`. Properties defined inside a `$ref` target are invisible to it, so they are all treated as additional and rejected.
Can additionalProperties allow extra keys but restrict their type?
Yes. Instead of setting it to `false`, set it to a schema such as `{ "type": "number" }`. Any property not listed in `properties` or `patternProperties` must then validate against that sub-schema.
Does omitting a property listed in properties cause an additionalProperties error?
No. `additionalProperties` only concerns properties that are present in the data but not declared in the schema. Missing properties are governed by the separate `required` keyword.
What is the difference between additionalProperties and unevaluatedProperties?
`additionalProperties` only considers properties claimed by `properties` and `patternProperties` in the same schema object. `unevaluatedProperties` is aware of properties evaluated by any applicator in the schema, including those inside `allOf`, `anyOf`, and `$ref`, making it more reliable when composing schemas.
Why does my Python jsonschema validator not raise an error for extra properties?
The most likely cause is that the schema is not being passed correctly to the validator, or the wrong draft validator class is being used. Verify the argument order in your `validate()` call and ensure the validator matches the `$schema` version declared in your schema.