TOON vs YAML — İki Kompakt Format, Çok Farklı İşler

YAML ve TOON'un ikisi de "JSON'dan daha okunabilir" olarak tanımlanıyor — ve bu tanım her ikisi için teknik olarak doğru, bu da onu işe yaramaz kılıyor. Gerçek soru şu: kim için okunabilir ve hangi amaçla? YAML insan düzenleme için optimize edilmiş: yorumlar, çıpalar, çok satırlı dizeler, geliştiricilerin yapılandırma hakkında düşündüğü şekli yansıtan girinti. TOON makine işleme için optimize edilmiş: minimum token, belirsizlik yok, yalnızca insan konforu için var olan sözdizimi yok. Bunlar farklı işler. Bunları karıştırmak LLM istemlerinde YAML kullanımına yol açıyor — bu JSON'dan daha kötü — ve Kubernetes manifest'lerinde TOON kullanımına, ki bunu kimse elle düzenlemek istemez. Bu makale çizgiyi net olarak çiziyor.

YAML'ı İki Cümlede Özetlemek

YAML, yapılandırma dosyaları, CI/CD ardışık düzenleri ve bir geliştiricinin elle okuyup yazıp bakımını yapacağı her yapılandırılmış belge için tasarlanmış insan dostu bir veri serileştirme formatıdır. Tanımlayıcı özellikleri — satır içi yorumlar, çıpa/takma ad DRY mekaniği, çok satırlı dize literalleri ve girinti tabanlı yapı — hepsi formatı makineler için verimli değil, insanlar için hoş kılmak amacıyla var.

Kanonik kullanım örnekleri GitHub Actions iş akışları, Kubernetes manifest'leri, Docker Compose dosyaları ve kodun yanında gönderilen uygulama yapılandırmasıdır. Bir insan dosyayı açıp düzenleyecekse, YAML güçlü bir seçimdir. YAML 1.2 spesifikasyonu, YAML 1.1'i rahatsız eden bir dizi uç durumu resmileştirdi — en kötü şöhretiyle Norveç Sorunu, ülke kodu NO'nun YAML 1.1 ayrıştırıcılarında boolean false olarak ayrıştırılmasıydı. Modern YAML 1.2 hedefleyen ayrıştırıcılar bunu doğru şekilde işler, ancak YAML'ın görünürdeki basitliğinin gerçek ayrıştırıcı karmaşıklığını gizlediğinin yararlı bir hatırlatıcısıdır.

• Yorumlar. # bu bir yorumdur — YAML satır içi ve tam satır yorumları destekler. Bu tek başına onu bir insanın bakımını yapacağı herhangi bir yapılandırma için doğru seçim yapar.
• Çıpalar ve takma adlar. Bir bloğu &anchor ile bir kez tanımlayın, *alias ile herhangi bir yerde yeniden kullanın. Kubernetes yapılandırmaları ve çok ortamlı CI ardışık düzenleri için DRY sağlamada temel.
• Çok satırlı dizeler. Literal (|) ve katlanan (>) blok skalerler bir YAML dosyasının içine kabuk betikleri, SQL sorguları veya sertifika verilerini temiz biçimde yerleştirmenizi sağlar.
• Okunabilir girinti. Yapı boşlukla tanımlanır ve bu geliştiricilerin iç içe yapılandırma hiyerarşileri hakkında düşünme biçimiyle doğal olarak örtüşür.
• Zayıflıklar. Girinti hassasiyeti, yanlış yerleştirilmiş bir boşluğun ayrıştırma hatası anlamına geldiği anlamına gelir. Sekme karakterleri yasaktır. YAML 1.1 boolean zorlaması (Norveç Sorunu, yes/no, on/off) gerçek üretim hatalarına neden oldu. Tablo verileri nesne dizisi olarak ifade edildiğinde JSON'dan bile daha ayrıntılıdır.

TOON'u İki Cümlede Özetlemek

TOON, her tokenun paraya mal olduğu ve bağlam penceresi alanının sınırlı olduğu büyük dil modellerine ve bu modellerden yapılandırılmış veri iletmek için tasarlanmış kompakt bir serileştirme formatıdır. Temel yeniliği tablo notasyonudur: her kaydın aynı alanları paylaştığı veri kümeleri için, anahtarlar bir başlıkta bir kez tanımlanır ve sonraki her satırda atlanır — bu JSON ve YAML'ın yaptığının tam tersidir.

