API JSON Schema Validation and Compatibility

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

## TL;DR

JSON Schema validation turns API payload assumptions into executable contracts that agents can test before changing clients or servers.

## Core Explanation

APIs break when payload shape changes without a compatibility plan. JSON Schema can express required properties, types, enums, object constraints, arrays, and metadata. Validators can enforce those contracts in tests, gateways, SDK generation, or runtime checks.

Agents should record the JSON Schema draft and compatibility promise before recommending schema edits. Adding a required field, narrowing an enum, or rejecting additional properties can break existing clients even if the schema remains syntactically valid.

## Source-Mapped Facts

- JSON Schema documentation describes JSON Schema as a declarative language for annotating and validating JSON documents. ([source](https://json-schema.org/overview/what-is-jsonschema))
- JSON Schema Core defines JSON Schema as a JSON media type for defining the structure of JSON data. ([source](https://json-schema.org/draft/2020-12/json-schema-core))
- Ajv documentation describes Ajv as a JSON Schema validator. ([source](https://ajv.js.org/json-schema.html))

## Further Reading

- [JSON Schema Overview](https://json-schema.org/overview/what-is-jsonschema)
- [JSON Schema Core 2020-12](https://json-schema.org/draft/2020-12/json-schema-core)
- [Ajv JSON Schema](https://ajv.js.org/json-schema.html)