jxn 0.1 명세

jxn(JSON eXplained Notation)은 JSON 의 형태와 뜻을 정의하는 언어(스키마 언어)다 -- 사람이 읽는 정의에 뜻과 관계를 적고, JSON Schema 로 옮긴다. 이 문서는 jxn 0.1 의 명세다. 2026-09-26 확정. 1.0 전(0.x)에는 뒤로 깨는 변경이 있을 수 있다 -- 바뀐 것은 CHANGELOG.md 에 적는다.

• 예는 전부 합성이다 (주문 · 상품 · 카탈로그 · 주문 이력).
• ```jxn 블록은 완결된 파일이다 -- 참조 구현의 시험이 읽어 진단이 없어야 한다. ```text 블록은 조각이다.
• 이 문법이 왜 이렇게 되었나는 notes/ 에 있다 -- 처음 적으며 부딪힌 문제(문법-노트-0.1.md)와 결정(문법-0.1-결정.md).

0. 한눈에#

파일로도 있다 -- examples/order/order.jxn (인스턴스 order.json).

jxn 0.1

-- # 목록과 주석

list owner {                         -- 닫힌 목록 (정의 파일이 스스로 선언한다)
  customer                           -- 고객이 넣은 값
  system                             -- 시스템이 계산한 값
  warehouse                          -- 창고 시스템이 돌려준 원문
}
tag owner  : set<owner>  inherit need    -- @owner 주석. 조상에서 이어받고, 모든 키에 있어야 한다
tag status need                          -- jxn 이 주는 status 를 모든 키에 요구한다

anchor change  = order.history : Change  -- 이웃 주소 change[-1] = 바로 앞 Change (Note 는 건너뛴다)
anchor catalog external                  -- 인스턴스 밖의 것

-- # 주문

root order {                         -- 주문 하나
  @owner system  @status stable
  id: string                         -- 주문 번호
    @status stable
  items: array<Item> min 1           -- 담은 상품
    @owner customer  @status stable
  total: number                      -- 합계 금액
    @status stable
    derived-from items[].price       -- 담은 상품 값의 합
  method: "card" | "cash"            -- 결제 방법
    @status stable
  payment?: by method {              -- 결제 -- 방법이 모양을 정한다
    @status draft
    card => { last4: string }        -- 카드 끝 네 자리
      @status draft
      -- 한 줄 object 의 키(last4)는 이 갈래의 주석을 쓴다
    cash => absent                   -- 현금이면 없다
  }
  history: array<Change | Note>      -- 주문 이력
    @status stable
    -- 고치지 않고 붙이기만 한다. 갈래는 어느 키가 있나로 갈린다
}

def Item {                           -- 담은 상품 하나
  @status stable
  sku: string                        -- 상품 코드
    @status stable
    refers-to catalog.items
  price: number                      -- 담을 때의 값
    @status stable
}

def Change {                         -- 단계가 바뀐 기록
  @status stable
  from: State                        -- 바뀌기 전 단계
    @status stable
    equals change[-1].to             -- 바로 앞 변경의 도착 단계에서 출발한다
  to: State                          -- 바뀐 단계
    @status stable
}

def Note {                           -- 사람이 남긴 메모
  @owner customer  @status draft
  text: string                       -- 메모 글
    @status draft
}

def State = "open" | "paid" | "shipped"   -- 주문의 단계
  @status stable

1. 파일과 줄 -- 문법은 줄 단위다#

• 파일은 UTF-8 글이고 확장자는 .jxn 이다. 줄 끝은 LF · CRLF 둘 다 된다.
• 한 줄은 첫 낱말로 종류가 정해진다. 들여쓰기는 모양일 뿐 뜻이 없다 (블록은 { } 가 가른다).
• 빈 줄은 뜻이 없다.

