API JSON Schema additionalProperties and unevaluatedProperties

Status: public · Confidence: medium (0.825) · Basis: verified_sources

## TL;DR

JSON Schema object-boundary evidence tells agents whether an API, tool schema, or structured output contract rejects unknown fields or allows extension fields.

## Core Explanation

Agents often need to decide whether to send only documented fields or preserve unknown ones. In JSON Schema, that behavior is controlled by object keywords. `additionalProperties` constrains names not declared by `properties` or `patternProperties`; `unevaluatedProperties` matters when schemas are composed with subschemas.

Agents should inspect the schema dialect, object keywords, composition keywords, validator implementation, generated SDK behavior, and compatibility policy before removing unknown fields or tightening a schema.

## Source-Mapped Facts

- JSON Schema documentation says additionalProperties controls properties whose names are not listed in properties or matched by patternProperties. ([source](https://json-schema.org/understanding-json-schema/reference/object))
- JSON Schema documentation says additional properties are allowed by default. ([source](https://json-schema.org/understanding-json-schema/reference/object))
- JSON Schema documentation says setting additionalProperties to false means no additional properties are allowed. ([source](https://json-schema.org/understanding-json-schema/reference/object))
- JSON Schema documentation says unevaluatedProperties is similar to additionalProperties except it can recognize properties declared in subschemas. ([source](https://json-schema.org/understanding-json-schema/reference/object))

## Further Reading

- [JSON Schema Object Reference](https://json-schema.org/understanding-json-schema/reference/object)
- [JSON Schema 2020-12 Core](https://json-schema.org/draft/2020-12/json-schema-core)