Guides / Empty result sets

Empty JSON Array to CSV: Keep the Header, Write No Data Row

Zero records still need an export contract

A search endpoint can return an empty array because a filter matched no records. The array tells you the result count, but it contains no object from which to discover field names. The receiving system may still expect a header even when nothing matched. Keep the schema separately from the returned records.

This guide assumes that your receiving contract has already declared two columns, id and text. Those names are an explicit example, not information inferred from the empty array. An exporter that invents a column called value, or creates one empty object, changes the contract rather than solving the missing-schema problem.

Our executed empty fixture

Input JSON: []
Declared fields: ["id", "text"]
Saved CSV, escaped: 'id,text\r\n'
Parsed records: [["id", "text"]]
Data records after the header: 0

Executed on 2026-10-20 with Python 3.12.14. The saved file contains only the header record. A strict CSV read-back recovered exactly that two-field header. The trailing record terminator is not a fabricated empty data record.

writer.writerow(["id", "text"])
writer.writerows([])

Python's CSV writer reference describes writerow and writerows; our code supplies the schema before iterating over the input. RFC 8259, section 5 allows an array with no elements. Neither source specifies your application's CSV header policy, so we state that policy explicitly here.

Do not silently treat every empty-looking input as []

We executed these rejection cases before publication. They failed before creating an output file. In particular, one empty object is one source element, so accepting it as zero records would conceal an input problem. A different application may allow missing fields, but it must specify that separately.

Reproduce the local example

These are independent Python examples, not measurements of the browser converter. Download the input, exporter, saved CSV and execution evidence into one folder. Use Python 3.12 or later and a new output filename.

python explicit-id-text-export.py empty-array-input.json new-result.csv

The demonstration contract has exactly two string fields, id and text. It rejects missing or extra keys, non-string values, duplicate object keys, invalid UTF-8 and nonstandard JSON constants. It reads at most 1,000,001 bytes and rejects inputs over the 1,000,000-byte demonstration policy. That limit is a code policy, not a measured browser limit. Arrays, nested objects and automatic type conversion are outside this example.

The output uses UTF-8 and CRLF record endings. Exclusive file creation prevents overwriting an existing file. A disk error may leave a partial file; inspect the error before trying a new filename. Faithful text conversion does not neutralize spreadsheet formulas, so use a suitable text import workflow for untrusted data.

How should a consumer count this file?

Parse CSV records, validate the first record against the expected schema, then count the remaining records. In this example the remaining count is zero. Do not require a dummy row of empty strings: it would become a record that never existed in the source. If your downstream importer refuses a header-only file, handle its empty-result path explicitly.

An empty result set differs from an empty field inside an existing record. This page solves only the former. For the latter, see null, missing and empty field states. For a nonempty export, verify every row and field before accepting the result.

A simple handoff checklist

Record the expected column names, confirm the source really is an array, save a header-only output when its length is zero, and tell the recipient that the result has zero data records. An empty query result is not automatically a conversion error; silently manufacturing a row is not a faithful workaround.

The workflow in three original diagrams