JSON Lines и NDJSON: что это и как читать
Обновлено
JSON Lines — текстовый файл, в котором каждая строка — законченное значение JSON. Целиком такой файл не является одним документом JSON, поэтому обычный парсер читает первую строку и спотыкается о вторую. Это спотыкание Python и называет «Extra data».
Как выглядит файл JSON Lines
{"id":1,"event":"login","user":"ann"}
{"id":2,"event":"view","user":"bob"}
{"id":3,"event":"logout","user":"ann"}- Текст в UTF-8, одно значение JSON на строку, обычно объект. Значение не переносится: перевод строки внутри строки пишется как
\n. - Строки разделяет
\n;\r\nтоже работает, потому что пробелы вокруг значения не считаются. Последнюю строку тоже стоит закончить\n, чтобы следующая запись не приклеилась к ней. - Пустая строка — не запись. Многие читатели её пропускают, некоторые падают: лучше не писать.
- Расширения —
.jsonlи.ndjson. JSON Lines и NDJSON (newline-delimited JSON) — две спецификации одного формата; чаще всего встречается типapplication/x-ndjson, например в bulk API Elasticsearch.
Почему json.load падает с «Extra data»
>>> json.load(open("events.jsonl"))
json.decoder.JSONDecodeError: Extra data: line 2 column 1 (char 38)По RFC 8259 текст JSON — одно значение, вокруг которого могут быть только пробелы. Парсер читает первый объект, видит { в начале второй строки и не берётся гадать, что это. Строгие парсеры говорят одно и то же, каждый своими словами:
| Парсер | Сообщение на файле выше | Проверено |
|---|---|---|
Python json.load | Extra data: line 2 column 1 (char 38) — «лишние данные: строка 2, колонка 1» | запуском, Python 3.9.6 |
V8 JSON.parse (Node.js, Chrome) | Unexpected non-whitespace character after JSON at position 38 (line 2 column 1) — «непробельный символ после JSON» | запуском, Node 25.1.0 |
Firefox JSON.parse | unexpected non-whitespace character after JSON data | по исходникам |
Go json.Unmarshal | invalid character '{' after top-level value — «символ { после значения верхнего уровня» | запуском, Go 1.25.3 |
| C# System.Text.Json | '{' is invalid after a single JSON value. Expected end of data. | по исходникам |
| jq | ошибки нет: jq читает поток значений | запуском, jq 1.7.1 |
| Наш валидатор | «Лишнее после JSON», строка 2, колонка 1 | запуском |
Если файл и правда JSON Lines, его читают построчно, как ниже. Если задумывался один документ, после значения что-то лишнее: второй вставленный объект, случайная скобка, строка лога. Эти случаи разобраны на странице Лишнее после JSON; попробовать в валидаторе.
Чтение и запись JSON Lines в Python
import json
def read_jsonl(path):
with open(path, encoding="utf-8") as f:
for n, line in enumerate(f, start=1):
if not line.strip():
continue # пустые строки пропускаем
try:
yield json.loads(line)
except json.JSONDecodeError as e:
raise ValueError(f"{path}:{n}: {e}") from None
for record in read_jsonl("events.jsonl"):
print(record["id"], record["event"])
with open("out.jsonl", "w", encoding="utf-8") as f:
for record in records:
f.write(json.dumps(record, ensure_ascii=False) + "\n")Генератор держит в памяти одну строку, так что размер файла не важен, а ошибка называет номер строки: events.jsonl:3: Expecting property name enclosed in double quotes: line 1 column 21 (char 20). json.dumps без indent никогда не пишет настоящий перевод строки, поэтому каждая запись остаётся на своей строке. В pandas формат читает pd.read_json(path, lines=True).
Чтение JSON Lines в JavaScript и Node.js
import { createReadStream } from 'node:fs';
import { createInterface } from 'node:readline';
const lines = createInterface({ input: createReadStream('events.jsonl'), crlfDelay: Infinity });
let n = 0;
for await (const line of lines) {
n++;
if (!line.trim()) continue;
const record = JSON.parse(line);
console.log(record.id, record.event);
}
// Небольшой файл, уже прочитанный в строку:
const records = text.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
// Запись:
const out = records.map((r) => JSON.stringify(r)).join('\n') + '\n';readline читает файл потоком, и память не растёт. Счётчик n нужен, чтобы сообщить, какая строка сломана: позиция в сообщении V8 считается внутри строки, а не от начала файла.
Чтение JSON Lines в Go
dec := json.NewDecoder(f)
for {
var e Event
if err := dec.Decode(&e); err == io.EOF {
break
} else if err != nil {
return err
}
fmt.Println(e.ID, e.Event)
}json.Decoder читает значение за значением, а переводы строк считает пробелами. Чтобы называть номера строк, берут bufio.Scanner и json.Unmarshal на каждую строку, но сначала поднимают его предел: буфер по умолчанию — 64 КиБ, и строка длиннее останавливает чтение с bufio.Scanner: token too long. Перед циклом — sc.Buffer(make([]byte, 0, 64*1024), 10*1024*1024). Запись — один вызов на запись: json.NewEncoder(w).Encode(v) сам добавляет перевод строки.
JSON Lines и jq
jq -c 'select(.user == "ann")' events.jsonl # фильтр, по записи на строку
jq -s '.' events.jsonl > events.json # JSON Lines в один массив
jq -c '.[]' events.json > events.jsonl # массив обратно в JSON Lines
jq -s 'length' events.jsonl # сколько записейjq читает поток значений, поэтому JSON Lines ему не нужно объявлять. -c печатает каждый результат одной строкой, -s (slurp) собирает всё в массив. Сломанная строка останавливает jq с позицией в файле: jq: parse error: Expected another key-value pair at line 3, column 21.
Когда JSON Lines нужен, а когда нет
- Логи и потоки событий. Добавить запись — дописать одну строку: ничего раньше не переписывается, а сбой стоит максимум последней строки.
- Большие выгрузки. Читатель держит в памяти одну запись, а
head,tail,split,wc -lиgrepработают с записями без всякого парсера JSON. - Датасеты и пакетные API. Обучающие данные и файлы пакетных заданий часто приходят в
.jsonl; BigQuery называет формат newline-delimited JSON. - Массовая загрузка. Эндпоинт
_bulkв Elasticsearch принимает NDJSON: строка с действием, следом строка с документом.
Один документ JSON лучше для конфигов, для ответов API, которые читают целиком, и для всего, что человек правит руками. Наш форматтер и валидатор проверяют один документ: чтобы посмотреть там файл JSON Lines, вставь одну строку или сначала собери файл в массив через jq -s.
Частые вопросы о JSON Lines
Файл JSON Lines — это валидный JSON?
Нет. Каждая его строка по отдельности — валидный JSON, а файл целиком — нет. Поэтому json.load и JSON.parse останавливаются на второй строке.
Чем JSON Lines отличается от NDJSON?
На практике ничем: оба — одно значение JSON на строку, разделитель \n. Это две спецификации одной идеи, с расширениями .jsonl и .ndjson.
Как превратить JSON Lines в массив JSON?
jq -s . file.jsonl > file.json. В Python: json.dump(list(read_jsonl(path)), f). Обратно из массива: jq -c '.[]' file.json.
Может ли одна запись занимать несколько строк?
В JSON Lines — нет. jq и json.Decoder в Go прочитают и записи с отступами, но построчные инструменты сломаются, и файл перестанет быть JSON Lines.