Converting JSON to CSV seems straightforward until you try it with real-world data. What you expect to be a clean tabular export often turns into a mess: nested objects become [object Object], arrays get concatenated oddly, headers don't match your data structure, and suddenly your spreadsheet is useless. This happens because JSON and CSV are fundamentally different data models, and the conversion requires intelligent flattening strategies.

The Problem: JSON is Hierarchical, CSV is Flat

JSON supports nested structures: objects within objects, arrays of objects, mixed types. CSV is inherently flat: rows and columns, no nesting. When you convert JSON to CSV, something has to give.

Consider this typical API response:

[
  {
    "id": 1,
    "name": "Alice",
    "contact": {
      "email": "alice@example.com",
      "phone": "+1234567890"
    },
    "tags": ["developer", "admin"]
  },
  {
    "id": 2,
    "name": "Bob",
    "contact": {
      "email": "bob@example.com"
    },
    "tags": ["designer"]
  }
]

You'd expect this to convert cleanly into a CSV table. But what happens with the nested contact object? And how should the tags array be represented?

Issue #1: Nested Objects Become Unreadable

The most common problem: nested objects get stringified into something like [object Object] or raw JSON strings in a single cell.

Bad conversion (no flattening):

id,name,contact,tags
1,Alice,[object Object],"[""developer"",""admin""]"
2,Bob,[object Object],"[""designer""]"

This is useless for data analysis. The contact field is unreadable, and the tags array is a stringified JSON value.

Solution: Flatten Nested Objects with Dot Notation

A proper JSON to CSV converter should flatten nested structures using dot-separated keys:

id,name,contact.email,contact.phone,tags
1,Alice,alice@example.com,+1234567890,"developer,admin"
2,Bob,bob@example.com,,"designer"

Now contact.email and contact.phone are separate columns, making the data usable in spreadsheets and databases.

Issue #2: Arrays Create Ambiguous Columns

Arrays in JSON can have multiple values, but CSV expects a single value per cell. There's no one right answer — it depends on your use case.

Strategy 1: Join Array Values

The simplest approach is to concatenate array values with a delimiter (comma, semicolon, pipe):

tags
"developer,admin"
"designer"

This works for simple tags or categories but loses structure if the array contains objects.

Strategy 2: Create One Column Per Array Index

For arrays with a known maximum length, you can create indexed columns:

tags[0],tags[1]
developer,admin
designer,

This maintains individual values but becomes unwieldy with variable-length arrays and wastes columns if most rows have fewer items.

Strategy 3: Expand Rows (Denormalize)

If your array contains important distinct values, you might want one row per array item:

id,name,contact.email,tag
1,Alice,alice@example.com,developer
1,Alice,alice@example.com,admin
2,Bob,bob@example.com,designer

This duplicates parent data but makes filtering and analysis easier in tools like Excel or SQL databases.

Issue #3: Inconsistent Headers Across Objects

Real-world JSON often has inconsistent structure. Not every object has the same keys, and CSV requires uniform headers.

Example:

[
  { "id": 1, "name": "Alice", "role": "admin" },
  { "id": 2, "name": "Bob" },
  { "id": 3, "name": "Carol", "role": "user", "department": "Engineering" }
]

Bob has no role, and Carol has a department field that others don't.

Solution: Collect All Possible Keys First

A robust converter must:

1. Scan all objects in the array to discover every unique key
2. Generate a complete header row with all possible columns
3. Fill missing values with empty strings or nulls

Result:

id,name,role,department
1,Alice,admin,
2,Bob,,
3,Carol,user,Engineering

Issue #4: Special Characters Break CSV Parsing

JSON strings can contain any character, including commas, quotes, and newlines. These must be properly escaped in CSV.

Example JSON with special characters:

{
  "description": "This is a "quoted" value, with commas",
  "notes": "Line one\nLine two"
}

Solution: Proper CSV Escaping

According to CSV standards (RFC 4180):

• Fields containing commas, quotes, or newlines must be enclosed in double quotes: "value"
• Double quotes within a field must be escaped by doubling them: ""
• Newlines within quoted fields are preserved

Correct output:

description,notes
"This is a ""quoted"" value, with commas","Line one
Line two"

Issue #5: Empty Arrays and Null Values

How should empty arrays and null values be represented in CSV?

{
  "id": 1,
  "tags": [],
  "description": null
}

Common Conventions

