Flatten nested JSON arrays

Arrays are where flattening stops being obvious. A single object can become one flat map, but an array might mean "one flat object per row" or "expand every item with an index." Order payloads, event batches, search results, and analytics logs all use arrays differently, so the right JSON flattener behavior depends on the destination.

This page focuses on flattening JSON arrays online. It uses the same engine as the Flatten JSON tool, but the examples here are written for arrays of records and nested list fields.

JSON array flattener example

Input:

[
  {
    "id": "ord_1",
    "customer": { "email": "ada@example.com" },
    "items": [
      { "sku": "book", "qty": 2 },
      { "sku": "pen", "qty": 4 }
    ]
  }
]

Flattened with indexed array paths:

[
  {
    "id": "ord_1",
    "customer.email": "ada@example.com",
    "items.0.sku": "book",
    "items.0.qty": 2,
    "items.1.sku": "pen",
    "items.1.qty": 4
  }
]

That format is useful for quick QA review because every nested value has a visible path. It is less ideal when the array can contain hundreds of items, because each index can become a separate column.

When to flatten arrays by index

Index-based flattening is best when each record has a small, predictable number of child items. Examples include two addresses, three attribution fields, one latest invoice, or a small set of feature flags.

For long line-item arrays, indexed paths can create wide output. In that case, flatten the parent fields first, then normalize or explode line items into separate rows with a pipeline step. The parent order can keep order.id, while each item row gets items.sku, items.qty, and items.price.

Flatten array of objects for CSV

CSV exporters usually want an array of flat objects:

[
  { "user.name": "Ada", "user.plan": "pro" },
  { "user.name": "Grace", "user.plan": "team" }
]

That shape converts cleanly because every object becomes one row. If your next step is spreadsheet export, pair this page with Flatten JSON for CSV and then JSON to CSV.

Common array flattening mistakes

• Flattening huge arrays into items.0, items.1, items.2 columns when the destination really needs separate rows.
• Forgetting that missing items produce empty CSV cells.
• Treating arrays of primitives and arrays of objects the same way.
• Losing item order when downstream tools sort columns alphabetically.
• Using . as a delimiter when original keys already contain dots.

Array flattening vs unflattening

Indexed paths can usually be rebuilt if the delimiter and indexes are preserved. For example, items.0.sku and items.1.sku can become an items array again. Use Unflatten JSON when a flat array path map needs to become nested JSON for an API request.

Related flatten JSON tools

• JSON flattener - the general-purpose flatten and nest tool.
• Flatten JSON for CSV - turn nested paths into spreadsheet columns.
• Flatten API Response JSON - inspect nested REST, GraphQL, and webhook payloads.
• Unflatten JSON - rebuild arrays and objects from indexed flat paths.