What Is JSON Schema?

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It describes the expected structure of your data — what fields exist, their types, required properties, and value constraints. Think of it as a "type system" for JSON.

It's used in API request/response validation, configuration file validation, form generation, and documentation. The current standard is Draft 2020-12.

Basic Schema Structure

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "age": { "type": "integer", "minimum": 0 }, "email": { "type": "string", "format": "email" } }, "required": ["name", "email"]
}

This schema validates that the JSON object has a non-empty name string, a non-negative integer age, and a valid email. The required array specifies which properties must be present.

Type Keywords

JSON Schema supports these primitive types:

  • "string" — with minLength, maxLength, pattern, format
  • "number" / "integer" — with minimum, maximum, multipleOf
  • "boolean" — true or false
  • "array" — with items, minItems, maxItems, uniqueItems
  • "object" — with properties, additionalProperties, patternProperties
  • "null" — JSON null value

Nested Objects and Arrays

{ "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "roles": { "type": "array", "items": { "type": "string", "enum": ["admin", "user", "editor"] } } }, "required": ["id", "name"] } } }
}

Conditional Validation

JSON Schema supports if/then/else for conditional rules, and combinators like oneOf, anyOf, allOf for composing schemas:

{ "type": "object", "properties": { "payment_type": { "enum": ["credit_card", "bank_transfer"] } }, "if": { "properties": { "payment_type": { "const": "credit_card" } } }, "then": { "required": ["card_number", "cvv"] }, "else": { "required": ["account_number", "routing_number"] }
}

Validation Tools and Libraries

  • Ajv (JavaScript) — The fastest JSON Schema validator, supports all drafts
  • jsonschema (Python) — Widely used Python validator
  • Zod / Yup — TypeScript-first alternatives that generate schemas
  • JSON Schema Generators — Auto-generate schemas from sample data

Try our JSON Schema Generator to instantly create a schema from any JSON payload, or validate existing JSON with our JSON Formatter.

Best Practices

  • Always set additionalProperties: false in strict APIs to reject unexpected fields
  • Use $ref and $defs to avoid duplicating schemas
  • Document schemas alongside your API using OpenAPI (which uses JSON Schema)
  • Version your schemas and validate breaking changes in CI
  • Start by generating a schema from real data, then refine constraints

JSON Schema in API Development

Most modern API frameworks support JSON Schema for request validation. OpenAPI (Swagger) specifications use JSON Schema to define request bodies and responses. This means your schema can serve triple duty: validation, documentation, and client code generation.

By validating incoming requests against a schema, you catch malformed data at the API boundary before it reaches your business logic — reducing bugs and improving security.