# JSON Lines и NDJSON: что это и как читать

> Понять, что такое JSON Lines (NDJSON), почему json.load падает с «Extra data» и как читать и писать файл построчно в Python, JavaScript, Go и jq.

- Адрес: https://jsonstatham.dev/ru/guides/json-lines/
- Язык: Русский (ru)
- Английская версия: https://jsonstatham.dev/guides/json-lines.md
- Обновлено: 2026-11-08

JSON Lines — текстовый файл, в котором каждая строка — законченное значение JSON. Целиком такой файл не является одним документом JSON, поэтому обычный парсер читает первую строку и спотыкается о вторую. Это спотыкание Python и называет «Extra data».

## Как выглядит файл JSON Lines

```json
{"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»

```python
>>> 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 |
| Наш [валидатор](https://jsonstatham.dev/ru/validator/) | «Лишнее после JSON», строка 2, колонка 1 | запуском |

Если файл и правда JSON Lines, его читают построчно, как ниже. Если задумывался один документ, после значения что-то лишнее: второй вставленный объект, случайная скобка, строка лога. Эти случаи разобраны на странице [Лишнее после JSON](https://jsonstatham.dev/ru/errors/extra-data/); [попробовать в валидаторе](https://jsonstatham.dev/ru/validator/?sample=extra_data).

## Чтение и запись JSON Lines в Python

```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

```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

```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

```shell
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, которые читают целиком, и для всего, что человек правит руками. Наш [форматтер](https://jsonstatham.dev/ru/) и валидатор проверяют один документ: чтобы посмотреть там файл 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.
