JSON Schema Examples: Objects, Arrays, Enums, and Conditional Rules

JSON Schema describes the shape and constraints of JSON data. It can document an API contract, validate configuration files, protect an import pipeline, and turn assumptions such as “status is required” into executable rules. The examples below use modern JSON Schema vocabulary and are intentionally small enough to adapt.

Start with an object and required fields

This schema accepts an object with a required string id and a required status. additionalProperties: false catches misspelled or unexpected keys.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "status"],
  "properties": {
    "id": { "type": "string", "minLength": 1 },
    "status": { "enum": ["pending", "active", "disabled"] }
  },
  "additionalProperties": false
}

Use additionalProperties: false deliberately. It is useful for controlled configuration and internal APIs, but public APIs may need to tolerate new fields for backward compatibility.

Validate nested objects

Nested rules belong inside the relevant property. Here the address itself is required, and two fields inside it are also required.

{
  "type": "object",
  "required": ["name", "address"],
  "properties": {
    "name": { "type": "string" },
    "address": {
      "type": "object",
      "required": ["country", "postalCode"],
      "properties": {
        "country": { "type": "string", "minLength": 2 },
        "postalCode": { "type": "string", "pattern": "^[A-Za-z0-9 -]+$" }
      },
      "additionalProperties": false
    }
  }
}

A regex checks text shape, not real-world existence. If postal codes must be valid for a specific country, keep that business rule outside the generic schema or use carefully tested conditional schemas.

Constrain arrays and items

Use items to describe every element, and array keywords to control size and duplicates.

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "required": ["sku", "quantity"],
    "properties": {
      "sku": { "type": "string", "minLength": 1 },
      "quantity": { "type": "integer", "minimum": 1 }
    },
    "additionalProperties": false
  }
}

Remember that uniqueItems compares complete JSON values. Two objects with the same sku but different quantities are still different objects; enforcing uniqueness by one field usually requires application logic.

Reuse definitions with $defs

Repeated structures should have one source of truth. Define them under $defs and reference them with $ref.

{
  "$defs": {
    "money": {
      "type": "object",
      "required": ["amount", "currency"],
      "properties": {
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
      },
      "additionalProperties": false
    }
  },
  "type": "object",
  "properties": {
    "subtotal": { "$ref": "#/$defs/money" },
    "total": { "$ref": "#/$defs/money" }
  }
}

For financial systems, consider representing decimal amounts as validated strings or integer minor units so binary floating-point behavior is explicit.

Add conditional requirements

if, then, and else are useful when one field changes which other fields are required.

{
  "type": "object",
  "required": ["deliveryMethod"],
  "properties": {
    "deliveryMethod": { "enum": ["pickup", "shipping"] },
    "shippingAddress": { "type": "string", "minLength": 1 },
    "pickupLocationId": { "type": "string", "minLength": 1 }
  },
  "allOf": [
    {
      "if": { "properties": { "deliveryMethod": { "const": "shipping" } } },
      "then": { "required": ["shippingAddress"] },
      "else": { "required": ["pickupLocationId"] }
    }
  ]
}

Keep conditional schemas readable. If the rules begin to model permissions, inventory, or workflow state, perform those checks in application code and use Schema for the structural contract.

A reliable workflow

1. Start from representative valid and invalid samples.

1. Generate a baseline with the JSON Schema Generator.

1. Add required fields and constraints based on the contract, not just one sample.

1. Test missing fields, wrong types, boundary values, extra keys, and empty collections.

1. Store the schema in version control and run it in automated tests.

The official JSON Schema documentation is the reference for vocabulary and draft behavior. A generator accelerates the first draft, but the final schema must reflect business intent and compatibility requirements.