Handling JSON Lines Format in Specialized Formatters

JSON Lines is not a single pretty-printed JSON document. It is a sequence of separate JSON values written one per line, usually for logs, exports, and streaming pipelines. That is why a normal JSON formatter often fails on line 2, while a formatter with JSONL or NDJSON support can validate and normalize the file correctly.

For search users landing here directly, the key idea is simple: a specialized formatter should treat each physical line as its own JSON payload, report errors by line number, and avoid reformatting records into multi-line blocks unless it is explicitly converting the file into standard JSON first.

JSON Lines, JSONL, and NDJSON

In practice, people often use JSON Lines, JSONL, and NDJSON interchangeably. They all describe line-delimited JSON data, but the naming conventions you see in tools and APIs can differ.

That means a capable formatter should not care whether the file is called events.jsonl or events.ndjson. It should care about whether the content actually follows the one-value-per-line rule.

What Makes a JSON Lines File Valid

The rules are stricter than many articles suggest. A valid JSON Lines or NDJSON file is not just “lots of JSON objects separated by Enter.”

{"id":1,"name":"Apple"}
{"id":2,"name":"Banana"}
null
[1,2,3]

{
  "id": 1,
  "name": "Apple"
}
{"id":2,"name":"Banana"}

Why Standard JSON Formatters Fail

A standard formatter expects one JSON document from the first byte to the last. JSON Lines gives it multiple top-level JSON values back to back, so the parser usually accepts the first line and then throws an “extra data” or “unexpected token” style error when it encounters the second line.

[
  {"id":1,"name":"Apple"},
  {"id":2,"name":"Banana"}
]

{"id":1,"name":"Apple"}
{"id":2,"name":"Banana"}

What a Specialized Formatter Should Actually Do

The useful behavior is not “pretend this is normal JSON.” It is to parse, validate, and rewrite records safely without destroying the line-delimited structure.

• Split the input on newlines and inspect each non-empty line independently.
• Parse each line as a complete JSON value.
• Report exact line numbers for failures instead of stopping with a generic document-level error.
• Normalize whitespace inside each record and usually write it back as one compact line.
• Preserve record order so log streams and exports remain meaningful.
• Offer a separate “convert to array” view when a human wants classic multi-line pretty-printing.

That last point matters. If a formatter expands one record into several physical lines and saves it as-is, the result is no longer valid JSON Lines. Pretty display mode is fine in an interface, but the exported file still needs one complete JSON value per line.

Best Formatting Modes for JSONL and NDJSON

Common Problems and How to Fix Them

When to Keep JSON Lines vs Convert to Standard JSON

Keep the data as JSON Lines when you are handling logs, event streams, append-only datasets, or very large exports that benefit from record-by-record processing. Convert it to a standard JSON array when you need human-friendly pretty-printing, schema inspection, or a downstream tool that only accepts one root document.

What to Look for in a Formatter

A good JSONL formatter should explicitly mention JSON Lines, JSONL, or NDJSON support. It should validate each line independently, tell you which line failed, accept .jsonl and .ndjson inputs, and avoid saving multi-line records unless it is deliberately converting the data into standard JSON.

Conclusion

Handling JSON Lines correctly is mostly about respecting the delimiter model. Each line is its own JSON value, the file is usually UTF-8, blank lines are risky, and classic whole-document pretty-printing is the wrong output mode unless you first convert to ordinary JSON. Specialized formatters succeed because they understand those rules instead of forcing line-delimited data through a normal JSON parser.