JSON Schema Explained: How to Define and Validate Data Structures

When you are building an API, processing data files, or working with configuration, you often need to enforce that incoming JSON has the right structure. JSON Schema is the standard tool for this.

A JSON Schema is itself a JSON document that describes the expected structure of another JSON document — the types of values, which fields are required, allowed ranges, patterns, and more.

A Simple Example

Here is a JSON document describing a user:

{
  "id": 42,
  "username": "alice_dev",
  "email": "alice@example.com",
  "isActive": true
}

And here is a JSON Schema that validates it:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "username", "email"],
  "properties": {
    "id":       { "type": "integer", "minimum": 1 },
    "username": { "type": "string",  "minLength": 3 },
    "email":    { "type": "string",  "format": "email" },
    "isActive": { "type": "boolean" }
  },
  "additionalProperties": false
}

This schema says: the object must have id, username, and email. The id must be a positive integer, username at least 3 chars, email must look like an email address. No extra fields are allowed.

Core JSON Schema Keywords

type

Specifies the expected data type. Valid values: string, number, integer, boolean, array, object, null.

{ "type": "string" }      // only strings pass
{ "type": "integer" }     // only whole numbers
{ "type": ["string", "null"] }  // string or null

required

An array of property names that must be present in the object:

{
  "type": "object",
  "required": ["name", "email"]
}

properties

Defines schemas for individual object properties. Each key is a property name and its value is a nested schema:

{
  "properties": {
    "age":  { "type": "integer", "minimum": 0, "maximum": 120 },
    "name": { "type": "string" }
  }
}

String Constraints

Number Constraints

Array Constraints

{
  "type": "array",
  "items": { "type": "string" },   // all items must be strings
  "minItems": 1,                     // at least one item
  "maxItems": 10,                    // at most ten items
  "uniqueItems": true                // no duplicate values
}

Combining Schemas

anyOf — valid if it matches any of the listed schemas

{
  "anyOf": [
    { "type": "string" },
    { "type": "number" }
  ]
}

allOf — valid only if it matches all listed schemas

{
  "allOf": [
    { "type": "object" },
    { "required": ["id"] }
  ]
}

oneOf — valid if it matches exactly one of the listed schemas

{
  "oneOf": [
    { "type": "integer" },
    { "type": "string", "format": "uuid" }
  ]
}

Using JSON Schema in Practice

Python with jsonschema

pip install jsonschema

import jsonschema
import json

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

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

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

JavaScript with Ajv

npm install ajv

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

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

const validate = ajv.compile(schema);
const data = { name: 'Alice', age: 30 };

if (validate(data)) {
  console.log('Valid!');
} else {
  console.log(validate.errors);
}

JSON Schema and Excel Conversion

When converting JSON to Excel, having a schema for your data helps in several ways:

• Column ordering — the schema's properties order can define the column order in the output spreadsheet
• Type enforcement — knowing that a field is an integer prevents it from being formatted as text in Excel
• Documentation — the schema serves as documentation for what each column means
• Validation before conversion — reject records that do not match the schema instead of producing a corrupted spreadsheet