How to Convert JSON to CSV: Methods and Tools

March 31, 2026 · 12 min read

Converting JSON to CSV is one of the most common data transformation tasks developers and data analysts face. Whether you're exporting API responses for analysis, preparing data for spreadsheet applications, or integrating systems with different format requirements, understanding how to effectively convert between these formats is essential.

This comprehensive guide walks you through everything you need to know about JSON to CSV conversion, from basic concepts to advanced techniques for handling complex nested structures.

Understanding JSON and CSV Formats

Before diving into conversion techniques, it's important to understand the fundamental differences between JSON and CSV formats and when to use each.

What is JSON?

JSON (JavaScript Object Notation) is a lightweight, text-based format designed for data interchange. It's human-readable and machine-parseable, making it the de facto standard for web APIs and configuration files.

JSON supports complex data structures including:

• Objects: Key-value pairs enclosed in curly braces
• Arrays: Ordered lists of values enclosed in square brackets
• Nested structures: Objects and arrays can contain other objects and arrays
• Multiple data types: Strings, numbers, booleans, null values

Here's a typical JSON example showing nested data:

{
  "employee": {
    "name": "Jane Smith",
    "details": {
      "age": 31,
      "email": "[email protected]"
    }
  },
  "department": "Finance",
  "projects": ["Budget 2026", "Audit Q1"]
}

What is CSV?

CSV (Comma-Separated Values) is a simple, flat file format used to store tabular data. Each line represents a row, and commas separate the columns. CSV files are universally supported by spreadsheet applications like Excel, Google Sheets, and data analysis tools.

Key characteristics of CSV:

• Flat structure: Two-dimensional rows and columns only
• Simple data types: Everything is treated as text or numbers
• Header row: First row typically contains column names
• Universal compatibility: Supported by virtually all data tools

The same employee data in CSV format:

employee_name,employee_age,employee_email,department
Jane Smith,31,[email protected],Finance

Format Comparison Table

Flattening JSON: The Core Challenge

The primary challenge in converting JSON to CSV is flattening JSON's potentially nested structure into CSV's flat, two-dimensional format. This process requires strategic decisions about how to represent hierarchical data in a tabular format.

Understanding Nested Structures

JSON can contain multiple levels of nesting, which don't have a direct equivalent in CSV. Consider this vehicle data example:

{
  "vehicle": {
    "model": "Sedan",
    "specs": {
      "engine": "V8",
      "transmission": "Automatic",
      "features": {
        "safety": ["ABS", "Airbags"],
        "comfort": ["AC", "Heated Seats"]
      }
    },
    "price": 25000
  }
}

This structure has three levels of nesting plus arrays. Converting it to CSV requires flattening these nested objects into a single row with multiple columns.

Flattening Strategies

There are several approaches to flattening nested JSON:

1. Dot Notation Flattening

The most common approach uses dot-separated paths to represent nested keys:

vehicle.model,vehicle.specs.engine,vehicle.specs.transmission,vehicle.price
Sedan,V8,Automatic,25000

This method preserves the hierarchical relationship in the column names while creating a flat structure.

2. Underscore Notation

Similar to dot notation but uses underscores for better compatibility with some systems:

vehicle_model,vehicle_specs_engine,vehicle_specs_transmission,vehicle_price
Sedan,V8,Automatic,25000

3. Array Handling

Arrays present a special challenge. Common approaches include:

• Separate rows: Create one row per array element (denormalization)
• Concatenation: Join array values with a delimiter (e.g., semicolon)
• Indexed columns: Create separate columns for each array index
• JSON string: Keep the array as a JSON string within the CSV cell

Handling Missing Fields

JSON objects in an array may have different fields. When converting to CSV, you need to account for missing fields:

[
  {"name": "Alice", "age": 30, "city": "NYC"},
  {"name": "Bob", "age": 25},
  {"name": "Carol", "city": "LA", "country": "USA"}
]

