YAML과 TOON은 모두 "JSON보다 더 읽기 쉽다"고 설명됩니다 — 그리고 그 설명은 둘 다에게 기술적으로 사실이며, 이는 그것을 쓸모없게 만듭니다. 진짜 질문은: 누구에게 읽기 쉽고, 어떤 목적으로? YAML은 사람의 편집을 위해 최적화되어 있습니다: 주석, 앵커, 여러 줄 문자열, 개발자가 설정에 대해 생각하는 방식을 반영하는 들여쓰기. TOON은 기계 처리를 위해 최적화되어 있습니다: 최소 토큰, 모호함 없음, 순전히 사람의 편의를 위해 존재하는 구문 없음. 이것은 다른 작업입니다. 혼동하면 LLM 프롬프트에 YAML이 들어가게 됩니다 — JSON보다 더 나쁩니다 — 그리고 Kubernetes 매니페스트에 TOON이 들어가게 됩니다, 아무도 손으로 편집하기를 원하지 않는. 이 문서는 선을 명확히 그립니다.

두 문장으로 YAML

YAML은 설정 파일, CI/CD 파이프라인, 개발자가 직접 읽고 쓰고 유지하는 구조화된 문서를 위해 설계된 사람 친화적인 데이터 직렬화 형식입니다. 인라인 주석, 앵커/앨리어스 DRY 메커니즘, 여러 줄 문자열 리터럴, 들여쓰기 기반 구조 — 이 정의 기능들은 모두 형식을 기계에 효율적이게 하는 것이 아니라 사람에게 즐겁게 만들기 위해 존재합니다.

표준 사용 사례는 GitHub Actions 워크플로우, Kubernetes 매니페스트, Docker Compose 파일, 코드와 함께 배포되는 애플리케이션 설정입니다. 사람이 파일을 열고 편집해야 하는 경우 YAML이 좋은 선택입니다. YAML 1.2 사양은 YAML 1.1을 괴롭혔던 많은 엣지 케이스들을 공식화했습니다 — 가장 악명 높은 것은 Norway Problem으로, 국가 코드 NO가 YAML 1.1 파서에서 불리언 false로 파싱되었습니다. 현대 파서들은 YAML 1.2를 타겟으로 하여 이것을 올바르게 처리하지만, YAML의 겉보기 단순함이 실제 파서 복잡성을 숨긴다는 것을 상기시켜주는 유용한 예시입니다.

  • 주석. # 이것은 주석입니다 — YAML은 인라인과 전체 줄 주석을 지원합니다. 이것만으로도 사람이 유지하는 설정에 올바른 선택이 됩니다.
  • 앵커와 앨리어스. &anchor로 블록을 한 번 정의하고, *alias로 어디서나 재사용합니다. Kubernetes 설정과 다중 환경 CI 파이프라인의 DRY에 필수적입니다.
  • 여러 줄 문자열. 리터럴(|)과 접힌(>) 블록 스칼라를 사용하면 YAML 파일 안에 셸 스크립트, SQL 쿼리 또는 인증서 데이터를 깔끔하게 포함할 수 있습니다.
  • 읽기 쉬운 들여쓰기. 구조는 공백으로 정의되며, 개발자가 중첩 설정 계층에 대해 생각하는 방식에 자연스럽게 맵핑됩니다.
  • 약점. 들여쓰기 민감성은 잘못 배치된 공백이 파싱 오류가 됨을 의미합니다. 탭 문자는 금지됩니다. YAML 1.1 불리언 강제 변환(Norway Problem, yes/no, on/off)은 실제 프로덕션 버그를 일으켰습니다. 객체 배열로 표현된 표 형식 데이터는 JSON보다도 더 장황합니다.

두 문장으로 TOON

