# JSON to CSV Converter

> Turns a JSON object, an array of objects or an array of arrays into a UTF-8 CSV or tab-separated file. It can flatten nested object paths, protects formula-like spreadsheet cells by default, and never uploads the source.

Use it: https://tessalor.com/en/data/json-to-csv

This tool runs entirely in the browser. Nothing entered into it is uploaded.

## How it is done

1. Decode the file as UTF-8, discard a leading UTF-8 marker when present, and parse it with the browser's built-in JSON parser. Empty or syntactically invalid input is refused with the parser's reason.
2. Decide the row model from the top level. One object is one row; an array of objects is many named rows; an array of arrays is many positional rows. Mixed row shapes are refused rather than guessed.
3. For object rows, collect the union of keys in first-seen order so a field that appears only in a later record still gets one stable column and earlier rows get an empty cell there.
4. When flattening is selected, walk nested objects into escaped dot paths such as profile.city. Keep arrays as JSON in one cell because their length is data, not a dependable set of columns.
5. Render null or a missing field as an empty cell, booleans and numbers as JSON values, strings as text, and any remaining object or array as compact JSON.
6. When formula protection is on, prefix string cells and headings whose first meaningful character is =, +, - or @ with an apostrophe. Real JSON numbers, including negative numbers, remain numeric.
7. Double every quote inside a field and wrap a field in quotes when it contains the chosen separator, a quote or a line break. End every row with CRLF as the CSV convention specifies.
8. Add the optional three-byte UTF-8 marker, encode the complete text, and offer .csv for comma or semicolon output or .tsv for tabs. Nothing is sent away at any point.

## Assumptions

- Supported top-level shapes are one object, an array containing only objects, or an array containing only arrays. A primitive, an empty array or a mixture of row shapes has no unambiguous table and is refused.
- Object columns are the union of keys across every row, ordered by the first appearance of each key. Missing and null are both empty CSV cells because CSV has no distinct null value.
- Flattening descends through objects only. Arrays remain compact JSON in one cell; expanding list positions would let one unusually long row create thousands of columns and would pretend position means the same thing in every record.
- A literal dot or backslash inside a JSON key is escaped with a backslash before path segments are joined, so a key named profile.city cannot collide with the nested path profile then city.
- Formula protection applies only to JSON strings and column names. A typed JSON number such as -2 stays -2; the string "-2" is prefixed because a spreadsheet decides cell type from the CSV text.
- The UTF-8 marker is enabled by default for older Excel versions. It adds the three bytes EF BB BF and no row or column data; other spreadsheet and database tools normally tolerate it.
- Comma and semicolon output use the .csv extension. A tab separator uses .tsv and the text/tab-separated-values MIME type rather than labelling tabular data as comma-separated.
- Input is capped at 20 MB, at 500,000 rows and 5,000 columns. The rendered text is capped at 64 million characters so one expansion cannot exhaust the tab's memory.

## Inputs

| Name | Label | Type | Default | Range |
| --- | --- | --- | --- | --- |
| `source` | JSON file | file | chosen on your device | application/json, text/json, up to 20 MB |
| `nestedMode` | Nested objects and arrays | select | stringify |  |
| `delimiter` | Column separator | select | , |  |
| `formulaProtection` | Protect spreadsheet formula cells | toggle | true |  |
| `bom` | Add an Excel UTF-8 marker | toggle | true |  |

## Outputs

- `rows` — Rows written (integer), primary
- `columns` — Columns written (integer)
- `inputShape` — Input shape (text)
- `fileBytes` — Output size (bytes) (integer)

## Questions

### Is the JSON file uploaded before it becomes CSV?

No. A worker in this browser tab decodes the file, parses the JSON, builds the rows and encodes the download. The browser test for this page loads a real fixture and fails if any request leaves the site while the file is present.

### What happens when later JSON objects have different keys?

Every key gets one column in the order it first appears. Earlier or later records that do not carry that key get an empty cell, so values never slide into the wrong heading merely because one object omitted a field.

### Why is there an apostrophe before some spreadsheet cells?

Text beginning with =, +, - or @ can be interpreted as a formula when a CSV is opened in spreadsheet software. Formula protection prefixes those strings with an apostrophe so untrusted exported data remains text. Turn it off only when the formulas are deliberate and the source is trusted.

### Why does flattening leave a JSON array in one cell?

An object's key is schema; an array's length and order are data. Expanding array positions would let one long list widen the whole file and would imply that item zero has the same meaning in every row. Keeping the array as JSON preserves it without inventing that claim.

### Should I choose comma, semicolon or tab?

Comma is the interoperable CSV default. Semicolon is useful in locales where the comma is a decimal mark and spreadsheet software expects a semicolon list separator. Tab is best when the text contains many commas and produces an honestly named TSV file.

### What is the Excel UTF-8 marker and do I need it?

It is the three-byte sequence EF BB BF at the beginning of the file. It helps older Excel versions recognise UTF-8 without an import dialog, so names and non-Latin scripts open correctly. Modern data tools usually do not need it, and the advanced toggle can omit it.

## Sources

- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://www.rfc-editor.org/rfc/rfc8259) — Internet Engineering Task Force, applies to 2017. Retrieved 2026-08-01.
- [RFC 4180: Common Format and MIME Type for Comma-Separated Values Files](https://www.rfc-editor.org/rfc/rfc4180) — Internet Engineering Task Force, applies to 2005. Retrieved 2026-08-01.
- [CSV Injection](https://owasp.org/www-community/attacks/CSV_Injection) — OWASP Foundation. Retrieved 2026-08-01.
- [Opening CSV UTF-8 files correctly in Excel](https://support.microsoft.com/en-us/office/opening-csv-utf-8-files-correctly-in-excel-8a935af5-3416-4edd-ba7e-3dfd2bc4a032) — Microsoft. Retrieved 2026-08-01.

## Variants

- [How do I convert a JSON array to CSV for Excel?](https://tessalor.com/en/data/json-to-csv/json-array-to-csv-for-excel)
- [How do I flatten nested JSON into CSV columns?](https://tessalor.com/en/data/json-to-csv/flatten-nested-json-to-csv)

---

Estimate, not advice. See https://tessalor.com/en/disclaimer.
Machine-readable catalogue: https://tessalor.com/api/tools.json