What is CSV?

A rectangle of text

CSV represents one table: an optional header row of column names, then one line per record with fields separated by commas. That is the whole model. It has no types, no nesting, no metadata, and no way to describe more than one table in a file.

Its reach is the reason to care about it. Every spreadsheet, database, and analytics tool imports CSV, which makes it the practical export format when a non-programmer needs to open your data.

id,status,total
ord_101,paid,129.5
ord_102,failed,42

Only a flat array of objects converts cleanly

Because CSV is a rectangle, converting JSON to CSV requires a JSON array of objects with consistent keys — that array is the table, each object is a row, and the union of keys is the header. The nested document used elsewhere in these articles has an object at the root wrapping an array, so it has no single obvious table.

When your data is nested, either point the converter at the array you actually want as a table, or flatten first. A converter that silently picks one array for you is guessing at which part of the document you meant.

Quoting, and the dialect problem

RFC 4180 sets out the common rules: fields containing a comma, a double quote, or a line break are wrapped in double quotes, and an embedded double quote is escaped by doubling it. A field can legally contain a newline, which is why splitting a CSV file on line breaks is a bug rather than a shortcut.

In practice the standard is advisory. Separators vary by locale — semicolons are common where the comma is a decimal mark — and encodings, line endings, and leading byte-order marks all differ between producers. CSV is best understood as a family of dialects rather than one format.

Everything is a string

CSV has no type system, so 42, 0042, and 4.2e1 are three strings until a consumer decides otherwise — and consumers decide differently. Spreadsheets are the most aggressive: a leading zero is commonly stripped, a value shaped like a date is reformatted, and a long numeric identifier can be rewritten in scientific notation. Converting CSV back to JSON means re-inferring the types that the CSV conversion discarded.