Çoğu geliştiricinin kısa bir veri formatı listesi vardır: API'ler için JSON, elektronik tablolar için CSV, yapılandırma dosyaları için YAML, belki eski sistemlerle çalışıyorsanız XML. Ancak AI araçları dünyasında sessiz sedasız yolunu açan ve bilmeye değer yeni bir format var — TOON, ya da Token-Oriented Object Notation (Token Odaklı Nesne Gösterimi). Belirli bir sorun için sıfırdan tasarlandı: token bütçenizi tüketmeden büyük dil modellerine yapılandırılmış veri aktarmak.

TOON Nedir?

TOON, Token-Oriented Object Notation (Token Odaklı Nesne Gösterimi) anlamına gelir. Bu, yapılandırılmış veriler LLM istemlerine veya yanıtlarına gömüldüğünde tüketilen token sayısını en aza indirmek için özel olarak oluşturulmuş kompakt bir veri serileştirme formatıdır. Bunu tüm ayrıntılar çıkarılmış JSON olarak düşünün — dizilerde tekrarlanan anahtar adları yok, gereksiz tırnak işaretleri yok, sondaki boşluklar yok — mümkün olduğunca az sözdizimsel gürültüyle yalnızca sinyal.

npm paketi @toon-format/toon'dur ve herhangi bir Node.js projesinde veya modern paketleyicide çalışan basit bir encode / decode API'si sunar. TOON dosyaları .toon uzantısını kullanır.

Neden Sadece JSON Kullanmayalım?

JSON, bant genişliğinin ucuz ve ayrıştırmanın çalışma zamanı tarafından yönetildiği makine-makine iletişimi için mükemmeldir. Ancak OpenAI API'sine veya Anthropic API'sine yönelik bir istemin parçası olarak veri gönderirken her karakter sayılır — kelimenin tam anlamıyla. Her iki API da token başına ücret alır ve tokenlar kabaca 4 İngilizce metin karakterine karşılık gelir.

100 kullanıcı kaydından oluşan bir tabloyu düşünün. JSON'da, anahtarları — "id", "name", "role", "email" — her kayıt için tekrarlarsınız. Bu aynı yapısal bilginin 100 kopyasıdır. TOON'un tablo sözdizimi bu anahtarları bir kez tanımlar ve ardından değerleri satır satır listeler, CSV'nin yaptığı gibi, ancak nesne yapısı korunarak. Gerçek dünya veri kümelerinde token tasarrufu kompakt JSON ile karşılaştırıldığında %40-70 olabilir.

Pratik kural: Bir isteme birkaçtan fazla kayıt gömüyorsanız, TOON neredeyse her zaman JSON'dan daha ucuz olacaktır. JSON'dan TOON'a dönüştürücümüzü kullanarak yükünüzün tam olarak ne kadar küçüldüğünü görün.

Bir Bakışta TOON Sözdizimi

TOON dört temel veri şeklini destekler: skalarlar (dizeler, sayılar, booleanlar), diziler, nesneler ve tablo verileri. JSON ile çalıştıysanız skalar ve koleksiyon sözdizimi tanıdık gelecektir — tablo formatı TOON'un gerçekten farklılaştığı yerdir.

Basit bir nesne dış süslü parantezlerin boşluğunu kaldırır, gereksiz tırnak işaretlerini atlar ve anahtar-değer çiftlerini virgüllerle ayırır:

text
{name:Alice,age:30,role:admin}

Skalarlardan oluşan basit bir dizi tam olarak beklediğiniz gibi görünür:

text
[1,2,3]

İşte ilginç kısım — tablo verileri. Bu, TOON'u LLM kullanım senaryoları için cazip kılan sözdizimidir. Bir dizideki her nesne için anahtarları tekrarlamak yerine, şemayı başlıkta bir kez tanımlarsınız ve değerleri satır satır listelersiniz:

text
users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor

Bu blok, 3 kullanıcı nesnesinden oluşan bir diziyi temsil eder — aşağıdaki JSON'a eşdeğer — ancak tokenların bir kesrinde. users[3]{id,name,role} başlığı bir ayrıştırıcıya şunu söyler: "bu users adlı bir değişken, 3 satırı var ve her satır id, name ve role alanlarıyla eşleşiyor". Satırlar saf değerlerdir, anahtar tekrarı yoktur.

json
[
  { "id": 1, "name": "Alice", "role": "admin" },
  { "id": 2, "name": "Bob",   "role": "user"  },
  { "id": 3, "name": "Charlie", "role": "editor" }
]

@toon-format/toon Paketini Kurma ve Kullanma

Resmi npm paketi hem JavaScript değerlerini TOON dizelerine kodlamayı hem de TOON dizelerini JavaScript nesne ve dizilerine geri çözmeyi yönetir. npm kayıt defterinden yükleyin:

bash
npm install @toon-format/toon

Paket iki işlev dışa aktarır — encode ve decode:

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

// Decode a TOON string → JavaScript value
const toonString = `users[3]{id,name,role}:
  1,Alice,admin
  2,Bob,user
  3,Charlie,editor`;

const users = decode(toonString);
console.log(users[0].name); // "Alice"
console.log(users[1].role); // "user"

// Encode a JavaScript value → TOON string
const config = {
  model: 'gpt-4o',
  temperature: 0.7,
  maxTokens: 1024,
  stream: true
};

const toon = encode(config, { indent: 2 });
console.log(toon);
// {model:gpt-4o,temperature:0.7,maxTokens:1024,stream:true}

encode()'daki indent seçeneği çıktının güzel biçimlendirilip biçimlendirilmeyeceğini kontrol eder. LLM istemleri için genellikle token tasarrufu için kompakt çıktı (girinti yok) istersiniz. Hata ayıklama veya insan tarafından okunabilir .toon dosyaları için { indent: 2 } güzelce biçimlendirilmiş çıktı verir.

Gerçek Dünya Kullanım Senaryosu: Kayıtları Bir LLM'ye Gönderme

Kullanıcı etkinliğini özetlemesi gereken bir ürün analitik özelliği oluşturduğunuzu hayal edin. Veritabanınızdan son oturum kayıtlarını çekiyor ve doğal dil özetlemesi için bir LLM'ye göndermek istiyorsunuz. Bu TOON ile şöyle görünür:

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

const sessions = [
  { userId: 101, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 101, action: 'view_report',  duration: 142, page: '/reports/q1' },
  { userId: 101, action: 'export_csv',   duration: 8,   page: '/reports/q1' },
  { userId: 102, action: 'login',        duration: 0,   page: '/dashboard' },
  { userId: 102, action: 'edit_profile', duration: 37,  page: '/settings'  }
];

const toonPayload = encode(sessions);
// sessions[5]{userId,action,duration,page}:
//   101,login,0,/dashboard
//   101,view_report,142,/reports/q1
//   101,export_csv,8,/reports/q1
//   102,login,0,/dashboard
//   102,edit_profile,37,/settings

const prompt = `Summarise the following user activity. Data is in TOON format.\n\n${toonPayload}`;

Bu 5 oturum kaydının TOON temsili, "userId", "action", "duration" ve "page"'i beş kez tekrarlayacak olan eşdeğer JSON'dan önemli ölçüde kısadır. Yüzlerce kayıt üzerinde tasarruf önemlidir ve doğrudan daha düşük API maliyetlerine ve daha hızlı yanıt sürelerine (dikkat penceresinde işlenecek daha az token) dönüşür.

TOON'da Temel Veri Tipleri

