Skip to content
Owais Khan Software Reviews
How-To Guides

JSON Schema additionalProperties: Complete Guide with Examples

Learn how additionalProperties works in JSON Schema with clear examples: false, true, and schema-typed variants explained.

By Owais Khan

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:

  1. Collect the set of property names present in the instance: {isbn, title, year, discount_code}.
  2. Collect the names declared in properties: {isbn, title, year}.
  3. Remove the declared names from the instance set. Remainder: {discount_code}.
  4. Because additionalProperties is false and 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:

  1. Instance property set: {sensor_id, timestamp, raw_voltage}.
  2. Remove names found in properties: {sensor_id, timestamp} removed → remainder {raw_voltage}.
  3. For each regex in patternProperties, remove matching names: ^metric_[a-z]+$ does not match raw_voltage → remainder still {raw_voltage}.
  4. Remainder is non-empty and additionalProperties is false → 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

Frequently asked questions

What is the default behaviour of additionalProperties when it is not specified?
When `additionalProperties` is absent, it is treated as an empty schema, meaning any additional properties are allowed. By default, providing additional properties is valid in JSON Schema.
Can additionalProperties be set to a schema instead of just true or false?
Yes. The value of `additionalProperties` can be a boolean or a valid JSON Schema object. When set to a schema, any property not matched by `properties` or `patternProperties` must validate against that sub-schema.
Does additionalProperties: false also make all properties required?
No. `additionalProperties: false` only prevents unknown property names; it does not make any property mandatory. Use the `required` keyword separately to enforce which properties must be present.
How does additionalProperties interact with patternProperties?
When `additionalProperties` is `false`, a property name must match either a key in `properties` or a regular expression in `patternProperties`. If it matches either, it is exempt from the `additionalProperties` restriction.
Is additionalProperties: false supported in OpenAPI v2 (Swagger)?
OpenAPI Specification v2 does not officially support `additionalProperties` as a boolean. OAS v2 tooling such as parsers and codegen only accepts an object (schema) as the value. Boolean support was properly introduced in OAS v3.
Which JSON Schema draft introduced additionalProperties?
The `additionalProperties` keyword has been present since Draft 0 of JSON Schema. In the 2020-12 draft it belongs to the Applicator vocabulary and its specification is defined in the JSON Schema core document.