What JSON Schema Is
JSON Schema is a vocabulary for annotating and validating JSON documents. A schema is itself a JSON document that describes the expected structure: which fields are required, what types they should be, valid ranges, allowed string patterns, and nested object shapes.
Think of it as a type system for data at rest or in transit — similar to TypeScript interfaces but for raw JSON, usable in any language.
Basic Structure
json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 0 },
"email": { "type": "string", "format": "email" }
},
"required": ["name", "email"]
}
This schema defines an object with three optional properties (name, age, email), of which name and email are required. Age must be an integer ≥ 0.
Data Types
JSON Schema supports all JSON types: string, number, integer, boolean, array, object, null.
You can allow multiple types: "type": ["string", "null"] — accepts a string or null.
String Validation
json
{
"type": "string",
"minLength": 3,
"maxLength": 50,
"pattern": "^[a-zA-Z0-9_]+$"
}
format provides named formats: "email", "uri", "date" (YYYY-MM-DD), "date-time" (ISO 8601), "uuid", "ipv4". Note: format is an annotation by default — validators must explicitly opt in to enforce it.
Number Validation
json
{
"type": "number",
"minimum": 0,
"maximum": 100,
"multipleOf": 0.01
}
exclusiveMinimum and exclusiveMaximum exclude the boundary values. multipleOf validates that the value is a multiple of the given number (useful for currency: 0.01 means two decimal places).
Array Validation
json
{
"type": "array",
"items": { "type": "string" },
"minItems": 1,
"maxItems": 10,
"uniqueItems": true
}
items defines the schema for all array elements. prefixItems (draft 2020-12) validates positional items in a tuple.
Object Validation
json
{
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id"],
"additionalProperties": false
}
additionalProperties: false rejects any property not listed in properties. Useful for strict validation but can break forward compatibility — a common mistake in long-lived APIs.
Composition Keywords
**allOf** — the value must be valid against all listed schemas. Used to extend or combine schemas.
**anyOf** — the value must be valid against at least one schema. Used for flexible types.
**oneOf** — the value must be valid against exactly one schema.
**not** — the value must not be valid against the schema.
json
{
"oneOf": [
{ "type": "string" },
{ "type": "integer" }
]
}
Reuse with $ref and $defs
Define reusable schema components in $defs and reference them with $ref:
json
{
"$defs": {
"address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" }
}
}
},
"properties": {
"billing": { "$ref": "#/$defs/address" },
"shipping": { "$ref": "#/$defs/address" }
}
}
Schema Versions
JSON Schema has several published drafts. Draft 2020-12 is the current standard. Draft-07 is still widely supported by libraries. Check your validation library's supported draft before writing schemas.
NoxaKit's JSON Schema Validator checks your JSON against a schema in the browser. The JSON to TypeScript converter can generate TypeScript interfaces from a JSON sample — useful as a starting point for writing a schema.