The resulting CSV should include all possible columns, with empty values where data is missing:

name,age,city,country
Alice,30,NYC,
Bob,25,,
Carol,,LA,USA

Conversion Methods Explained

There are multiple ways to convert JSON to CSV, each suited to different scenarios and skill levels. Let's explore the main approaches.

Online Conversion Tools

Online converters are the quickest solution for one-off conversions or when you don't want to write code. These tools typically offer a simple interface where you paste JSON and receive CSV output.

Advantages:

• No installation required
• Instant results
• User-friendly interface
• No programming knowledge needed

Limitations:

• File size restrictions
• Privacy concerns with sensitive data
• Limited customization options
• Not suitable for automation

Try our JSON to CSV Converter for quick, browser-based conversions with support for nested structures and custom delimiters.

Command-Line Tools

Command-line utilities are perfect for automation, batch processing, and integration into data pipelines.

Popular CLI tools include:

• jq: Powerful JSON processor with CSV output capabilities
• csvkit: Suite of utilities including in2csv for JSON conversion
• Miller: Multi-format data processing tool

Example using jq:

jq -r '.[] | [.name, .age, .city] | @csv' input.json > output.csv

Programming Libraries

For complex conversions or integration into applications, programming libraries offer the most flexibility and control.

We'll cover specific implementations in the next section.

Online Conversion Tools

Online JSON to CSV converters provide immediate solutions without requiring software installation. Here's what to look for in a quality converter.

Essential Features

A good online converter should offer:

• Nested object flattening: Automatic handling of multi-level JSON structures
• Array handling options: Choice between different array conversion strategies
• Custom delimiters: Support for semicolons, tabs, or custom separators
• Preview functionality: See results before downloading
• Error handling: Clear messages for invalid JSON
• Privacy protection: Client-side processing for sensitive data

When to Use Online Tools

Online converters are ideal for:

• Quick one-time conversions
• Testing JSON structure before automation
• Small to medium-sized files (typically under 10MB)
• Situations where you can't install software
• Learning how JSON flattening works

Recommended ConvKit Tools

ConvKit offers several related conversion tools that work seamlessly together:

• JSON to CSV Converter - Primary conversion tool with advanced flattening options
• CSV to JSON Converter - Reverse conversion when needed
• JSON Formatter - Validate and format JSON before conversion
• CSV Viewer - Preview and validate your converted CSV files

Programmatic Conversion Approaches

For recurring conversions, automation, or integration into applications, programmatic approaches offer the most flexibility and control.

Python Implementation

Python is the most popular language for data transformation tasks. Here's a comprehensive example using the pandas library:

import pandas as pd
import json

# Load JSON data
with open('data.json', 'r') as f:
    data = json.load(f)

# Convert to DataFrame (handles flattening automatically)
df = pd.json_normalize(data)

# Export to CSV
df.to_csv('output.csv', index=False)

# For nested arrays, use record_path
df = pd.json_normalize(
    data,
    record_path=['items'],
    meta=['id', 'name']
)
df.to_csv('output.csv', index=False)

The json_normalize() function automatically flattens nested structures using dot notation.

JavaScript/Node.js Implementation

For JavaScript environments, the json2csv library provides robust conversion capabilities:

const { Parser } = require('json2csv');
const fs = require('fs');

// Read JSON file
const jsonData = JSON.parse(fs.readFileSync('data.json', 'utf8'));

// Configure parser
const parser = new Parser({
  flatten: true,
  unwind: ['items'], // Handle arrays
  delimiter: ','
});

// Convert and save
const csv = parser.parse(jsonData);
fs.writeFileSync('output.csv', csv);

Java Implementation

For Java applications, libraries like Jackson and OpenCSV work well together:

import com.fasterxml.jackson.databind.ObjectMapper;
import com.opencsv.CSVWriter;

ObjectMapper mapper = new ObjectMapper();
List> data = mapper.readValue(
    new File("data.json"),
    new TypeReference>>(){}
);

