How to Convert a JSON Array to CSV: Objects, 2D Arrays & Unwinding

Quick answer

To convert a JSON array to CSV, determine the array structure: an array of objects maps each object to a row with object keys as headers; a 2D array of arrays maps row-by-row directly into CSV lines; and an array of primitives (strings or numbers) maps into a single-column table. If your records contain nested arrays, choose whether to unwind items into multiple rows or split them into indexed columns (items.0, items.1). You can convert any JSON array format instantly in your browser with zero server uploads using our free JSON to CSV converter.

---

1. Array of objects (Standard tabular JSON)

The most common data format exported from REST APIs, database queries, and webhooks is a top-level array of JSON objects.

Example input

[
  { "id": 101, "name": "Alice Chen", "role": "Engineer", "active": true },
  { "id": 102, "name": "Bob Taylor", "role": "Designer" },
  { "id": 103, "name": "Carol Danvers", "role": "Product Manager", "active": true }
]

Resulting CSV output

id,name,role,active
101,Alice Chen,Engineer,true
102,Bob Taylor,Designer,
103,Carol Danvers,Product Manager,true

Key considerations

• Key union: Different objects in the array may contain different keys (such as active missing in record 102). A compliant converter scans records to collect the union of all keys, emitting empty fields for missing values without throwing errors.
• Root wrapper objects: Some APIs return { "data": [ ... ] } or { "results": [ ... ] } rather than a bare array. In our online JSON to CSV tool, the parser automatically detects nested arrays and lets you select the target array path.

---

2. 2D array (Array of arrays / Matrix)

When JSON represents a compact matrix or raw spreadsheet dump, it is often structured as an array of arrays.

Example input

[
  ["Product ID", "Item Name", "Price", "In Stock"],
  ["SKU-001", "Mechanical Keyboard", 129.99, true],
  ["SKU-002", "Ergonomic Mouse", 69.50, false],
  ["SKU-003", "Desk Mat (90x40cm)", 24.00, true]
]

Resulting CSV output

Product ID,Item Name,Price,In Stock
SKU-001,Mechanical Keyboard,129.99,true
SKU-002,Ergonomic Mouse,69.50,false
SKU-003,Desk Mat (90x40cm),24.00,true

In a 2D array, the first row acts as the column header row, and each subsequent inner array represents one horizontal data row.

---

3. Array of scalar primitives

Sometimes data is an array of raw strings, numbers, or IDs:

[
  "user_2048",
  "user_2049",
  "user_2050",
  "user_2051"
]

Resulting CSV output

value
user_2048
user_2049
user_2050
user_2051

Each scalar primitive becomes a single row under an assigned header name (such as value or item).

---

4. Handling nested arrays inside objects

When objects contain child arrays, converting them to flat rows requires choosing an explicit array strategy:

[
  {
    "orderId": "ORD-771",
    "customer": "Elena Rostova",
    "items": ["Keyboard", "Mousepad", "Cable"]
  }
]

Strategy A: One row per item (Unwind / Explode)

Best for SQL relational database imports. The parent fields are duplicated across rows for each item in the array:

orderId,customer,items
ORD-771,Elena Rostova,Keyboard
ORD-771,Elena Rostova,Mousepad
ORD-771,Elena Rostova,Cable

Strategy B: One column per index

Each item index becomes a separate column header (items.0, items.1, items.2):

orderId,customer,items.0,items.1,items.2
ORD-771,Elena Rostova,Keyboard,Mousepad,Cable

Strategy C: Joined cell

Concatenates array elements into a single quoted CSV cell using a custom delimiter:

orderId,customer,items
ORD-771,Elena Rostova,"Keyboard; Mousepad; Cable"

Strategy D: Raw JSON string

Keeps the array as literal JSON text within the cell for later processing:

orderId,customer,items
ORD-771,Elena Rostova,"[""Keyboard"", ""Mousepad"", ""Cable""]"

For deeper examples of nested objects and paths, read our tutorial on flattening nested JSON structures.

---

Programmatic conversion examples

Convert JSON array in Python with pandas

import json
import pandas as pd

# Load JSON array
with open("records.json", "r", encoding="utf-8") as f:
    data = json.load(f)

# Flatten array of objects
df = pd.json_normalize(data)

# Optional: Unwind a nested array column named 'tags'
if "tags" in df.columns:
    df = df.explode("tags")

df.to_csv("output.csv", index=False)

Convert JSON array in Node.js (Standard Library)

import { readFile, writeFile } from 'node:fs/promises';

const raw = await readFile('records.json', 'utf8');
const array = JSON.parse(raw);

// Collect all unique keys from objects in the array
const headers = [...new Set(array.flatMap(obj => Object.keys(obj)))];

// Escape CSV cell values safely
const escapeCell = (val) => {
  if (val == null) return '';
  const str = Array.isArray(val) ? val.join('; ') : String(val);
  return /[",\n]/.test(str) ? `"${str.replaceAll('"', '""')}"` : str;
};

// Build CSV rows
const lines = [
  headers.join(','),
  ...array.map(row => headers.map(header => escapeCell(row[header])).join(','))
];

await writeFile('output.csv', lines.join('\n'), 'utf8');

---

Common conversion mistakes to avoid

1. Not scanning all records for keys: Inspecting only the first item in an array risks omitting properties that only appear in later rows. Always compute the union of all keys across the dataset.
2. Silent precision loss on long IDs: Numbers exceeding 15 digits (like 18-digit Discord, Snowflake, or Twitter IDs) lose precision when parsed by spreadsheets. Use our JSON to Excel converter to format numeric IDs as explicit text cells.
3. Malformed JSON formatting: An unclosed bracket or trailing comma prevents JSON parsing. Validate your payload with the client-side JSON Validator before conversion.