Nested JSON Example: Working With Complex Structures

Why JSON Gets Nested

Real-world data is hierarchical. A customer has orders, each order has items, each item has a product with attributes, and each product may have reviews. JSON supports this naturally because objects and arrays can contain other objects and arrays to any depth. Understanding how to read, write, and navigate nested JSON is essential for working with APIs, databases, and configuration systems.

A Real-World Nested JSON Example

Here's a complete e-commerce order document with five levels of nesting:

{
  "order": {
    "id": "ORD-2024-78542",
    "status": "shipped",
    "createdAt": "2024-11-20T14:30:00Z",
    "customer": {
      "id": "CUST-1042",
      "name": "Sarah Mitchell",
      "email": "sarah@example.com",
      "address": {
        "shipping": {
          "street": "456 Oak Avenue",
          "city": "Austin",
          "state": "TX",
          "zip": "73301",
          "country": "US"
        },
        "billing": {
          "street": "456 Oak Avenue",
          "city": "Austin",
          "state": "TX",
          "zip": "73301",
          "country": "US"
        }
      }
    },
    "items": [
      {
        "sku": "LAPTOP-PRO-15",
        "name": "ProBook Laptop 15\"",
        "quantity": 1,
        "price": 1299.99,
        "category": {
          "primary": "Electronics",
          "sub": "Laptops",
          "tags": ["portable", "professional", "2024-model"]
        }
      },
      {
        "sku": "USB-C-HUB-7",
        "name": "7-Port USB-C Hub",
        "quantity": 2,
        "price": 49.99,
        "category": {
          "primary": "Electronics",
          "sub": "Accessories",
          "tags": ["usb-c", "hub", "portable"]
        }
      }
    ],
    "payment": {
      "method": "credit_card",
      "last4": "4242",
      "total": 1399.97,
      "currency": "USD",
      "breakdown": {
        "subtotal": 1399.97,
        "tax": 115.50,
        "shipping": 0,
        "discount": {
          "code": "SAVE10",
          "amount": 139.99
        }
      }
    }
  }
}

Understanding Access Patterns

When working with nested JSON in code, you access values using dot notation or bracket notation. Here are the paths to reach different parts of this document:

// Customer's shipping city (4 levels deep)
order.customer.address.shipping.city  → "Austin"

// First item's subcategory (4 levels deep)
order.items[0].category.sub  → "Laptops"

// Discount code (4 levels deep)
order.payment.breakdown.discount.code  → "SAVE10"

// Second item's first tag (5 levels deep)
order.items[1].category.tags[0]  → "usb-c"

// Total payment amount (2 levels deep)
order.payment.total  → 1399.97

Each dot or bracket in the path represents one level of depth. The deeper you go, the more fragile the access becomes — any missing intermediate property will throw an error in most languages.

Safe Access in Different Languages

When working with deeply nested JSON, always guard against missing intermediate keys:

// JavaScript — optional chaining
const city = data?.order?.customer?.address?.shipping?.city ?? "Unknown";

// Python — nested .get() with defaults
city = data.get("order", {}).get("customer", {}).get("address", {}).get("shipping", {}).get("city", "Unknown")

// jq (command-line)
jq '.order.customer.address.shipping.city // "Unknown"' data.json

When Deep Nesting Becomes a Problem

While JSON supports unlimited nesting depth, deep structures create real issues:

• Readability drops. Developers struggle to mentally parse structures beyond three or four levels.
• Fragile access paths. Long chains like order.customer.address.shipping.city are prone to null-reference errors if any intermediate key is missing.
• Database mapping gets complex. Deeply nested documents are harder to index, query, and update in most databases.
• Serialization overhead. Very deep structures take longer to parse and serialize, especially on resource-constrained devices.

Flattening Strategies

If your JSON is getting too deep, consider these alternatives:

// Instead of deeply nested:
{
  "order": {
    "customer": {
      "address": {
        "shipping": {
          "city": "Austin"
        }
      }
    }
  }
}

// Use a flatter structure with compound keys:
{
  "orderId": "ORD-2024-78542",
  "customerName": "Sarah Mitchell",
  "shippingCity": "Austin",
  "shippingState": "TX",
  "shippingZip": "73301"
}

The flattened version trades hierarchical structure for simplicity. Use references (IDs) instead of embedding entire sub-objects when the nested data is shared across documents or updated independently.

Common Mistakes to Avoid

• Nesting for the sake of it.Don't create wrapper objects that serve no purpose. If address always means shipping address, skip the extra nesting level.
• Duplicating data across levels. In the example above, currency appears in payment. Don't repeat it inside breakdown too.
• Forgetting to handle missing keys. Always use optional chaining or equivalent when traversing nested JSON from external sources.
• Mixing arrays and objects inconsistently. If items is an array in one response and an object in another, consumers will break.