CSVWriter writer = new CSVWriter(new FileWriter("output.csv"));

// Write headers
Set headers = data.get(0).keySet();
writer.writeNext(headers.toArray(new String[0]));

// Write data rows
for (Map row : data) {
    writer.writeNext(row.values().toArray(new String[0]));
}
writer.close();

Language Comparison

Handling Complex JSON Structures

Real-world JSON data often contains complex nested structures, arrays of objects, and inconsistent schemas. Here's how to handle these challenges effectively.

Deeply Nested Objects

When dealing with multiple levels of nesting, you need to decide how deep to flatten. Consider this e-commerce order example:

{
  "order": {
    "id": "ORD-001",
    "customer": {
      "name": "John Doe",
      "address": {
        "street": "123 Main St",
        "city": "Boston",
        "state": "MA",
        "zip": "02101"
      }
    },
    "items": [
      {
        "product": "Widget",
        "quantity": 2,
        "price": 19.99
      }
    ]
  }
}

Flattening strategy options:

Option 1: Full flattening - Create columns for every nested field:

order.id,order.customer.name,order.customer.address.street,order.customer.address.city,...

Option 2: Selective flattening - Flatten only to a certain depth and keep deeper structures as JSON strings:

order_id,customer_name,customer_address,items
ORD-001,John Doe,"{""street"":""123 Main St"",...}","[{""product"":""Widget"",...}]"

Option 3: Multiple CSV files - Create separate files for different entity types with foreign keys:

orders.csv:

order_id,customer_name
ORD-001,John Doe

order_items.csv:

order_id,product,quantity,price
ORD-001,Widget,2,19.99

Arrays of Objects

Arrays of objects are particularly challenging. Here are the main approaches:

1. Row Expansion (Denormalization)

Create one row per array element, repeating parent data:

order_id,customer_name,product,quantity,price
ORD-001,John Doe,Widget,2,19.99
ORD-001,John Doe,Gadget,1,29.99

This is the most common approach for relational data analysis.

2. Column Expansion

Create separate columns for each array index:

order_id,customer_name,item_0_product,item_0_quantity,item_1_product,item_1_quantity
ORD-001,John Doe,Widget,2,Gadget,1

This works only when arrays have a known maximum length.

3. Concatenation

Join array values with a delimiter:

order_id,customer_name,products,quantities
ORD-001,John Doe,"Widget;Gadget","2;1"

This preserves data in a single row but requires parsing later.

Handling Inconsistent Schemas

JSON arrays often contain objects with different fields. Your conversion process must handle this gracefully:

[
  {"id": 1, "name": "Alice", "email": "[email protected]", "age": 30},
  {"id": 2, "name": "Bob", "phone": "555-0100"},
  {"id": 3, "name": "Carol", "email": "[email protected]", "department": "Sales"}
]

Best practices:

• Union all fields: Create columns for all fields that appear in any object
• Use empty values: Leave cells empty (not "null" or "undefined") for missing fields
• Document schema: Keep track of which fields are optional
• Validate data: Check for unexpected fields that might indicate data quality issues

Common Conversion Pitfalls

Even experienced developers encounter issues when converting JSON to CSV. Here are the most common problems and how to avoid them.

Data Loss Issues

Problem: CSV doesn't support data types, so type information is lost during conversion.

Example: The number 007 becomes 7, and the boolean true becomes the string "true".

Solutions:

• Add type indicator columns if you need to convert back to JSON
• Use string formatting to preserve leading zeros: "007"
• Document data types in a separate schema file
• Consider using JSON strings for complex values that need type preservation

Special Character Handling

Problem: Commas, quotes, and newlines in data can break CSV structure.

Example: A description field containing Product, "Premium" quality will split incorrectly.

Solutions:

• Always quote fields containing special characters
• Escape quotes by doubling them: "Product, ""Premium"" quality"
• Consider using alternative delimiters (tabs, pipes) for data with many commas
• Use proper CSV libraries that handle escaping automatically

