대부분의 데이터 형식은 하나의 청중을 위해 설계되었습니다: 사람 또는 기계. JSON은 사람 쪽으로 기웁니다. MessagePack 같은 바이너리 형식은 기계 쪽으로 기웁니다. TOON은 명시적으로 그러한 형식들이 발명되었을 때 존재하지 않았던 세 번째 청중을 위해 설계되었습니다: 대형 언어 모델. TOON의 모든 구문 결정은 토큰 효율성을 우선시합니다 — 예산을 초과하지 않고 AI에게 더 많은 컨텍스트를 전달할 수 있도록 최소 토큰으로 최대 구조화된 데이터를 맞추는 것입니다. 이 가이드는 단순한 스칼라부터 진정으로 다르게 만드는 표 형식 표기법까지 모든 TOON 구문 기능을 다룹니다.

TOON이 다른 점

TOON은 Token-Optimised Object Notation의 약자입니다. 핵심 아이디어는 간단합니다: 데이터 직렬화 형식 인 JSON은 토큰당 API 가격이 생기기 훨씬 전에 설계되었습니다. JSON은 기계 간 통신에 적합하지만, payload가 gpt-4o 프롬프트에 들어가는 200행 데이터셋인 경우 모든 따옴표 표시, 모든 중괄호, 모든 반복 키 이름에 대해 비용을 지불하고 있습니다. TOON은 그 낭비를 제거합니다. 단일 npm 패키지로 설치됩니다 — @toon-format/toon — 그리고 파일은 .toon 확장자를 사용합니다.

스칼라 값 — 문자열, 숫자, 불리언

TOON 스칼라는 JSON 대응과 매우 유사하지만 한 가지 중요한 차이점이 있습니다: 문자열 값은 쉼표, 콜론 또는 괄호 같은 특수 문자가 포함되지 않으면 따옴표가 필요하지 않습니다. 이것만으로도 텍스트 중심의 데이터셋에서 의미 있는 토큰 수를 줄일 수 있습니다.

text
// Numbers — exactly like JSON
42
3.14
-7

// Booleans — lowercase, same as JSON
true
false

// Strings — no quotes needed for simple values
hello
Alice
Widget Pro

문자열에 쉼표, 콜론 또는 괄호가 포함되면 JSON처럼 이중 따옴표로 묶습니다. 따라서 "New York, NY"는 따옴표가 필요하지만, London은 필요하지 않습니다. 간단한 규칙, 큰 절약.

객체 — 노이즈 없는 키:값 쌍

TOON 객체는 key:value 구문을 사용한 중괄호를 사용합니다. 키는 절대 따옴표로 묶이지 않습니다 — 그것만으로도 JSON에 비해 키당 두 문자를 절약합니다. 쌍은 쉼표로 구분됩니다. 후행 쉼표 없음, 마지막 쌍 다음 콜론 없음.

text
{name:Alice,age:31,city:London,active:true}

동등한 JSON과 비교해 보세요:

json
{"name": "Alice", "age": 31, "city": "London", "active": true}

동일한 데이터, 더 적은 문자, 그리고 객체 배열로 작업할 때 토큰 절약이 극적으로 누적됩니다. 그 점에서...

배열 — 값의 순서 있는 목록

TOON의 배열은 쉼표로 구분된 값을 가진 대괄호를 사용합니다 — JSON과 동일하게, 단 베어 문자열 값에는 따옴표가 없습니다.

text
// Array of strings
[Alice,Bob,Carol]

// Array of numbers
[10,20,30,40,50]

// Mixed types (same rules as JSON)
[Widget Pro,29.99,true,101]

// Array of objects
[{id:1,name:Alice},{id:2,name:Bob}]

객체 배열은 작동하지만 이것이 TOON의 킬러 기능이 등장하는 곳입니다. 구조화된 데이터가 두세 개 이상의 행이 있으면 표 형식 표기법이 훨씬 더 효율적입니다.

표 형식 표기법 — 모든 것을 바꾸는 기능

