Nested Object Validation in JSON Schema

Nested Object Validation

Real-world JSON data is rarely flat — it contains objects within objects. JSON Schema handles nested structures naturally by defining sub-schemas for each level of nesting.

Basic Nesting

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

The inner schema validates address as an object with a required city string property. Each nesting level has its own independent properties, required, and other keywords.

How the Example Schema Works

The schema defines a two-level nested structure with an optional third level:

Level 1 — the root object requires both user and address.

Level 2 — user is an object with a required name and an optional age. The address object requires street, city, and country, with optional postalCode and coordinates.

Level 3 — coordinates is an object nested inside address, with required latitude (range -90 to 90) and longitude (range -180 to 180).

The test data passes all three levels: the user has a name, the address has all required fields, and the coordinates are valid geographic values.

Required at Each Level

A critical point: each object has its own required array. The root-level required: ["user", "address"] does not make user.name required — that is controlled by the required inside the user sub-schema.

Avoiding Deep Nesting with $ref

When schemas get deeply nested, readability suffers. Use $ref with $defs to flatten the structure:

{
  "type": "object",
  "properties": {
    "address": { "$ref": "#/$defs/Address" }
  },
  "$defs": {
    "Address": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "coordinates": { "$ref": "#/$defs/GeoPoint" }
      }
    },
    "GeoPoint": {
      "type": "object",
      "properties": {
        "latitude": { "type": "number" },
        "longitude": { "type": "number" }
      }
    }
  }
}

This approach keeps each definition at the top level, making schemas easier to read, test, and reuse. See the ref-definitions example for a deep dive into $ref.

Error Path Reporting

When validation fails in a nested structure, good validators report the JSON Pointer path to the error (e.g., /address/coordinates/latitude). This makes debugging deeply nested structures straightforward.