규약은 카테고리별 모양을 스키마로 강제하지 않는다. JSON Schema(규약 2.2절)와 그 파생 zod 검증기는 62종(대분류 21 + 결합 41) 전체가 공통 한 벌이다 — type: Gauge인데 measure가 없어도 스키마 검증은 통과한다. 카테고리 적합성은 검증이 아니라 검색 단계에서 세 겹으로 정해진다:
| 겹 | 무엇이 정하나 | 어긋나면 |
|---|
| ① 성립 조건 | capability-table 2절 — 개수 범위 + 내용 조건(dataset 모양· 필수 필드) | 그 카테고리가 후보에서 빠지고 fallback으로 내려간다 (규약 5절) |
| ② 읽는 필드 선언 | capability reads — 그 카테고리가 읽는 entity 필드· relation· params 목록 | 목록 밖 필드는 합법이지만 무시된다 (조용한 손실) |
| ③ params 어휘 | capability-table 2절 속성 열 — 키와 값 어휘· 기본값 | 스키마상 params는 자유 객체 — 오타· 환각 키도 통과 후 무시 |
entity 스키마는 공통이고, 카테고리마다 "읽는 entity 필드"만 다르다. 15개 필드(label· items[]· value· unit· period· emphasis· weight· speaker· author· source· avatar· organization· children[]· values[]· components[])는 어느 블록에서나 합법이지만, 예컨대 period는 Timeline이, weight는 Pyramid가, speaker는 DialogueChat이 읽는다 — 각 카드의 "선택 내용" 행이 그 목록이다. decoration만 카테고리 무관 공통이다(ornament· background 각각 prefer/indifferent/avoid — 내용이 아니라 검색 선호 신호).
그래서 아래 각 카드의 "유효한 모양"은 ①을 채우고 ②· ③이 읽는 필드만 쓴 YAML이다. 초록 표시는 정본 예시(yaml-examples.md) 원문이고, 주황 표시 25종은 정본 예시가 아직 없어 capability 행에서 유도한 골격이다 — 구조 감각용 참고로만 쓰고, 정본 예시 추가 전까지 프롬프트· 골든셋에 그대로 옮기지 않는다.
공통 골격의 실제 모양 — 카테고리 무관 부분 전량
version: "0.5" # 고정
title: 분기 실적 요약 # 필수 · 페이지 수준의 유일한 자유 텍스트
components: # 1개 이상 · 상한 없음
- type: RelationalComparison.VennDiagram # 생성기가 권하는 카테고리 (검색이 그대로 따를 의무는 없다 — 규약 6절)
alternatives: # "못 쓸 때 대신 쓸 카테고리를 선호 순서로" (규약 0절 5번)
- AttributeComparison.Versus # ⚠ fallback 체인을 복사하는 자리가 아님 (아래 설명)
params: { } # 표현 속성 — 허용 키는 카테고리별 (각 카드)
structure:
entities:
- { label: 자사 강점 } # id 는 적지 않는다 — 파싱 후 기계가 e1, e2… 부여
- { label: 경쟁사 강점 }
relations: # 블록 안 관계 · entities 의 label 을 가리킨다 (검증 때 id 로 해석)
- type: intersects # 어휘 2종: intersects(교집합) · compares(대비)
of: [자사 강점, 경쟁사 강점] # 2개 이상 · 그 블록 entities 에 없는 label 이면 검증 실패 → 재생성
desc: 양쪽 모두 보유 # 선택 · 교집합/대비 칸에 들어갈 텍스트
decoration: # 꾸밈구조 — 이 컴포넌트에만 적용 (규약 2.7절)
ornament: prefer # 축 2종이 전부: ornament(꾸밈 요소) · background(배경)
background: avoid # 값 3종이 전부: prefer · indifferent · avoid — 축 1개 이상 필수
relations: [] # page 수준 관계 — 자리만 예약, 생성기는 채우지 않는다
decoration: { } # page 수준 꾸밈 — 자리만 예약, 생성기는 채우지 않는다
| 필드 | 정확한 의미 | 흔한 오해 |
|---|
alternatives | 생성기가 입력 내용을 보고 판단한 대안 카테고리를 선호 순서로 적는 배열. 적혀 있으면 검색이 capability 의 fallback 순서보다 먼저 본다 (규약 6.1절 — fallback 은 "카테고리 대 카테고리만" 보는 정적 상수, alternatives 는 "그 입력의 내용"을 보는 생성물이라 둘을 함께 둔다). 단 6.1절 스스로 "가정이고 아직 실측이 없다" — optional 로 열어 두고 생성기 정책으로 켜고 끈다 | fallback 대상들을 복사해 넣는 자리가 아니다 — fallback 체인은 capability-table 3.2절에 고정돼 있고 검색이 소유한다(안 적어도 알아서 내려간다). 예: 같은 Pyramid 라도 층 크기 차이가 의미면 Staircase, 단순 3단 분류면 List — 이 판단은 내용을 읽어야 나온다(6.1절 예시) |
relations (블록 안) | entities 사이의 관계. intersects(교집합)· compares(대비) 2종, of는 label 참조 2개 이상, desc는 관계 칸 텍스트. 읽는 카테고리는 둘뿐 — VennDiagram(intersects)· Versus(compares) | 못 읽는 카테고리에 적어도 오류가 아니다 — 규약 1절 "선언되지 않은 것은 무시한다". fallback 때 관계를 못 그리는 도착지면 P7 로 처리 |
relations (page 수준) | 자리만 예약 — 생성기는 채우지 않는다 (규약 0절 9· 10번). 블록을 가리킬 수단으로 컴포넌트 id와 함께 열어 둔 것 | 스키마에 있다고 채우는 필드가 아니다 |
decoration (page 수준) |
decoration (컴포넌트) | 꾸밈구조 — 축 2종(ornament· background) × 선호값 3종(prefer· indifferent· avoid), 축 1개 이상. 전 카테고리 공통(카테고리별 차이 없음) · 내용이 아니라 검색 선호 신호. 설계 의도 SSoT 는 design/decoration-model.md (DRAFT, 축은 늘어날 수 있음) | 렌더 지시가 아니다 — 후보 선택에 쓰는 선호값이다. fallback 때 params 처럼 버려지는 대상도 아니고 내용처럼 옮겨지는 대상도 아닌 별도 축 |
담을 수 없는 것 (전 카테고리 공통): 컴포넌트 단위의 제목· 설명(캡션) 자유 텍스트. 경계 계약(2026-08-15, "딸린 제목· 설명· 범례· 수치는 그 표현의 일부")의 질의 쪽 거울이 절반만 있는 상태 — 수치· 범례는 matrix가 받지만 제목· 설명은 자리가 없다. 페이지 수준 title(필수)이 유일한 자유 텍스트다. dataset 전용 카테고리(차트류· Gauge· BigNumber 등)에서 특히 손실이 된다.