JSON to CSV Tutorial: Convert Arrays to Spreadsheet Rows

Start with a JSON array of objects

CSV is a table format, so the cleanest input is a list of similar records.

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com",
    "active": true
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com",
    "active": false
  }
]

id,name,email,active
1,Alice,alice@example.com,true
2,Bob,bob@example.com,false

Choose CSV headers

Headers usually come from the union of keys across all objects. If the first object does not include every key, scan the whole array before writing the header row.

[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob", "team": "Support" }
]

// Headers should be: id,name,team

Flatten nested JSON objects

CSV cannot store nested objects directly. A common convention is dot notation.

[
  {
    "id": 1,
    "name": "Alice",
    "address": {
      "city": "Paris",
      "country": "FR"
    }
  }
]

// id,name,address.city,address.country
// 1,Alice,Paris,FR

Escape commas, quotes, and newlines

CSV values that contain commas, double quotes, or line breaks must be wrapped in double quotes. Double quotes inside the value are escaped by doubling them.

[
  { "note": "Hello, world" },
  { "note": "She said \"yes\"" }
]

// note
// "Hello, world"
// "She said ""yes"""

Common JSON to CSV mistakes

• Trying to convert one deeply nested object without deciding what the rows are.
• Using only the first object to determine headers when later rows have extra keys.
• Flattening arrays into ambiguous text without a delimiter convention.
• Forgetting that spreadsheet apps may reinterpret IDs, dates, and long numbers.