ADR-0007: 모델 직렬화 형식 JSON

이후 변경

  • 2026-11-03: 같은 모델 JSON(들여쓰기 없이)이 공유 링크에도 담긴다. 파일과 같은 검증 파서로 읽고 버전 규칙도 같다 → ADR-0043
  • 2026-11-03: 문서 설정(settings)에 그림 문구의 언어 locale이 더해졌다. 그림의 고정 문구가 저장할 때의 화면 언어를 따르던 예외가 사라져, 같은 모델이면 화면 언어와 상관없이 같은 텍스트가 나온다. locale이 없는 파일은 연 사람의 화면 언어로 읽는다 → ADR-0041, 3.3 노드별 필드
  • 2026-11-02: 마크다운의 nschart 코드 블록에 손으로 적는 글의 형식을 요구사항에 더했다. 이 ADR이 정한 .ns.svg 안의 모델은 JSON 그대로이고, 코드 블록의 문법(YAML도 후보)은 따로 정한다 → R-FMT-12, 2026-11-02-02-release-yaml-review
  • 2026-11-01: 읽을 때 모르는 키가 있는 객체는 깨진 파일로 거부하고(열고 바로 저장하면 그대로), U+FFFE · U+FFFF는 JSON 이스케이프로 적는다 → 3.2 CDATA 이스케이프, 3.3 노드별 필드
  • 2026-10-25: JSON을 담는 모델 요소의 네임스페이스와 접두어(ans)를 정했다. 형식의 판 번호는 JSON의 version 필드와 모델 요소의 version 속성에 같은 값으로 들어간다 → ADR-0035, 2. 문서 구조

배경

ADR-0005에 따라 모델을 SVG의 <metadata> 안에 텍스트로 넣는다. 텍스트 형식으로 JSON과 YAML을 비교했다.

결정 기준

  • 같은 모델이면 항상 같은 텍스트가 나와야 한다. (R-FMT-03)
  • 블록 텍스트에 어떤 내용이 들어가도 안전해야 한다. (R-FMT-04)
  • SVG 안에서 공백이 바뀌어도 깨지지 않아야 한다.
  • 의존성이 적어야 한다 (Obsidian 플러그인 번들 크기).
  • 사람이 읽을 수 있고 git diff가 가능해야 한다.

검토한 대안

YAML

  • 장점: 괄호와 따옴표가 적어 읽기 좋음, 여러 줄 텍스트가 자연스러움, 주석 지원
  • 단점:
    • 라이브러리가 필요함 (웹·데스크톱)
    • 따옴표 스타일, 긴 줄 접기 같은 옵션과 라이브러리 버전에 따라 출력이 바뀜
    • a: b, # 주석, yes/no, 1.10 같은 코드성 블록 텍스트에 따옴표 처리가 자주 필요함
    • 들여쓰기가 곧 구조라서, SVG를 다시 정렬하는 도구가 공백을 바꾸면 모델이 깨짐
    • 주석과 손 편집의 장점은, 저장할 때마다 모델을 새로 쓰는 구조에서는 살지 않음

JSON

  • 장점: 브라우저 내장 파서, 모든 문자열이 따옴표로 감싸져 안전, 들여쓰기가 의미를 갖지 않음, 출력이 일정함, JSON Schema 도구가 많음
  • 단점: YAML보다 읽기 불편, 손으로 고칠 때 쉼표·따옴표 실수가 잦음

결정

모델은 JSON으로 직렬화한다. 출력 규칙은 다음과 같다. (자세한 내용은 3.1 출력 규칙)

  • 2칸 들여쓰기 (압축하지 않음)
  • 객체 키 순서 고정 (스키마 정의 순서)
  • 기본값 생략 여부를 속성마다 정해 일관되게 적용
  • ]]>는 CDATA를 나눠서 기록

결과

  • 좋아지는 점: 의존성 없음, 안정적인 출력, git diff 가능
  • 감수하는 점: 파일을 손으로 고치기는 YAML보다 불편하다.