json2csv

Convert JSON files to structured CSV tables with automatic nested flattening.

Place .json files in the input/ folder, run the script, and get clean .csv tables in the output/ folder — one CSV per input JSON.

Features

• Nested objects → flattened with underscore notation
  • {"address": {"city": "Jakarta"}} becomes column address_city
• Arrays of objects → parent rows are duplicated for each element (expands downward, not sideways)
  • {"siblings": [{"name": "Jaka"}, {"name": "Raka"}]} creates 2 rows
• Multiple JSON formats supported
  • Standard JSON array: [{...}, {...}]
  • Single object: {...}
  • JSON sequence: {...},{...},{...} (objects separated by commas, no brackets)
• Batch processing — all .json files in the input folder processed at once
• Zero external dependencies — uses only Python standard library (json, csv, os, argparse)

Quick Start

CLI

# Process all JSON files in input/ → output CSVs in output/
python json2csv.py

# Custom directories
python json2csv.py --input ./data --output ./results

# Process a single file
python json2csv.py --file mydata.json

Docker

# Build the image
docker build -t json2csv .

# Run (mount local input/output directories)
docker run --rm -v "%cd%/input:/app/input" -v "%cd%/output:/app/output" json2csv

# Process a single file with Docker
docker run --rm -v "%cd%/input:/app/input" -v "%cd%/output:/app/output" json2csv --file mydata.json

Note: For Linux/Mac, replace %cd% with $(pwd).

Example

Input (input/example_nested.json)

{
  "id": 1,
  "name": "Budi",
  "siblings": [
    {"num": 1, "name": "Jaka", "age": {"years": 10, "months": 5}},
    {"num": 2, "name": "Raka", "age": {"years": 8, "months": 3}}
  ]
}

Output (output/example_nested.csv)

id,name,siblings_num,siblings_name,siblings_age_years,siblings_age_months
1,Budi,1,Jaka,10,5
1,Budi,2,Raka,8,3

Notice how:

• age (nested object) becomes siblings_age_years and siblings_age_months
• Each sibling creates a new row with the parent data (id, name) duplicated

Command Line Options

Flag	Short	Description	Default
--input	-i	Input directory containing JSON files	input
--output	-o	Output directory for generated CSV files	output
--file	-f	Process a single specific file	All .json files

Project Structure

json2csv/
├── input/                  # Place .json files here (user data is gitignored)
│   ├── example_simple.json # Example: flat JSON with array of strings
│   ├── example_nested.json # Example: nested objects + array of objects
│   └── .gitkeep
├── output/                 # Generated .csv files appear here
│   ├── example_simple.csv  # Example output (git-tracked)
│   ├── example_nested.csv  # Example output (git-tracked)
│   └── .gitkeep
├── json2csv.py             # Main conversion script
├── Dockerfile              # Docker container build
├── requirements.txt        # Documentation only (no dependencies)
├── .gitignore              # Ignores user data + generated CSVs
├── plan.md                 # Design document & implementation checklist
└── README.md               # This file

License

MIT