JSON Schema additionalProperties: Complete Guide with Examples
Learn how additionalProperties works in JSON Schema with clear examples: false, true, and schema-typed variants explained.
The additionalProperties keyword in JSON Schema controls what happens to object 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 blocks them entirely, while setting it to a schema object constrains their values.
Symptom: Unexpected Extra Fields Are Slipping Through Validation
The most common reason developers reach for additionalProperties is discovering that their validator happily accepts objects with fields they never intended to allow. This is expected behaviour: by default, providing additional properties is valid in JSON Schema. A schema that only declares properties does not automatically reject unknown keys.
Consider a schema for a library book record:
{
"type": "object",
"properties": {
"isbn": { "type": "string" },
"title": { "type": "string" },
"year": { "type": "integer" }
}
}
Against this schema, the following object passes validation even though discount_code was never declared:
{ "isbn": "978-3-16-148410-0", "title": "Dune", "year": 1965, "discount_code": "SAVE20" }
The fix — set additionalProperties to false:
{
"type": "object",
"properties": {
"isbn": { "type": "string" },
"title": { "type": "string" },
"year": { "type": "integer" }
},
"additionalProperties": false
}
Now the same object with discount_code fails validation. Only isbn, title, and year are permitted. An object containing only those three keys — or any subset of them — still passes, because additionalProperties: false restricts extra keys, not missing ones (that is the job of required).
Step-by-step how the validator decides:
- Collect the set of property names present in the instance:
{isbn, title, year, discount_code}. - Collect the names declared in
properties:{isbn, title, year}. - Remove the declared names from the instance set. Remainder:
{discount_code}. - Because
additionalPropertiesisfalseand the remainder is non-empty, validation fails.
If the remainder were empty, validation would succeed.
Symptom: You Need Extra Fields, But Only of a Specific Type
A stricter-than-default but more flexible-than-false scenario arises when you want to allow additional properties, but only if their values conform to a particular shape. Setting additionalProperties to a schema object (not a boolean) achieves this.
Imagine a configuration object where the three core keys are typed explicitly, but teams can add their own metadata keys — as long as every value is a string:
{
"type": "object",
"properties": {
"service_name": { "type": "string" },
"port": { "type": "integer" },
"enabled": { "type": "boolean" }
},
"additionalProperties": { "type": "string" }
}
Valid instance — the extra key owner has a string value:
{ "service_name": "auth", "port": 8080, "enabled": true, "owner": "platform-team" }
Invalid instance — the extra key retry_count has an integer value, which violates the additionalProperties schema:
{ "service_name": "auth", "port": 8080, "enabled": true, "retry_count": 3 }
The validator applies the additionalProperties sub-schema only to properties not already matched by properties or patternProperties. The declared keys service_name, port, and enabled are validated by their own schemas inside properties as usual.
If you are building schemas by hand and want to verify the structure quickly, the free OpenAI Structured Outputs JSON Schema Converter can save you time by converting existing type definitions into valid JSON Schema format.
Symptom: additionalProperties: false Breaks When Combined with patternProperties
A rarer but confusing failure occurs when developers add patternProperties alongside additionalProperties: false and find that some dynamically-named keys are still being rejected.
The rule is: when additionalProperties is false, a property name in the instance must match either a key in properties or a regular expression in patternProperties. If it matches neither, validation fails.
Example — a metrics object where fixed keys are declared and dynamic measurement keys follow a naming pattern:
{
"type": "object",
"properties": {
"sensor_id": { "type": "string" },
"timestamp": { "type": "string" }
},
"patternProperties": {
"^metric_[a-z]+$": { "type": "number" }
},
"additionalProperties": false
}
Valid instance:
{ "sensor_id": "S-42", "timestamp": "2024-01-15T10:00:00Z", "metric_temp": 21.5, "metric_humidity": 60.0 }
Invalid instance — raw_voltage matches neither properties nor the ^metric_[a-z]+$ pattern:
{ "sensor_id": "S-42", "timestamp": "2024-01-15T10:00:00Z", "raw_voltage": 3.3 }
Step-by-step validation for the invalid instance:
- Instance property set:
{sensor_id, timestamp, raw_voltage}. - Remove names found in
properties:{sensor_id, timestamp}removed → remainder{raw_voltage}. - For each regex in
patternProperties, remove matching names:^metric_[a-z]+$does not matchraw_voltage→ remainder still{raw_voltage}. - Remainder is non-empty and
additionalPropertiesisfalse→ validation fails.
A common mistake is forgetting that patternProperties regular expressions are not automatically anchored. The pattern metric_ would match raw_metric_data as well as metric_temp, which may be unintentional. Wrapping patterns in ^...$ makes matching explicit and predictable.
How to Confirm Your Fix Is Working
After updating your schema, test it against at least four cases to be sure:
| Test object | Expected result | What it proves |
|---|---|---|
| Only declared properties, all correct types | ✅ Pass | Schema still accepts valid data |
| Declared properties plus one unknown key | ❌ Fail | additionalProperties: false is active |
Declared properties plus one key matching patternProperties |
✅ Pass | Pattern exemption works |
| Extra key with wrong type (when using schema form) | ❌ Fail | Sub-schema on additionalProperties is enforced |
If additionalProperties is absent from your schema entirely, treat it as equivalent to {} — an empty schema that accepts any value. Absence is not the same as false. This is a frequent source of confusion: the default is permissive, not restrictive.
For the 2020-12 draft, additionalProperties is classified in the Applicator vocabulary and its annotation records the set of property names it successfully validated, which downstream keywords like unevaluatedProperties can use to make further decisions.
Open the OpenAI Structured Outputs JSON Schema Converter