JSON Schema Explained — Validate Your API Data
Published: May 28, 2025 · 6 min read
How do you ensure that JSON data from an API, a form submission, or a config file has the correct structure? You write a JSON Schema. Think of it as a contract that describes exactly what valid data looks like — what fields are required, what types they should be, and what values are acceptable.
What is JSON Schema?
JSON Schema is itself written in JSON. It describes the expected structure of a JSON document — similar to how a TypeScript interface defines the shape of an object, or how an XML DTD/XSD validates XML documents. JSON Schema is an open standard (currently at Draft 2020-12) supported by validators in every major language.
A Simple Example
Given this JSON data:
A schema that validates it:
This schema says: the data must be an object with a required name (non-empty string) and email (valid email format), plus an optional age (integer between 0 and 150).
Schema Keywords Reference
| Keyword | Purpose | Example |
|---|---|---|
type | Expected data type | "string", "number", "object", "array" |
properties | Define object fields | {"name": {"type": "string"}} |
required | Fields that must exist | ["name", "email"] |
items | Schema for array items | {"type": "string"} |
minimum/maximum | Number range | "minimum": 0 |
minLength/maxLength | String length | "maxLength": 100 |
pattern | Regex for strings | "pattern": "^[A-Z]" |
enum | Allowed values | "enum": ["active", "inactive"] |
Nested Objects and Arrays
Schemas can validate deeply nested structures:
Where JSON Schema is Used
- OpenAPI/Swagger — API documentation uses JSON Schema to define request/response bodies
- Form validation — Libraries like Ajv (JavaScript) validate form data against schemas
- Configuration files — VS Code uses schemas to validate settings.json, package.json, etc.
- Data contracts — Microservices agree on data formats using shared schemas
- Code generation — Generate TypeScript types, validation code, or documentation from schemas
- Testing — Validate API responses in automated tests
Validation Libraries
- JavaScript: Ajv (fastest), Zod, Yup
- Python: jsonschema, pydantic
- Java: everit-org/json-schema
- Go: xeipuuv/gojsonschema
- .NET: Newtonsoft.Json.Schema
Generate a Schema Automatically
Don't want to write schemas by hand? Our JSON Schema Generator creates a schema from sample data. Paste your JSON, click Generate, and get a complete schema instantly. You can then refine it by adding constraints, patterns, and descriptions.