모델 JSON 스키마

모델 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이 원본입니다. 이 문서는 그 모양을 스키마의 눈으로 다시 보입니다.
  • 모델의 TypeScript 타입과 불변식은 1. 타입과 3. 불변식에 있습니다.
  • 스키마는 모양만 봅니다. 이 버전이 지원하는 값(텍스트의 언어, 테마, 그림 문구의 언어)만 나열하고, 파일이 지켜야 하지만 모양으로는 적을 수 없는 규칙은 앱의 파서가 봅니다(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로 담깁니다.

필드타입필수허용 값설명
formatstring필수"ariadne-nsd"만형식의 이름. 항상 "ariadne-nsd"
versioninteger필수1만형식 버전. 이 버전은 1이다. 더 높으면 앱이 새 버전을 받으라고 알리고, 0은 프로토타입의 파일이라 열지 않는다
settingssettings필수-문서 설정
diagrams다이어그램의 배열, 1개 이상필수-다이어그램의 목록. 렌더링하는 순서다
viewview필수-뷰 상태. 접힘과 펴 보기는 실행 취소의 대상이고, 이름 띠와 결과 기호는 아니다

2.2 settings (문서 설정)

문서와 함께 저장되어 파일을 받은 사람에게도 같게 보이는 설정입니다.

필드타입필수허용 값설명
textKindstring필수"plain" · "c" · "cpp" · "java" · "javascript" · "python" · "bash"블록 텍스트의 언어. 구문 강조의 색만 정하고 글꼴과 레이아웃은 바꾸지 않는다
themestring필수"default" · "dark" · "high-contrast" · "print"테마의 이름. 색 값은 기록하지 않는다
headStylestring필수"title" · "shape"헤더를 렌더링하는 모양: 다이어그램 위의 제목처럼(title), 또는 모양으로(shape)
localestring생략 가능"en" · "ko"편집기가 렌더링 결과에 표시하는 문구(참 · 거짓, default 등)의 언어. 없으면 연 사람의 화면 언어로 읽는다
textOutlinesboolean생략 가능-텍스트를 외곽선으로 저장한다. true일 때만 기록한다

2.3 다이어그램

헤더 하나(없을 수 있음)와 본문 블록들입니다.

필드타입필수허용 값설명
idstring필수d1, d2 … (^d[1-9][0-9]*$)다이어그램의 id
headhead생략 가능-헤더. 헤더가 없는 다이어그램은 이 키를 기록하지 않는다
body블록의 배열, 1개 이상필수-본문의 블록들. 위에서 아래로 렌더링한다
folds접기 영역의 배열생략 가능-본문 줄의 접기 영역. 비면 기록하지 않는다

2.4 head (헤더)

다이어그램의 머리입니다. Event는 일이 일어날 때의 흐름, Method는 호출 블록이 호출할 수 있는 흐름입니다.

필드타입필수허용 값설명
kindstring필수"method" · "event"헤더의 종류
textstring필수-헤더의 이름. Method면 그것을 호출하는 호출 블록이 이 이름을 보인다

2.5 view (뷰 상태)

문서를 어떻게 보고 있었는지입니다. 문서의 id를 약하게 가리켜, 없는 id가 있어도 깨진 파일이 아닙니다. 새 문서는 {"folded":[],"opened":[],"bands":true,"resultSymbol":"←"}입니다.

필드타입필수허용 값설명
foldedstring의 배열필수-접힌 것(접기 영역, 펴 보인 곳의 접기 영역, If · Case의 분기, 반복 블록)의 id. 펴 보인 호출 블록 자리의 접힘은 호출 경로를 앞에 붙여 적는다(b4/는 그 자리가 자기 접힘과 접기 영역을 갖는다는 표시, b4/r3은 그 자리에서 접힌 분기 · 반복 블록)
openedstring의 배열의 배열필수b1, b2 … (^b[1-9][0-9]*$)그 위치에서 펴 보인 호출 블록의 경로. 바깥 호출 블록부터 안쪽으로 기록한다
bandsboolean필수-접기 영역 · 펴 보기의 이름 띠를 보이는가
resultSymbolstring필수"←" · "="호출 블록에서 결과와 호출 사이에 렌더링하는 기호

2.6 블록

kind로 가르는 다섯 꼴 가운데 하나입니다. 블록의 배열(body)은 비지 않습니다: 빈 분기에도 빈 처리 블록이 하나 있습니다.

꼴: 처리 블록 · If 블록 · Case 블록 · 반복 블록 · 호출 블록

2.7 처리 블록

텍스트를 한 줄 이상 담는 상자입니다.

필드타입필수허용 값설명
idstring필수b1, b2 … (^b[1-9][0-9]*$)블록의 id
kindstring필수"process"만블록의 종류
textstring필수-블록의 텍스트. 빈 블록은 ""

2.8 If 블록

조건과 두 분기입니다.

필드타입필수허용 값설명
idstring필수b1, b2 … (^b[1-9][0-9]*$)블록의 id
kindstring필수"if"만블록의 종류
textstring필수-조건
yes분기필수-조건이 참일 때의 분기
no분기필수-조건이 거짓일 때의 분기

2.9 Case 블록

가를 값과 값마다의 분기, 그리고 default 분기입니다.

필드타입필수허용 값설명
idstring필수b1, b2 … (^b[1-9][0-9]*$)블록의 id
kindstring필수"case"만블록의 종류
textstring필수-가를 값
armsCase의 분기의 배열필수-값마다의 분기. 왼쪽부터 렌더링한다
otherwise분기생략 가능-default 분기. 없으면 기록하지 않는다

2.10 반복 블록 (While · Do-While · For)

조건 칸과 반복할 블록들입니다. While은 조건 칸이 위, Do-While은 아래입니다.

필드타입필수허용 값설명
idstring필수b1, b2 … (^b[1-9][0-9]*$)블록의 id
kindstring필수"while" · "doWhile" · "for"블록의 종류
textstring필수-조건(For는 반복의 머리)
body블록의 배열, 1개 이상필수-반복할 블록들
folds접기 영역의 배열생략 가능-본문 줄의 접기 영역. 비면 기록하지 않는다

2.11 호출 블록

다른 흐름을 호출하는 블록입니다. 호출 대상의 이름은 복사해 갖지 않고 대상으로 가리킵니다.

필드타입필수허용 값설명
idstring필수b1, b2 … (^b[1-9][0-9]*$)블록의 id
kindstring필수"call"만블록의 종류
target호출 대상필수-호출 대상
argsstring필수-인자
resultstring필수-반환값을 받는 곳. 없으면 ""
siteFolds펴 보인 곳의 접기 영역의 배열생략 가능-이 호출 블록을 펴 보인 곳(안에 보이는 Method의 블록) 위의 접기 영역. 처음 펼 때 복사한 Method의 접기 영역도 여기 있다. 비면 기록하지 않는다

2.12 분기 (yes · no · otherwise)

If의 두 분기와 Case의 default 분기입니다.

필드타입필수허용 값설명
idstring필수r1, r2 … (^r[1-9][0-9]*$)분기의 id
labelstring생략 가능-렌더링되는 참 · 거짓이나 default 대신 쓰는 이름. 편집하지 않았으면 기록하지 않는다
body블록의 배열, 1개 이상필수-분기의 블록들
folds접기 영역의 배열생략 가능-분기 줄의 접기 영역. 비면 기록하지 않는다

2.13 Case의 분기 (arms의 원소)

Case에서 값 하나의 분기입니다.

필드타입필수허용 값설명
idstring필수r1, r2 … (^r[1-9][0-9]*$)분기의 id
labelstring필수-분기의 값. 그 분기의 라벨로 렌더링한다
body블록의 배열, 1개 이상필수-분기의 블록들
folds접기 영역의 배열생략 가능-분기 줄의 접기 영역. 비면 기록하지 않는다

2.14 접기 영역 (folds의 원소)

한 줄 안의 연속된 블록 범위와 그 이름입니다.

필드타입필수허용 값설명
idstring필수f1, f2 … (^f[1-9][0-9]*$)접기 영역의 id
firststring필수b1, b2 … (^b[1-9][0-9]*$)범위의 처음 블록의 id
laststring필수b1, b2 … (^b[1-9][0-9]*$)범위의 끝 블록의 id
namestring생략 가능-이름. 없으면 기록하지 않는다

2.15 펴 보인 곳의 접기 영역 (siteFolds의 원소)

펴 보인 호출 블록 안에 보이는 Method의 블록 위에 만든 접기 영역입니다. 가장 바깥의 호출 블록에 속합니다.

필드타입필수허용 값설명
idstring필수f1, f2 … (^f[1-9][0-9]*$)접기 영역의 id
viastring의 배열필수b1, b2 … (^b[1-9][0-9]*$)이 호출 블록 안에서 거쳐 펴 보인 안쪽 호출 블록의 id. 바로 안이면 []
firststring필수b1, b2 … (^b[1-9][0-9]*$)범위의 처음 블록(호출하는 Method의 블록)의 id. 없어지면 범위가 줄어든다
laststring필수b1, b2 … (^b[1-9][0-9]*$)범위의 끝 블록의 id
namestring생략 가능-이름. 없으면 기록하지 않는다

2.16 호출 대상

kind로 가르는 네 꼴 가운데 하나입니다.

꼴: 호출 대상: local · 호출 대상: named

2.17 호출 대상: local

이 문서 안의 Method 다이어그램입니다.

필드타입필수허용 값설명
kindstring필수"local"만대상의 종류
diagramstring필수d1, d2 … (^d[1-9][0-9]*$)호출하는 Method 다이어그램의 id

2.18 호출 대상: named

다이어그램이 아니라 블록에 적은 이름입니다(라이브러리 함수, 아직 그리지 않은 서브루틴, 지워진 Method의 이름 등).

필드타입필수허용 값설명
kindstring필수"named"만대상의 종류
namestring필수-블록에 적은 이름

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. 스키마 원문