What is the difference between additionalItems and additionalProperties in JSON Schema?

additionalItems vs. additionalProperties in JSON Schema

Explore the key differences between additionalItems and additionalProperties in JSON Schema, understanding how they control array and object validation respectively.

JSON Schema is a powerful tool for validating the structure of JSON data. When defining schemas, you often need to control what happens when data contains elements or properties not explicitly listed in your schema. This is where additionalItems and additionalProperties come into play. While their names sound similar, they serve distinct purposes, each tailored to a specific JSON data type: arrays and objects.

Understanding additionalItems for Arrays

The additionalItems keyword is used exclusively with arrays. It controls the validation of array elements that appear after the elements explicitly defined by the items keyword (when items is an array of schemas). If items is a single schema, additionalItems has no effect, as that single schema already applies to all items in the array.

When items is an array of schemas, each schema in items validates the corresponding element in the instance array by position. Any elements in the instance array beyond the length of the items array are then validated by additionalItems.

additionalItems can be a boolean or a schema:

• true (default): Any additional items are allowed and not validated against any specific schema.
• false: No additional items are allowed. The instance array must not have more elements than there are schemas in the items array.
• Schema: Any additional items must conform to the provided schema.

{
  "type": "array",
  "items": [
    { "type": "string" },
    { "type": "number" }
  ],
  "additionalItems": { "type": "boolean" }
}

JSON Schema using additionalItems to validate extra array elements.

In the example above, the first item must be a string, the second a number. Any subsequent items (third, fourth, etc.) must be booleans. If additionalItems were false, an array like ["hello", 123, true] would be invalid because true is an additional item, and none are allowed.

flowchart TD
    A[Array Instance] --> B{Length > items array length?}
    B -- Yes --> C{Additional Items Present}
    C --> D{"additionalItems" value?}
    D -- true --> E[Allow all additional items]
    D -- false --> F[Disallow additional items]
    D -- Schema --> G[Validate additional items against schema]
    B -- No --> H[No additional items to validate]

Flowchart illustrating additionalItems validation logic.

Understanding additionalProperties for Objects

The additionalProperties keyword is used exclusively with objects. It controls the validation of properties that are present in the instance object but are not explicitly listed in the properties keyword and do not match any patterns in the patternProperties keyword.

Similar to additionalItems, additionalProperties can be a boolean or a schema:

• true (default): Any additional properties are allowed and not validated against any specific schema.
• false: No additional properties are allowed. The instance object must only contain properties explicitly defined in properties or matching patternProperties.
• Schema: Any additional properties must conform to the provided schema.

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

JSON Schema using additionalProperties to validate extra object properties.

In this example, the name property must be a string and age an integer. Any other properties, such as city or occupation, must also be strings. If additionalProperties were false, an object like {"name": "Alice", "age": 30, "city": "New York"} would be invalid because city is an additional property, and none are allowed.

flowchart TD
    A[Object Instance] --> B{Property in 'properties' or 'patternProperties'?}
    B -- No --> C{Additional Property Found}
    C --> D{"additionalProperties" value?}
    D -- true --> E[Allow all additional properties]
    D -- false --> F[Disallow additional properties]
    D -- Schema --> G[Validate additional properties against schema]
    B -- Yes --> H[Validate against specific property schema]

Flowchart illustrating additionalProperties validation logic.

Key Differences Summarized

The fundamental distinction lies in the data structure they apply to:

• additionalItems: Applies to arrays, specifically to elements beyond the length of the items array when items is an array of schemas.
• additionalProperties: Applies to objects, specifically to properties not explicitly defined in properties or matched by patternProperties.

Both keywords provide flexibility in how strictly you want to define your data structures, allowing you to either permit, forbid, or further validate unexpected elements/properties.

Comparison of additionalItems and additionalProperties.