TOON은 모든 토큰이 돈이고 컨텍스트 창 공간이 유한한 대형 언어 모델에서 구조화된 데이터를 주고받기 위해 설계된 압축 직렬화 형식입니다. 핵심 혁신은 표 형식 표기법입니다: 모든 레코드가 동일한 필드를 공유하는 데이터셋의 경우, 키는 헤더에 한 번 선언되고 모든 후속 행에서 생략됩니다 — 이것은 JSON과 YAML이 하는 것과 반대입니다.

TOON은 설정 형식이 아니며 그렇게 의도된 적도 없습니다. 주석 구문이 없습니다. 앵커가 없습니다. 500행 TOON 데이터셋을 손으로 편집하고 싶지 않을 것입니다, 바이너리 파일을 손으로 편집하고 싶지 않은 것처럼. TOON이 제공하는 것은 JSON보다 훨씬 적은 토큰으로 동일한 정보를 인코딩하는 형식입니다 — 그리고 더 적은 토큰은 더 낮은 API 비용, 프롬프트당 더 많은 유효 데이터셋, 컨텍스트 창 한계에 대한 더 적은 압박을 의미합니다. OpenAI 토크나이저는 이것을 실제로 보는 가장 빠른 방법입니다: 동일한 데이터셋을 두 형식으로 붙여넣고 비교해 보세요.

  • 표 형식 표기법. name[count]{col1,col2,...}: 뒤에 줄당 값의 한 행. 키는 행 수에 관계없이 정확히 한 번 나타납니다.
  • 객체 표기법. {key:value,key2:value2} — 키에 따옴표 없음, 추가 공백 없음.
  • 명확한 파싱. 불리언 강제 변환 없음, 들여쓰기 민감성 없음, 사양 버전 차이 없음.
  • 주석 구문 없음. TOON에는 인라인 주석 메커니즘이 없습니다 — 설계상. 이것은 문서 형식이 아닌 데이터 형식입니다.
  • 약점. 틈새 도구, 사람이 편집하는 이야기 없음, 개발자가 직접 열고 편집할 파일에는 적합하지 않음.

나란히 비교: 각 형식의 고유 영역에서 동일한 데이터

가장 정직한 비교는 각 형식이 실제로 잘하는 일을 보여주는 것입니다 — 하나가 명백히 잘못된 도구인 대결을 강요하지 않고.

먼저 Kubernetes Deployment 매니페스트. 이것은 YAML의 홈 영역입니다: 주석이 있고, 공유 값에 앵커가 있으며, Kubernetes 객체의 논리 계층에 맵핑되는 깊은 중첩이 있는 사람이 유지하는 설정 파일입니다:

yaml
# Deployment manifest for the payments-service
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-service
  namespace: production
  labels:
    app: payments-service
    version: "2.4.1"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: payments-service
  template:
    metadata:
      labels:
        app: payments-service
    spec:
      containers:
        - name: payments-service
          image: registry.example.com/payments-service:2.4.1
          ports:
            - containerPort: 8080
          env:
            - name: DB_HOST
              valueFrom:
                secretKeyRef:
                  name: payments-db-secret
                  key: host
            - name: LOG_LEVEL
              value: "info"
          resources:
            requests:
              cpu: "250m"
              memory: "256Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"

TOON으로 작성하는 것은 의미가 없습니다 — 표 형식 데이터가 아니고, 사람이 편집해야 하며, 자명하지 않은 값을 설명하는 주석의 혜택을 받습니다. 여기서는 YAML이 올바른 도구이고 경쟁이 없습니다.

이제 TOON의 홈 영역에서 동일한 데이터: 분석을 위해 LLM에 전달되는 사용자 데이터셋. 이것은 TOON의 표 형식 표기법이 역할을 하는 곳입니다:

text
users[12]{id,email,plan,mrr,country,signupDate,churned}:
  1001,[email protected],pro,99.00,US,2024-01-15,false
  1002,[email protected],starter,19.00,GB,2024-02-03,false
  1003,[email protected],enterprise,499.00,DE,2023-11-20,false
  1004,[email protected],pro,99.00,CA,2024-03-10,true
  1005,[email protected],starter,19.00,AU,2024-01-28,false
  1006,[email protected],pro,99.00,US,2023-12-05,false
  1007,[email protected],enterprise,499.00,FR,2024-02-14,false
  1008,[email protected],starter,19.00,IN,2024-03-22,true
  1009,[email protected],pro,99.00,US,2024-01-09,false
  1010,[email protected],enterprise,499.00,JP,2023-10-31,false
  1011,[email protected],starter,19.00,BR,2024-04-01,false
  1012,[email protected],pro,99.00,US,2024-02-19,true

YAML로 작성하는 것 — 각 7개의 키를 가진 12개의 객체 배열 — 은 모든 7개의 키 이름을 12번 반복합니다. 이것은 84개의 값에 대한 84개의 키 선언입니다. TOON은 각 키를 한 번만 선언합니다.

YAML이 TOON을 항상 이기는 곳

사람이 열고, 읽고, 편집할 파일은 YAML(또는 더 간단한 경우 JSON)에 속합니다. 결정적인 장점은 주석과 앵커입니다 — TOON이 단순히 가지고 있지 않은 두 가지 기능입니다.

  • CI/CD 파이프라인. GitHub Actions, GitLab CI, CircleCI — 모두 YAML 기본. 디버깅 중에 단계를 주석 처리하는 능력은 진정으로 유용합니다.
  • Kubernetes와 Helm. 모든 매니페스트, 모든 값 파일, 모든 차트 템플릿. YAML 앵커 시스템은 복잡한 Helm 차트에서 환경 설정 반복을 피하기 위해 적극적으로 사용됩니다.
  • Docker Compose. 자명하지 않은 포트 바인딩, 볼륨 마운트, 네트워크 설정을 설명하는 주석이 있는 다중 서비스 정의.
  • 애플리케이션 설정 파일. pyproject.toml 스타일 설정, 애플리케이션 설정, 인라인 설명 주석이 있는 기능 플래그.
  • 사람이 PR에서 검토하는 버전 관리의 모든 파일. YAML 설정의 주석은 문서의 일부입니다. TOON은 이 워크플로우에 전혀 참여할 수 없습니다.
앵커에 대한 참고: YAML 앵커(&anchor)와 앨리어스 (*alias)는 활용도가 낮지만 강력합니다. 여러 컨테이너에서 동일한 환경 변수를 공유하는 Kubernetes 설정은 &common-env로 한 번 정의하고 *common-env로 블록을 참조할 수 있습니다 — 어떤 템플릿 엔진 없이 파일을 DRY하게 유지합니다. TOON에는 동등한 메커니즘이 없습니다.

TOON이 YAML을 항상 이기는 곳

프로그래밍 방식으로 생성되어 LLM에 전달되는 모든 데이터는 TOON에 속합니다. YAML은 실제로 이 사용 사례에 대해 JSON보다 더 나쁩니다 — 들여쓰기 중심의 구문과 반복 키 이름이 모델이 필요로 하는 어떤 정보도 추가하지 않으면서 토큰을 추가합니다.

  • LLM 프롬프트 페이로드. 분석, 분류 또는 풍부화를 위해 GPT-4o, Claude 또는 Gemini에 데이터셋 제공. TOON의 표 형식 표기법은 JSON에 비해 토큰 수를 40~60% 줄이고, YAML에 비해서는 차이가 더 큽니다.
  • LLM 출력 지시. 모델에게 TOON으로 응답하도록 지시하면 더 짧고 저렴한 출력이 생성됩니다. LLM에서의 YAML 출력은 장황하고 들여쓰기에 민감합니다 — 잘못 정렬된 공백 하나가 파싱을 깨뜨립니다.
  • 프로그래밍 방식으로 생성된 데이터셋. 코드가 데이터를 구성하는 경우, TOON을 구성해야 합니다. 주석이나 읽기 쉬운 들여쓰기의 혜택을 받을 사람이 없습니다.
  • 대용량 배치 파이프라인. 하루에 10,000개의 레코드를 LLM을 통해 실행하나요? 50% 토큰 감소는 API 청구서에서 해당 항목의 50% 감소입니다.
  • 컨텍스트 창 압박. 동일한 토큰 비용으로 모델의 컨텍스트 한계 내에 더 많은 데이터를 맞춰야 할 때, TOON을 사용하면 더 많은 행을 포장할 수 있습니다.

