34-ndjson-storage

Status: ACTIVE
AppliesTo: v10

SSOT

이 문서는 NDJSON 저장 포맷의 정본이다.

목적/범위

NDJSON(Line-delimited JSON) 파일의 저장 포맷(내용/확장자)을 정의한다.

이 스킬은 "저장 포맷"만 정의한다. 구체적인 폴더 경로/라우팅은 각 도메인 스킬에서 정한다:

• String Table: skills/devian-data/33-string-table/SKILL.md → .../string/ndjson/...
• 일반 Table: skills/devian-data/32-json-row-io/SKILL.md → .../ndjson/...

NDJSON 포맷 규칙 (Hard Rules)

파일 인코딩

UTF-8 텍스트

내용 형식

NDJSON (Line-delimited JSON)

• 한 줄 = JSON object 1개
• 빈 줄 금지
• JSON array ([]) 금지

{"id":"item1","value":100}
{"id":"item2","value":200}
{"id":"item3","value":300}

확장자 규칙 (중요)

파일 확장자는 .json이다.

• 내용이 NDJSON이라도 확장자는 .json 사용
• 소비 측(Unity/툴링) 요구로 .json 고정
• .ndjson 확장자 금지

결정성 (Deterministic)

같은 입력이면 항상 같은 출력이 나와야 한다.

• 라인 순서: 입력 데이터 순서 유지
• JSON stringify: 컴팩트 포맷 (들여쓰기 없음)
• 필드 순서: 각 도메인 스킬에서 정의

빌더 API

소스 경로

framework-ts/tools/builder/generators/ndjson-storage.js

Export 함수

/**
 * Object 배열을 NDJSON 문자열로 변환
 * @param {Array<object>} objects - JSON object 배열
 * @returns {string} NDJSON 문자열
 */
export function encodeNdjsonFromObjects(objects);

/**
 * JSON 문자열 배열을 NDJSON 문자열로 변환
 * @param {Array<string>} lines - 이미 JSON.stringify된 라인 배열
 * @returns {string} NDJSON 문자열
 */
export function encodeNdjsonFromLines(lines);

동작 규칙

• encodeNdjsonFromObjects: objects.map(o => JSON.stringify(o)).join('\n')
• encodeNdjsonFromLines: lines.join('\n')
• 빈 배열이면 '' 반환 (기존 동작과 호환)

금지 행동

• NDJSON 내용을 JSON array([])로 바꾸기 금지
• 확장자를 .ndjson로 바꾸기 금지 (.json 유지)
• 라인 끝에 trailing comma 추가 금지

DoD (검증 가능)

PASS 조건

• NDJSON 파일 확장자가 .json임
• 파일 내용이 한 줄당 JSON object 1개
• JSON array가 아님
• 빈 줄 없음
• 같은 입력이면 같은 출력 (결정성)

FAIL 조건

• 파일 확장자가 .ndjson
• 내용이 JSON array
• 빈 줄 포함
• 비결정적 출력

Reference

• Consumer: skills/devian-data/32-json-row-io/SKILL.md (일반 Table)
• Consumer: skills/devian-data/33-string-table/SKILL.md (String Table)