JSON Schema
A vocabulary that allows you to annotate and validate JSON documents.
Detailed Explanation
As APIs grow complex, ensuring that the JSON data being sent and received matches a specific format becomes critical. JSON Schema defines the structure, data types, and required fields for your data. It is widely used for automated testing, API documentation (Swagger/OpenAPI), and client-side form validation.
Quick Summary
JSON Schema is a declarative JSON-based language for describing the shape of JSON documents, types, required fields, value ranges, patterns, and validating them. It is the contract language behind OpenAPI and most modern API tooling.
Key Takeaways
- A schema is itself a JSON document, so it can be transmitted, stored, and tooled the same way as the data it describes.
- Core keywords: type, properties, required, items, enum, pattern, minimum/maximum, additionalProperties.
- Schemas can compose via $ref, allOf, anyOf, oneOf, letting you build a library of reusable definitions.
- Validators exist for every major language (Ajv in JS, jsonschema in Python, justify in Go) and run identically across them.
- Latest drafts: 2020-12 is current; many tools still target draft-07 because adoption lags the spec.
When to use it
- Validating API request and response bodies on the server before processing.
- Driving client-side form validation from the same schema the backend uses, eliminating drift.
- Generating typed clients and documentation from OpenAPI definitions (which embed JSON Schema).
- Configuring tools and CI pipelines, VS Code, GitHub Actions, and many CLIs accept JSON Schema files for input validation and autocomplete.
Common Mistakes
- Forgetting additionalProperties: false, by default, unknown fields are silently accepted, which hides client bugs.
- Mixing schema drafts in the same project so different validators interpret the same schema differently.
- Putting business rules ("order total must be ≤ user balance") in the schema; schemas validate shape, not invariants across multiple records.
- Hand-writing TypeScript types that don't match the schema, use a generator (json-schema-to-typescript) and treat the schema as the source of truth.
JSON Schema, Frequently Asked
Is JSON Schema the same as OpenAPI?
No. OpenAPI describes whole HTTP APIs, endpoints, methods, parameters, responses. It uses a JSON Schema dialect to describe the shape of each request and response body. JSON Schema is one piece of the larger OpenAPI spec.
Should I share JSON Schemas between client and server?
Yes, that's where they pay off. One schema becomes runtime validation on the server, runtime validation in the client, and generated types in both. Drift between client and server contracts is the bug class this avoids.
Is JSON Schema replaced by Zod or Yup?
Zod, Yup, and Valibot are code-first validators in a single language. JSON Schema is language-agnostic and machine-readable, which is why API specs and tooling use it. Many projects use Zod in app code and emit JSON Schema from it for OpenAPI docs.