토큰 수 현실

다음은 세 가지 형식으로 동일한 10행 데이터셋입니다. 숫자는 근사치이지만 OpenAI 토크나이저가 GPT-4o의 토큰화에 대해 보고하는 것과 일치합니다.

객체 배열의 YAML:

yaml
- id: 1
  username: alice_chen
  plan: pro
  mrr: 99.00
  country: US
- id: 2
  username: bob_martin
  plan: starter
  mrr: 19.00
  country: GB
- id: 3
  username: carol_white
  plan: enterprise
  mrr: 499.00
  country: DE
- id: 4
  username: dan_patel
  plan: pro
  mrr: 99.00
  country: CA
- id: 5
  username: eve_torres
  plan: starter
  mrr: 19.00
  country: AU
- id: 6
  username: frank_liu
  plan: pro
  mrr: 99.00
  country: US
- id: 7
  username: grace_kim
  plan: enterprise
  mrr: 499.00
  country: FR
- id: 8
  username: henry_obi
  plan: starter
  mrr: 19.00
  country: IN
- id: 9
  username: iris_novak
  plan: pro
  mrr: 99.00
  country: US
- id: 10
  username: james_sato
  plan: enterprise
  mrr: 499.00
  country: JP

TOON 표 형식 표기법, 동일한 데이터:

text
users[10]{id,username,plan,mrr,country}:
  1,alice_chen,pro,99.00,US
  2,bob_martin,starter,19.00,GB
  3,carol_white,enterprise,499.00,DE
  4,dan_patel,pro,99.00,CA
  5,eve_torres,starter,19.00,AU
  6,frank_liu,pro,99.00,US
  7,grace_kim,enterprise,499.00,FR
  8,henry_obi,starter,19.00,IN
  9,iris_novak,pro,99.00,US
  10,james_sato,enterprise,499.00,JP
이 데이터셋에 대한 대략적인 토큰 수: YAML ≈ 290 토큰. JSON(동등한 객체 배열) ≈ 230 토큰. TOON ≈ 115 토큰. YAML은 TOON보다 나쁜 것이 아닙니다 — 표 형식 데이터에 대해 JSON보다도 나쁩니다, 왜냐하면 들여쓰기 구문이 JSON의 중괄호가 하지 않는 토큰을 추가하기 때문입니다. TOON은 YAML에 비해 약 2.5배, JSON에 비해 약 2배 우세합니다. OpenAI 토크나이저로 확인하세요.

표 형식 데이터에서 YAML이 JSON보다 더 나쁜 이유는 구조적입니다: YAML은 들여쓰기와 함께 키-값 쌍당 한 줄을 사용하여 5필드 객체는 목록 마커 외에 5줄이 필요합니다. JSON은 적어도 전체 객체를 하나의 중괄호 세트로 감쌉니다. TOON은 키 반복을 완전히 제거합니다 — 키는 한 번 나타나고, 값은 행으로 패킹됩니다. 절약은 행 수와 필드 수에 따라 누적됩니다.

코드에서 TOON 사용

@toon-format/toon 패키지가 인코딩과 디코딩을 처리합니다:

bash
npm install @toon-format/toon
ts
import { encode, decode } from '@toon-format/toon';

