TOON Sözdizimi Kılavuzu — Skalarlardan Tablo Verilerine

Çoğu veri formatı tek bir kitle için tasarlandı: insanlar veya makineler. JSON insan tarafına yatıyor. MessagePack gibi ikili formatlar makine tarafına yatıyor. TOON ise bu formatlar icat edildiğinde var olmayan üçüncü bir kitle için açıkça tasarlandı: büyük dil modelleri. TOON'daki her sözdizimi kararı token verimliliğini önceliklendiriyor — bütçenizi patlatmadan bir yapay zekaya daha fazla bağlam iletebilmek için minimum tokenda maksimum yapılandırılmış veriyi sığdırmak amacıyla. Bu kılavuz, basit skalerlerden onu gerçekten farklı kılan tablo notasyonuna kadar her TOON sözdizimi özelliğini kapsıyor.

TOON'u Farklı Kılan Nedir

TOON, Token-Optimised Object Notation'ın kısaltmasıdır. Temel fikir basittir: veri serileştirme formatları gibi JSON, token başına API fiyatlandırması henüz bir şey değilken tasarlandı. JSON makine-to-makine iletişim için iyidir, ancak payload'ınız bir gpt-4o istemine giden 200 satırlık bir veri kümesiyse, her tırnak işareti, her süslü parantez ve tekrarlanan her anahtar adı için ödeme yapıyorsunuz. TOON bu israfı ortadan kaldırıyor. Tek bir npm paketi olarak yükleniyor — @toon-format/toon — ve dosyalar .toon uzantısını kullanıyor.

Skaler Değerler — Dizeler, Sayılar, Booleanlar

TOON skalerleri JSON karşıtlarına çok benziyor, ancak önemli bir fark var: dize değerleri, virgül, iki nokta üst üste veya köşeli parantez gibi özel karakterler içermedikçe tırnak gerektirmiyor. Bu tek başına metin ağırlıklı veri kümelerinden anlamlı miktarda token kesiyor.

// 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

Bir dize virgül, iki nokta veya köşeli parantez içerdiğinde, JSON gibi çift tırnak içine alın. Yani "New York, NY" tırnak gerektiriyor, ancak London gerektirmiyor. Basit kural, büyük tasarruf.

Nesneler — Gürültüsüz Anahtar:Değer Çiftleri

TOON nesneleri anahtar:değer sözdizimiyle süslü parantezler kullanır. Anahtarlar asla tırnak içine alınmaz — bu tek başına JSON'a kıyasla anahtar başına iki karakter tasarrufu sağlar. Çiftler virgülle ayrılır. Sondaki virgül yok, son çiftten sonra iki nokta üst üste yok.

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

Bunu eşdeğer JSON ile karşılaştırın:

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

Aynı veri, daha az karakter ve nesne dizileriyle çalışırken token tasarrufu çarpıcı biçimde artıyor. Tam da bu konudan bahsederken...

Diziler — Sıralı Değer Listeleri

TOON'daki diziler virgülle ayrılmış değerlerle köşeli parantez kullanır — tıpkı JSON gibi, sadece sade dize değerlerinde tırnak işareti olmadan.

// 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}]

Nesne dizileri çalışır, ancak TOON'un öldürücü özelliği tam burada devreye giriyor. İki veya üç satırdan fazla yapılandırılmış veriniz varsa, tablo notasyonu çok daha verimlidir.

Tablo Notasyonu — Her Şeyi Değiştiren Özellik

Tablo notasyonu TOON'un başlık özelliğidir. Gerçek çalışmada sürekli karşılaştığınız senaryolar için tasarlandı: benzer nesnelerin listesi — ürünler, kullanıcılar, işlemler, günlük girişleri — her satırda anahtarları tekrarlamak tam bir israftır. Sözdizimi şu şekildedir:

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

Ayrıştırmak gerekirse: name veri kümesinin etiketi, [count] veri satırı sayısı (zorunlu — ayrıştırıcıya kaç satır okunacağını tam olarak söyler), {col1,col2,...} başlık satırı, iki nokta üst üste : başlığı bitirir ve sonraki her girintili satır bir satır değerdir. İşte gerçek bir ürünler örneği:

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

Şimdi aynı veriyi JSON nesneleri dizisi olarak düşünün. "id", "name", "price", "inStock" ve "category"'yi beş kez yazmanız gerekirdi — artı çevreleyen tüm parantezler, köşeli parantezler ve tırnaklar. Bu veri şekli için tablo TOON gösterimi token sayısında yaklaşık %60 daha küçük.

Bir kullanıcı veri kümesi aynı deseni izler:

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

İç İçe Geçme — Nesneler, Diziler ve Tablo Bir Arada

