TL;DR

• NDJSON은 여러 JSON 인스턴스를 줄바꿈(\n)으로 구분하여 스트리밍 환경에서 메모리 효율적으로 처리할 수 있게 설계된 데이터 포맷이다.
• 개별 행은 유효한 단일 JSON 값이어야 하며, 전체 문서는 UTF-8로 인코딩되어야 한다.

NDJSON (Newline Delimited JSON)

1. 개요 및 배경

표준 JSON은 배열([]) 전체를 파싱해야 하므로 대용량 스트림 환경에서 메모리 오버헤드가 크다. NDJSON은 이 문제를 해결하기 위해 각 JSON 값을 독립적인 행(Line)으로 처리하도록 규정한다. 이를 통해 수 기가바이트의 데이터도 전체 로드 없이 줄 단위(Line-by-line) 스트리밍 파싱이 가능해진다.

---

2. 핵심 규격 (Spec)

직렬화 규칙 (Serialization)

1. 행 단위 원자성: 각 줄은 독립적으로 유효한 JSON(RFC 8259)이어야 한다.
2. 구분자: 각 JSON 텍스트 뒤에는 반드시 줄바꿈 기호인 \n (ASCII 0x0A)이 위치해야 한다. (\r\n 또한 수용 가능)
3. 내부 줄바꿈 금지: JSON 데이터 내부의 문자열이나 서식에는 \n이나 \r이 포함될 수 없다. (반드시 이스케이프 처리 필요)
4. 인코딩: 모든 데이터는 UTF-8 인코딩을 필수적으로 사용한다.

파싱 규칙 (Parsing)

• 파서는 스트림에서 \n을 만날 때마다 즉시 해당 행을 JSON으로 디코딩하여 처리할 수 있어야 한다.
• 빈 줄(Empty line)은 파서의 구현 설정에 따라 무시될 수 있다.

---

3. 기술 사양 및 활용

• Media Type: application/x-ndjson
• File Extension: .ndjson, .jsonl (JSON Lines와 혼용)

예시 (Example)

{"name": "Alice", "role": "admin"}
{"name": "Bob", "role": "user", "active": true}
{"name": "Charlie", "meta": {"login_count": 5}}

예시에서는 실무 관행에 따라 각 행을 독립적인 JSON 객체로 구성했다. 다만 규격상 각 행의 단위는 객체로 제한되지 않고, 유효한 단일 JSON 값이다. 행 사이에 배열 구분자(,)나 전체를 감싸는 대괄호([])가 없는 것이 특징이다.

주요 활용 맥락

• 로그 수집 및 분석: 로그 이벤트를 실시간으로 스트리밍하여 ELK 스택 등으로 전송할 때 표준으로 사용된다.
• 대규모 데이터셋 교환: ML 학습용 데이터셋(예: HuggingFace 데이터셋)이나 벤치마크 데이터를 효율적으로 저장하고 로드할 때 필수적이다.

NDJSON vs JSON Lines

두 포맷은 기술적으로 거의 동일하며 실무에서도 상호 교환 가능하다. JSON Lines가 조금 더 넓은 범용적 명칭으로 쓰이며, NDJSON은 명시적인 스펙 규격(ndjson-spec)을 지칭하는 경향이 있다.

---

Connections

• SSE vs NDJSON — 데이터 포맷(NDJSON)과 전송 프로토콜(SSE)의 기술적 차이 및 LLM 스트리밍에서의 SSE + JSON payload 사례 비교
• JSON 값과 JSON 객체의 차이 — NDJSON의 각 행을 JSON 객체가 아니라 JSON 값/JSON 텍스트로 설명해야 하는 이유
• UTF-8 — NDJSON의 표준 인코딩 규격
• ASCII (American Standard Code for Information Interchange) — 구분자 \n(10), \r(13)의 정의 기반
• Base64 인코딩 — NDJSON 내부에 이진 데이터를 포함시키기 위한 필수 전처리 기법
• SSE (Server-Sent Events) — HTTP 이벤트 스트리밍 프로토콜. SSE 안에는 보통 NDJSON이 아니라 JSON payload가 담기며, 전체 스트림은 text/event-stream으로 해석된다.

Related MOCs

• [[MOCs - Computer Science(CS)]]