파일 형식 명세
배포 대상들이 주고받는 저장 파일, 곧 모델을 내장한 SVG의 형식입니다. 앱들 사이의 계약(호환성 계약)이므로, 웹 1.0 뒤에는 형식 버전이 바뀔 때만 수정합니다(DR-0018).
- 관련 요구사항: 3.4 파일 형식
- 관련 결정: ADR-0005(모델 내장 SVG), ADR-0045(그림 지문, 텍스트 외곽선), ADR-0006(확장자), ADR-0007(JSON), ADR-0014(Drive), ADR-0017(접기 영역의 이름), ADR-0018(화면 그대로 저장, 뷰 상태), ADR-0021(Event와 Method), ADR-0022(호출 블록), ADR-0026(서브셋 글꼴), ADR-0034(기본 블록 글꼴), ADR-0035(모델 네임스페이스, 프로토타입 파일)
- 같은 모델 JSON(3장)이 웹의 공유 링크에도 담깁니다. 링크의 봉투(이름, 압축, 링크 형식의 버전)는 이 명세 밖이고 웹 설계에 있습니다 → 3. 공유 URL과 보기 모드, ADR-0043
- 모델의 구조는 4.4 문서 모델과 4.5 내용과 뷰 상태를 따릅니다. 필드 이름과 스키마는 01-model 설계에서 굳혔습니다(v1, 3장).
지금 상태
이 명세의 v1은 MVP의 코드(
src/packages/core/src/format/)에 구현되어 있습니다. 웹 1.0 전까지는 버전을 올리지 않고 고칠 수 있습니다(DR-0018). 프로토타입이 쓰는 파일(version: 0)은 이 형식과 다릅니다(7장).
1. 확장자와 판별
| 확장자 | 쓰는 곳 |
|---|---|
이름.ns.svg | Obsidian 플러그인(만드는 파일), Google Drive에서 만드는 파일(ADR-0014), Claude skill이 생성하는 파일. 데스크톱 · 웹도 연다 |
이름.ns | 데스크톱 · 웹에서 만드는 파일. 내용은 .ns.svg와 같다 |
- 확장자는 1차 판별에만 쓴다.
- 실제로 열 때는
<metadata>안의 모델 요소가 있는지로 확인한다(내용 기반 판별). - 모델 요소가 없거나 JSON이 손상되었으면 편집 불가로 처리한다. 원본 파일은 덮어쓰지 않는다. 그림 요소를 역해석해 모델을 복원하지 않는다(R-FMT-06).
.nsd(Structorizer)는 이 형식이 아니다. 가져오기 대상으로만 취급한다.
열지 못한 이유는 넷 가운데 하나다. 셸은 이것으로 사용자에게 보일 말을 고른다(→ 1. 파일 열기·저장). 어느 경우든 원본은 덮어쓰지 않는다.
| 이유 | 언제 |
|---|---|
noModel | SVG가 아니거나, <metadata> 안에 모델 요소가 없다 |
prototype | 프로토타입이 쓴 파일(<metadata id="ariadne-nsd-model">, version: 0)이다(7장). 사용자에게는 noModel과 같게 보인다 |
damaged | XML · JSON이 깨졌거나, 모델이 이 명세(필드, id 형식, 정의되지 않은 키)나 불변식(01-model)을 어긴다. 모델 요소의 version 속성과 JSON의 version이 다를 때도 이것이다 |
newerVersion | 이 앱보다 새 버전이 쓴 파일이다(5장). 앱 업데이트를 안내한다 |
2. 문서 구조
classDiagram direction TB class svg["svg (루트, SVG 1.1)"] svg : width, height, viewBox class metadata class document["ans:document (모델 요소)"] document : version document : drawing-sha256 class cdata["CDATA (모델 JSON)"] class styleEl["style"] class fontface["@font-face (서브셋 글꼴, data URI)"] class paper["rect (종이)"] class render["g.ans-render (그림 요소)"] svg *-- "1" metadata svg *-- "1" styleEl svg *-- "1" paper svg *-- "1" render metadata *-- "1" document : 정확히 하나 document *-- "1..*" cdata : 이스케이프로 나뉠 수 있음 (3.2) styleEl *-- "0..*" fontface
UML 클래스 다이어그램으로 나타낸 XML 요소의 포함 관계입니다. 채운 마름모(*--)는 합성(자식 요소), 숫자는 다중성입니다. 위아래 순서는 문서 안의 순서가 아닙니다. 순서는 아래 예시를 따릅니다.
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="…" height="…" viewBox="…">
<metadata>
<ans:document xmlns:ans="https://github.com/reddiana/AriadneNSD" version="1" drawing-sha256="…"><![CDATA[
{ "format": "ariadne-nsd", "version": 1, … }
]]></ans:document>
</metadata>
<style>
@font-face { font-family: "…"; src: url(data:font/woff;base64,…); } /* 서브셋 글꼴 (WOFF) */
</style>
<rect width="100%" height="100%" fill="#ffffff"/> <!-- 종이 -->
<g class="ans-render" transform="translate(.5 .5)" font-family="…" style="font-kerning:none"> … </g> <!-- 모델에서 생성한 그림 -->
</svg>-
출력의 모양은 위 예시 그대로다(주석만 빼고). XML 선언(
<?xml …?>)은 쓰지 않는다. 모델 JSON은<![CDATA[로 끝나는 줄 다음 줄에 들여쓰지 않고 시작하고,]]></ans:document>는 제 줄에 둔다. 넣을 글꼴이 없어도<style>은 빈 채로 둔다. 파일은 줄 바꿈(LF) 하나로 끝난다. -
루트는 SVG 1.1
<svg>요소다(R-FMT-01). -
모델 요소의 네임스페이스 URI는
https://github.com/reddiana/AriadneNSD이고 접두어는ans다. 버전 번호는 넣지 않는다. 주소가 아니라 이름이므로, 저장소의 위치가 바뀌어도 그대로 둔다 → ADR-0035 -
모델 요소의 이름은
ans:document다. 모델 요소는<metadata>안에 정확히 하나 있다. 모델 요소의version속성과 JSON의version필드는 같은 값이다. 다르면 깨진 파일(damaged)로 판정한다. -
모델 요소의
drawing-sha256속성은 그림 지문이다: 이 파일에서<metadata>요소를 뺀 나머지(곧 순수 SVG)의 SHA-256(UTF-8, 소문자 16진수 64자)이다(4.1). 저장할 때 항상 기록한다. 읽을 때 없어도 받는다(그 파일은 그림 부분을 확인하지 않음). -
서브셋 글꼴: 번들한 글꼴을 그림 부분에 쓰인 문자만 남기도록 서브세팅해
<style>의@font-face에 data URI로 넣는다. 그림 요소의font-family는 이 글꼴 다음에 폴백 글꼴 목록을 지정한다 → ADR-0026, R-FMT-07. 서브셋 글꼴도 같은 모델이면 같은 바이트여야 한다(3.1). 서브셋 글꼴의 형식은 WOFF(font/woff)다. 압축은 버전을 고정한 JS zlib 라이브러리로 한다 → ADR-0039. 기본 블록 글꼴의font-family이름은AriadneNSD Mono이다(D2Coding은 OFL의 예약 글꼴 이름이라 고친 글꼴에 쓰지 못함 → ADR-0034). 서브셋에는 원래 글꼴의 이름 레코드(저작권 · OFL 고지)를 모두 남긴다 -
종이: 테마의 종이 색 사각형을 둔다(밝은 기본 테마는 흰색). 투명하게 두지 않는다. 렌더링 결과의 색은 항상 테마의 색이다 → R-FMT-08, 2. 레이어와 출력
-
그림 요소는 모델에서 생성한 파생 데이터일 뿐이며, 읽을 때 무시한다(단일 원천은 모델: R-FMT-05). 저장되는 렌더링 결과는 지금 화면 그대로이고 오버레이 레이어의 표시(선택 표시 등)는 넣지 않는다 → ADR-0018
3. 모델 JSON
맨 위의 구조는 아래와 같습니다. 같은 구조의 JSON Schema(모양만, 이 버전이 지원하는 값만)가 src/packages/core/schema/model.schema.json에 있고 사이트에는 /model.schema.json으로 놓입니다 → 3.1 LLM · 에이전트를 위한 안내서. 객체마다의 필드 표와 스키마가 보지 못하는 규칙은 모델 JSON 스키마에 있습니다(스키마에서 만든 문서). 이 문서의 JSON 예제는 테스트가 꺼내 실제 파서로 엽니다(3.1 문서 속 예제(doctest)와 값 목록).
{
"format": "ariadne-nsd",
"version": 1,
"settings": { "textKind": "plain", "theme": "default", "headStyle": "shape", "locale": "ko", "textOutlines": true },
"diagrams": [
{
"id": "d1",
"head": { "kind": "method", "text": "partition(a, lo, hi)" },
"body": [ … 블록 … ]
}
],
"view": {
"folded": [ … 접힌 접기 영역 · 분기의 id, 펴 보인 곳의 접힘 … ],
"opened": [ … 인라인으로 펴 보인 호출 블록의 경로 … ],
"bands": true,
"resultSymbol": "←"
}
}| 묶음 | 무엇 | undo |
|---|---|---|
settings | 문서 설정: 블록 텍스트의 언어(R-LAY-06), 테마, 헤더 모양(R-LAY-10), 그림 문구의 언어(R-NFR-04, ADR-0041), 텍스트를 외곽선으로 저장(R-FMT-10) | 대상 |
diagrams | 다이어그램의 목록(순서가 있음). 헤더(없음 / Event / Method, ADR-0021)와 본문 | 대상 |
| 블록 | 처리 · If · Case · While · Do-While · For · 호출 등(kind로 판별하는 유니온). 제어 블록은 분기나 본문으로 블록의 줄(Seq)을 합성한다. 줄은 비지 않는다 | 대상 |
| 호출 블록 | 호출 대상 Method의 id(참조), 인자, 결과. 이름을 적는 호출 블록은 id 대신 적은 이름을 가진다(필드는 모델 1.5 → R-BLK-08). 이름 문자열을 복사해 갖지 않는다. 참조하던 Method가 없어지면 마지막에 보이던 이름을 적은 호출 블록이 된다 → ADR-0022, ADR-0049 | 대상 |
| 접기 영역 | 한 줄 안의 연속된 블록 범위(처음 · 끝 블록의 id)와 이름(없을 수 있음) → ADR-0017. 펴 보인 곳의 접기 영역은 그 호출 블록에 속한다(R-EDIT-16) | 대상 |
view | 뷰 상태: 접힘, 펴 보기, 이름 띠 보기, 결과 기호 → ADR-0018, 02-interaction-rules | 대상 아님 |
- 블록, 다이어그램, 접기 영역은 모두 안정 id(문서가 바뀌어도 유지되는 식별자)를 갖는다. 뷰 상태와 호출 블록은 id로 참조한다.
- 화면의 줌과 스크롤 위치, 선택은 저장하지 않는다.
- 노드별 필드는 3.3에 있다.
3.1 출력 규칙
직렬화는 결정적이어야 한다: 같은 모델이면 항상 바이트 단위로 같은 파일이 나온다(R-FMT-03).
- UTF-8, 줄바꿈은 LF, 2칸 들여쓰기.
- 객체 키의 순서는 스키마에 정한 순서로 고정한다.
- 기본값과 같은 속성을 생략할지는 스키마에서 속성마다 정하고, 항상 그대로 따른다.
view의 목록(folded,opened)은 id를 문서 순서(다이어그램 순서, 그 안의 깊이 우선 순서)로 늘어놓는다. 접고 편 차례에 따라 달라지지 않는다.folded에는 지금 문서에 있는, 접을 수 있는 것(접기 영역, 펴 보인 곳의 접기 영역, If · Case의 분기, 반복 블록)의 id만 기록한다. 없어진 id는 기록하지 않는다. 한 줄 안에서는 블록들(과 그 안)을 먼저, 그 줄의 접기 영역을 뒤에 기록한다.folded의 뒤에는 펴 보인 호출 블록 자리의 접힘을 호출 경로의 문서 순서로 기록한다(ADR-0046)."b4/"는 경로b4가 자기 접힘과 자기 접기 영역을 갖는다는 표시이고(처음 펼 때 Method의 접기 영역을 그 호출 블록의siteFolds로 복사했다 → ADR-0047), 바로 뒤의"b4/r3"은 그 자리에서 호출하는 Method의 분기 · 반복 블록r3이 접혀 있다는 뜻이다. 겹쳐 폈으면"b4/b9/","b4/b9/r3"이다. 그 자리의 접기 영역의 접힘은 그 id로 앞쪽에 기록한다.- 경로가 끝나는 Method에 접기 영역이 있으면
"b4/"를 언제나 기록한다. 없으면 다시 열었을 때 같은 모습이 되는 자리는 기록하지 않는다: 펴 보인 자리는 접힘이 Method와 같으면, 닫힌 자리는 그 자리와 Method 모두 접힌 것이 없으면 기록하지 않는다. 그래서 펴 보인 Method에 접기 영역이 없고 그 안에 접힌 것이 없는 문서에는 이 항목이 없다. - 펴 보인 경로에
"b4/"가 없는 파일(이 규칙 전에 저장한 파일)은 열 때 그 자리를 처음 펴는 것으로 보고 Method의 접힘과 접기 영역을 가져온다. 연 모습은 같고, 다시 저장하면 사본과"b4/"가 더해진다. - 지금도 갈 수 있는 경로, 그 Method에 있는 id만 기록한다. 지원하지 않는 형태의 항목은 없는 id처럼 무시하고 저장할 때 기록하지 않는다. 이 항목이 생기기 전의 앱도 같은 이유로 이 파일을 연다.
- 경로가 끝나는 Method에 접기 영역이 있으면
opened에는 지금도 갈 수 있는 경로만 한 번씩 기록한다: 경로의 id가 모두 호출 블록이고, 안쪽 것은 바로 바깥 호출 블록이 호출하는(같은 문서의) Method 안에 있다.
- 서브셋 글꼴은 문자를 코드 포인트 순으로 서브세팅하고, 같은 버전의 서브세팅 도구와 같은 버전 · 같은 수준의 압축 라이브러리로 만든다.
- 렌더링 결과 안의 텍스트 가운데 편집기가 표시하는 고정 문구(“참” · “거짓”, ”⋯ 블록 n개”, “(이름 없음)“)는
settings.locale의 언어로 표시한다. 저장하는 사람의 화면 언어(UI 언어)는 파일에 들어가지 않는다. 그래서 같은 모델이면 누가 어느 화면 언어로 저장해도 같은 파일이다(R-NFR-04, ADR-0041).
3.2 CDATA 이스케이프
JSON 텍스트에 ]]>가 나오면 CDATA를 나눠서 쓴다(R-FMT-04).
]]> → ]]]]><![CDATA[>
읽을 때는 XML 파서가 여러 CDATA 섹션을 하나의 텍스트로 합쳐 주므로 따로 처리할 필요가 없다.
U+FFFE와 U+FFFF는 XML에 쓸 수 없는 문자다. 이 둘은 JSON의 문자열 안에만 나올 수 있으므로 JSON 이스케이프(, )로 기록한다. 읽으면 같은 문자열이 된다.
3.3 노드별 필드
필드는 표의 순서대로 기록한다(3.1의 키 순서). “생략”은 그 값일 때 키를 기록하지 않는다는 뜻이다. 타입은 1. 타입과 같고, 다른 곳은 줄(Seq) 하나다(아래 표 뒤).
| 노드 | 필드 (순서대로) | 생략 |
|---|---|---|
| 문서 | format(항상 "ariadne-nsd") · version · settings · diagrams · view | 없음 |
settings | textKind · theme · headStyle("shape" | "title") · locale("en" | "ko") · textOutlines(true) | textOutlines는 끔(false)이면 (읽을 때는 locale이 없어도 받고, textOutlines: false도 받는다) |
| 다이어그램 | id · head · body · folds | head는 헤더가 없으면, folds는 비면 |
head | kind("event" | "method") · text | 없음 |
| 처리 | id · kind: "process" · text | 없음 (빈 블록은 text: "") |
| If | id · kind: "if" · text · yes · no | 없음 |
| Case | id · kind: "case" · text · arms · otherwise | otherwise는 default 분기가 없으면 |
분기 (yes · no · otherwise) | id · label · body · folds | label은 편집하지 않았으면, folds는 비면 |
Case의 분기 (arms의 원소) | id · label · body · folds | folds는 비면 |
| While · Do-While · For | id · kind("while" | "doWhile" | "for") · text · body · folds | folds는 비면 |
| 호출 | id · kind: "call" · target · args · result · siteFolds | siteFolds는 비면 |
target | kind 다음에 그 종류의 필드 (01-model): local은 diagram, named는 name. 예전 파일의 lost(lastName, 선택 file)와 external(file · diagram · lastName)은 lastName을 name으로 한 named로 읽고, 저장할 때는 named로 쓴다 → ADR-0049 | 없음 |
접기 영역 (folds의 원소) | id · first · last · name | name은 없으면 |
| 펴 보인 곳의 접기 영역 | id · via · first · last · name | name은 없으면 |
view | folded · opened · bands · resultSymbol("←" | "=") | 없음 (빈 목록도 적음) |
- 줄(
Seq)은 따로 객체를 두지 않는다. 줄은 언제나 한 주인(다이어그램 · 분기 · 반복 블록)의 하나뿐인 본문이라, 블록의 배열을 주인의body에, 그 줄의 접기 영역을 주인의folds에 둔다. 그래서 파일이 한 겹 얕고, 접기 영역이 없는 문서에는folds가 보이지 않는다. - id는 종류마다의 접두사와 1 이상의 정수(앞에 0 없음)다: 다이어그램
d, 블록b, 분기r, 접기 영역f(펴 보인 곳의 것도) → 1.7 id. 이 형식이 아니면 깨진 파일이다. 블록을 가리키는 참조(접기 영역의first·last등)도 형식만 검사한다. - 정의되지 않은 키가 있는 객체는 깨진 파일(
damaged)로 거부한다. 정의되지 않은 키를 버리고 열면 “열고 바로 저장하면 그대로”(QA-04)를 지킬 수 없기 때문이다. 생략하는 목록을 빈 목록으로 적은 것("folds": [])은 받는다(저장할 때는 생략한다). textKind: 블록 텍스트의 언어. 값은"plain"(일반 텍스트) ·"c"·"cpp"·"java"·"javascript"(JavaScript · TypeScript) ·"python"·"bash"다. 새 문서는"plain"이다. 언어는 구문 강조의 색만 정하고 글꼴과 레이아웃은 바꾸지 않는다 → ADR-0042. 언어를 더해도 형식의 버전은 그대로다. 지원하지 않는 값(뒤의 버전이 더한 언어)을 만나면 모델에는"plain"을 두고, 받은 값은 모델 밖에 따로 보존한다(editor의 세션이 가진다 → 2. 상태와 선택). 저장할 때 모델의 값이 아직"plain"이면 보존한 값을 그대로 기록한다.theme: 테마의 이름."default"(밝은 테마) ·"dark"(어두운 테마) ·"high-contrast"(고대비) ·"print"(흑백 인쇄) 가운데 하나다. 색 값은 기록하지 않는다(그림 부분에 이미 그 색으로 렌더링되어 있다). 지원하지 않는 값은 기본 테마로 그리고, 값은 그대로 둔다 → 8. 테마, ADR-0044locale: 그림 문구의 언어. 값의 목록은 화면 언어의 목록(core의locales)과 같다. 새 문서는 만든 사람의 화면 언어다 → ADR-0041- 없으면(이 필드가 생기기 전에 저장한 파일) 연 사람의 화면 언어로 읽는다. 마이그레이션은 두지 않고, 다음에 저장할 때 그 값을 기록한다. 그래서 이런 파일은 처음 저장하는 사람의 화면 언어에 따라 바이트가 다르다. 한 번 저장한 뒤로는 같다.
- 지원하지 않는 값(뒤의 버전이 더한 언어)은 연 사람의 화면 언어로 그리고, 받은 값은
textKind처럼 모델 밖에 따로 보존한다. 사용자가 그 문서의 그림 문구의 언어를 바꾸지 않았으면 저장할 때 보존한 값을 그대로 기록한다. - 문자열이 아니면 깨진 파일이다.
textOutlines: 텍스트를 외곽선으로 저장(4.3).true일 때만 기록한다.true·false가 아니면 깨진 파일이다.- 헤더 · 호출 블록 · 여러 다이어그램 · 접기 영역은 MVP 뒤의 기능이지만 v1 형식에 들어 있다. 그 기능을 낼 때 뜻이 바뀌면 버전을 올리고 마이그레이션을 둔다(5장).
작은 예입니다. 처리 블록 하나와 If 하나가 든, 헤더 없는 다이어그램입니다.
{
"format": "ariadne-nsd",
"version": 1,
"settings": { "textKind": "plain", "theme": "default", "headStyle": "shape", "locale": "ko" },
"diagrams": [
{
"id": "d1",
"body": [
{ "id": "b1", "kind": "process", "text": "x = read()" },
{
"id": "b2", "kind": "if", "text": "x > 0",
"yes": { "id": "r1", "body": [ { "id": "b3", "kind": "process", "text": "print(x)" } ] },
"no": { "id": "r2", "body": [ { "id": "b4", "kind": "process", "text": "" } ] }
}
]
}
],
"view": { "folded": [], "opened": [], "bands": true, "resultSymbol": "←" }
}(예는 읽기 좋게 줄을 줄였습니다. 실제 파일은 3.1대로 2칸 들여쓰기로 한 키에 한 줄입니다.)
4. 그림 부분
그림 요소의 모습(색, 선, 타이포그래피, 치수)은 04-visual-design을 따른다. 요소 구성(<rect>, <path>, <circle>, <text>)과 클래스 이름은 3. SVG 렌더링에서 정했다. 그림 부분은 <metadata>를 뺀 모든 것이다: 루트 <svg>의 속성, <style>(서브셋 글꼴), 종이, <g class="ans-render">.
4.1 그림 지문
다른 도구로 그림 부분만 고친 파일을 알아보기 위한 값이다(R-FMT-09) → ADR-0045
- 쓰기: 파일 텍스트에서
<metadata>요소의 줄(앞의 들여쓰기와 그 앞의 줄 바꿈부터</metadata>까지)을 뺀 텍스트의 SHA-256을 모델 요소의drawing-sha256에 기록한다. 이 텍스트는 4.2의 순수 SVG와 바이트까지 같다. - 읽기: 같은 방법으로 다시 계산해 비교한다. 줄 바꿈은 LF로 바꾸고(CRLF로 바꿔 체크아웃한 파일은 고친 것이 아님), 앞의 BOM은 빼고 계산한다.
<metadata>가 다른 마크업과 한 줄에 있으면 그 요소만 뺀다. - 결과는 셋이다: 같음, 다름(그림 부분이 고쳐짐), 알 수 없음(지문이 없는 파일). 다르면 셸이 열면서 알린다(편집기는 모델로 그리고, 저장하면 그림 부분이 모델로 다시 만들어짐 → 6. 셸과의 연결). 다르더라도 파일은 연다. 모델은 그대로 원본이다(R-FMT-05).
- 모델만 고친 파일(JSON을 손으로 고침)은 지문이 같다. 그림 부분은 열 때 항상 모델에서 다시 렌더링하므로 알릴 것이 없다.
4.2 순수 SVG
순수 SVG(R-EXP-02)는 저장 파일에서 <metadata> 요소만 뺀 것이다. 그림 요소 · 서브셋 글꼴 · 종이 · 클래스 이름은 그대로 둔다. 그래서 같은 모델이면 같은 바이트이고(3.1), 저장 파일의 그림 지문과 같은 텍스트의 지문이다. 모델 요소가 없으므로 편집기로는 열리지 않는다(noModel, 1장). 확장자는 .svg다.
4.3 텍스트 외곽선
문서 설정 textOutlines가 켜져 있으면(R-FMT-10) 렌더링 결과의 텍스트를 번들 글꼴의 글리프 외곽선(<path>)으로 직렬화한다. 모델의 텍스트는 그대로다.
- 텍스트 요소 하나가
<path>여러 개가 된다. 테두리가 있으면 맨 아래에 획만 렌더링한<path>를 보통 글자와 굵은 글자로 나눠 하나씩 두고, 그 위에 글자를 색마다 보통 글자 하나, 굵은 글자 하나의<path>로 둔다. 색의 순서는 텍스트에 처음 나오는 순서이므로 구문 강조가 있으면<path>가 그만큼 늘어난다. 해당하는 글자가 없는<path>는 쓰지 않는다. 좌표 규칙(소수 둘째 자리)은 다른 요소와 같다 → 3. SVG 렌더링 - 기울임 텍스트는 글리프 외곽선을 기준선 기준으로 기울여 같은
<path>에 넣는다(font-style을 쓰지 않고, 기울임 때문에<path>가 더 나뉘지는 않는다). 글자의 자리와 폭은 기울이지 않은 텍스트와 같다. - 번들 글꼴에 없는 문자가 든 텍스트 요소는
<text>로 남는다. 서브셋 글꼴에는 그런 요소의 문자만 넣는다. 남은 텍스트가 없으면@font-face를 넣지 않는다(<style>은 빈 채로 둠). - 같은 모델이면 같은 바이트다(3.1). 외곽선은 버전을 고정한 번들 글꼴에서 읽는다.
5. 버전 관리
- 형식 버전은 정수이며 1부터 시작한다.
- 읽기: 이전 버전 파일은 버전별 마이그레이션 함수(v1→v2→…)를 차례로 적용해 현재 버전의 모델로 바꾼다.
- 쓰기: 항상 현재 버전으로 직렬화한다.
- 현재보다 새 버전 파일을 만나면(전방 호환 없음) 편집 불가로 처리하고, 앱 업데이트를 안내한다.
열기의 전체 흐름은 다음과 같다(1장의 판별과 이 장의 마이그레이션). 불변식 검사는 6. 공통 관심사의 “정합성”이다.
sequenceDiagram participant S as 셸 (DocumentStore) participant E as editor participant F as core/파일 형식 S->>S: 파일을 읽는다 S->>+E: open({ store, text: SVG 문자열 }) E->>+F: deserialize(SVG 문자열) F->>F: XML 파싱, metadata 안의 모델 요소 찾기 alt 모델 요소 없음 · JSON 손상 F-->>E: 오류: 편집 불가 (원본은 건드리지 않음) else 현재보다 새 버전 F-->>E: 오류: 앱 업데이트 안내 else 현재 버전 이하 F->>F: 마이그레이션 v(n)→…→현재 F->>F: 불변식 검사 F-->>-E: 문서(내용 + 뷰 상태) end E-->>-S: onStatus (열렸으면 파일 이름, 아니면 이유)
6. 미결정 사항
아직 없음.
7. 프로토타입과 다른 곳
프로토타입(journal/assets/2026-10-10-ns-prototype.html)은 버리는 코드이고, 그 파일은 이 형식의 v1이 아닙니다. 제품은 프로토타입의 version: 0 파일을 열지 않습니다. 모델 요소가 없는 파일과 같이 편집할 수 없음으로 다룹니다(1장 3) → ADR-0035
- 모델을
<metadata id="ariadne-nsd-model">안에 바로 넣는다(네임스페이스가 있는 모델 요소 없음).version: 0이다. - 헤더 텍스트를 Method도
event필드에 둔다. 분기는yes·no·c0…, 접기 영역은 블록처럼type: "range"와children을 가진 컨테이너 노드로 둔다(아키텍처는 “줄에 붙은 마커”). - 펴 보인 곳의 접기 영역을 문서 맨 위의
siteFolds에 둔다(이 명세는 호출 블록에 딸림). - 서브셋 글꼴을 넣지 않고, 블록 텍스트의 언어와 결과 기호를 저장하지 않는다.