CSV to JSON — headers, types, and edge cases

CSV (comma-separated values) is a table as text: rows separated by newlines and fields separated by a delimiter—usually a comma, sometimes a tab (TSV) or semicolon. JSON is a tree: objects, arrays, strings, numbers, booleans, and null. Converting between them is mostly mechanical, but the details matter because CSV carries almost no type information and no standard object shape beyond “a grid of strings.”

Headers — who names the keys?

If the first row is a header row, each subsequent row becomes a JSON object whose keys come from those header cells.

• Stable headers: Prefer short, unique names without spaces if you control the export (customer_id rather than Customer ID). Duplicate header names collide: many tools keep the last occurrence or append suffixes—know your converter’s rule before you rely on it.
• No header row: Some pipelines treat every row as an array of strings (["a","b"]), or synthesize keys like column_0, column_1. That is valid JSON, but it is easy to misalign if someone later adds a header line by hand.
• Human-edited CSV: Extra spaces in header cells (" Name ") become part of the key unless the tool trims them. Decide whether trimming is part of your contract.

Types — CSV is strings until you say otherwise

In strict CSV, every field is text. A cell 42 is the two characters 4 and 2, not the JSON number 42, until a layer coerces types.

Common coercion pitfalls:

• Leading zeros: 007 might become the number 7 in a naive converter. If IDs or postal codes must keep leading zeros, keep them as strings (or quote them in CSV and disable numeric coercion).
• Booleans: true, false, yes, no are all ambiguous patterns; locale and casing differ. Either define an explicit mapping or leave everything as strings in JSON and let downstream code parse.
• Dates: 01/02/2026 is meaningless without knowing MDY vs DMY. Prefer ISO 8601 in the source (2026-01-02) or store dates as strings and parse with an explicit format.
• Empty cells: Often become "" or null depending on settings. Pick one convention for APIs and tests so "" and missing values do not mean different things in different environments.
• Decimals and thousands separators: 1,234.56 vs 1.234,56 will break naive number parsing. Again, treat as string until you know the locale.

For many workflows, “all string values in JSON” is the safest first step; add typing in application code where you know the schema.

Edge cases that break naïve split-by-comma

• Quoted fields and embedded commas: A single field can contain commas if wrapped in double quotes. Newlines can appear inside quoted fields—line-based splitting without a real CSV parser will corrupt the grid.
• Escaped quotes: Inside quotes, "" represents one literal " character.
• Different delimiters: European exports often use ; when comma is the decimal separator. Auto-detection helps, but verify on a sample row.
• Uneven row lengths: If one row has fewer columns than the header, some tools pad with empty strings; others drop or error. Uneven extra columns may be truncated or preserved—check behavior before piping into a strict schema.
• BOM (byte order mark): A UTF-8 BOM at the start of the file can make the first header look like \ufeffid instead of id. Strip BOM or configure the parser to ignore it so keys match what you expect.
• Trailing blank lines: Exporters often add a final newline; “empty” rows may or may not be skipped. Greedy skipping of empty lines is usually what you want for data files, but not always for intentionally sparse tables.

When JSON is the better interchange format

Choose JSON when you need nested structures, explicit types, a single obvious document root, or schema validation. CSV stays excellent for flat snapshots, spreadsheets, and huge row counts where a streaming row model wins.

Try it locally in your browser

Use the CSV to JSON tool to paste or upload CSV, toggle header handling, and copy JSON—all on your machine. To inspect or pretty-print JSON afterward, open the JSON Formatter & Validator.

Related reading

• What is JSON? for how JSON types and syntax differ from CSV’s implicit model.
• Minifying JSON safely when you need compact JSON after conversion.