ENRU

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.loadExtra 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.parseunexpected non-whitespace character after JSON dataпо исходникам
Go json.Unmarshalinvalid 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.