JSON Schema Validation Tutorial for Beginners

Why Use JSON Schema?

Without schema validation, bad data silently enters your system and causes bugs downstream. JSON Schema catches errors at the boundary — before your application processes the data. It is also self-documenting: the schema itself describes what valid data looks like.

• Validate API request and response payloads
• Validate configuration files (CI/CD, app config)
• Generate documentation from the schema
• Generate forms and UI from the schema
• Provide clear error messages when data is invalid

Your First Schema

A JSON Schema is itself a JSON object. Here is the simplest possible schema — it accepts any valid JSON:

{}

Now let us define a schema for a user object:

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

This schema says: the data must be an object with a name (non-empty string), an email (valid email format), and an optional age (integer between 0 and 150). Both name and email are required.

Core Type Keywords

JSON Schema supports six primitive types:

• "string" — Text. Keywords: minLength, maxLength, pattern, format.
• "number" — Floating point. Keywords: minimum, maximum, multipleOf.
• "integer" — Whole numbers only. Same keywords as number.
• "boolean" — True or false.
• "array" — Ordered list. Keywords: items, minItems, maxItems, uniqueItems.
• "object" — Key-value pairs. Keywords: properties, required, additionalProperties.

Validation Keywords in Practice

Here are the most commonly used validation keywords with examples:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["active", "inactive", "pending"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "uniqueItems": true
    },
    "metadata": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "created": { "type": "string", "format": "date-time" }
      }
    }
  }
}

The enum keyword restricts a value to a fixed set of options. additionalProperties: false rejects any properties not explicitly defined — useful for strict API contracts.

Composition: allOf, anyOf, oneOf

JSON Schema supports composing schemas together:

• allOf — Data must match all listed schemas (intersection).
• anyOf — Data must match at least one schema (union).
• oneOf — Data must match exactly one schema (exclusive or).
• not — Data must not match the schema.

These are powerful for modeling discriminated unions, optional extensions, and complex validation logic without duplicating schema definitions.

Reusable Schemas with $ref

The $ref keyword lets you reference a schema defined elsewhere, avoiding duplication. Define reusable types in a $defs block and reference them:

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "zip": { "type": "string", "pattern": "^[0-9]{5}$" }
      },
      "required": ["street", "city", "zip"]
    }
  },
  "type": "object",
  "properties": {
    "billing": { "$ref": "#/$defs/address" },
    "shipping": { "$ref": "#/$defs/address" }
  }
}

Libraries and Tools

JSON Schema validation is supported in every major language:

• JavaScript/TypeScript: Ajv, Zod (Zod can convert to/from JSON Schema)
• Python: jsonschema, fastjsonschema
• Go: gojsonschema
• Ruby: json_schemer
• Online: Use the CheckFast JSON Validator to validate JSON data quickly.