JSON & Schema

JSON Schema additionalProperties Explained

Object schemas allow additional properties by default. Set additionalProperties to false to reject unmatched keys, or provide a schema to validate their values.

Published Aug 20, 2026 · Updated Oct 3, 2026

The default: extra properties are allowed

Omitting additionalProperties allows unmatched fields, as does additionalProperties: true. A debug or metadata field does not fail validation merely because it is absent from properties. Rules for named fields still apply.

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

Reject unknown fields with additionalProperties: false

{
  "type": "object",
  "properties": { "name": { "type": "string" } },
  "required": ["name"],
  "additionalProperties": false
}

Valid: only the declared field

{ "name": "Mira" }

Invalid: an extra field

{ "name": "Mira", "debug": true }

The extra debug key fails this schema. Removing name also fails, because the separate required rule requires it.

Validation reports whether the object satisfies the schema; it does not remove extra fields. Removing fields requires a separate transformation or a validator-specific option.

Check both objects in JSON Schema Validator →

Validate extra properties with a schema

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

Here { "label": "ready" } passes, while { "count": 3 } fails: each extra value must be a string. For a fixed set of allowed values, use enum.

properties vs patternProperties vs additionalProperties

Keyword	Matches
properties	Exact property names
patternProperties	Names matching a regular expression
additionalProperties	Names unmatched by the first two

Composed schemas and unevaluatedProperties

additionalProperties is evaluated within its schema location, which can surprise authors using allOf. unevaluatedProperties can express a later boundary in newer drafts, but use it only with a validator and declared draft that support it.

See oneOf, anyOf and allOf before closing a composed schema. The JSON Schema object reference explains why properties declared in sibling branches can still be rejected.

Common mistakes

Assuming objects are closed by default.
Forgetting required when a known field must exist.
Using additionalProperties: false inside one allOf branch and expecting it to see sibling properties.
Changing an API to a closed schema without compatibility review.

Try the example

Observe an extra object field

Generate a baseline from a sample that includes a debug field before choosing a closed contract.

{"name":"Alice","age":30,"debug":true}

Expected result: The generated schema includes all observed fields and keeps policy decisions explicit.

Try the example

Reject an unknown debug field

Use a closed object schema and inspect the additional-property error.

additionalProperties: false
data: {name, age, debug}

Expected result: Validation rejects debug as an additional property.

Start from a sample

Generate the object structure

Generate known properties, then choose the extra-field policy your contract requires.

Open JSON to JSON Schema Generator →