• 줄 끝의 -- 는 그 줄의 뜻이다 -- 선언이면 description, 관계면 note, 값이면 그 값의 description. 따옴표 밖에서, 줄 머리이거나 앞이 공백인 첫 -- 에서 자른다. 뒤의 -- 는 글이다.
• 뜻은 한 줄, 풀이는 여러 줄. 선언의 뜻(한 문장)은 줄 끝 -- 에만 쓴다. 더 할 말은 뒤따르는 말 줄로 쓴다 -- 여러 줄 description 표지는 두지 않는다.
• 주석 · 관계 · 말 · 물음은 바로 앞 선언에 붙는다. { 를 연 선언이면 그 블록 안의 첫 선언 전까지 그 선언의 것이다 -- 블록 전체에 대한 말은 블록 첫머리(여는 줄 바로 아래)에 쓴다. 말 · 물음 줄은 이 이어짐을 끊지 않는다.
• 머리 줄 바로 뒤의 말 줄(다음 선언 전까지)은 그 머리의 풀이다.
• } 뒤에는 앞 선언이 없다 -- 닫은 뒤에 오는 주석 · 관계 줄은 오류다.
• jxn 머리 줄보다 위의 말 줄은 파일의 풀이다.

2. 구성 -- 꼴 · 뜻 · 예 · JSON Schema#

2-1. 닫힌 목록 list#

list owner {
  customer        -- 고객이 넣은 값
  "external api"  -- 공백이 있으면 따옴표
  0               -- 수도 된다
}

• 정의 파일이 제 목록을 선언한다 (jxn 은 틀만 준다). 값마다 뜻을 단다.
• 값의 JSON 타입은 JSON 과 같다 -- 따옴표 없는 수는 number, 나머지는 string ("0" 은 string). enum 값 · 갈래 이름표도 같다.
• JSON Schema: 목록 자체는 나가지 않는다. 그 목록을 값으로 쓰는 주석이 x-owner 로 나가고, jxn check 가 값이 목록 안인지 본다.

2-2. 주석 선언 tag#

tag note    : text                          -- 글
tag src     : set<text>                     -- 글 여럿
tag owner   : set<owner>   inherit need     -- 목록의 값 하나 이상
tag audience: set<role> | all  inherit need -- 목록 값들, 또는 낱말 all 홀로
tag stage   : stage        inherit          -- 목록의 값 하나
tag status  need                            -- jxn 이 준 주석에 방식만 더한다 (2-15)

• 값의 꼴: text · 목록 이름(하나) · set<목록> · set<text>(쉼표로 여럿) · 낱말(홀로 쓰는 값). | 로 잇는다.
• 방식: inherit = 가장 가까운 조상의 값을 이어받는다. need = 이어받기를 푼 뒤 모든 키에 있어야 한다. 둘 다 없으면 선택.
• 쓰는 곳: @owner customer, system · 한 줄에 여럿 @owner system @status stable. 공백이 든 값은 따옴표 -- @note "두 낱말".
• 이름 status 는 jxn 이 준다 -- 파일이 list status 나 타입을 단 tag status : ... 를 선언하면 오류다.
• JSON Schema: x-<tag>. 값이 하나면 스칼라, 여럿이면 배열.

2-3. 정의 root · def#

root order { ... }                 -- 인스턴스의 뿌리 -- 파일에 하나
def Item { ... }                   -- 이름 붙은 object
def Method = "card" | "cash"       -- 이름 붙은 타입식
def Money = number min 0           -- 주석 · 관계 줄이 뒤따를 수 있다
  @status stable

• def 이름은 대문자로 시작한다 -- 타입식에서 기본 타입 · 낱말과 갈린다.
• JSON Schema: root -> 문서의 뿌리, def -> $defs/<이름>, 쓰는 곳은 $ref.

2-4. 키 -- 늘 있다 · 없을 수 있다 · null 일 수 있다#

id: string                  -- 늘 있다                  -> required
note?: string               -- 없을 수 있다             -> required 에 넣지 않는다
coupon: null | Coupon       -- 늘 있되 null 일 수 있다  -> required + anyOf [null, ...]
"ship to": Address          -- 낱말 꼴이 아닌 키는 따옴표

