JSONL vs JSON: when to use each

A normal JSON file must parse as one JSON value. For tabular data, that value is often an array of objects: [ {"id": 1}, {"id": 2} ]. The reader usually needs the complete syntax to be valid before it can parse the document.

A JSONL file contains separate JSON values separated by newlines: one object, array, string, or other JSON value per line. In practice, most JSONL datasets use one object per line. The file as a whole is not a single JSON array unless a tool treats it specially.

JSONL is easy to append. A service can write one event at a time without reopening a large array and adding commas. A downstream processor can read line by line, recover after a bad line, and split files by byte ranges more easily than with one giant JSON document.

This is why JSONL appears in model training data, application logs, database exports, search indexes, and event pipelines. It favors streaming operations over document nesting.

The most common JSONL mistake is wrapping all rows in [ and ], which turns it back into JSON. The most common JSON mistake is concatenating objects with no array or commas, which is invalid JSON but may be valid JSONL if each object is on its own line.

Blank lines are another choice. Some parsers ignore them; stricter tools reject them because an empty line is not valid JSON. If you control the export, write exactly one JSON object per line and end the file with a final newline for Unix tooling.

JSON array to JSONL is straightforward when the array contains records. Each element becomes one line. JSONL to JSON wraps records in an array and inserts commas. Memory use can become an issue if a huge JSONL file is collected into one JSON array.

Nested data remains nested in either format. If the target is CSV, a separate flattening step is needed. Arrays, objects, and missing keys need explicit conventions before exporting to rows and columns.

Use JSON for API responses, config files, and data documents where the whole structure matters. Use JSONL for streams, logs, queues, and bulk exports where records can be processed independently.

For spreadsheet users, neither JSON nor JSONL is ideal unless the structure is flat. Convert to CSV or XLSX after deciding which nested fields should become columns.

File size changes the best choice. A small settings file should be one JSON document because it is easier to validate as a whole. A multi-gigabyte event export should usually be JSONL because tools can stream, split, compress, and retry record by record.

For command-line processing, JSONL also fits Unix text habits. You can sample with head, count lines with wc -l, and process batches without parsing the entire dataset. That convenience depends on the rule that records do not contain literal unescaped newlines outside JSON strings.

Compression works well with both formats, but access patterns differ. A compressed JSONL file can still be processed as records when the tool streams decompression. A compressed JSON array still has to respect the single-document grammar during parsing.

A final export contract should name the format explicitly as JSON or JSONL. Many failures come from a producer sending newline-delimited records to a consumer that expected one array, or the reverse.