What is JSON Schema?
JSON Schema is a powerful vocabulary that allows you to annotate and validate JSON documents. It defines the expected structure, content, data types, and constraints of your JSON data. Think of it as a blueprint or contract that your JSON data must follow.
⚠️ Warning
📊 Why JSON Schema Matters in 2025
99%
Fewer data-related bugs with schema validation
75%
Faster API development with schemas
50%
Reduction in data cleaning effort
10x
Better error messages with validation
Key Benefits of JSON Schema
- Data Validation - Automatically validate incoming data against your schema
- Documentation - Schemas serve as living documentation of your data structure
- Code Generation - Generate TypeScript types, Python dataclasses, Java POJOs from schemas
- UI Generation - Automatically generate forms from schemas (react-jsonschema-form)
- Testing - Generate test data that conforms to your schema
- Contract Testing - Ensure APIs adhere to defined contracts
Getting Started with JSON Schema
A JSON Schema is itself a JSON document. Here's the simplest possible schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/user.schema.json",
"title": "User",
"description": "A user object",
"type": "object"
}Understanding Schema Keywords
| Keyword | Purpose | Example |
|---|---|---|
| $schema | Declares which draft of JSON Schema you're using | "https://json-schema.org/draft/2020-12/schema" |
| $id | Unique identifier for the schema (often a URL) | "https://example.com/user.schema.json" |
| title | Human-readable title for documentation | "User" |
| description | Detailed description for documentation | "A user object..." |
| type | Specifies the JSON data type expected | "object", "array", "string" |
Validation Keywords Complete Reference
String Validation Keywords
{
"type": "string",
"minLength": 1,
"maxLength": 100,
"pattern": "^[a-zA-Z0-9]+$",
"format": "email",
"enum": ["admin", "user", "guest"]
}📝 String Formats
date- "2024-01-15"time- "14:30:00"date-time- "2024-01-15T14:30:00Z"email- "user@example.com"hostname- "example.com"ipv4- "192.168.1.1"ipv6- "2001:0db8::1"uri- "https://example.com"uuid- "123e4567-e89b-12d3-a456-426614174000"json-pointer- "/users/0/name"regex- "^[a-z]+$"
🔢 Number Validation Keywords
{
"type": "number",
"minimum": 0,
"maximum": 100,
"exclusiveMinimum": 0,
"exclusiveMaximum": 100,
"multipleOf": 5
}Array Validation Keywords
{
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 10,
"uniqueItems": true,
"additionalItems": false,
"contains": {
"type": "string",
"pattern": "^admin"
}
}Object Validation Keywords
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 0 },
"email": { "type": "string", "format": "email" }
},
"required": ["name", "email"],
"additionalProperties": false,
"minProperties": 1,
"maxProperties": 10,
"propertyNames": {
"pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
}
}Conditional Validation
if/then/else
{
"type": "object",
"properties": {
"type": { "type": "string", "enum": ["individual", "company"] }
},
"if": {
"properties": { "type": { "const": "individual" } }
},
"then": {
"required": ["firstName", "lastName"],
"properties": {
"firstName": { "type": "string" },
"lastName": { "type": "string" }
}
},
"else": {
"required": ["companyName", "taxId"],
"properties": {
"companyName": { "type": "string" },
"taxId": { "type": "string", "pattern": "^[0-9]{9}$" }
}
}
}allOf, anyOf, oneOf
{
"anyOf": [
{ "type": "string", "maxLength": 10 },
{ "type": "number", "minimum": 0 }
]
}
{
"oneOf": [
{ "required": ["email"] },
{ "required": ["phone"] }
]
}
{
"allOf": [
{ "type": "object" },
{ "required": ["id"] },
{ "properties": { "id": { "type": "integer" } } }
]
}Advanced Features: $ref and $defs
Reuse schema definitions across your document to avoid repetition:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zipCode": { "type": "string", "pattern": "^[0-9]{5}$" }
},
"required": ["street", "city"]
},
"contact": {
"type": "object",
"properties": {
"email": { "type": "string", "format": "email" },
"phone": { "type": "string", "pattern": "^\+?[0-9]{10,15}$" }
}
}
},
"type": "object",
"properties": {
"billingAddress": { "$ref": "#/$defs/address" },
"shippingAddress": { "$ref": "#/$defs/address" },
"primaryContact": { "$ref": "#/$defs/contact" },
"secondaryContact": { "$ref": "#/$defs/contact" }
}
}📘 Info
💡 External $ref
You can also reference external schemas:
{
"properties": {
"user": { "$ref": "https://example.com/schemas/user.json" }
}
}JSON Schema Implementations by Language
🟨
JavaScript/Node.js
- AJV - Fastest, most popular
- joi - Alternative validation library
- tv4 - Tiny validator
- json-schema-generator - Generate schemas from data
🐍
Python
- jsonschema - Reference implementation
- pydantic - Generate schemas from models
- marshmallow - Object serialization/validation
- fastjsonschema - Fast Python implementation
☕
Java
- everit-json-schema - Popular Java implementation
- networknt/json-schema-validator - Fast, feature-rich
- justify - Modern Java validator
#️⃣
C#/.NET
- NJsonSchema - Generate from .NET types
- Json.NET Schema - Newtonsoft's implementation
- Manatee.Json - Full specification support
🔷
Go
- gojsonschema - Pure Go implementation
- jsonschema - Generate schemas from Go structs
- santhosh-tekuri/jsonschema - Draft 2020-12 support
💎
Ruby
- json-schema - Ruby implementation
- dry-validation - Modern validation library
- activemodel-json-validator - Rails integration
Real-World Schema Examples
Example 1: E-commerce Product
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Product",
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid" },
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"description": { "type": "string", "maxLength": 5000 },
"price": { "type": "number", "minimum": 0, "multipleOf": 0.01 },
"currency": { "type": "string", "enum": ["USD", "EUR", "GBP", "INR"] },
"inStock": { "type": "boolean", "default": true },
"quantity": { "type": "integer", "minimum": 0 },
"categories": {
"type": "array",
"items": { "type": "string" },
"uniqueItems": true
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": { "type": "string", "format": "uri" },
"alt": { "type": "string" },
"isPrimary": { "type": "boolean", "default": false }
}
}
},
"createdAt": { "type": "string", "format": "date-time" },
"updatedAt": { "type": "string", "format": "date-time" }
},
"required": ["id", "name", "price", "currency"],
"additionalProperties": false
}Example 2: API Response Wrapper
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "APIResponse",
"type": "object",
"properties": {
"success": { "type": "boolean" },
"data": { "type": ["object", "array", "null"] },
"error": {
"type": "object",
"properties": {
"code": { "type": "string" },
"message": { "type": "string" },
"details": { "type": "array", "items": { "type": "string" } }
}
},
"meta": {
"type": "object",
"properties": {
"requestId": { "type": "string", "format": "uuid" },
"timestamp": { "type": "string", "format": "date-time" },
"version": { "type": "string", "pattern": "^v\d+\.\d+\.\d+$" },
"pagination": {
"type": "object",
"properties": {
"page": { "type": "integer", "minimum": 1 },
"limit": { "type": "integer", "minimum": 1, "maximum": 100 },
"total": { "type": "integer", "minimum": 0 },
"pages": { "type": "integer", "minimum": 0 }
}
}
}
}
},
"if": {
"properties": { "success": { "const": true } }
},
"then": {
"required": ["data"],
"not": { "required": ["error"] }
},
"else": {
"required": ["error"],
"not": { "required": ["data"] }
}
}Frequently Asked Questions
Q: What's the difference between JSON Schema and XML Schema (XSD)?
JSON Schema is for validating JSON data, while XSD is for validating XML. JSON Schema is simpler, more readable, and better integrated with modern web development. XSD is more powerful for complex document validation but much more complex to learn and use.
Q: Does JSON Schema validate against a specific JSON version?
JSON Schema validates the structure and content of JSON data, not the JSON syntax itself. The JSON must first be syntactically valid (using JSON.parse or equivalent) before schema validation can be applied.
Q: Can JSON Schema validate across multiple files?
Yes! Using the $ref keyword, you can reference external schema files. Some validators also support remote $ref (URLs). This allows you to build modular, reusable schema libraries.
Q: How do I generate TypeScript types from JSON Schema?
Use tools like json-schema-to-typescript, quicktype, or typescript-json-schema. These generate accurate TypeScript interfaces from your schemas.
Validate Your JSON with Confidence
Use our free JSON formatter with built-in validation to ensure your data meets your schema requirements.
✓ Validate JSON Now →
