JSON Schema, explained
A JSON Schema is itself a JSON document. It states what a valid value looks like, and validators in nearly every language check data against it. The current release is draft 2020-12.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["id", "amount"],
"properties": {
"id": { "type": "string" },
"amount": { "type": "integer", "minimum": 0 },
"currency": { "enum": ["usd", "eur", "gbp"] }
}
}APIs use JSON Schema to validate request bodies, generate types and forms, and document payloads. OpenAPI 3.1 is fully aligned with JSON Schema 2020-12, while OpenAPI 3.0 used an extended subset with some differences, such as nullable.
Schema diffs are a good first check for breaking changes: a field added to required, a narrowed enum or a changed type is easy to detect mechanically. A schema cannot express meaning, though. Switching amount from dollars to cents keeps the schema identical and still breaks every client, which is why schema checks are paired with behavioral tests such as traffic replay.
Related terms
- OpenAPI Specification: The OpenAPI Specification is a standard, language-agnostic format (YAML or JSON) for describing HTTP APIs: their paths, operations, parameters, schemas and authentication.
- Breaking change: A breaking change is a change to an API that causes a correctly written client, which worked before, to fail or behave differently without modifying its code.
- Contract testing: Contract testing verifies that an API provider and its consumers agree on the requests and responses they exchange, so either side can change without silently breaking the other.