모델 JSON(저장 파일의 <ans:document> 안과 공유 링크에 담기는 JSON)의 JSON Schema(draft 2020-12)를 사람이 읽도록 풀어 쓴 것입니다. 원본은 src/packages/core/schema/model.schema.json이고, 사이트에는 다른 AI와 프로그램을 위해 /model.schema.json으로 놓입니다 → 3.1 LLM · 에이전트를 위한 안내서
필드의 뜻, 기록하는 순서, 생략 규칙, 지원하지 않는 값을 만났을 때는 3. 모델 JSON이 원본입니다. 이 문서는 그 모양을 스키마의 눈으로 다시 보입니다.
스키마는 모양만 봅니다. 이 버전이 지원하는 값(텍스트의 언어, 테마, 그림 문구의 언어)만 나열하고, 파일이 지켜야 하지만 모양으로는 적을 수 없는 규칙은 앱의 파서가 봅니다(3장).
이 문서는 손으로 고치지 않습니다
src/scripts/model-schema-doc.mjs가 스키마에서 만듭니다(src/에서 pnpm schema-doc). 스키마의 설명은 다른 프로그램을 위한 영어이고, 이 문서의 한국어 설명은 src/packages/core/schema/model.schema.ko.json에 있습니다. 설명이 빠진 객체나 필드가 있거나 이 문서가 스키마와 다르면 pnpm check가 실패합니다.
1. 객체의 관계
채운 마름모(◆)는 담는 것과 그 수, 빈 삼각형(△)은 oneOf의 꼴입니다(kind로 가름). 상자 안은 다른 객체를 담지 않는 필드입니다.
classDiagram
class Document {
format
version
}
class Settings {
textKind
theme
headStyle
locale
textOutlines
}
class Diagram {
id
}
class Head {
kind
text
}
class View {
folded
opened
bands
resultSymbol
}
class Block {
<<oneOf>>
id
kind
}
class ProcessBlock {
text
}
class IfBlock {
text
}
class CaseBlock {
text
}
class LoopBlock {
text
}
class CallBlock {
args
result
}
class Branch {
id
label
}
class Arm {
id
label
}
class Fold {
id
first
last
name
}
class SiteFold {
id
via
first
last
name
}
class CallTarget {
<<oneOf>>
kind
}
class LocalTarget {
diagram
}
class NamedTarget {
name
}
Document *-- "1" Settings : settings
Document *-- "1..*" Diagram : diagrams
Document *-- "1" View : view
Diagram *-- "0..1" Head : head
Diagram *-- "1..*" Block : body
Diagram *-- "*" Fold : folds
Block <|-- ProcessBlock
Block <|-- IfBlock
Block <|-- CaseBlock
Block <|-- LoopBlock
Block <|-- CallBlock
IfBlock *-- "1" Branch : yes
IfBlock *-- "1" Branch : no
CaseBlock *-- "*" Arm : arms
CaseBlock *-- "0..1" Branch : otherwise
LoopBlock *-- "1..*" Block : body
LoopBlock *-- "*" Fold : folds
CallBlock *-- "1" CallTarget : target
CallBlock *-- "*" SiteFold : siteFolds
Branch *-- "1..*" Block : body
Branch *-- "*" Fold : folds
Arm *-- "1..*" Block : body
Arm *-- "*" Fold : folds
CallTarget <|-- LocalTarget
CallTarget <|-- NamedTarget
2. 객체마다의 필드
“필수”는 반드시 기록하는 키, “생략 가능”은 정해진 경우에 기록하지 않는 키입니다(언제 생략하는지는 설명 칸과 3.3 노드별 필드). 어느 객체든 표에 없는 키가 있으면 스키마도 파서도 거절합니다(additionalProperties: false).
2.1 문서
모델 JSON의 맨 위 객체입니다. 저장 파일의 <ans:document> 안에, 공유 링크에는 봉투의 model로 담깁니다.
필드
타입
필수
허용 값
설명
format
string
필수
"ariadne-nsd"만
형식의 이름. 항상 "ariadne-nsd"
version
integer
필수
1만
형식 버전. 이 버전은 1이다. 더 높으면 앱이 새 버전을 받으라고 알리고, 0은 프로토타입의 파일이라 열지 않는다
다이어그램의 머리입니다. Event는 일이 일어날 때의 흐름, Method는 호출 블록이 호출할 수 있는 흐름입니다.
필드
타입
필수
허용 값
설명
kind
string
필수
"method" · "event"
헤더의 종류
text
string
필수
-
헤더의 이름. Method면 그것을 호출하는 호출 블록이 이 이름을 보인다
2.5 view (뷰 상태)
문서를 어떻게 보고 있었는지입니다. 문서의 id를 약하게 가리켜, 없는 id가 있어도 깨진 파일이 아닙니다. 새 문서는 {"folded":[],"opened":[],"bands":true,"resultSymbol":"←"}입니다.
필드
타입
필수
허용 값
설명
folded
string의 배열
필수
-
접힌 것(접기 영역, 펴 보인 곳의 접기 영역, If · Case의 분기, 반복 블록)의 id. 펴 보인 호출 블록 자리의 접힘은 호출 경로를 앞에 붙여 적는다(b4/는 그 자리가 자기 접힘과 접기 영역을 갖는다는 표시, b4/r3은 그 자리에서 접힌 분기 · 반복 블록)
opened
string의 배열의 배열
필수
b1, b2 … (^b[1-9][0-9]*$)
그 위치에서 펴 보인 호출 블록의 경로. 바깥 호출 블록부터 안쪽으로 기록한다
bands
boolean
필수
-
접기 영역 · 펴 보기의 이름 띠를 보이는가
resultSymbol
string
필수
"←" · "="
호출 블록에서 결과와 호출 사이에 렌더링하는 기호
2.6 블록
kind로 가르는 다섯 꼴 가운데 하나입니다. 블록의 배열(body)은 비지 않습니다: 빈 분기에도 빈 처리 블록이 하나 있습니다.
다이어그램이 아니라 블록에 적은 이름입니다(라이브러리 함수, 아직 그리지 않은 서브루틴, 지워진 Method의 이름 등).
필드
타입
필수
허용 값
설명
kind
string
필수
"named"만
대상의 종류
name
string
필수
-
블록에 적은 이름
3. 스키마가 보지 못하는 규칙
아래는 스키마를 통과해도 앱이 깨진 파일(damaged)로 거절하는 것입니다. 파서(src/packages/core/src/format/parse-model.ts)가 모양을 읽은 뒤 모델의 불변식(src/packages/core/src/model/invariants.ts)을 검사합니다. 번호는 3. 불변식의 번호입니다. 테스트가 이 규칙마다 스키마는 통과하고 파서는 거절하는 모델을 만들어 검증합니다(src/packages/core/node/model-schema.test.ts).
규칙
불변식
문서 안의 id(다이어그램, 블록, 분기, 접기 영역, 펴 보인 곳의 접기 영역)는 모두 다르다
3
Case는 분기가 적어도 하나 있다: arms가 비었으면 otherwise가 있어야 한다
4
접기 영역의 first와 last는 그 접기 영역이 속한 줄(같은 body)의 블록이고, first가 last보다 앞이거나 같다
5
한 줄의 접기 영역들은 서로 떨어져 있거나 하나가 다른 하나를 온전히 품는다(부분 중첩되지 않음). 범위가 똑같은 접기 영역은 둘이 없다
5
local 호출 대상의 diagram은 이 문서의 다이어그램이고, 그 헤더는 Method다
6
헤더도 내용도 없는 다이어그램(head가 없고 본문이 빈 처리 블록 하나)은 다이어그램이 그것 하나일 때만 있다
7
스키마가 이미 보는 불변식도 있습니다: 다이어그램이 적어도 하나(1, diagrams의 minItems), 비지 않는 줄(2, body의 minItems), If의 두 분기(4, yes · no가 필수).
거꾸로 파서가 스키마보다 너그러운 곳도 있습니다. 뒤의 버전이 쓴 파일을 이 버전이 열 수 있게 하려는 것입니다 → 3.3 노드별 필드
textKind · locale이 이 버전이 지원하지 않는 문자열이면 파서는 일반 텍스트 · 연 사람의 화면 언어로 그리고, 받은 값은 저장할 때 그대로 기록한다. theme이 지원하지 않는 이름이면 기본 테마로 그리고 값은 그대로 둔다. 스키마는 이 버전이 지원하는 값만 받는다.
version이 1보다 낮으면 파서는 마이그레이션해 읽는다(0은 프로토타입이라 열지 않음). 스키마는 지금 판(1)만 받는다.
블록을 가리키는 id(접기 영역의 first · last, via, view의 목록)는 꼴만 본다. view와 펴 보인 곳의 접기 영역은 없는 id를 가리켜도 된다(약한 참조).
4. 스키마 원문
model.schema.json (펼쳐 보기)
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://ariadnensd.com/model.schema.json", "title": "AriadneNSD model JSON, format version 1", "description": "The shape of an AriadneNSD document's model JSON: the JSON inside a saved .ns.svg file and inside a share link. Spec: https://github.com/reddiana/AriadneNSD/blob/main/docs/05-spec/01-file-format.md (section 3). How to make a share link from it: https://ariadnensd.com/llms.txt. This schema checks the shape only, with the values this version knows; the app also checks the invariants: every id is used once in the whole document, a local call names a Method diagram, a fold's first and last blocks are in its sequence in that order, and a diagram with neither a header nor blocks is the only diagram.", "type": "object", "additionalProperties": false, "required": ["format", "version", "settings", "diagrams", "view"], "properties": { "format": { "const": "ariadne-nsd" }, "version": { "const": 1 }, "settings": { "type": "object", "additionalProperties": false, "required": ["textKind", "theme", "headStyle"], "properties": { "textKind": { "description": "The language of the text in blocks, for syntax colors only.", "enum": ["plain", "c", "cpp", "java", "javascript", "python", "bash"] }, "theme": { "enum": ["default", "dark", "high-contrast", "print"] }, "headStyle": { "description": "How headers are drawn: as a title above the diagram, or as a shape.", "enum": ["title", "shape"] }, "locale": { "description": "The language of the words the editor draws (True/False, default). Left out: the opener's screen language.", "enum": ["en", "ko"] }, "textOutlines": { "description": "Save the text as outlines. Written only when true.", "type": "boolean" } } }, "diagrams": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "required": ["id", "body"], "properties": { "id": { "$ref": "#/$defs/diagramId" }, "head": { "description": "Left out for a diagram without a header.", "type": "object", "additionalProperties": false, "required": ["kind", "text"], "properties": { "kind": { "enum": ["method", "event"] }, "text": { "type": "string" } } }, "body": { "$ref": "#/$defs/body" }, "folds": { "$ref": "#/$defs/folds" } } } }, "view": { "description": "How the document was being viewed. For a new document: {\"folded\":[],\"opened\":[],\"bands\":true,\"resultSymbol\":\"←\"}.", "type": "object", "additionalProperties": false, "required": ["folded", "opened", "bands", "resultSymbol"], "properties": { "folded": { "type": "array", "items": { "type": "string" } }, "opened": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/$defs/blockId" } } }, "bands": { "type": "boolean" }, "resultSymbol": { "enum": ["←", "="] } } } }, "$defs": { "diagramId": { "type": "string", "pattern": "^d[1-9][0-9]*$" }, "blockId": { "type": "string", "pattern": "^b[1-9][0-9]*$" }, "branchId": { "type": "string", "pattern": "^r[1-9][0-9]*$" }, "foldId": { "type": "string", "pattern": "^f[1-9][0-9]*$" }, "body": { "description": "Blocks drawn top to bottom. Never empty: an empty branch holds an empty process block.", "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/block" } }, "folds": { "description": "Fold regions over blocks of this sequence. May be left out when empty.", "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "first", "last"], "properties": { "id": { "$ref": "#/$defs/foldId" }, "first": { "$ref": "#/$defs/blockId" }, "last": { "$ref": "#/$defs/blockId" }, "name": { "type": "string" } } } }, "branch": { "type": "object", "additionalProperties": false, "required": ["id", "body"], "properties": { "id": { "$ref": "#/$defs/branchId" }, "label": { "description": "Replaces the drawn True/False or default.", "type": "string" }, "body": { "$ref": "#/$defs/body" }, "folds": { "$ref": "#/$defs/folds" } } }, "arm": { "type": "object", "additionalProperties": false, "required": ["id", "label", "body"], "properties": { "id": { "$ref": "#/$defs/branchId" }, "label": { "type": "string" }, "body": { "$ref": "#/$defs/body" }, "folds": { "$ref": "#/$defs/folds" } } }, "siteFold": { "description": "A fold region over blocks seen inside an opened call block.", "type": "object", "additionalProperties": false, "required": ["id", "via", "first", "last"], "properties": { "id": { "$ref": "#/$defs/foldId" }, "via": { "type": "array", "items": { "$ref": "#/$defs/blockId" } }, "first": { "$ref": "#/$defs/blockId" }, "last": { "$ref": "#/$defs/blockId" }, "name": { "type": "string" } } }, "callTarget": { "oneOf": [ { "description": "A Method diagram in this document.", "type": "object", "additionalProperties": false, "required": ["kind", "diagram"], "properties": { "kind": { "const": "local" }, "diagram": { "$ref": "#/$defs/diagramId" } } }, { "description": "A name written in the block, not a diagram.", "type": "object", "additionalProperties": false, "required": ["kind", "name"], "properties": { "kind": { "const": "named" }, "name": { "type": "string" } } } ] }, "block": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": ["id", "kind", "text"], "properties": { "id": { "$ref": "#/$defs/blockId" }, "kind": { "const": "process" }, "text": { "type": "string" } } }, { "type": "object", "additionalProperties": false, "required": ["id", "kind", "text", "yes", "no"], "properties": { "id": { "$ref": "#/$defs/blockId" }, "kind": { "const": "if" }, "text": { "type": "string" }, "yes": { "$ref": "#/$defs/branch" }, "no": { "$ref": "#/$defs/branch" } } }, { "type": "object", "additionalProperties": false, "required": ["id", "kind", "text", "arms"], "properties": { "id": { "$ref": "#/$defs/blockId" }, "kind": { "const": "case" }, "text": { "type": "string" }, "arms": { "type": "array", "items": { "$ref": "#/$defs/arm" } }, "otherwise": { "$ref": "#/$defs/branch" } } }, { "type": "object", "additionalProperties": false, "required": ["id", "kind", "text", "body"], "properties": { "id": { "$ref": "#/$defs/blockId" }, "kind": { "enum": ["while", "doWhile", "for"] }, "text": { "type": "string" }, "body": { "$ref": "#/$defs/body" }, "folds": { "$ref": "#/$defs/folds" } } }, { "type": "object", "additionalProperties": false, "required": ["id", "kind", "target", "args", "result"], "properties": { "id": { "$ref": "#/$defs/blockId" }, "kind": { "const": "call" }, "target": { "$ref": "#/$defs/callTarget" }, "args": { "type": "string" }, "result": { "description": "Receives the return value; empty for none.", "type": "string" }, "siteFolds": { "type": "array", "items": { "$ref": "#/$defs/siteFold" } } } } ] } }}