• "없을 수 있다" 와 "null 일 수 있다" 를 가른다. 칸이 고정된 기록(늘 있고, 할 일이 없으면 null)에서 이 차이가 뜻이다.
• | 의 차례에는 뜻이 없다 (null | T = T | null). 여러 줄 object 에서 null | { 처럼 앞에 두기를 권한다 -- null 가능이 첫 줄에 보인다.
• 낱말 꼴 = 영문자 · _ · $ 로 시작하고 영문자 · 숫자 · _ · $ · - 로 이어진다. 그 밖의 키는 따옴표로 쓴다.

2-5. 타입식#

lines: array<{              -- 여러 줄 object 는 `{` 로 열고 `}>` 로 닫는다
  sku: string
  qty: integer min 1
}>
stock: map<sku -> integer>  -- 상품 코드마다 재고

2-6. 값마다 뜻을 다는 허용 값 enum { }#

state: enum {                    -- 주문의 단계
  @status stable
  -- 반품은 다음 판에서 정한다      (state 의 풀이 -- 블록 첫머리)
  -- # 담는 동안
  open                           -- 담는 중
  held        @since 2           -- 잠시 멈춤
  -- # 값을 치른 뒤
  paid        @since 2           -- 결제됨
    -- 부분 결제는 아직 없다        (paid 의 풀이)
  shipped     @since 3  @status draft   -- 보냄
}

• 값 줄 = 값 · (선택) 한 줄 주석 · 줄 끝 -- 뜻. 값마다 주석이 다를 때(처음 나온 판 등) 쓴다.
• 머리(-- #)로 값을 무리로 가를 수 있다 -- jxn doc 이 무리째 보인다.
• JSON Schema: enum: [...] + x-jxn-values: [{value, description, x-...}].

2-7. 펼치기 ...Name#

def Address { street: string, city: string }
shipTo: {
  ...Address
  note?: string            -- Address 에 키 하나를 더한다
}

• JSON Schema: 안에 풀어 넣는다. 닫힌 def 를 $ref 로 부르면 키를 더할 수 없다 (2020-12 에서 additionalProperties: false 는 $ref 너머를 모른다). $defs 가 겹쳐 나오는 것은 감수한다.

2-8. 갈래 by#

키 하나의 모양을 이웃 키가 정한다 (필드 갈래):

method: "card" | "cash" | "voucher"
payment?: by method {                 -- 결제 내용
  card => { last4: string }
  voucher => Voucher
  cash => absent                      -- 현금이면 payment 키가 없다
}

object 의 키 집합을 한 키가 정한다 (object 갈래):

def Discount {
  kind: "percent" | "fixed"
  by kind {
    percent => { rate: number }       -- 이 갈래에서만 rate 가 있다
    fixed   => { amount: number }
  }
}

• 갈래 줄 = 값[, 값 ...] => 타입 -- 같은 모양의 값은 한 줄에 묶는다.
• 값 목록의 정본은 판별 키의 타입이다. 갈래의 이름표는 그 값을 빠짐없이 · 남김없이 · 겹침없이 덮어야 한다 -- 어긋나면 오류다. 필드 갈래에서 키가 없는 값은 absent 로 적는다.
• 갈래에도 주석 · 관계가 붙는다. 갈래 안에 적은 관계는 그 갈래의 조건을 when 에 저절로 더한다 -- jxn doc 은 합친 조건을 보인다.
• JSON Schema: 부모 object 의 allOf 에 갈래마다 {if: {properties: {method: {enum: [card]}}, required: [method]}, then: {properties: {payment: <T>}, required: [payment]}}. 부모는 unevaluatedProperties: false.

2-9. 키가 있나로 갈리는 합 A | B#

history: array<Change | Note>     -- Change 는 from 이, Note 는 text 가 있다

• 판별 값이 없다 -- 어느 키가 있나로 갈린다. object def 둘 이상의 합은 서로를 가르는 "반드시 있는 키" 가 있어야 한다 -- 없으면 오류다.
• JSON Schema: anyOf. 도구는 갈래 이름을 def 이름에서 짓는다.

2-10. 기대하는 모양 expect T#

reply: expect StockReply          -- 창고가 돌려준 원문. 모양이 어긋나도 그대로 적힌다
replyCheck: array<string>         -- 어긋난 칸 -- 어긋남은 여기가 말한다

• 밖에서 온 원문을 그대로 남기는 칸을 위한 것이다. 엄격히 검사하면 "어긋난 원문을 남겼다" 는 올바른 인스턴스가 떨어진다.
• JSON Schema: x-jxn-expect: <T> -- 표준 검사기는 무엇이든 통과시킨다.
• jxn check: 그 자리를 T 로 따로 대어 보고, 어긋남을 오류가 아닌 "어긋남" 급으로 낸다 (종료 코드 0). --strict 면 오류다.

2-11. 관계#

total: number
  derived-from items[].price              -- 담은 상품 값의 합
sku: string
  refers-to catalog.items                 -- 카탈로그에 있는 상품
from: State
  equals change[-1].to                    -- 바로 앞 변경의 도착 단계에서 출발한다
coupon?: Coupon
  adds-to cart.discounts                  -- 쿠폰을 넣으면 할인 목록에 들어간다
removed?: array<string>
  removes-from cart.items                 -- 뺀 상품 코드
paid: boolean
  sets order.locked                       -- 결제되면 주문이 잠긴다
refund?: Refund
  reason-of change[+1]  when change[+1].to == "refunded"

• 낱말은 열하나다 (jxn 이 준다). sets · clears 는 켜고 끄는 상태에만, 모음에 넣고 빼는 것은 adds-to · removes-from 으로.
• 한 번만 적는다 -- 주어 쪽에. 과녁 쪽의 거꾸로 읽기는 jxn doc 이 보인다.
• .sub rel ... -- 주어를 선언의 아래 키로 좁힌다. 공유 def 를 쓰는 자리에서 그 안쪽 키의 관계를 적을 때 쓴다:

  shipped => Parcel
    .carrier refers-to catalog.carriers

• JSON Schema: x-relations: [{sub?, rel, key, when?, note}].

2-12. 주소#

주소  := 앵커 [ "." 경로 ] | 경로          앵커가 없으면 home 에서
경로  := 조각 ("." 조각)*
조각  := 이름 | 이름"[]" | "*"             이름[] = 배열의 원소 · * = map 의 아무 키
앵커  := 이름 "[" ("+n" | "-n" | "*" | "..-n") "]" | 이름

선언:

home   order.history[]                    -- 앵커 없는 주소 = 주어가 든 이력 원소의 뿌리에서
anchor history = order.history            -- history[+1] · history[-1] = 바로 옆 원소
anchor change  = order.history : Change   -- change[-1] = 바로 앞 Change (다른 갈래는 건너뛴다)
anchor order   = order                    -- 뿌리
anchor catalog external                   -- 인스턴스 밖 -- 검사하려면 함께 받아야 한다

• [+n] [-n] = n 번째 뒤 · 앞. [*] = 아무 원소 (refers-to 의 과녁). [..-n] = n 번째 앞까지의 모든 원소 (범위).
• 이름 : Def = 배열 원소 가운데 그 갈래만 센다.
• home 이 없으면 home 은 뿌리다.
• 주소의 첫 이름이 앵커 이름이면 앵커다 -- 같은 이름의 키보다 앞선다.
• external 앵커는 인스턴스에 없는 것(참조 데이터 · 계산으로만 있는 상태)이다. 그 관계는 그것을 함께 받아야 검사된다.
• 앵커 없는 주소는 쓰는 자리마다 푼다. def 안의 관계라면 도구는 그 def 를 쓰는 자리마다 home 에서 주소를 풀어 보고, 한 곳이라도 안 풀리면 오류다. (배열 원소로 한 번만 쓰이는 def 는 home 이 하나라 잘 풀린다.)
• 이름[주소] (대괄호 안에 주소 -- 값으로 찾기)는 오류다. 외부 조인을 열 자리로 남겨 둔다 (5절).

2-13. 조건 when#

when   := 절 (" and " 절)*
절     := 주소 op 값
op     := "==" | "!=" | "in"
값     := JSON 값 | enum def 이름 (in 의 오른쪽)

예: when method == "card" · when state in ["paid", "shipped"] · when method in Method.

2-14. 이어받기#

• inherit 주석은 가장 가까운 조상에서 온다. 조상 = 감싼 object · 배열 · 갈래 · 쓰는 자리.
• 우선순위: def 안쪽 키에 적은 값 > 쓰는 자리에 적은 값 > def 머리에 적은 값 > 쓰는 자리가 조상에서 이어받은 값. "쓰는 자리" 는 def 를 곧장 타입으로 쓰는 키 · 갈래다 (k: D · k: null | D · k: array<D> · k: map<.. -> D> · k: expect D · v => D). 배열의 합(array<A | B>)에서는 원소마다 제 def 머리가 선다.
• 그러니 def 머리의 값은 조상의 값보다 가깝다 -- def 를 어디서 쓰든 따라간다. 쓰는 자리가 적어서 덮을 때만 진다.
• description · 풀이와 inherit 가 없는 주석(status 등)은 이어받지 않는다. 단, 타입이 def 하나뿐인 키에 -- 가 없으면 그 def 의 description 을 쓴다 (같은 뜻을 두 번 안 적으려고).
• "이 아래 일부만" 은 부모에 값을 달고 아래 키가 덮어 적는다. jxn doc 은 아래 키의 값이 갈리는 자리에 "(아래 일부 ...)" 를 보인다.

  shipTo: {
    @shared no
    street: string
    city: string
      @shared yes
  }

2-15. 상태 status -- jxn 이 준다#

• 정의 자체의 상태라 도메인과 상관없이 jxn 이 준다. 나머지 주석(누가 채우나 · 누가 읽나 · 출처 · 짧은 풀이 ...)은 모두 파일이 선언한다.
• 이어받지 않는다. 기본은 선택이고, tag status need 한 줄로 모든 키에 요구한다. 기본값은 없다 -- 적지 않은 것은 "없음" 으로 보인다.
• jxn doc: 트리 배지 · 점검 칸(없음 · draft · stub 인 키). 화면에서는 정함 · 초안 · 모름으로 보여도 된다.
• JSON Schema: x-jxn-status.

3. 한 표로 -- JSON Schema 로#

jxn 은 인스턴스에서 아무것도 추론하지 않는다 -- required 도 적힌 대로다. 예시 JSON 은 jxn doc 이 보여 주기에만 쓴다.

4. 오류#

아래는 틀린 파일이다 -- 도구는 JSON Schema 를 내지 않는다. 괄호 안은 참조 구현(jxn build)의 진단 코드다.

경고 -- 파일은 옳고 도구가 알린다.

5. 0.1 에 없는 것#

쓰는 곳이 없거나 한 곳이다 -- 쓰임이 요구할 때 연다 (INTENT 7절). 까닭은 notes/문법-0.1-결정.md C.

• need 에 범위 (need in Def.*)
• 범위 주소 [..-n] 에 조건
• 외부 조인 (when catalog[item.sku].kind == ...) -- 이름[주소] 는 그때까지 오류다
• map 의 키가 def 를 가리킬 때 propertyNames
• 갈래 이름표에 enum def 이름 (그 값 모두)
• 문자열 모양 (format · pattern) · 상태 deprecated
• home 여럿 · "제 원소" 주소 -- home 밖 배열의 원소 안에서 제 이웃 키를 가리키는 길 (P27)