JSON Schema Tutorial: Validate Your JSON

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. Think of it as a contract: your schema defines the shape your data must conform to, and validators check incoming data against it. JSON Schema is widely used for API request/response validation, form validation, configuration file enforcement, and code generation.

This tutorial walks you through JSON Schema from the ground up — starting with basic types and building to nested objects, required fields, patterns, conditional logic, and reusable definitions.

Your First JSON Schema

A JSON Schema is itself a JSON object. Here's the simplest possible schema that validates a user object:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "description": "A user account",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Unique identifier"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": ["id", "name", "email"]
}

Core Keywords

• type — the JSON type: string, number, integer, boolean, array, object, null
• properties — defines the expected fields on an object
• required — array of field names that must be present
• $schema — declares which JSON Schema draft you're using

String Validation

JSON Schema offers several keywords for constraining string values:

{
  "type": "string",
  "minLength": 3,
  "maxLength": 50,
  "pattern": "^[a-zA-Z0-9_]+$",
  "format": "email"
}

• minLength / maxLength — character count constraints
• pattern — a regular expression the string must match
• format — semantic validation: email, uri, date, date-time, uuid
• enum — restrict to a fixed set of allowed values

Array Validation

Arrays have their own set of constraints:

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

The items keyword defines the schema that each element must satisfy. Set uniqueItems: true to reject duplicate values — useful for tag lists or permission sets.

Reusable Definitions with $defs

Use $defs to avoid repeating the same schema structure across multiple properties:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "Address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "country": { "type": "string" }
      },
      "required": ["street", "city", "country"]
    }
  },
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "billingAddress": { "$ref": "#/$defs/Address" },
    "shippingAddress": { "$ref": "#/$defs/Address" }
  }
}

Conditional Schemas with if/then/else

JSON Schema supports conditional validation — useful when the required fields depend on another field's value:

{
  "type": "object",
  "properties": {
    "paymentMethod": { "type": "string", "enum": ["card", "bank"] },
    "cardNumber": { "type": "string" },
    "bankAccount": { "type": "string" }
  },
  "if": {
    "properties": { "paymentMethod": { "const": "card" } }
  },
  "then": {
    "required": ["cardNumber"]
  },
  "else": {
    "required": ["bankAccount"]
  }
}

Key Takeaways

• JSON Schema validates structure, types, ranges, patterns, and required fields
• Use $defs + $ref to build reusable, DRY schemas
• Use if/then/else for conditional validation logic
• The format keyword validates semantic types like email and UUID
• Use JSONStudio's JSON to JSON Schema converter to auto-generate a schema from sample data