NDJSON 완전 가이드: Newline Delimited JSON 설명

NDJSON 사양

github.com/ndjson/ndjson-spec의 공식 NDJSON 사양은 의도적으로 최소한입니다. 단일 텍스트 스트림에서 여러 JSON 값을 직렬화하기 위한 간단한 규칙을 정의합니다. 핵심 규칙은 간단합니다:

이 사양은 형식에 헤더, 메타데이터, 스키마 정보를 추가하는 것을 명시적으로 피합니다. 이를 통해 NDJSON을 최대한 간단하게 유지하고 표준 Unix 텍스트 처리 도구와 호환됩니다. 각 줄에 모든 유효한 JSON 값이 허용되지만, 실제로 대부분의 NDJSON 파일은 일관된 키 집합을 가진 JSON 객체를 포함합니다.

• 각 줄은 정확히 하나의 유효한 JSON 값(객체, 배열, 문자열, 숫자, 불리언 또는 null)을 포함해야 합니다.
• 줄은 줄바꿈 문자 '\n'(U+000A)으로 구분됩니다. 캐리지 리턴 '\r'(U+000D)은 '\n' 앞에 올 수 있지만 필수는 아닙니다.
• 마지막 JSON 값 뒤의 후행 줄바꿈은 허용되지만 필수는 아닙니다.
• 각 JSON 값에는 값 자체 내에 이스케이프되지 않은 줄바꿈 문자가 포함되어서는 안 됩니다.

규칙이 최소한이므로 JSON 직렬라이저가 있는 모든 프로그래밍 언어에서 NDJSON을 쉽게 생성할 수 있습니다. 각 레코드를 직렬화하고, 줄바꿈을 추가하고, 출력에 쓰기만 하면 됩니다. 닫는 괄호, 후행 쉼표, 감싸는 배열 구조에 대해 걱정할 필요가 없습니다.

NDJSON MIME 타입: application/x-ndjson

NDJSON의 등록된 MIME 타입은 application/x-ndjson입니다. 이 콘텐츠 타입은 응답 본문에 줄바꿈 구분 JSON 데이터가 포함되어 있음을 나타내기 위해 HTTP 헤더에서 사용됩니다. GitHub API, Docker Registry API, Elasticsearch bulk API를 포함한 많은 스트리밍 API가 NDJSON 응답을 전달하기 위해 이 MIME 타입을 사용합니다.

Content-Type: application/x-ndjson

# Example: curl a streaming API
curl -H "Accept: application/x-ndjson" https://api.example.com/events/stream

# Example: Express.js response
res.setHeader('Content-Type', 'application/x-ndjson');
res.write(JSON.stringify(record) + '\n');

일부 API는 application/json-seq(RFC 7464)이나 text/plain도 대안으로 수락합니다. 그러나 application/x-ndjson이 줄바꿈 구분 JSON 스트림에 가장 널리 채택된 MIME 타입입니다. JSON 레코드를 스트리밍하는 새 API를 구축할 때는 최대 호환성을 위해 application/x-ndjson을 사용하세요.

HTTP 스트리밍 API에서의 NDJSON

NDJSON은 실시간 데이터를 전달하는 HTTP 스트리밍 API의 사실상 표준입니다. 서버가 NDJSON 응답을 보내면 클라이언트는 전체 응답이 완료될 때까지 기다리지 않고 첫 번째 레코드가 도착하는 즉시 처리를 시작할 수 있습니다. 이는 대형 JSON 배열을 반환하는 것보다 빠르고 메모리 효율적입니다.

NDJSON 스트리밍을 사용하는 인기 서비스로는 Docker Registry(이미지 레이어 이벤트), Elasticsearch(대량 작업), Apache CouchDB(변경 피드) 및 많은 최신 이벤트 기반 API가 있습니다. 이 패턴은 Server-Sent Events 대안, 실시간 로그 테일링, 웹 애플리케이션의 점진적 데이터 로딩과 잘 작동합니다.

import express from 'express';

const app = express();

app.get('/api/events/stream', (req, res) => {
  res.setHeader('Content-Type', 'application/x-ndjson');
  res.setHeader('Transfer-Encoding', 'chunked');

  // Simulate streaming events
  let id = 0;
  const interval = setInterval(() => {
    id++;
    const event = {
      id,
      type: 'heartbeat',
      timestamp: new Date().toISOString(),
    };
    res.write(JSON.stringify(event) + '\n');

    if (id >= 100) {
      clearInterval(interval);
      res.end();
    }
  }, 100);

  req.on('close', () => clearInterval(interval));
});

app.listen(3000);

async function* readNdjsonStream(url) {
  const response = await fetch(url, {
    headers: { 'Accept': 'application/x-ndjson' },
  });

  const reader = response.body
    .pipeThrough(new TextDecoderStream())
    .getReader();

  let buffer = '';
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += value;
    const lines = buffer.split('\n');
    buffer = lines.pop();
    for (const line of lines) {
      if (line.trim()) yield JSON.parse(line);
    }
  }
  if (buffer.trim()) yield JSON.parse(buffer);
}

// Usage
for await (const event of readNdjsonStream('/api/events/stream')) {
  console.log('Received:', event);
}

NDJSON과 JSONL: 상호 운용성

NDJSON과 JSONL(JSON Lines)은 기능적으로 동일한 형식입니다. 둘 다 줄바꿈 문자로 구분된 줄당 하나의 JSON 값을 저장합니다. 유효한 NDJSON 파일은 유효한 JSONL이기도 하며, 그 반대도 마찬가지입니다. .ndjson 파일을 .jsonl로 이름을 바꿔도(또는 그 반대로) 단 한 바이트의 내용도 변경하지 않아도 되며, 한 형식을 읽는 모든 도구가 다른 형식도 읽을 수 있습니다.

유일한 차이점은 외관적입니다: NDJSON은 github.com/ndjson/ndjson-spec에서 온 것으로 .ndjson 확장자와 application/x-ndjson MIME 타입을 사용하고, JSONL은 jsonlines.org에서 온 것으로 .jsonl 확장자를 사용합니다. 실제로 대부분의 개발자는 두 이름을 동의어로 취급합니다. 프로젝트에서 이미 JSONL을 사용하고 있다면 NDJSON으로 마이그레이션할 필요가 없으며, 라이브러리가 NDJSON을 지원한다고 하면 .jsonl 파일에서도 변경 없이 작동합니다.