How to Convert JSON to CSV

Overview

JSON and CSV solve different problems, and converting between them means reconciling two different data models. JSON supports arbitrary nesting — objects inside objects, arrays inside objects — with no enforced uniformity across records. CSV is strictly tabular: a fixed set of columns, one row per record, every cell a plain string. Converting JSON to CSV is not a mechanical reformatting exercise; it requires deliberate decisions about how to flatten structure that CSV cannot natively represent.

This is a routine need for anyone working with API responses, NoSQL exports, or log data that needs to land in a spreadsheet or BI tool. Get the flattening decisions wrong and you end up with misaligned columns, dropped fields, or arrays mangled into unreadable strings. This guide walks through the conversion methodically, then points you to the JSON to CSV Formatter to automate the parts that are easy to get wrong by hand.

What You Need

• A JSON file or API response, ideally structured as an array of objects (the most common shape for tabular conversion)
• Awareness of whether your objects share identical keys or vary in structure
• A spreadsheet application (Excel, Google Sheets, or similar) or text editor to inspect the output
• The JSON to CSV Formatter to handle flattening and key-unioning automatically

Step 1: Understand the Structural Mismatch

Before converting anything, internalize the core incompatibility: JSON is hierarchical, CSV is flat. A JSON object can nest nodes infinitely deep and can hold arrays of mixed-length, mixed-type values inside any field. CSV has exactly two dimensions — rows and columns — with no concept of nesting at all.

[
  { "name": "Aanya", "address": { "city": "Mumbai", "pincode": "400001" }, "tags": ["vip", "returning"] },
  { "name": "Rohan", "address": { "city": "Pune", "pincode": "411001" }, "tags": ["new"] }
]

There is no single "correct" CSV representation of this data — several reasonable ones exist, depending on how you handle the nested address object and the tags array. Every later step is really about making that choice deliberately rather than letting a converter make it for you implicitly.

Step 2: Identify All Unique Keys Across Records

JSON arrays of objects frequently have inconsistent keys — some records include an optional field that others omit entirely. Before you can build a CSV header row, you need the union of every key that appears across every object in the array, not just the keys present in the first record.

[
  { "name": "Aanya", "email": "aanya@example.com" },
  { "name": "Rohan", "phone": "+91-9876543210" }
]

Here the first record has email but no phone; the second has the reverse. A naive converter that only inspects the first object generates a header of name, email and silently drops every phone value. The correct header is the union: name, email, phone, with empty cells filling in wherever a record lacks that key.

Step 3: Flatten Nested Objects

Nested objects need to be converted into flat column names before they can map onto CSV's two-dimensional grid. The standard approach is to join the parent key and child key with a separator — typically a dot or underscore — recursively, until every value is a primitive (string, number, boolean, or null).

{ "name": "Aanya", "address": { "city": "Mumbai", "pincode": "400001" } }

flattens to columns: name, address.city, address.pincode (or address_city, address_pincode). If the nesting goes deeper — say address.geo.lat — the same joining logic applies recursively. Pick one separator and apply it consistently; mixing dot and underscore notation in the same file makes columns harder to reverse-flatten later.

Step 4: Handle Arrays Within Records

Arrays nested inside a JSON object are the trickiest part of the conversion, because there is no flattening convention that is universally "correct" — the right choice depends on what you plan to do with the CSV afterward. Three approaches are common:

1. Join into a delimited string within one cell. ["vip", "returning"] becomes vip;returning. This keeps one row per record but requires the consumer to split on the delimiter. Avoid a comma as the internal delimiter in a comma-separated file — a semicolon or pipe is safer.
2. Expand into multiple rows (denormalize). Each array item gets its own row, repeating other fields. Three tags becomes three rows — clean per-value data, but more rows and duplicated fields.
3. Create indexed columns. tags becomes tag_1, tag_2, tag_3, sized to the longest array in the dataset, with empty slots for shorter ones. One row per record, but a wide, sparse table if lengths vary a lot.

Choose based on downstream use: delimited strings for human-readable spreadsheets, denormalized rows for further aggregation, and indexed columns when array position itself carries meaning (such as ranked preferences).

Step 5: Convert and Validate the Output

With your flattening and array-handling approach decided, run the conversion. The JSON to CSV Formatter automates key-unioning and nested flattening — paste your JSON in and it produces a properly aligned CSV with a consistent header row.

After conversion, always validate the output before relying on it:

• Open the CSV in a spreadsheet tool and confirm column count matches the number of unique keys you expect.
• Spot-check rows from records with missing fields — confirm those cells are empty rather than shifted into the wrong column.
• Pay special attention to any text field that contained a comma, quote, or line break in the original JSON — these require correct CSV escaping, and a converter that gets this wrong will misalign every column to its right.
• If your data included Unicode characters (currency symbols, accented names), confirm the file was saved as UTF-8 so characters render correctly when reopened.

If you need the reverse direction — a flat CSV that needs to become structured JSON for an API — use the CSV to JSON Formatter, which reverses the process based on the column naming convention in the header row.

Common Mistakes to Avoid

Not escaping special characters within field values. A text field containing a comma — for example "Compact, lightweight, durable" — splits into multiple columns unless wrapped in double quotes per the CSV escaping rule. This is the single most common cause of misaligned CSV output, and it stays invisible until you open the file and notice extra columns that shouldn't exist.

Losing data type information. CSV has no type system: numbers, booleans, and dates are all written as plain strings. A price field with JSON value 499.99 and a sku field with JSON value "499.99" are indistinguishable once written to CSV. Anyone consuming the file downstream must re-parse fields into the correct type from prior knowledge of the schema — the file itself gives no hint.

Assuming all objects in a JSON array share identical keys. This holds for tightly controlled, schema-validated data, but fails constantly for real-world API exports and evolving data models. Always compute the full key union across every record before generating the header row, rather than trusting the first object to represent the whole dataset's shape.

Formula & Methodology

The formal rule for CSV field escaping comes from RFC 4180: any field containing a comma, double quote, or newline must be enclosed in double quotes, and any double quote within the field must itself be doubled (" becomes ""). A field like He said "hello" becomes "He said ""hello""" in a properly escaped CSV.

The general conversion algorithm, regardless of which tool implements it, follows four stages:

1. Collect every object in the JSON array and compute the union of all keys present, including nested keys discovered during flattening.
2. Flatten each object recursively, joining nested keys with a consistent separator until every value is a primitive.
3. Resolve arrays according to your chosen strategy — delimited string, row expansion, or indexed columns — applied consistently across the dataset.
4. Serialize the flattened records as CSV rows under the unioned header, applying RFC 4180 escaping to any field containing a comma, quote, or newline.

Going the reverse direction with the CSV to JSON Formatter requires the inverse of step 2: splitting each column name on the separator used during flattening, then rebuilding the nested structure level by level. This only succeeds cleanly if the original flattening used one consistent naming convention throughout — a file mixing address.city and address_zip styles cannot be unambiguously reconstructed into nested JSON.