TL;DR

• NDJSON은 스트리밍 프로토콜(TCP, UNIX pipe 등)에서 여러 JSON 인스턴스를 전송하기 위한 줄바꿈 구분 포맷이다.
• 한 줄에 하나의 유효한 JSON 텍스트, \n으로 구분, UTF-8 인코딩 필수.

NDJSON (Newline Delimited JSON)

배경

JSON 자체에는 스트림 내에서 여러 JSON 값을 구분하는 표준화된 방법이 없다. NDJSON은 이 문제를 해결하기 위해 줄바꿈(\n)을 구분자 로 사용하는 규약을 정의한다. 스트리밍 전송뿐 아니라 반구조화 데이터의 저장에도 적합하다.

핵심 규칙

Serialization (직렬화)

1. 각 JSON 텍스트는 RFC 8259를 준수해야 한다.
2. 각 JSON 텍스트 뒤에 반드시 \n (0x0A) 를 붙인다.
3. \r (0x0D)는 \n 앞에 선택적으로 올 수 있다 (\r\n 허용).
4. JSON 텍스트 내부에 줄바꿈(\n)이나 캐리지 리턴(\r)이 포함되면 안 된다.
5. 모든 데이터는 UTF-8 인코딩이어야 한다.

Parsing (파싱)

1. 파서는 \n (0x0A)과 \r\n (0x0D0A) 모두를 줄 구분자로 수용해야 한다.
2. 파싱할 수 없는 JSON은 에러를 발생시켜야 한다.
3. 빈 줄 무시 여부는 선택 사항이며, 해당 동작을 문서화하고 설정 가능하게 해야 한다.

미디어 타입 & 확장자

• Media Type: application/x-ndjson
• File Extension: .ndjson

예시

{"some":"thing"}
{"foo":17,"bar":false,"quux":true}
{"may":{"include":"nested","objects":["and","arrays"]}}

각 줄이 하나의 유효한 JSON 객체이며, 줄바꿈으로 구분된다.

활용 맥락

• 로그 스트리밍: 각 로그 이벤트를 한 줄의 JSON으로 기록 → 파이프라인 처리 용이
• 대용량 데이터 교환: 전체 파일을 파싱하지 않고 줄 단위로 스트리밍 처리 가능
• 데이터셋 포맷: ML 학습 데이터, 벤치마크 데이터셋 등에서 널리 사용 (예: JSON Lines와 사실상 동일)

NDJSON vs JSON Lines

NDJSON과 JSON Lines (.jsonl)는 사실상 동일한 포맷이다. 미디어 타입과 확장자만 다르다.

---

Connections

• JSON Lines — 사실상 동일 포맷, 확장자·미디어 타입만 상이
• SSE (Server-Sent Events) — SSE는 HTTP 이벤트 프로토콜(id, retry, event type 내장), NDJSON은 프로토콜 무관 순수 직렬화 포맷
• Base64 인코딩 — JSON 내 바이너리 필드를 Base64로 인코딩하여 NDJSON에 실을 수 있다

Source Trail

• 원본 스펙: ndjson/ndjson-spec (GitHub)
• 기반 표준: RFC 8259 (JSON)

Related MOCs

• Computer Science