JSON Schema

JSON Schema Explained: What It Is, How It Works, and Why You Need It

Learn what JSON Schema is, how validation works, core data types and keywords, real-world API contract examples, and why you need it for reliable data.

PlayWithJSON Team

Oct 8, 2026

9 min read

Beyond Syntax: The Need for an Application Contract

JSON is the undisputed lingua franca for web APIs, microservices, and modern data storage. However, while standard JSON ensures that your data is syntactically well-formed, it cannot guarantee that the payload contains the specific keys, data types, and business rules your application actually requires.

This is where JSON Schema comes in. JSON Schema provides an open, industry-standard vocabulary to describe the structure, mandatory fields, permitted types, value ranges, and constraints of JSON documents.

In this guide, we explore how JSON Schema works, its essential building blocks, real-world API examples, and how it protects your systems from bad data.

What Is JSON Schema? (Data vs. Blueprint)

At its core, JSON Schema is a standard for defining and validating the structure of JSON data. The simplest way to understand it is:

JSON = The Data (Payload)

Holds the concrete values transmitted across the wire or stored in files.

JSON Schema = The Rulebook (Contract)

Declares which fields must exist, their data types, and value limits.

1. The Concrete JSON DataActual Values

JSON

1{
2  "name": "John",
3  "age": 30,
4  "email": "john@example.com"
5}

2. The Corresponding JSON SchemaValidation Rules

JSON

1{
2  "$schema": "https://json-schema.org/draft/2020-12/schema",
3  "type": "object",
4  "properties": {
5    "name": {
6      "type": "string"
7    },
8    "age": {
9      "type": "integer"
10    },
11    "email": {
12      "type": "string"
13    }
14  },
15  "required": ["name", "age", "email"]
16}

Why Do We Need JSON Schema?

JSON is deliberately schema-less and flexible. While great for rapid prototyping, this flexibility creates severe security and reliability issues at scale.

Suppose your backend endpoint calculates insurance quotes and expects:

JSON

1{
2  "name": "John",
3  "age": 30
4}

Now imagine a malicious actor or buggy mobile app sends:

JSON

1{
2  "name": 123,
3  "age": "thirty"
4}

The Danger: This payload is 100% syntactically valid JSON (no missing commas, no syntax errors). But when your backend runs user.age + 5, it evaluates to "thirty5" in JavaScript or crashes with a TypeError in Python!

With a JSON Schema gatekeeper at your API boundary, requests with wrong types are rejected immediately with an automatic 400 Bad Request before reaching your database.

How JSON Schema Validation Works

Validation is a simple deterministic pipeline: The JSON document and JSON Schema are passed to a validator engine. The engine compares each node against the schema rules.

1. Raw JSON Data

2. JSON Schema Rulebook

3. Validator Engine (AJV / jsonschema)

4. Valid ✅ / Error Report ❌

Example: Enforcing Integer Age

JSON

1{
2  "type": "object",
3  "properties": {
4    "age": {
5      "type": "integer"
6    }
7  },
8  "required": ["age"]
9}

✅ Passes Validation (type is integer):

JSON

1{
2  "age": 25
3}

❌ Fails Validation (type is string):

JSON

1{
2  "age": "25" // Fails: "25" is a string, not an integer
3}

A Complete User Schema Example

Here is a clean user schema defining both required fields (name, email) and an optional field (age):

JSON

1{
2  "type": "object",
3  "properties": {
4    "name": {
5      "type": "string"
6    },
7    "age": {
8      "type": "integer"
9    },
10    "email": {
11      "type": "string"
12    }
13  },
14  "required": ["name", "email"]
15}

All fields provided (Valid):

JSON

1{
2  "name": "Alice",
3  "age": 28,
4  "email": "alice@example.com"
5}

Optional field "age" omitted (Also Valid):

JSON

1{
2  "name": "Alice",
3  "email": "alice@example.com"
4  // age is omitted, but valid since it's optional!
5}

JSON Schema Core Data Types

JSON Schema supports 7 fundamental types, each with its own specialized validation keywords:

Type	Description	Example Values	Validation Keywords
string	Textual data	"John", "admin@site.com"	minLength, maxLength, pattern, format
number	Floating-point or decimal numbers	19.99, -4.5, 100	minimum, maximum, multipleOf
integer	Strictly whole numbers	25, 0, -10 (no fractions)	minimum, maximum, multipleOf
boolean	Boolean truth values	true or false	enum: [true, false]
object	Unordered key-value pairs	{ "name": "John" }	properties, required, additionalProperties
array	Ordered collection of items	["JS", "Python"]	items, minItems, maxItems, uniqueItems
null	Explicit null value	null	type: ["string", "null"]

