Controlling additionalProperties in JSON Schema

What Is additionalProperties?

By default, JSON Schema allows objects to contain keys not listed in properties. The additionalProperties keyword lets you control this behavior — either rejecting unknown keys or constraining their types.

Default Behavior (Permissive)

Without additionalProperties, any extra keys are silently accepted:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  }
}

An object { "name": "Alice", "age": 30 } is valid even though age is not defined in properties.

Strict Mode: false

Setting additionalProperties: false rejects any key not listed in properties (or patternProperties):

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string" }
  },
  "additionalProperties": false
}

Now { "name": "Alice", "age": 30 } is invalid because age is not a declared property.

Typed Additional Properties

You can also set additionalProperties to a schema that extra keys must conform to:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "additionalProperties": { "type": "string" }
}

This allows any extra keys, as long as their values are strings.

Generator Behavior

Most generators default to omitting additionalProperties, which means the generated schema is permissive. For strict API validation, you should add "additionalProperties": false manually after generation.

When to Use Each Setting

• false — API request bodies where you want to reject typos and unexpected fields.
• true (or omitted) — Extensible formats like configuration files where plugins may add custom keys.
• Schema value — Key-value maps where keys are dynamic but values follow a consistent type (e.g., localization dictionaries, feature flags).

Interaction with required

additionalProperties: false does not affect which properties are required. You still need the required array to specify mandatory fields. The two keywords are complementary — required says what must be present, additionalProperties says what must not be present beyond the declared set.