How to convert JSON to CSV (and back) without losing data

JSON and CSV are the two workhorse formats of data work, and converting between them looks trivial right up until a field contains a comma, an object nests three levels deep, or Excel opens your file and mangles every non-ASCII character. This guide covers what actually goes wrong and the rules that prevent it — plus a free converter that handles all of it locally in your browser.

What the conversion actually involves

CSV is a rectangular table: rows and columns, nothing else. JSON is a tree: objects inside objects, arrays, mixed types. Converting JSON to CSV therefore means deciding how to flatten a tree into a grid, and converting CSV to JSON means deciding how to grow a grid into a tree. Every converter makes these decisions slightly differently, which is why the same JSON can produce different CSVs in different tools — and why understanding the three decisions below will save you an afternoon of confused spreadsheets.

Rule 1 — quoting beats escaping

The CSV specification (RFC 4180) says a field containing a comma, a double quote, or a line break must be wrapped in double quotes, and any quote inside the field is doubled. A value like Say "hello", then leave becomes "Say ""hello"", then leave". Converters that skip this produce files that open fine in one program and explode in another. When you evaluate any converter, test it with a comma, a quote and a newline in the same field before trusting it with real data.

Rule 2 — flattening nested objects

A nested JSON object becomes multiple columns by joining the key path with a separator, conventionally a dot. The object {"user": {"name": "Ana", "plan": "pro"}} yields columns user.name and user.plan. This preserves all the information while keeping the table readable. The deeper alternative — JSON inside a CSV cell — is technically possible and practically awful, because it hides the data from every spreadsheet user and most analysis tools.

Rule 3 — arrays are the hard part

Arrays do not fit tables naturally, and every tool picks one of three strategies. Joining turns ["a", "b"] into a single cell "a; b" — compact, but you lose structure. Expanding turns one record with a 3-item array into three rows, repeating the other columns — analysis-friendly, but row counts lie about record counts. Indexing creates tagged.0, tagged.1 columns — predictable, but wide data. None is universally right; just make sure you know which one your converter uses before you count anything.

Numbers, nulls and types

JSON carries types; CSV does not. After a round trip, the number 1, the string "1" and the boolean true all look like a bare 1 in a cell, and null becomes an empty field indistinguishable from an empty string. Serious converters type-cast numbers and booleans on the way back to JSON and document that nulls arrive as empty cells; hand-rolled scripts usually return everything as strings, which silently breaks downstream code that compares or sums. If exact types matter to your pipeline, verify them on a small sample before converting the real dataset.

The Excel trap: encoding and line endings

Two boring failures account for most "my CSV is broken" reports. First, encoding: Excel assumes legacy encodings unless your file starts with a UTF-8 BOM, so accented characters and non-Latin scripts turn to garbage; a good converter writes UTF-8 with BOM, or you import via Excel's Data-from-Text dialog and pick UTF-8 explicitly. Second, line endings: RFC 4180 wants CRLF, and some libraries emit bare LF that older parsers mishandle. If a file opens perfectly everywhere except one ancient internal tool, line endings are the prime suspect.

Converting CSV back to JSON

The reverse direction is gentler: the header row becomes keys, each data row becomes an object, and everything arrives as a string unless the converter type-casts numbers and booleans (good ones do, and say so). Watch for header rows with duplicate or empty column names — they produce objects with colliding keys — and for files where someone hand-edited the CSV and broke the quoting. The ToolFolio JSON-CSV converter handles both directions in your browser with proper quoting and dot-notation flattening, free and with no upload of your data to anyone.

Questions people ask