String Constraints (Length & RegEx)

JSON

1{
2  "type": "string",
3  "minLength": 3,
4  "maxLength": 50,
5  "pattern": "^[A-Za-z ]+$"
6}

Numeric Range Constraints

JSON

1{
2  "type": "number",
3  "minimum": 0,
4  "maximum": 100
5}

Validating Arrays & Allowed Enum Values

In production APIs, arrays and restricted options are everywhere. JSON Schema lets you enforce strict item types and allowed sets:

Typed Array Schema (Only Strings Allowed):

JSON

1{
2  "type": "array",
3  "items": {
4    "type": "string"
5  }
6}

✅ Valid:

JSON

1[
2  "JavaScript",
3  "Python",
4  "Rust"
5]

❌ Invalid:

JSON

1[
2  "JavaScript",
3  123,
4  true
5]

Enums (Restricted Allowed Values):

JSON

1{
2  "type": "string",
3  "enum": [
4    "pending",
5    "shipped",
6    "delivered",
7    "cancelled"
8  ]
9}

A value of "pending" passes, while an unexpected state like "processing" immediately fails validation.

Nested Objects & Arrays of Objects

Real-world JSON payloads are rarely flat. JSON Schema handles nested structures seamlessly by recursively applying properties and items:

Nested Object (User with Address):

JSON

1{
2  "type": "object",
3  "properties": {
4    "name": {
5      "type": "string"
6    },
7    "address": {
8      "type": "object",
9      "properties": {
10        "city": { "type": "string" },
11        "country": { "type": "string" }
12      },
13      "required": ["city", "country"]
14    }
15  },
16  "required": ["name", "address"]
17}

Array of Objects (Users List):

JSON

1{
2  "type": "object",
3  "properties": {
4    "users": {
5      "type": "array",
6      "items": {
7        "type": "object",
8        "properties": {
9          "name": { "type": "string" },
10          "age": { "type": "integer" }
11        },
12        "required": ["name", "age"]
13      }
14    }
15  },
16  "required": ["users"]
17}

Real-World Production Example: User Registration API

Here is a complete schema contract for a user signup endpoint that validates string lengths, regex email formatting, age limits, and booleans:

JSON

1{
2  "type": "object",
3  "properties": {
4    "username": {
5      "type": "string",
6      "minLength": 3
7    },
8    "email": {
9      "type": "string",
10      "format": "email"
11    },
12    "age": {
13      "type": "integer",
14      "minimum": 18
15    },
16    "newsletter": {
17      "type": "boolean"
18    }
19  },
20  "required": ["username", "email", "age"]
21}

✅ Valid Payload (Meets all contract criteria):

JSON

1{
2  "username": "john123",
3  "email": "john@example.com",
4  "age": 25,
5  "newsletter": true
6}

❌ Invalid Payload (3 separate rule violations):

JSON

1{
2  "username": "jo",           // Too short (minLength: 3)
3  "email": "not-an-email",    // Format invalid
4  "age": 15                   // Below minimum 18
5}

JSON Schema vs. TypeScript Types: What's the Difference?

Developers often ask: “If I use TypeScript, why do I still need JSON Schema?”

TypeScript (Compile Time)Developer Only

TypeScript

1// Development-time static check (TypeScript)
2type User = {
3  name: string;
4  age: number;
5  email?: string;
6};

Types are completely erased during compilation to JavaScript. They cannot validate real incoming network data arriving at runtime.

JSON Schema (Runtime Execution)Live Gatekeeper

JSON

1// Runtime JSON validation standard (JSON Schema)
2{
3  "type": "object",
4  "properties": {
5    "name": { "type": "string" },
6    "age": { "type": "integer" },
7    "email": { "type": "string" }
8  },
9  "required": ["name", "age"]
10}

Evaluates actual JSON payloads in memory on live production servers, protecting APIs against bad payloads at runtime.

4 Common JSON Schema Mistakes to Avoid

1. Assuming "properties" Automatically Means Required

Listing a field in "properties" only defines its type if present. To make it mandatory, you must explicitly list its key in the "required" array.

JSON

1{
2  "properties": { "name": { "type": "string" } },
3  "required": ["name"] // Mandatory!
4}

2. Using "number" When You Strictly Need an "integer"

Using "number" allows decimals like 25.4. For counts, IDs, age, and pagination offsets, always declare "type": "integer".

JSON

1{
2  "age": { "type": "integer", "minimum": 0 }
3}

3. Forgetting to Define "items" for Arrays

Specifying "type": "array" alone permits mixed-type arrays ([1, "two", true]). Always use the "items" keyword to enforce item structure.

