JSON Lines
Community convention for line-delimited JSON
JSON Lines, also written as JSONL, is a text format for storing structured data in which each line of a file is a complete, independent JSON value, typically an object. It is used to represent sequences of records, such as log entries or…
Definition
JSON Lines, also written as JSONL, is a text format for storing structured data in which each line of a file is a complete, independent JSON value, typically an object. It is used to represent sequences of records, such as log entries or streaming data, without wrapping the whole collection in an outer JSON array. Its main advantage over a single large JSON array is that files can be read, written, and processed one line at a time.
Overview
Standard JSON represents a collection of records as a single array, which means a parser generally must read the entire structure into memory before it can access any individual record, and appending a new record requires rewriting the closing bracket and inserting a comma. JSON Lines solves this by dropping the enclosing array entirely: each line stands alone as a complete JSON value, so records can be processed and appended independently. Mechanically, a JSON Lines file is just a plain text file where each line, separated by a newline character, contains one valid JSON value with no trailing comma and no surrounding array brackets. A reader can process the file by reading one line at a time, parsing that line as JSON, and moving to the next, which means memory usage stays constant regardless of file size and a writer can append new records simply by writing another line at the end of the file. JSON Lines differs from a JSON array in exactly this streamability, and it differs from CSV in that each line can hold arbitrarily nested and typed structures rather than being limited to flat rows of strings. It is closely related to formats used for columnar big-data storage, but those formats optimize for compact binary storage and fast columnar queries, whereas JSON Lines optimizes for simplicity, human readability, and streaming line-by-line access at the cost of larger file sizes and no built-in schema. In practice, JSON Lines is common as the output format for log aggregation pipelines, as an interchange format for machine learning training datasets where each line is one labeled example, and as a format for streaming API responses where a client wants to start processing records before the full response has arrived. Command-line tools and data-processing libraries widely support reading and writing it directly because its line-oriented structure maps naturally onto standard text-processing tools. Its main limitation is the lack of a shared schema or type enforcement across lines, meaning consumers must validate structure themselves if a guarantee of a consistent shape is important. It also carries more overhead per record than compact binary formats designed for high-volume storage, so very large, performance-critical datasets often convert JSON Lines into a columnar binary format for long-term storage while still using JSON Lines as the human-readable interchange or logging format at the edges of a pipeline. Pairing it with a schema definition language addresses the validation gap directly, letting a pipeline enforce a consistent record shape while still keeping the simplicity of a line-oriented text file for everyday inspection and debugging.
Specification
- Each line is an independent, self-contained JSON value
- No enclosing array brackets or trailing commas needed
- Supports constant-memory streaming, line-by-line processing
- New records can be appended without rewriting the file
- Human-readable and directly compatible with text-processing tools
- Common in logging, ML datasets, and streaming API responses
Use Cases
Alternatives
Frequently Asked Questions
From the Blog
Working With JSON in Python
Python's json module converts between JSON text and Python objects with four core functions. Learn to parse, create, read, and write JSON with practical examples.
Read More ProgrammingJavaScript Objects and JSON Explained
JavaScript objects store data as key-value pairs, and JSON is a text format for exchanging that data. Learn how they relate, differ, and convert between each other.
Read More ProgrammingPython File I/O: Reading and Writing Files
Almost every real Python program reads or writes files — logs, configs, CSVs, JSON, reports. This guide covers text files, CSV, JSON, binary files, and the modern pathlib approach, with best practices for safe file handling.
Read More ProgrammingBuilding REST APIs With Node.js and Express
Build a REST API with Node.js and Express by defining routes, handling JSON, and returning proper status codes. Here is how to structure one from scratch.
Read More