How to Convert Nested JSON to CSV Without Losing Fields

Converting a flat JSON array to CSV is straightforward. Real datasets are rarely flat.

API responses often contain nested objects, arrays, optional fields, large numeric identifiers, and properties that appear only in later records. A basic conversion can silently drop data, misalign columns, or change values when the CSV is opened in spreadsheet software.

This guide covers the main problems and how to handle them safely.

The converted table can be reviewed and adjusted before exporting CSV or XLSX.

A simple JSON to CSV conversion

This JSON is already tabular:

[
  {
    "name": "Ada",
    "role": "Engineer"
  },
  {
    "name": "Linus",
    "role": "Developer"
  }
]

It maps cleanly to:

name,role
Ada,Engineer
Linus,Developer

Each object becomes a row, and each property becomes a column.

The problems begin when the structure becomes more complex.

1. Flatten nested objects

Consider this dataset:

[
  {
    "id": 101,
    "name": "Ada",
    "company": {
      "name": "Analytical Systems",
      "country": "UK"
    }
  }
]

CSV does not support nested objects directly. One practical solution is to flatten nested fields using dot notation:

id,name,company.name,company.country
101,Ada,Analytical Systems,UK

This preserves the original field relationships without storing the complete object as an unreadable JSON string.

For deeper structures:

{
  "customer": {
    "address": {
      "city": "London"
    }
  }
}

The resulting column can be:

customer.address.city

The flattening rule should remain predictable throughout the dataset.

2. Handle arrays consistently

Arrays may contain primitive values, objects, different numbers of items, or mixed structures.

Example:

[
  {
    "name": "Ada",
    "skills": ["JavaScript", "Python"]
  },
  {
    "name": "Linus",
    "skills": ["C"]
  }
]

One approach is to expand array positions into numbered columns:

name,skills__001,skills__002
Ada,JavaScript,Python
Linus,C,

The second row keeps an empty skills__002 cell instead of shifting data into the wrong column.

Arrays of objects can follow the same pattern:

{
  "orders": [
    {
      "id": 1,
      "total": 25
    },
    {
      "id": 2,
      "total": 40
    }
  ]
}

Possible columns include:

orders__001.id
orders__001.total
orders__002.id
orders__002.total

This may not be the ideal structure for every analysis workflow, but it creates stable columns without discarding values.

3. Scan every record for columns

A common conversion mistake is using only the first object to determine the CSV headers.

Consider:

[
  {
    "id": 1,
    "name": "Ada"
  },
  {
    "id": 2,
    "name": "Linus",
    "email": "[e-mail]"
  }
]

Using only the first object would produce:

id,name
1,Ada
2,Linus

The email field disappears.

A safer converter scans the complete dataset and creates a union of every discovered field:

id,name,email
1,Ada,
2,Linus,[e-mail]

Missing values become empty cells while every row remains correctly aligned.

4. Preserve large numeric identifiers

JavaScript cannot safely represent every large integer as a normal number.

For example:

{
  "accountId": 9223372036854775807
}

That value exceeds JavaScript's safe integer range. Parsing it normally may change the final digits.

This matters for values such as:

• Database IDs
• Order numbers
• Social media identifiers
• Financial reference numbers
• Snowflake-style IDs

Large identifiers should be preserved as text rather than silently rounded.

Spreadsheet software may also display long identifiers using scientific notation, so treating them as strings is often safer.

5. Support JSONL and NDJSON

Not every dataset is stored as one JSON array.

JSON Lines and NDJSON store one complete JSON object on each line:

{"id":1,"name":"Ada"}
{"id":2,"name":"Linus"}
{"id":3,"name":"Grace"}

This format is common in:

• Log exports
• Streaming systems
• Data pipelines
• Large datasets
• Command-line workflows

A useful converter should recognize both standard JSON arrays and line-delimited JSON.

Each valid line becomes one table row.

6. Escape CSV values correctly

CSV values need escaping when they contain:

• Commas
• Quotation marks
• New lines
• The selected delimiter

A value such as:

London, United Kingdom

Must be exported as:

"London, United Kingdom"

Quotation marks inside a quoted value must be doubled.

This value:

She said "hello"

Becomes:

"She said ""hello"""

Without correct escaping, columns may become misaligned when the file is opened.

7. Protect against spreadsheet formulas

Spreadsheet software may interpret cells beginning with certain characters as formulas.

Potential examples include:

=SUM(A1:A5)
+CMD
-10+20
@IMPORTXML(...)

This is commonly called CSV or spreadsheet formula injection.

A safer CSV export can prefix suspicious values so the spreadsheet treats them as text instead of executing them as formulas.

This is especially important when the original JSON contains values from users, forms, APIs, or external systems.

8. Preview the table before exporting

A table preview helps reveal structural problems before creating the final file.

Useful checks include:

• Were nested fields flattened correctly?
• Did later records introduce additional columns?
• Are arrays expanding consistently?
• Are large identifiers unchanged?
• Are unexpected fields present?
• Are some columns mostly empty?

Column selection is also useful when an API response contains dozens of fields but only a few are needed.

9. Choose CSV or XLSX based on the workflow

CSV is usually better when:

• The file will be imported into another system
• Portability matters
• A simple text format is preferred
• The dataset will be processed by code

XLSX can be more convenient when:

• The file will be opened directly in spreadsheet software
• Users expect a native spreadsheet file
• Long identifiers need more controlled handling
• A structured workbook is preferred

The correct format depends on what will happen after conversion.

Practical checklist

Before exporting JSON data, confirm that the converter:

1. Scans every record for fields
2. Flattens nested objects predictably
3. Handles arrays without shifting columns
4. Keeps missing values aligned
5. Preserves large integer identifiers
6. Escapes delimiters, quotation marks, and new lines
7. Protects against spreadsheet formulas
8. Supports JSONL and NDJSON when needed
9. Provides a preview before downloading
10. Lets users remove unnecessary columns

A converter built for these cases

I built Olivez JSON to CSV Converter while working through these problems.

It supports:

• JSON, JSONL, and NDJSON
• Pasted data
• Local files up to 100 MB
• Public JSON URLs
• Nested object flattening
• Stable numbered array columns
• Full-dataset column discovery
• Large integer preservation
• Table preview and column selection
• CSV and XLSX export
• Custom CSV delimiters
• Spreadsheet formula protection

Local files and pasted data are processed on your device, and no account is required.

https://olivez.in/tool/json-to-csv-converter

The goal was not only to replace braces with commas. It was to make the conversion predictable enough that you can inspect the result and trust the exported file.