TOON beklediğiniz yerlerde iç içe geçmeyi destekler. Bir nesne dizi değeri içerebilir. Tablo satırı nesne içerebilir. Bu, düz satırlara tam olarak uymayan gerçek dünya verilerini temsil etmenizi sağlar.

Dizi içeren nesne:

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

Bir sütunda gömülü nesne içeren tablo verisi (adres verisi, meta veri vb. için kullanışlı):

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}

Mümkün olduğunda iç içe geçmeyi sığ tutun. İki veya üç seviye derinlikte TOON hala token sayısında kazanır. Derin özyinelemeli yapılar, şema doğrulaması için daha zengin araçlara sahip JSON tarafından daha iyi sunulur — bunun için MDN JSON referansı'na bakın.

npm Paketiyle Çalışma

npm veya uyumlu herhangi bir paket yöneticisiyle yükleyin. TOON Node.js'te ve modern tarayıcılarda çalışır.

npm install @toon-format/toon

Paket iki fonksiyon dışa aktarır: encode ve decode. Bu tüm genel API'dir — kasıtlı olarak minimal.

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 } seçeneği satır değerlerinin girintilenmesini kontrol eder. encode'u yalnızca diziler değil, düz nesneler ve ilkel değerler üzerinde de kullanabilirsiniz — en kompakt TOON gösterimini otomatik olarak seçer. Çıktıyı incelemek ve güzel yazdırmak için TOON Biçimleyici'ye yapıştırın.

Yaygın Hatalar

Bunlar, TOON'a yeni geliştiricilerin genellikle ilk saat içinde yaptığı hatalar:

• Tablo notasyonunda yanlış satır sayısı. products[3] yazıp sonra 4 veri satırı eklemek, ayrıştırıcı sürümüne bağlı olarak ayrıştırma hatasına veya son satırın sessizce düşürülmesine neden olur. Satırlarınızı sayın ve sayıyı güncel tutun. TOON Doğrulayıcı bunu hemen yakalar.
• Nesne anahtarlarını tırnak içine almak. {"name":Alice} geçersiz TOON'dur — anahtarlar asla tırnak içine alınmaz. Tırnakları çıkarın: {name:Alice}.
• Başlıktan sonra iki nokta üst üste unutmak. products[2]{id,name} ardından satır sonu gelirse başarısız olur. Sondaki iki nokta üst üste gereklidir: products[2]{id,name}:.
• Anahtar:değer çiftlerinde iki nokta üst üste etrafında boşluk kullanmak. {name : Alice} geçerli değildir. Boşluk yok: {name:Alice}.
• Tırnak işareti olmayan dize değerlerine virgül gömmek. Bir ürün adı "Bolts, Nuts & More" ise, tablo satırlarında tırnak içine almalısınız: 101,"Bolts, Nuts & More",4.99,true.
• Skalerler üzerinde decode'dan JSON çıktısı beklemek. decode("42") JavaScript sayısı 42 döndürür, JSON nesnesi değil. TOON yerel JS türlerine çözer.

TOON ve JSON Arasında Dönüştürme

TOON ve JSON tamamen birbirine dönüştürülebilir — TOON, JSON'ın serileştirdiği aynı mantıksal veri modelinin bir üst kümesidir. Mevcut bir veri kümesini bir LLM'e göndermeden önce küçültmek için JSON'dan TOON'a'yı, sonucu yalnızca JSON kullanan bir aşağı akış sistemine beslemeniz gerektiğinde geri dönüştürmek için TOON'dan JSON'a'yı kullanın. Node.js'te iş akışını otomatikleştiriyorsanız encode ve decode fonksiyonları bunu programatik olarak halleder. Temel veri yapısı spesifikasyonu, JavaScript'teki JSON global'inden gelen kavramlarla yakından ilişkilidir.

Özet

TOON sözdizimi kasıtlı olarak kompakttır. Tırnaklı anahtar yok, tablolarda tekrarlanan anahtar adı yok, basit dize değerlerinde zorunlu tırnak yok. Bir tablo bloğunu elle yazdığınızda hemen anlıyorsunuz — 40 satır JSON'a sığan bir veri kümesi 8 satır TOON'a sığıyor. npmjs.com/@toon-format/toon'daki npm paketi API yüzeyini küçük tutuyor: encode ve decode, öğrenecek başka bir şey yok. Güzel yazdırmak için TOON Biçimleyici'yi, sözdizimi hatalarını yakalamak için TOON Doğrulayıcı'yı, mevcut verilerinizi dönüştürmek için JSON'dan TOON'a'yı ve sonucu standart formda geri almanız gerektiğinde TOON'dan JSON'a'yı kullanın.