표 형식 표기법은 TOON의 헤드라인 기능입니다. 실제 작업에서 끊임없이 만나는 시나리오를 위해 설계되었습니다: 유사한 객체 목록 — 제품, 사용자, 트랜잭션, 로그 항목 — 모든 행에 키를 반복하는 것은 순수한 낭비입니다. 구문은:

text
name[count]{col1,col2,col3,...}:
  row1val1,row1val2,row1val3
  row2val1,row2val2,row2val3

분해하면: name은 데이터셋의 레이블, [count]는 데이터 행 수(필수 — 파서에게 얼마나 많은 줄을 읽어야 하는지 정확히 알려줍니다), {col1,col2,...}는 헤더 행, 콜론 :은 헤더를 끝내고, 각 들여쓰기된 줄은 값의 한 행입니다. 실제 제품 예시는 다음과 같습니다:

text
products[5]{id,name,price,inStock,category}:
  101,Widget Pro,29.99,true,Tools
  102,Gadget Plus,49.99,true,Electronics
  103,Thing Basic,9.99,false,Misc
  104,Super Doohickey,74.99,true,Electronics
  105,Budget Widget,14.99,true,Tools

이제 동일한 데이터를 JSON 객체 배열로 상상해 보세요. "id", "name", "price", "inStock", "category"를 각각 다섯 번 작성해야 합니다 — 더하기 주변의 모든 중괄호, 괄호, 따옴표. 이 데이터 형태의 표 형식 TOON 표현은 토큰 수에서 약 60% 더 작습니다.

사용자 데이터셋도 동일한 패턴을 따릅니다:

text
users[4]{id,username,email,role,active}:
  1,alice_dev,[email protected],admin,true
  2,bob_writer,[email protected],editor,true
  3,carol_ops,[email protected],viewer,false
  4,dan_qa,[email protected],editor,true
개수는 필수입니다. 줄 바꿈만 세는 열 헤더 CSV와 달리, TOON의 [count]는 구문의 일부이며 실제 데이터 행 수와 일치해야 합니다. 파서는 테이블이 끝나는 시점을 알기 위해 이것을 사용합니다 — 특히 TOON이 더 큰 구조 안에 포함된 경우에 유용합니다. 즉시 개수 불일치를 잡으려면 TOON Validator를 사용하세요.

중첩 — 객체, 배열, 표 형식 모두 함께

TOON은 예상되는 곳에서 중첩을 지원합니다. 객체는 배열 값을 포함할 수 있습니다. 표 형식 행은 객체를 포함할 수 있습니다. 이렇게 하면 평면 행에 완벽하게 맞지 않는 실제 데이터를 나타낼 수 있습니다.

배열을 포함하는 객체:

text
{name:Alice,roles:[admin,editor],active:true}

한 열에 임베디드 객체가 있는 표 형식 데이터(주소 데이터, 메타데이터 등에 유용):

text
orders[3]{orderId,customer,total,address}:
  1001,alice_dev,89.97,{city:London,country:UK}
  1002,bob_writer,49.99,{city:Berlin,country:DE}
  1003,carol_ops,124.50,{city:Paris,country:FR}

가능한 한 중첩을 얕게 유지하세요. 두세 단계 깊이가 TOON이 여전히 토큰 수에서 이기는 곳입니다. 깊이 재귀적인 구조는 스키마 검증에 더 풍부한 도구가 있는 JSON이 더 잘 제공합니다 — MDN JSON 참조를 참조하세요.

npm 패키지 사용

npm 또는 호환 패키지 매니저로 설치하세요. TOON은 Node.js와 현대 브라우저에서 작동합니다.

bash
npm install @toon-format/toon

패키지는 두 가지 함수를 내보냅니다: encode와 decode. 이것이 전체 공개 API입니다 — 의도적으로 최소화.

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

// decode: TOON string → JS value
const toonString = `products[3]{id,name,price,inStock}:
  101,Widget Pro,29.99,true
  102,Gadget Plus,49.99,true
  103,Thing Basic,9.99,false`;