TOON bir yapılandırma formatı değildir ve hiçbir zaman öyle tasarlanmadı. Yorum sözdizimi yok. Çıpa yok. 500 satırlık bir TOON veri kümesini ikili dosya düzenler gibi elle düzenlemek istemezsiniz. TOON'un size sağladığı şey, aynı bilgiyi JSON'dan çok daha az tokenda kodlayan bir formattır — ve daha az token daha düşük API maliyetleri, istem başına daha büyük etkili veri kümeleri ve bağlam penceresi sınırlarına daha az baskı anlamına gelir. OpenAI tokenizer bunu pratikte görmenin en hızlı yoludur: aynı veri kümesini her iki formatta yapıştırın ve karşılaştırın.

• Tablo notasyonu. name[count]{col1,col2,...}: ardından satır başına bir değer satırı. Anahtarlar satır sayısından bağımsız olarak tam olarak bir kez görünür.
• Nesne notasyonu. {key:value,key2:value2} — anahtarlarda tırnak yok, fazladan boşluk yok.
• Belirsiz ayrıştırma. Boolean zorlaması yok, girinti hassasiyeti yok, spec versiyonu ayrılması yok.
• Yorum sözdizimi yok. TOON'un satır içi yorumlar için mekanizması yok — tasarım gereği. Bu bir veri formatıdır, belge formatı değil.
• Zayıflıklar. Niş araçlar, insan düzenleme hikayesi yok, bir geliştiricinin doğrudan açıp düzenleyeceği herhangi bir dosya için uygun değil.

Yan Yana: Her Formatın Kendi Alanındaki Veri

En dürüst karşılaştırma her formatın gerçekten iyi olduğu şeyi yapmasını gösterir — birinin açıkça yanlış araç olduğu bir karşılaştırma yapmak yerine.

Önce bir Kubernetes Deployment manifest'i. Bu YAML'ın kendi sahası: yorumlar, paylaşılan değerler için çıpalar ve Kubernetes nesnelerinin mantıksal hiyerarşisini yansıtan derin iç içe geçme ile insan tarafından bakımı yapılan bir yapılandırma dosyası:

# 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"

Bunu TOON'da yazmak anlamsız olurdu — tablo verisi değil, insanlar tarafından düzenlenecek ve açık olmayan değerleri açıklayan yorumlardan faydalanıyor. YAML burada doğru araçtır ve tartışma yoktur.

Şimdi TOON'un kendi sahasındaki aynı veri: analiz için bir LLM'e iletilen kullanıcı veri kümesi. TOON'un tablo notasyonunun işe yaradığı yer burasıdır:

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

Bunu YAML'da yazmak — her biri 7 anahtarlı 12 nesne dizisi — tüm 7 anahtar adını 12 kez tekrarlardı. Bu, 84 değer için 84 anahtar bildirimidir. TOON her anahtarı bir kez tanımlar.

YAML'ın Her Zaman TOON'u Geçtiği Durumlar

Bir insan açıp okuyup düzenleyecek her dosya YAML'a (veya daha basit durumlar için JSON'a) aittir. Belirleyici avantajlar yorumlar ve çıpalardır — TOON'un hiç sahip olmadığı iki özellik.

• CI/CD ardışık düzenleri. GitHub Actions, GitLab CI, CircleCI — hepsi YAML yerel. Hata ayıklama sırasında bir adımı yorum satırına alma yeteneği gerçekten kullanışlıdır.
• Kubernetes ve Helm. Her manifest, her değerler dosyası, her chart şablonu. YAML çıpa sistemi, ortam yapılandırmalarını tekrarlamaktan kaçınmak için karmaşık Helm chart'larında aktif olarak kullanılır.
• Docker Compose. Açık olmayan port bağlamalarını, birim bağlamalarını ve ağ yapılandırmalarını açıklayan yorumlarla çok servisli tanımlar.
• Uygulama yapılandırma dosyaları. pyproject.toml tarzı yapılandırmalar, uygulama ayarları, satır içi açıklayıcı yorumlarla özellik bayrakları.
• PR'larda insanların gözden geçirdiği sürüm kontrolündeki herhangi bir dosya. YAML yapılandırmasındaki yorumlar belgelemin bir parçasıdır. TOON bu iş akışına katılamaz.

TOON'un Her Zaman YAML'ı Geçtiği Durumlar

Programatik olarak üretilen ve bir LLM'e iletilen her veri TOON'a aittir. YAML aslında bu kullanım örneği için JSON'dan daha kötüdür — girinti ağırlıklı sözdizimi ve tekrarlanan anahtar adları, modelin ihtiyaç duymadığı token ekler.