TOON, JavaScript'te ve çoğu diğer dilde halihazırda kullandığınız primitiflerle temiz bir şekilde eşleşir:

  • Dizeler — Özel karakter içermediğinde tırnaksız. Virgül, iki nokta üst üste veya boşluk içerdiklerinde çift tırnak işaretiyle.
  • Sayılar — Tam sayılar ve ondalık sayılar olduğu gibi yazılır: 42, 3.14, -7.
  • Booleanlar — JSON ile aynı şekilde true ve false.
  • Null — Eksik veya tanımsız değerler için null olarak yazılır.
  • Diziler — Kısa listeler için satır içi köşeli parantez sözdizimi [val1,val2,val3]; nesne dizileri için tablo başlık sözdizimi.
  • Nesneler — Tek nesneler için süslü parantez sözdizimi {key:value,key2:value2}.
  • Tablo verileri — Gösterinin yıldızı: name[n]{col1,col2,...}: başlığı ardından virgülle ayrılmış satırlar — aynı şekle sahip herhangi bir kayıt koleksiyonu için ideal.

TOON'u Diğer Formatlarla Karşılaştırıldığında Ne Zaman Kullanmalı

TOON, genel amaçlı bir değişim formatı olarak JSON'un yerini almaya çalışmıyor. Belirli bir niş dolduruyor. İşte hızlı bir karar kılavuzu:

  • JSON kullanın REST API'leri oluştururken, bir veritabanında belgeler depolarken veya servisler arasında veri iletirken. JSON evrensel olarak desteklenir, iyi araçlanmış ve insan tarafından okunabilir.
  • TOON kullanın yapılandırılmış veriler bir istemin veya LLM bağlam penceresinin parçasıyken ve token sayısı önemli olduğunda. Tablo formatı kayıt satırlarıyla çalışırken parlıyor — kullanıcı listeleri, günlük girişleri, ürün katalogları, analiz olayları.
  • CSV kullanın yalnızca düz tablo verilerine ihtiyacınız olduğunda ve tüketici CSV beklediğinde (elektronik tablolar, BI araçları). CSV'nin nesne iç içe geçişi yoktur, bu nedenle TOON daha ifadelidir.
  • YAML kullanın okunabilirlik ve yorumların kompaktlıktan daha önemli olduğu insan tarafından düzenlenen yapılandırma dosyaları için.
  • LLM araç çıktıları için de TOON kullanın: bir LLM aracınızı çağırıp yapılandırılmış sonuçlar döndürürse, bu sonuçları TOON'da kodlamak API çağrısının hem giriş hem de çıkış tarafında token tasarrufu sağlar.
TOON'un mevcut JSON yükünüzle nasıl karşılaştırıldığından emin değil misiniz? JSON'unuzu JSON'dan TOON'a dönüştürücüye bırakın ve araç size her iki temsili yan yana gösterecek, tahmini token sayısı karşılaştırmasıyla birlikte.

Özet

TOON — Token-Oriented Object Notation — LLM çağı için oluşturulmuş kompakt bir serileştirme formatıdır. JSON'un tanıdık yapısını (nesneler, diziler, skalarlar) korurken kayıtlar arasında gereksiz anahtar tekrarını ortadan kaldıran bir tablo sözdizimi tanıtır. Sonuç, eşdeğer JSON'dan %40-70 daha küçük olabilen bir formattır; bu da OpenAI API, Anthropic API veya herhangi bir token faturalandırmalı LLM servisiyle çalışırken doğrudan daha düşük token maliyetlerine dönüşür.

TOON'u uygulamalı olarak keşfetmek istiyorsanız, burada tam bir araç paketimiz var: TOON belgelerini güzelleştirmek ve incelemek için TOON Biçimleyiciyi, sözdizimi hatalarını yakalamak için TOON Doğrulayıcıyı, mevcut yükleri taşımak için JSON'dan TOON'a dönüştürücüyü ve diğer yöne gitmeniz gerekiyorsa TOON'dan JSON'a dönüştürücüyü kullanın. @toon-format/toon npm paketi, TOON'u doğrudan Node.js'inize veya tarayıcı tarafı kodunuza dakikalar içinde entegre etmek için encode ve decode sağlar.

← All TOON articles Browse all categories →