CSV headers explained: why the first row matters
CSV → JSON usually treats the first row as headers. Those header cells become JSON keys, so header quality directly affects output quality.
How headers map to JSON
A CSV row is a list of values. Without headers, there are no stable names. When you use the first row as headers, each column gets a key and each subsequent row becomes an object.
Common header problems
- Empty header cells: lead to missing keys. Rename to col_3 etc.
- Duplicate headers: later values overwrite earlier ones in objects.
- Whitespace: “ name ” vs “name” creates inconsistent keys.
Practical fixes
- Trim headers.
- Rename empty/duplicate header cells.
- Re-export from the source system if possible (cleaner than manual edits).
Practical checklist (fast)
If you’re stuck, use this quick checklist to narrow the problem before you try “random fixes”. Start by validating the input format (syntax first), then confirm shape expectations (array vs object, headers vs rows). Convert a small sample, inspect the output, and only then export the full result.
- Validate: confirm the input is strict JSON/XML/CSV (no stray characters).
- Confirm shape: arrays vs objects; headers vs row lengths; repeated tags vs arrays.
- Test a sample: first 20–50 rows/items are enough to detect parsing issues.
- Export: copy/download the output and re-check it in the consumer (script/spreadsheet/API).
This workflow is privacy-first by design: All processing happens locally in your browser. Files are never uploaded.
Practical checklist (fast)
If you’re stuck, use this quick checklist to narrow the problem before you try “random fixes”. Start by validating the input format (syntax first), then confirm shape expectations (array vs object, headers vs rows). Convert a small sample, inspect the output, and only then export the full result.
- Validate: confirm the input is strict JSON/XML/CSV (no stray characters).
- Confirm shape: arrays vs objects; headers vs row lengths; repeated tags vs arrays.
- Test a sample: first 20–50 rows/items are enough to detect parsing issues.
- Export: copy/download the output and re-check it in the consumer (script/spreadsheet/API).
This workflow is privacy-first by design: All processing happens locally in your browser. Files are never uploaded.
FAQ
What if my CSV has no header row? You can generate column names (col_1, col_2...) or add headers manually.
Why do my JSON keys look weird? Encoding/BOM or hidden characters in the header row can corrupt keys.
Trust note: All processing happens locally in your browser. Files are never uploaded.
Local verification snippet
Run a quick local check before export/convert:
import csv
from io import StringIO
sample = text[:50000] # keep first chunk for fast local triage
rows = list(csv.reader(StringIO(sample)))
print('rows:', len(rows), 'columns(first row):', len(rows[0]) if rows else 0)