// Your dataset — could come from a database query, API response, anywhere
const users = [
  { id: 1001, email: '[email protected]', plan: 'pro',        mrr: 99.00,  country: 'US' },
  { id: 1002, email: '[email protected]',   plan: 'starter',    mrr: 19.00,  country: 'GB' },
  { id: 1003, email: '[email protected]', plan: 'enterprise', mrr: 499.00, country: 'DE' },
  // ...more rows
];

// Encode to TOON before inserting into your LLM prompt
const toonPayload = encode(users);
// users[3]{id,email,plan,mrr,country}:
//   1001,[email protected],pro,99.00,US
//   1002,[email protected],starter,19.00,GB
//   1003,[email protected],enterprise,499.00,DE

const prompt = `Analyse this user dataset and identify churn risk signals.
Return your findings as a TOON dataset with columns: id, riskScore, reason.

Dataset:
${toonPayload}`;

// After the LLM responds with TOON output, decode it back
const llmResponse = '...'; // TOON string from the model
const findings = decode(llmResponse);
console.log(findings[0]); // { id: 1001, riskScore: 'low', reason: 'Active, pro plan' }

결정 가이드

YAML과 TOON 중에서 선택하는 것은 실제로 거의 모호하지 않습니다:

  • YAML을 사용하세요 사람이 파일을 읽거나 편집할 경우 — CI/CD 파이프라인, Kubernetes 매니페스트, Docker Compose, 애플리케이션 설정, Ansible 플레이북.
  • YAML을 사용하세요 자명하지 않은 값을 설명하는 인라인 주석이 필요한 경우.
  • YAML을 사용하세요 복잡한 설정을 DRY하게 유지하는 앵커와 앨리어스가 필요한 경우.
  • YAML을 사용하세요 관례로 YAML을 기대하는 도구(Helm, GitHub Actions, k8s kubectl apply)와 작업하는 경우.
  • TOON을 사용하세요 데이터가 LLM 프롬프트에 들어가는 경우 — 특히 여러 행이 있는 표 형식 데이터.
  • TOON을 사용하세요 LLM에게 구조화된 데이터를 반환하도록 요청하고 더 짧고 저렴한 출력을 원하는 경우.
  • TOON을 사용하세요 토큰 수가 중요한 경우 — 대용량 파이프라인, 긴 데이터셋, 컨텍스트 창 압박.
  • TOON을 사용하세요 데이터가 프로그래밍 방식으로 생성되고 사람이 직접 편집하지 않는 경우.
  • JSON을 사용하세요(YAML이나 TOON이 아닌) REST API를 구축하거나, 데이터베이스에 데이터를 저장하거나, JSON을 기대하는 타사 도구와 통합하는 경우.

마무리

YAML과 TOON은 스택에서 완전히 다른 위치를 차지합니다. YAML은 코드와 함께 저장소에 속합니다 — 설정 파일, 파이프라인 정의, 인프라 매니페스트. TOON은 애플리케이션과 LLM API 간의 경계에 속합니다, 보내기 전에 구조화된 데이터를 가장 토큰 효율적인 표현으로 변환하고 나올 때 모델의 응답을 다시 변환합니다. 이러한 작업들 사이에는 의미 있는 겹침이 없습니다, 이것이 질문이 "어느 것이 더 좋은가"가 아니라 "어느 것이 여기에 속하는가"인 이유입니다.

TOON으로 작업하는 경우, TOON Formatter와 TOON Validator는 TOON 문자열을 검사하고 검증하는 가장 빠른 방법입니다. JSON to TOON 변환기는 LLM 사용을 위해 기존 JSON 페이로드를 TOON으로 변환하고, TOON to JSON 변환기는 모델이 TOON으로 응답하고 다운스트림 시스템이 JSON을 기대할 때 반환 여정을 처리합니다. YAML의 역사와 알려진 엣지 케이스에 대한 간결한 요약은 YAML에 대한 Wikipedia 문서를 참조하세요.

← All TOON articles Browse all categories →