Encoding Problems

Problem: Character encoding mismatches cause corrupted text, especially with international characters.

Solutions:

• Always use UTF-8 encoding for both input and output
• Include a BOM (Byte Order Mark) for Excel compatibility: \ufeff
• Test with non-ASCII characters before processing large datasets
• Specify encoding explicitly in your code: encoding='utf-8'

Memory Issues with Large Files

Problem: Loading large JSON files into memory causes crashes or extreme slowness.

Solutions:

• Use streaming parsers that process data incrementally
• Process data in chunks rather than all at once
• Consider using database intermediaries for very large datasets
• Monitor memory usage and set appropriate limits

Column Order Inconsistency

Problem: JSON objects don't guarantee property order, leading to inconsistent column ordering across conversions.

Solutions:

• Explicitly define column order in your conversion code
• Sort columns alphabetically for consistency
• Use a schema definition to specify column order
• Keep a master column list for repeated conversions

Best Practices for JSON to CSV Conversion

Follow these best practices to ensure reliable, maintainable, and efficient JSON to CSV conversions.

Planning Your Conversion

Before writing any code or using tools, plan your conversion strategy:

1. Analyze the JSON structure: Understand nesting depth, array locations, and field consistency
2. Define your use case: Will the CSV be used for analysis, import, or archival?
3. Choose flattening strategy: Decide how to handle nested objects and arrays
4. Consider reversibility: Can you convert back to JSON if needed?
5. Document decisions: Record your flattening rules for future reference

Validation and Testing

Always validate your conversions:

• Validate input JSON: Ensure JSON is well-formed before conversion
• Check row counts: Verify expected number of rows in output
• Spot-check data: Manually verify a sample of converted records
• Test edge cases: Include null values, empty arrays, special characters
• Verify encoding: Check that international characters display correctly

Performance Optimization

For large-scale conversions, optimize performance:

• Use streaming: Process data incrementally rather than loading everything into memory
• Batch processing: Split large files into smaller chunks
• Parallel processing: Use multiple threads or processes for independent records
• Efficient libraries: Choose libraries optimized for performance (e.g., orjson for Python)
• Profile your code: Identify bottlenecks and optimize hot paths

Maintaining Data Quality

Ensure high-quality output:

• Handle missing data consistently: Use empty strings, not "null" or "undefined"
• Preserve precision: Don't lose decimal places in numeric conversions
• Normalize data: Apply consistent formatting (dates, phone numbers, etc.)
• Remove duplicates: Check for and handle duplicate records
• Add metadata: Include conversion timestamp and source information

Documentation Standards

Document your conversion process thoroughly:

• Schema mapping: Document how JSON paths map to CSV columns
• Transformation rules: Explain any data transformations applied
• Known limitations: Document what data might be lost or transformed
• Example conversions: Provide before/after examples
• Version control: Track changes to conversion logic over time

Real-World Use Cases

Understanding practical applications helps you apply the right conversion techniques for your specific needs.

API Response Analysis

Scenario: You're analyzing API responses from a REST service to identify trends and patterns.

Challenge: API responses contain nested user data, timestamps, and arrays of related objects.

Solution:

• Use row expansion for arrays to create one row per item
• Flatten user objects with dot notation
• Convert timestamps to readable date formats
• Import into Excel or data analysis tools for visualization

This approach works well with our JSON to CSV Converter which handles nested structures automatically.

Database Migration

Scenario: Migrating data from a NoSQL database (MongoDB) to a relational database (PostgreSQL).

Challenge: NoSQL documents have flexible schemas and nested structures that need to fit into normalized tables.

Solution:

• Export collections as JSON
• Create separate CSV files for parent and child entities
• Use foreign keys to maintain relationships
• Import CSVs into relational database tables

Data Warehouse ETL

Scenario: Loading JSON event logs into a data warehouse for business intelligence.

Challenge: