JSON Toolkit

TOON 포맷 가이드: LLM에 넣기 전에 JSON을 가볍게 줄이기

핵심 요약: 균일한 배열을 JSON으로 LLM에 전달하면 반복되는 키 이름과 괄호가 토큰을 소모합니다. TOON은 들여쓰기 객체와 표 형태 배열로 구조를 한 번만 선언하고 데이터를 행 단위로 나열합니다. 공식 벤치마크에서는 약 40% 적은 토큰으로 더 높은 파싱 정확도를 얻었습니다. 이 글에서는 문법 규칙, 절약이 실제로 적용되는 조건, 변환하면 안 되는 경우, encode와 decode 연결 방법을 다룹니다.

중급약 6분 소요2026-11-10 발행2026-11-10 업데이트
TOON 표 형태 배열 문법: 필드 헤더를 한 번 선언하고 데이터 행을 한 줄씩 나열

JSON의 문법 오버헤드는 기계 간 전송에서는 문제가 되지 않지만, 토큰 단위로 과금되는 LLM 입력 쪽에서는 실제 비용이 됩니다. 같은 균일 배열도 키 이름이 수십 번 반복되고 괄호와 따옴표가 하나하나 토큰을 차지합니다. TOON의 발상은 새로운 데이터 모델을 만드는 것이 아니라, JSON 데이터 모델을 더 저렴한 표기법으로 다시 쓰는 것입니다.

TOON이란: JSON의 다른 인코딩이지 경쟁자가 아니다

TOON(Token-Oriented Object Notation)은 2025년에 공개된 오픈 포맷이며, 공식 위치를 한 문장으로 정리하면 JSON 데이터 모델의 컴팩트하고 무손실이며 사람이 읽을 수 있는 인코딩입니다. 새로운 타입을 전혀 도입하지 않습니다. 객체, 배열, 문자열, 숫자, 불리언, null이 모두 JSON과 일대일 대응되고, decode(encode(x))는 원본 데이터와 엄격하게 같습니다(Date, NaN 같은 JSON 밖 타입은 먼저 정규화해야 합니다). 왕복 변환은 무손실이고 결정적이어서 같은 입력은 항상 같은 출력을 냅니다. 재현 가능한 프롬프트 구성에서 이 결정성이 중요합니다.

인코딩 대상이 정확히 JSON 데이터 모델이므로 TOON의 올바른用法은 경계 포맷으로 쓰는 것입니다. 애플리케이션 내부에서는 평소처럼 JSON으로 비즈니스 로직을 돌리고, 프롬프트에 데이터를 넣기 직전에 한 번만 TOON으로 바꾸며, 모델 응답을 받으면 다시 JSON으로 돌려 처리합니다. 공식 문서는 이를 "translation layer"(번역 계층)라고 부릅니다. 파일 확장자 관례는 .toon이고 HTTP 전송의 임시 미디어 타입은 text/toon(UTF-8)입니다.

검색 시 주의할 점: 컴퓨터 그래픽의 Toon Shader(툰 렌더링)와는 아무 관련이 없습니다. 단어만 같은 전혀 다른 것입니다.

LLM 입력 쪽에서 JSON이 특히 비싼 이유

주문 목록, 사용자 명단, 로그 요약을 JSON 배열로 표현하면 토큰은 세 곳에 듭니다.

  1. 반복되는 키 이름. 50건의 주문 레코드는 "id", "amount", "status"를 각각 50번 씁니다. 데이터가 두 배가 되면 키 오버헤드도 두 배입니다.
  2. 구조 문장 부호. 중괄호, 대괄호, 콜론, 콤마가 모두 토큰을 소모하고 중첩이 깊을수록 밀도가 올라갑니다.
  3. 따옴표. 거의 모든 키와 문자열 값이 큰따옴표로 감싸집니다.

이 세 가지가 겹치면 토큰 과금 API 비용이 곧바로 올라가고, 긴 입력은 컨텍스트 창 한도에 더 빨리 닿으며, 아주 긴 입력에서는 모델이 필드를 누락하거나 잘못 대응시킬 확률도 올라갑니다. TOON 공식 홈페이지 벤치마크에 따르면 혼합 구조 테스트 세트에서 4개 모델 평균 토큰 약 40% 절감, 파싱 정확도는 JSON의 70%에서 74%로 상승했습니다. 즉 이 영역에서는 절약과 정확도가 트레이드오프가 아니며, 더 조밀한 구조가 경계를 더 잘 보이게 만들기 때문입니다.