• Empty arrays: Usually represented as empty strings in CSV
• Null values: Can be empty strings, the literal text null, or a configurable placeholder
• Missing keys: Always empty strings (indicates the key wasn't present)

Example output:

id,tags,description
1,,null

Some tools let you configure how nulls are displayed: blank, NULL, null, or a custom placeholder.

Real-World Scenario: Converting API Response to CSV

Let's walk through a complete example with a realistic API response:

[
  {
    "id": 101,
    "user": {
      "name": "Alice Johnson",
      "email": "alice@company.com"
    },
    "purchases": [
      { "item": "Laptop", "price": 1200 },
      { "item": "Mouse", "price": 25 }
    ],
    "created": "2026-01-10T10:30:00Z"
  },
  {
    "id": 102,
    "user": {
      "name": "Bob Smith",
      "email": "bob@company.com"
    },
    "purchases": [
      { "item": "Keyboard", "price": 80 }
    ],
    "created": "2026-01-11T14:22:00Z"
  }
]

Step 1: Choose a Flattening Strategy

Options:

• Flatten user object: Use dot notation (user.name, user.email)
• Handle purchases array: Either join items, expand rows, or stringify

Step 2: Apply Flattening (Row Expansion)

If we expand rows for each purchase:

id,user.name,user.email,purchases.item,purchases.price,created
101,Alice Johnson,alice@company.com,Laptop,1200,2026-01-10T10:30:00Z
101,Alice Johnson,alice@company.com,Mouse,25,2026-01-10T10:30:00Z
102,Bob Smith,bob@company.com,Keyboard,80,2026-01-11T14:22:00Z

This makes the data easy to analyze in spreadsheets: filter by user, sum prices, etc.

Alternative: Join Array Values

If row expansion isn't needed, join array items as JSON:

id,user.name,user.email,purchases,created
101,Alice Johnson,alice@company.com,"[{""item"":""Laptop"",""price"":1200},{""item"":""Mouse"",""price"":25}]",2026-01-10T10:30:00Z
102,Bob Smith,bob@company.com,"[{""item"":""Keyboard"",""price"":80}]",2026-01-11T14:22:00Z

This keeps one row per user but requires additional parsing if you want to work with purchases data.

How to Use JSON to CSV Conversion Tools

When using tools to convert JSON to CSV, look for these features:

• Automatic flattening: Nested objects should be flattened with dot notation
• Array handling options: Join, expand rows, or index-based columns
• Header detection: Scan all objects to generate complete headers
• Proper escaping: Handle commas, quotes, and newlines correctly
• Null/empty handling: Configurable representation of null values

The JSON to CSV converter on DevToys Pro provides all these options with a visual preview, letting you adjust settings before export.

Using JSONPath to Pre-Process Data

Before converting to CSV, you might want to extract or filter specific parts of a complex JSON structure. Use JSONPath queries to:

• Extract arrays: $.data.users[*]
• Filter by condition: $.users[?(@.active == true)]
• Select specific fields: $.users[*].['name', 'email']

Then convert the extracted result to CSV for cleaner, more focused exports.

JSON Formatting Before Conversion

If your JSON isn't properly formatted or contains syntax errors, fix it first with a JSON formatter and validator. This ensures:

• Valid JSON structure (no trailing commas, missing brackets, etc.)
• Readable formatting for debugging
• Identification of data issues before conversion

Best Practices for JSON to CSV Conversion

1. Understand your data structure first: Inspect the JSON to identify nesting, arrays, and inconsistencies
2. Choose the right array strategy: Join for simple lists, expand rows for detailed analysis
3. Preview before exporting: Always check the output format matches your expectations
4. Use JSONPath for filtering: Extract relevant data before conversion
5. Test with edge cases: Empty arrays, null values, special characters
6. Document your conversion settings: If you need to repeat the process, note which options you used

Common Error Messages and Fixes

"Cannot convert non-array JSON to CSV"

Solution: CSV conversion typically expects an array of objects. If your JSON is a single object, wrap it in an array: [{...}]

"Inconsistent column count"

Solution: Your JSON objects have different keys. Use a tool that scans all objects and generates complete headers.

"Arrays not properly flattened"

Solution: Check your converter's array handling settings. Choose between join, expand, or index strategies.

Key Takeaways

• JSON to CSV conversion requires flattening hierarchical data into a tabular format
• Nested objects should be flattened with dot notation for usable columns
• Array handling depends on your use case: join, expand rows, or create indexed columns
• Always scan all objects to generate complete headers for inconsistent structures
• Proper escaping of commas, quotes, and newlines is essential for valid CSV
• Use JSONPath to pre-process and filter data before conversion for better results

Related Tools:

• JSON to CSV / CSV to JSON Converter — Convert with flattening and array options
• JSON Formatter & Validator — Format and validate JSON before conversion
• JSONPath Tester — Extract and filter JSON data