Skip to main content

Should I Use CSV or JSON?

Use CSV for a flat, consistently tabular dataset that people or spreadsheet tools need to exchange. Use JSON when records are nested, fields vary, types such as booleans matter, or an API needs structured objects and arrays.

Choose a format from the shape of the data

RequirementCSV fitJSON fit
Flat rectangular tableStrongWorks but repeats keys
Nested records or arraysNeeds a conventionNative
Durable explicit typesExternal schema neededSome native types; schema still useful
Spreadsheet handoffOften convenientUsually needs import/transform
Web API payloadPossible for bulk dataCommon and expressive

Choose based on data shape before file size

CSV naturally expresses rows and columns. It is compact and familiar, but conventions vary around delimiters, character encodings, line endings, headers, nulls, and type inference. A nested address, a list of tags, or a record with optional sub-objects must be flattened, repeated, or encoded inside a field, which shifts complexity into undocumented conventions.

JSON provides objects, arrays, strings, numbers, booleans, and null. It can represent nesting directly and is a common fit for web APIs. It is more verbose because property names repeat, and JSON numbers do not by themselves preserve decimal precision or distinguish integer widths. Neither format supplies a business schema automatically; document required fields, units, identifiers, date formats, and null behavior.

Interoperability includes the consumer workflow

A format is useful only if the receiving system interprets it correctly. CSV is often easier for a data analyst to inspect, while newline-delimited JSON may be easier for a streaming pipeline than one huge JSON array. Test with the exact importer, locale, and character encoding. For sensitive or untrusted data, account for spreadsheet formula execution, oversized fields, deep JSON nesting, and resource limits.

Test the format against the whole workflow

  • Sketch the real data shape, including repeated and optional values.
  • List consumers and determine which format each can parse without manual repair.
  • Define encoding, schema, date and number conventions, null behavior, and maximum sizes.
  • Test a round trip with commas, quotes, line breaks, Unicode, empty values, and large identifiers.

One customer with multiple tags

Every CSV option needs a documented rule. If the consumer expects one row per customer and tags are truly multi-valued, JSON preserves the shape more directly.

JSON: {"id":"0012","tags":["trial","email"]}
CSV options: repeat rows, add tag columns, or encode a list in one cell

Trade-offs that are easy to overlook

  • Do not embed ad hoc JSON inside one CSV column unless every consumer understands that second parsing layer.
  • JSON object member order should not carry business meaning, and duplicate member names are not interoperable.
  • CSV’s visual simplicity can hide inconsistent row lengths, delimiters, encodings, and inferred spreadsheet types.

Use the decision in context

Apply the choice with the CSV Viewer. Compare the neighboring decision in leading zeros in CSV data.

Why Is Valid-Looking JSON Rejected?

JSON is usually rejected because its actual bytes violate the grammar, even when the text looks plausible: common causes are smart quotes, trailing commas, raw control characters, invalid numbers, or a JSON string mistaken for a JSON object.

CSV and JSON selection questions

Is CSV always smaller than JSON?

Often for flat data, but compression, repeated values, field names, and representation choices determine the actual result. Measure representative files.

Can JSON represent dates exactly?

JSON has strings and numbers but no dedicated date type. Use a documented string format and time-zone convention, commonly an RFC 3339 timestamp.

Standards to check before deciding