문법 해부: 들여쓰기 객체 + 표 형태 배열

같은 일기 예보 데이터의 세 가지 표현을 봅니다. JSON 버전은 약 117토큰입니다.

{
  "location": { "city": "Berlin", "country": "DE", "units": "metric" },
  "alerts": ["frost", "wind"],
  "forecast": [
    { "day": "Mon", "temp": { "min": -2, "max": 4 }, "condition": "snow", "rainChance": 80 },
    { "day": "Tue", "temp": { "min": 1, "max": 7 }, "condition": "cloudy", "rainChance": 20 },
    { "day": "Wed", "temp": { "min": 3, "max": 11 }, "condition": "sunny", "rainChance": 5 }
  ]
}

TOON 버전은 약 66토큰입니다.

location:
  city: Berlin
  country: DE
  units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
  Mon,-2,4,snow,80
  Tue,1,7,cloudy,20
  Wed,3,11,sunny,5

세 가지 형태가 전체를 커버하고, 직렬화기가 데이터 모양에 따라 자동으로 고릅니다.

형태 적합한 데이터 대응하는 JSON
들여쓰기 객체 중첩 객체 { "location": { ... } }, 중괄호 대신 들여쓰기
인라인 배열 원시값 배열 ["frost","wind"], [2]가 길이를 선언
표 형태 배열 균일 객체 배열 필드 이름은 헤더 {day,temp{min,max},...}에 한 번만, 각 행은 콤마로 구분된 값만

균일한 중첩 객체(temp{min,max})는 헤더 안으로 접혀 중첩 필드 그룹이 되고 데이터 행은 평평하게 유지됩니다. 따옴표 규칙은 최소 인용입니다. 문자열이 구분자나 특수 문자를 포함하거나 숫자로 오독될 때만 따옴표를 붙입니다. 이것이 "압축 JSON"보다 토큰을 더 아낄 수 있는 이유 중 하나입니다. YAML과의 핵심 차이는 TOON에 기계가 검증할 수 있는 명시적 길이 선언과 필드 헤더가 있다는 점이고, CSV와의 차이는 중첩과 타입을 유지한다는 점입니다.

[N]과 {fields}: 모델에 주는 구조 가드레일

[3]과 {day,...}는 단순한 토큰 절감 수단이 아니라 모델에 전달되는 검증 가능한 계약입니다.

  • 배열 길이 덕분에 모델은 "데이터셋에 몇 건이 있나"를 직접 답할 수 있고, 행 수가 맞지 않으면 잘림(truncation)을 즉시 드러냅니다.
  • 필드 헤더는 이름을 한 번만 선언하고 모델은 위치로 값을 맞춥니다. 매 행마다 키 대응을 다시 추측하면서 생기는 오류 면이 줄어듭니다.

이것은 사후 구제와 정반대 발상입니다. JSON 리페어러(수정 파이프라인 글 참조)는 모델이 깨진 JSON을 내보낸 뒤에 데이터를 살려내지만, TOON의 길이·필드 선언은 입력 쪽에서 깨진 데이터가 생길 확률을 낮춥니다. 양쪽을 다 하면 중간 단계의 파싱 실패율이 내려갑니다.

TOON을 쓰지 말아야 할 때

공식 "When Not to Use TOON" 절은 매우 솔직하며, 네 가지 경우를 그대로 외워도 됩니다.

경우 변환하지 말아야 할 이유 더 나은 선택
깊은 중첩·불균일 구조 표 적합도≈0%. 컴팩트 JSON이 더 유리할 때가 많음 컴팩트 JSON
반균일 배열 필드가 어긋나 절감 폭이 거의 사라짐 JSON 파이프라인 유지
순수 플랫 표 TOON은 CSV보다 5–10% 구조 오버헤드 CSV
지연 민감(로컬/양자화 모델) 토큰 감소 ≠ 더 빠른 추론 TTFT를 직접 측정