• LLM istem payload'ları. GPT-4o, Claude veya Gemini'ye analiz, sınıflandırma veya zenginleştirme için bir veri kümesi besleme. TOON'un tablo notasyonu token sayısını JSON'a kıyasla %40-60 azaltır ve YAML'a kıyasla fark daha da büyüktür.
• LLM çıktı talimatları. Bir modele TOON'da yanıt vermesini istemek daha kısa ve ucuz çıktı üretir. LLM'den YAML çıktısı ayrıntılı ve girinti hassastır — bir yanlış hizalanmış boşluk ve ayrıştırma bozulur.
• Programatik olarak üretilen veri kümeleri. Kodunuz veriyi oluşturuyorsa, TOON oluşturmalıdır. Yorumlardan veya okunabilir girintiden faydalanacak insan editörü yoktur.
• Yüksek hacimli toplu ardışık düzenler. Günde 10.000 kaydı bir LLM üzerinden mi çalıştırıyorsunuz? %50 token azalması, API faturanızın o satırında %50 azalma demektir.
• Bağlam penceresi baskısı. Bir modelin bağlam sınırına daha fazla veri sığdırmanız gerektiğinde, TOON aynı token maliyetiyle daha fazla satır sığdırmanızı sağlar.

Token Sayısı Gerçeği

İşte üç formatta aynı 10 satırlık veri kümesi. Sayılar yaklaşık ama OpenAI tokenizer'ın GPT-4o tokenizasyonu için bildirdiğiyle tutarlı.

YAML nesne dizisi:

- 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 tablo notasyonu, aynı veri:

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'ın tablo verilerde JSON'dan daha kötü performans göstermesinin nedeni yapısaldır: YAML girintiyle satır başına bir anahtar-değer çifti kullanır, bu nedenle 5 alanlı bir nesne liste işaretçisi artı 5 satıra mal olur. JSON tüm nesneyi en azından bir süslü parantez kümesiyle sarar. TOON anahtar tekrarını tamamen ortadan kaldırır — anahtarlar bir kez görünür, değerler satırlara paketlenir. Tasarruf satır sayısı ve alan sayısıyla birleşir.

Kodunuzda TOON Kullanımı

@toon-format/toon paketi kodlama ve çözmeyi halleder:

npm install @toon-format/toon

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' }

Karar Kılavuzu

YAML ve TOON arasındaki seçim pratikte neredeyse hiç belirsiz değildir:

• YAML kullanın eğer bir insan dosyayı okuyacak veya düzenleyecekse — CI/CD ardışık düzenleri, Kubernetes manifest'leri, Docker Compose, uygulama yapılandırması, Ansible playbook'ları.
• YAML kullanın eğer açık olmayan değerleri açıklamak için satır içi yorumlara ihtiyacınız varsa.
• YAML kullanın eğer karmaşık bir yapılandırmayı DRY tutmak için çıpalar ve takma adlara ihtiyacınız varsa.
• YAML kullanın eğer geleneksel olarak YAML bekleyen bir araçla çalışıyorsanız (Helm, GitHub Actions, k8s kubectl apply).
• TOON kullanın eğer veri bir LLM istemine gidiyorsa — özellikle birden fazla satırla tablo verisi.
• TOON kullanın eğer bir LLM'in yapılandırılmış veri döndürmesini istiyorsanız ve daha kısa, ucuz çıktı istiyorsanız.
• TOON kullanın eğer token sayısı önemliyse — yüksek hacimli ardışık düzenler, uzun veri kümeleri, bağlam penceresi baskısı.
• TOON kullanın eğer veri programatik olarak üretiliyorsa ve hiçbir insan onu doğrudan düzenlemeyecekse.
• JSON kullanın (YAML veya TOON değil) eğer bir REST API oluşturuyorsanız, bir veritabanında veri depoluyorsanız veya JSON bekleyen üçüncü taraf araçlarla entegrasyon yapıyorsanız.

Özet

YAML ve TOON yığınınızın tamamen farklı konumlarını işgal eder. YAML kodunuzun yanındaki deponuza aittir — yapılandırma dosyaları, ardışık düzen tanımları, altyapı manifest'leri. TOON uygulamanız ve LLM API'leri arasındaki sınıra aittir; burada gönderimden önce yapılandırılmış verilerinizi en token verimli gösterime dönüştürür ve dönüş yolunda modelin yanıtını geri çözer. Bu işler arasında anlamlı bir örtüşme yoktur, bu yüzden soru "hangisi daha iyi" değil "hangisi buraya aittir" sorusudur.

TOON ile çalışıyorsanız, TOON Biçimleyici ve TOON Doğrulayıcı TOON dizelerini incelemenin ve doğrulamanın en hızlı yoludur. JSON'dan TOON'a dönüştürücü mevcut JSON payload'larını LLM kullanımı için TOON'a dönüştürür ve TOON'dan JSON'a dönüştürücü bir model TOON döndürdüğünde ve aşağı akış sisteminiz JSON beklediğinde dönüş yolculuğunu halleder. Ayrıca Wikipedia'daki YAML makalesi'ne de bakabilirsiniz; formatın özlü bir tarihini ve bilinen uç durumların özetini içerir.