Key facts
- Each line must be valid JSON on its own; there are no surrounding [ ] brackets and no commas between records.
- Commonly served as application/x-ndjson (not IANA-registered); .jsonl files use the same structure.
- Used by the Elasticsearch/OpenSearch _bulk API, BigQuery and other warehouse loaders, log shippers and ML batch/training files.
- Files can be gigabytes because tools stream them line by line instead of loading everything into memory.
How to open a .ndjson file
Windows
Open it in VS Code or Notepad++. In PowerShell, parse each line with Get-Content data.ndjson | ForEach-Object { $_ | ConvertFrom-Json }.
macOS
Open it in VS Code or BBEdit, or install jq (brew install jq) and run jq . data.ndjson to pretty-print every record.
Linux
Preview with head -n 5 data.ndjson, pretty-print with jq . data.ndjson, filter with jq -c 'select(.status == 500)' data.ndjson, and count records with wc -l.
Common problems and fixes
- JSON.parse or a validator says 'Unexpected token' on line 2
- The whole file is being parsed as one JSON document. Parse it line by line, or wrap it into an array with jq -s . data.ndjson > data.json.
- Records are pretty-printed across multiple lines
- NDJSON needs each record on a single line. Compact it with jq -c . pretty.json > data.ndjson.
- One bad line breaks the import
- A truncated or hand-edited record is invalid. Find it by parsing each line separately (for example with jq in a loop, or a script that reports the line number) and fix or remove that record.
- Elasticsearch bulk request is rejected
- The _bulk body must alternate action and document lines and end with a final newline. Make sure the file ends with \n and is sent with Content-Type: application/x-ndjson.
Often converted to or from: JSON array, CSV, JSON Lines (.jsonl), Parquet