반균일 판정 기준은 표 적합도(tabular eligibility)입니다. 공식 참고치에 따르면 40–60% 수준에서는 절감 효과가 이미 미미합니다. 포맷 전환에는 파서, 검증기, 하류 스크립트를 바꾸는 현실적인 비용이 따르므로 이득이 10% 미만이면 건드리지 않는 편이 낫습니다.

적용: encode / decode와 CLI

공식 TypeScript 라이브러리의 양방향 변환입니다.

npm install @toon-format/toon
# 일괄 변환은 CLI로도 가능
npx @toon-format/cli input.json -o output.toon
import { encode, decode } from '@toon-format/toon'

const data = {
  users: [
    { id: 1, name: 'Ada', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' },
  ],
}

const toon = encode(data)
// users[2]{id,name,role}:
//   1,Ada,admin
//   2,Bob,user

const back = decode(toon)  // 원본 데이터와 엄격하게 같음

Python, Go, Rust, .NET 구현도 존재합니다. 채택 전에 공식 spec 저장소의 구현 목록을 확인하고, 사용할 문법 기능이 커버되는지 확인하세요. 프로덕션에 넣기 전에 왕복 검증을 실행합니다. decode(encode(원본))이 깊은 일치가 아니면 구현이나 데이터 어느 한쪽에 문제가 있는 것입니다.

기존 JSON 도구 체인과의 연계

TOON은 기존 JSON 처리를 전혀 바꾸지 않고 경계 변환 하나만 추가합니다. 권장 순서는 다음과 같습니다.

  1. 먼저 JSON 자체를 깨끗하게 만든다. 깨진 JSON에서는 깨진 TOON만 나옵니다. 문법 검증과 복구는 JSON 복구 가이드의 파싱 체인에 맡깁니다.
  2. 데이터 형태를 확인한다. 배열 안 객체의 필드가 모두 갖춰져 있나요? 갖춰져 있지 않으면 먼저 정규화하거나 변환할 가치가 없다고 판단합니다.
  3. 변환하고 표본 검사한다. 변환 후 데이터 행 하나를 꺼내 원본 JSON과 비교해 필드 정렬이 흐트러지지 않았는지 확인합니다.
  4. 이득을 추정한다. 균일 리스트라면 JSONL 파일 핸드북의 행 단위 사고방식을 스트리밍 변환에 적용할 수 있습니다. 크기와 비용의 관계는 JSON Minify와 Gzip의 실제 관계와 같은 교훈입니다. 먼저 재보고 바꾸는 편이 쌉니다.

TOON이 JSON을 대체할까?

아니요. TOON이 인코딩하는 것은 JSON 데이터 모델 그 자체이고, 역할은 프롬프트 경계의 표현 계층입니다. 프로그램 간 저장과 교환은 계속 JSON의 영역입니다. "모델에 주는" 구간만 TOON을 쓰고 나머지 체인은 그대로 둡니다.

TOON과 YAML·CSV는 어떤 관계인가?

객체 부분은 YAML과 비슷하고(중괄호 대신 들여쓰기), 균일 배열은 CSV와 비슷합니다(헤더를 한 번 선언하고 행을 흐르게 나열). 그러나 TOON에는 YAML에 없는 명시적 길이 선언이 있고, CSV에 없는 중첩과 타입 보존도 있습니다. 양쪽의 중간에 서서 기계 검증 가능한 구조 가드레일을 얹은 셈입니다.

TOON을 JSON으로 되돌릴 때 데이터가 손실되나?

손실되지 않습니다. 객체, 배열, 문자열, 숫자, 불리언, null이 모두 일대일 대응되고 decode(encode(x))는 엄격히 같습니다. 유일한 주의점은 Date, NaN 같은 JSON 밖 타입을 먼저 정규화하는 것입니다. 그렇지 않으면 왕복 후에야 같아집니다.

변환된 TOON이 맞는지 검증하려면?

두 가지 방법이 있습니다. 하나는 왕복 검증으로, encode 후 decode한 결과가 원본과 깊이 일치하는지 확인하는 것입니다. 다른 하나는 헤더를 눈으로 확인하는 것입니다. [N]의 숫자가 데이터 행 수와 같아야 하고, {fields}의 각 필드는 각 행의 콤마 구분 값과 일대일로 정렬되어야 합니다. 모델 쪽에서는 답하기 전에 먼저 배열 길이를 보고하도록 프롬프트에서 요구할 수도 있습니다.