JSON Schema

JSON Schema is a powerful tool for validating the structure of JSON data. It provides a contract for what JSON data is required for a given application and how it can be modified.

What is JSON Schema?

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It provides:

  • Data validation: Ensure data meets required structure
  • Documentation: Self-documenting JSON structure
  • Interaction control: Control how data is used
  • Code generation: Generate code from schemas

Basic Schema Example

Here's a simple JSON Schema that validates a person object:

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

This schema validates JSON data like:

{
    "firstName": "John",
    "lastName": "Doe",
    "age": 30,
    "email": "[email protected]"
}

Schema Keywords

Type Validation

  • type: Specifies the data type (string, number, object, array, boolean, null)
  • enum: Restricts value to a set of choices
  • const: Requires value to be exactly equal to specified value

String Validation

  • minLength / maxLength: String length constraints
  • pattern: Regular expression pattern
  • format: Predefined formats (email, uri, date-time, etc.)

Number Validation

  • minimum / maximum: Numeric range
  • multipleOf: Value must be multiple of specified number
  • exclusiveMinimum / exclusiveMaximum: Exclusive bounds

Object Validation

  • properties: Defines object properties
  • required: Array of required property names
  • minProperties / maxProperties: Property count constraints
  • additionalProperties: Controls additional properties

Array Validation

  • items: Schema for array items
  • minItems / maxItems: Array length constraints
  • uniqueItems: Whether items must be unique

Advanced Schema Features

Nested Objects

{
    "type": "object",
    "properties": {
        "address": {
            "type": "object",
            "properties": {
                "street": {"type": "string"},
                "city": {"type": "string"},
                "zipCode": {"type": "string"}
            },
            "required": ["street", "city"]
        }
    }
}

Array of Objects

{
    "type": "object",
    "properties": {
        "users": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string", "format": "email"}
                },
                "required": ["name", "email"]
            }
        }
    }
}

Conditional Validation

{
    "type": "object",
    "properties": {
        "country": {"type": "string"},
        "postalCode": {"type": "string"}
    },
    "if": {
        "properties": {"country": {"const": "USA"}}
    },
    "then": {
        "properties": {
            "postalCode": {"pattern": "^\\d{5}(-\\d{4})?$"}
        }
    }
}

Schema Validation Tools

Online Validators

Programming Libraries

  • JavaScript: Ajv, jsonschema
  • Python: jsonschema, fastjsonschema
  • Java: json-schema-validator, everit
  • PHP: justinrainbow/json-schema
  • Go: gojsonschema

Using Schema in Code

JavaScript Example with Ajv

const Ajv = require('ajv');
const ajv = new Ajv();

const schema = {
    type: "object",
    properties: {
        name: {type: "string"},
        age: {type: "integer", minimum: 0}
    },
    required: ["name", "age"]
};

const data = {
    name: "John",
    age: 30
};

const validate = ajv.compile(schema);
const valid = validate(data);

if (!valid) {
    console.log(validate.errors);
}

Python Example

import jsonschema

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "age"]
}

data = {"name": "John", "age": 30}

try:
    jsonschema.validate(instance=data, schema=schema)
    print("Valid!")
except jsonschema.exceptions.ValidationError as e:
    print(f"Invalid: {e.message}")

Best Practices

  • Start simple: Begin with basic validation and add complexity as needed
  • Document thoroughly: Use "description" and "title" keywords
  • Reuse definitions: Use $ref to avoid duplication
  • Version your schemas: Track changes to your schema
  • Test extensively: Test both valid and invalid data
  • Use appropriate formats: Leverage built-in format validators
  • Consider performance: Complex schemas can be slow to validate

Learning Resources