JSON Schema Tutorial: From Basics to Advanced Techniques

What is JSON Schema?

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It provides a contract for your JSON data, describing the structure, type constraints, and validation rules that your data must follow. Think of it as a blueprint for your JSON data.

JSON Schema is used for validating API requests and responses, documenting APIs, generating mock data, and ensuring data consistency across systems. It's language-independent, making it perfect for microservices and distributed systems.

Basic Schema Structure

Every JSON Schema is itself a JSON object. At its simplest, a schema can just define the type of data it expects. The most basic schema is an empty object, which validates any JSON value.

{
  "type": "string"
}

This schema simply states that the data must be a string. JSON Schema supports several primitive types: string, number, integer, boolean, null, array, and object.

Defining Object Schemas

Objects are the most common structure in JSON. Here's how to define a schema for an object with specific properties:

{
  "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 properties. The "required" array specifies which properties must be present. Age is optional, but name and email are required.

Working with Arrays

Arrays can contain items of a single type or mixed types. You can also specify minimum and maximum item counts:

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

This schema requires an array of strings with at least 1 and at most 10 items, where all items must be unique.

String Validation

Strings support various validation options including length constraints, patterns, and formats:

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

Common format values include: "email", "uri", "date-time", "ipv4", "ipv6", and "uuid". These provide built-in validation for common data types.

Number Validation

Numbers and integers support range validation and divisibility checks:

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 0.01
}

This is perfect for validating percentages or prices. Use "exclusiveMinimum" and "exclusiveMaximum" when you need strict inequality.

Enum Values

Use enum to restrict values to a specific set:

{
  "type": "string",
  "enum": ["pending", "active", "completed", "cancelled"]
}

Enums are perfect for status fields, categories, or any field with a limited set of valid values.

Nested Objects and References

For complex schemas, you can nest objects and use references to avoid repetition:

{
  "type": "object",
  "properties": {
    "user": {
      "$ref": "#/definitions/user"
    },
    "address": {
      "$ref": "#/definitions/address"
    }
  },
  "definitions": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      }
    },
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  }
}

References make schemas more maintainable and reusable, especially in large API definitions.

Generate Data from Your JSON Schema

Our tool makes it easy to generate mock data that matches your JSON schema. Define your schema and get realistic data instantly.

Try It Now →