JSON

1{
2  "type": "array",
3  "items": { "type": "string" }
4}

4. Confusing JSON Syntax Errors with Schema Failures

A trailing comma or missing quote will crash the JSON parser before schema validation even begins. First validate JSON syntax, then validate schema.

JSON

1// Must be valid JSON first before Schema validator can read it!

JSON Schema for Configuration Files

JSON Schema isn't just for REST APIs. Modern tools like VS Code, Docker, and Kubernetes use JSON Schemas to validate settings.json, tsconfig.json, and application environment configs before deployment:

JSON

1{
2  "type": "object",
3  "properties": {
4    "port": {
5      "type": "integer",
6      "minimum": 1024,
7      "maximum": 65535
8    },
9    "environment": {
10      "type": "string",
11      "enum": ["development", "staging", "production"]
12    },
13    "debug": {
14      "type": "boolean"
15    }
16  },
17  "required": ["port", "environment"]
18}

Interactive Schema Authoring Checklist

Before publishing your JSON Schema to an API gateway or npm package, verify these 10 essential quality checks:

Frequently Asked Questions

Summary

JSON is the Data. JSON Schema is the Rules.

Valid JSON alone does not guarantee data integrity. With JSON Schema, you establish a bulletproof contract across APIs, configuration files, and databases, eliminating runtime type crashes.

Generate JSON Schema from JSON Format & Validate JSON

Beyond Syntax: The Need for an Application Contract

In this guide, we explore how JSON Schema works, its essential building blocks, real-world API examples, and how it protects your systems from bad data.

1{ 2 "$schema": "https://json-schema.org/draft/2020-12/schema", 3 "type": "object", 4 "properties": { 5 "name": { 6 "type": "string" 7 }, 8 "age": { 9 "type": "integer" 10 }, 11 "email": { 12 "type": "string" 13 } 14 }, 15 "required": ["name", "age", "email"] 16}

1{ 2 "type": "object", 3 "properties": { 4 "name": { 5 "type": "string" 6 }, 7 "age": { 8 "type": "integer" 9 }, 10 "email": { 11 "type": "string" 12 } 13 }, 14 "required": ["name", "email"] 15}

Type

Description

Example Values

Validation Keywords

string

Textual data

"John", "admin@site.com"

minLength, maxLength, pattern, format

number

Floating-point or decimal numbers

19.99, -4.5, 100

minimum, maximum, multipleOf

integer

Strictly whole numbers

25, 0, -10 (no fractions)

minimum, maximum, multipleOf

boolean

Boolean truth values

true or false

enum: [true, false]

object

Unordered key-value pairs

{ "name": "John" }

properties, required, additionalProperties

array

Ordered collection of items

["JS", "Python"]

items, minItems, maxItems, uniqueItems

null

Explicit null value

null

type: ["string", "null"]

1{ 2 "type": "object", 3 "properties": { 4 "name": { 5 "type": "string" 6 }, 7 "address": { 8 "type": "object", 9 "properties": { 10 "city": { "type": "string" }, 11 "country": { "type": "string" } 12 }, 13 "required": ["city", "country"] 14 } 15 }, 16 "required": ["name", "address"] 17}

1{ 2 "type": "object", 3 "properties": { 4 "users": { 5 "type": "array", 6 "items": { 7 "type": "object", 8 "properties": { 9 "name": { "type": "string" }, 10 "age": { "type": "integer" } 11 }, 12 "required": ["name", "age"] 13 } 14 } 15 }, 16 "required": ["users"] 17}

1{ 2 "type": "object", 3 "properties": { 4 "username": { 5 "type": "string", 6 "minLength": 3 7 }, 8 "email": { 9 "type": "string", 10 "format": "email" 11 }, 12 "age": { 13 "type": "integer", 14 "minimum": 18 15 }, 16 "newsletter": { 17 "type": "boolean" 18 } 19 }, 20 "required": ["username", "email", "age"] 21}

1// Runtime JSON validation standard (JSON Schema) 2{ 3 "type": "object", 4 "properties": { 5 "name": { "type": "string" }, 6 "age": { "type": "integer" }, 7 "email": { "type": "string" } 8 }, 9 "required": ["name", "age"] 10}

1{ 2 "type": "object", 3 "properties": { 4 "port": { 5 "type": "integer", 6 "minimum": 1024, 7 "maximum": 65535 8 }, 9 "environment": { 10 "type": "string", 11 "enum": ["development", "staging", "production"] 12 }, 13 "debug": { 14 "type": "boolean" 15 } 16 }, 17 "required": ["port", "environment"] 18}