const data = decode(toonString);
console.log(data);
// [
//   { id: 101, name: "Widget Pro", price: 29.99, inStock: true },
//   { id: 102, name: "Gadget Plus", price: 49.99, inStock: true },
//   { id: 103, name: "Thing Basic", price: 9.99, inStock: false }
// ]

// encode: JS value → TOON string
const users = [
  { id: 1, username: 'alice_dev', active: true },
  { id: 2, username: 'bob_writer', active: false }
];

const toon = encode(users, { indent: 2 });
console.log(toon);
// users[2]{id,username,active}:
//   1,alice_dev,true
//   2,bob_writer,false

{ indent: 2 } 옵션은 행 값의 들여쓰기를 제어합니다. 배열뿐만 아니라 일반 객체와 기본 값에도 encode를 사용할 수 있습니다 — 자동으로 가장 압축된 TOON 표현을 선택합니다. 출력을 TOON Formatter에 붙여넣어 검사하고 보기 좋게 인쇄하세요.

일반적인 실수

이것은 TOON을 처음 접하는 개발자들이 주로 첫 번째 시간 안에 겪는 오류들입니다:

  • 표 형식 표기법에서 잘못된 행 수. products[3]를 쓰고 4개의 데이터 행을 포함하면 파서 버전에 따라 파싱 오류가 발생하거나 마지막 행이 조용히 삭제됩니다. 행을 세고 번호를 최신 상태로 유지하세요. TOON Validator가 즉시 이것을 잡습니다.
  • 객체 키에 따옴표 사용. {"name":Alice}는 유효하지 않은 TOON입니다 — 키는 절대 따옴표로 묶이지 않습니다. 따옴표를 제거하세요: {name:Alice}.
  • 헤더 다음 콜론 잊기. products[2]{id,name} 뒤에 줄 바꿈이 오면 실패합니다. 후행 콜론이 필요합니다: products[2]{id,name}:.
  • 키:값 쌍에서 콜론 주변 공백 사용. {name : Alice}는 유효하지 않습니다. 공백 없음: {name:Alice}.
  • 따옴표 없는 문자열 값에 쉼표 포함. 제품 이름이 "Bolts, Nuts & More"인 경우 표 형식 행에서 따옴표로 묶어야 합니다: 101,"Bolts, Nuts & More",4.99,true.
  • 스칼라에서 decode가 JSON 출력을 기대함. decode("42")는 JavaScript 숫자 42를 반환하며, JSON 객체가 아닙니다. TOON은 기본 JS 타입으로 디코딩합니다.

TOON과 JSON 사이 변환

TOON과 JSON은 완전히 상호 변환 가능합니다 — TOON은 JSON이 직렬화하는 동일한 논리 데이터 모델의 상위 집합입니다. JSON to TOON을 사용하여 LLM에 보내기 전에 기존 데이터셋을 축소하고, JSON 전용 다운스트림 시스템에 결과를 제공해야 할 때 TOON to JSON으로 변환하세요. encode와 decode 함수는 Node.js에서 워크플로우를 자동화하는 경우 이것을 프로그래밍 방식으로 처리합니다. 기본 데이터 구조 명세는 JavaScript의 JSON 전역의 개념과 밀접하게 관련되어 있습니다.

마무리

TOON 구문은 의도적으로 압축적입니다. 따옴표로 묶인 키 없음, 테이블에서 반복되는 키 이름 없음, 단순 문자열 값에 필수 따옴표 없음. 한 번 손으로 표 형식 블록을 작성하면 즉시 이유를 알게 됩니다 — JSON에서 40줄을 차지하는 데이터셋이 TOON에서는 8줄에 들어갑니다. npmjs.com/@toon-format/toon의 npm 패키지는 API 표면을 작게 유지합니다: encode와 decode, 더 배울 것 없음. TOON Formatter로 보기 좋게 인쇄하고, TOON Validator로 구문 오류를 잡고, JSON to TOON으로 기존 데이터를 변환하고, TOON to JSON으로 결과를 표준 형식으로 다시 받을 때 사용하세요.

← All TOON articles Browse all categories →