TOON vs YAML — Dois Formatos Compactos, Trabalhos Muito Diferentes

YAML e TOON são ambos descritos como "mais legíveis que JSON" — e essa descrição é tecnicamente verdadeira para ambos, o que a torna inútil. A questão real é: legível para quem, e para qual propósito? YAML é otimizado para edição humana: comentários, âncoras, strings multilinha, indentação que espelha como desenvolvedores pensam sobre configuração. TOON é otimizado para processamento de máquina: tokens mínimos, sem ambiguidade, sem sintaxe que existe puramente pelo conforto humano. Esses são trabalhos diferentes. Confundi-los leva ao YAML em prompts de LLM — o que é pior que JSON — e ao TOON em manifestos Kubernetes, que ninguém quer editar manualmente. Este artigo traça a linha com clareza.

YAML em duas frases

YAML é um formato de serialização de dados amigável aos humanos projetado para arquivos de configuração, pipelines de CI/CD e qualquer documento estruturado que um desenvolvedor leia, escreva e mantenha manualmente. Seus recursos definidores — comentários inline, mecânica DRY de âncora/alias, literais de string multilinha e estrutura baseada em indentação — todos existem para tornar o formato agradável para humanos, não eficiente para máquinas.

Os casos de uso canônicos são workflows do GitHub Actions, manifestos Kubernetes, arquivos Docker Compose, e configuração de aplicação que é enviada junto com o código. Se um ser humano deve abrir o arquivo e editá-lo, YAML é uma escolha forte. A especificação YAML 1.2 formalizou vários casos extremos que assolaram o YAML 1.1 — o mais famoso o Problema da Noruega, onde o código do país NO era analisado como booleano false em parsers YAML 1.1. Parsers modernos visando YAML 1.2 lidam com isso corretamente, mas é um lembrete útil de que a aparente simplicidade do YAML esconde complexidade real de parser.

• Comentários. # isto é um comentário — YAML suporta comentários inline e de linha completa. Isso sozinho o torna a escolha certa para qualquer configuração que humanos vão manter.
• Âncoras e aliases. Defina um bloco uma vez com &anchor, reutilize em qualquer lugar com *alias. Essencial para configs Kubernetes DRY e pipelines CI multi-ambiente.
• Strings multilinha. Escalares de bloco literal (|) e dobrado (>) permitem que você incorpore scripts shell, consultas SQL ou dados de certificado limpos dentro de um arquivo YAML.
• Indentação legível. A estrutura é definida por espaço em branco, o que mapeia naturalmente para como desenvolvedores pensam sobre hierarquias de configuração aninhadas.
• Fraquezas. A sensibilidade a indentação significa que um espaço mal posicionado é um erro de parse. Caracteres de tabulação são proibidos. A coerção booleana do YAML 1.1 (Problema da Noruega, yes/no, on/off) causou bugs reais em produção. Dados tabulares expressos como array de objetos são mais verbosos até que JSON.

TOON em duas frases

TOON é um formato de serialização compacto projetado para passar dados estruturados para e de modelos de linguagem grandes, onde cada token custa dinheiro e o espaço da janela de contexto é finito. Sua principal inovação é a notação tabular: para datasets onde cada registro compartilha os mesmos campos, as chaves são declaradas uma vez em um cabeçalho e omitidas de cada linha subsequente — o oposto do que JSON e YAML fazem.

TOON não é um formato de configuração e nunca pretendeu ser. Não há sintaxe de comentário. Não há âncoras. Você não iria querer editar manualmente um dataset TOON de 500 linhas da mesma forma que não iria querer editar manualmente um arquivo binário. O que TOON oferece é um formato que codifica as mesmas informações que JSON em significativamente menos tokens — e menos tokens significa custos de API mais baixos, datasets efetivos maiores por prompt, e menos pressão nos limites da janela de contexto. O tokenizador da OpenAI é a forma mais rápida de ver isso na prática: cole o mesmo dataset nos dois formatos e compare.

• Notação tabular. name[count]{col1,col2,...}: seguido de uma linha de valores por linha. As chaves aparecem exatamente uma vez independentemente da contagem de linhas.
• Notação de objeto. {key:value,key2:value2} — sem aspas nas chaves, sem espaço em branco extra.
• Parsing inequívoco. Sem coerção booleana, sem sensibilidade a indentação, sem divergência de versão de especificação.
• Sem sintaxe de comentário. TOON não tem mecanismo para comentários inline — por design. É um formato de dados, não um formato de documento.
• Fraquezas. Ferramentas de nicho, sem história de edição humana, não apropriado para qualquer arquivo que um desenvolvedor abra e edite diretamente.

Lado a lado: Os mesmos dados no elemento de cada formato

A comparação mais honesta mostra cada formato fazendo o que realmente é bom — sem forçar um confronto onde um é claramente a ferramenta errada.

Primeiro, um manifesto de Deployment Kubernetes. Este é o território doméstico do YAML: um arquivo de configuração mantido por humanos com comentários, âncoras para valores compartilhados, e aninhamento profundo que mapeia para a hierarquia lógica de um objeto Kubernetes:

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

Escrever isso em TOON seria inútil — não são dados tabulares, serão editados por humanos, e se beneficiam de comentários que explicam valores não óbvios. YAML é a ferramenta certa aqui e não há disputa.

Agora os mesmos dados no território doméstico do TOON: um dataset de usuários sendo passado para um LLM para análise. É aqui que a notação tabular do TOON faz o trabalho:

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

Escrever isso como YAML — um array de 12 objetos, cada um com 7 chaves — repetiria todos os 7 nomes de chave 12 vezes. São 84 declarações de chave para 84 valores. TOON declara cada chave uma vez.

Onde YAML bate TOON sempre

Qualquer arquivo que um ser humano vá abrir, ler e editar pertence ao YAML (ou JSON, para casos mais simples). As vantagens decisivas são comentários e âncoras — dois recursos que TOON simplesmente não tem.

• Pipelines de CI/CD. GitHub Actions, GitLab CI, CircleCI — todos nativos de YAML. A capacidade de comentar uma etapa durante a depuração é genuinamente útil.
• Kubernetes e Helm. Cada manifesto, cada arquivo de valores, cada template de chart. O sistema de âncoras YAML é ativamente usado em charts Helm complexos para evitar repetir configs de ambiente.
• Docker Compose. Definições de múltiplos serviços com comentários explicando bindings de porta não óbvios, montagens de volume e configs de rede.
• Arquivos de configuração de aplicação. Configs no estilo pyproject.toml, configurações de aplicação, flags de features com comentários explicativos inline.
• Qualquer arquivo em controle de versão que humanos revisam em PRs. Comentários em config YAML fazem parte da documentação. TOON não pode participar desse fluxo de trabalho.

Onde TOON bate YAML sempre

Qualquer dado que é gerado programaticamente e passado para um LLM pertence ao TOON. YAML é na verdade pior que JSON para este caso de uso — sua sintaxe pesada em indentação e nomes de chaves repetidos adicionam tokens sem adicionar nenhuma informação que o modelo precisa.

• Payloads de prompt de LLM. Alimentando um dataset para GPT-4o, Claude ou Gemini para análise, classificação ou enriquecimento. A notação tabular do TOON reduz a contagem de tokens em 40–60% em comparação com JSON, e em comparação com YAML a diferença é ainda maior.
• Instruções de saída de LLM. Instruir um modelo a responder em TOON produz saída mais curta e mais barata. Saída YAML de um LLM é verbosa e sensível a indentação — um espaço desalinhado e o parsing quebra.
• Datasets gerados programaticamente. Se seu código está construindo os dados, deve construir TOON. Não há editor humano para se beneficiar de comentários ou indentação legível.
• Pipelines de lote de alto volume. Rodando 10.000 registros por um LLM por dia? Uma redução de 50% nos tokens é uma redução de 50% nessa linha da sua conta de API.
• Pressão na janela de contexto. Quando você precisa caber mais dados dentro do limite de contexto de um modelo, TOON permite empacotar mais linhas ao mesmo custo de tokens.

A realidade da contagem de tokens

Aqui está o mesmo dataset de 10 linhas em três formatos. Os números são aproximados mas consistentes com o que o tokenizador da OpenAI reporta para a tokenização do GPT-4o.

Array YAML de objetos:

- 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

Notação tabular TOON, mesmos dados:

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

A razão pela qual YAML performa pior que JSON em dados tabulares é estrutural: YAML usa uma linha por par chave-valor com indentação, então um objeto de 5 campos custa 5 linhas mais o marcador de lista. JSON pelo menos envolve o objeto inteiro em um conjunto de chaves. TOON elimina a repetição de chaves completamente — as chaves aparecem uma vez, os valores são empacotados em linhas. A economia se acumula com a contagem de linhas e campos.

Usando TOON em seu código

O pacote @toon-format/toon lida com codificação e decodificação:

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

Guia de decisão

A escolha entre YAML e TOON quase nunca é ambígua na prática:

• Use YAML se um humano vai ler ou editar o arquivo — pipelines CI/CD, manifestos Kubernetes, Docker Compose, configuração de aplicação, playbooks Ansible.
• Use YAML se você precisa de comentários inline para explicar valores não óbvios.
• Use YAML se você precisa de âncoras e aliases para manter uma configuração complexa DRY.
• Use YAML se você está trabalhando com uma ferramenta que espera YAML por convenção (Helm, GitHub Actions, k8s kubectl apply).
• Use TOON se os dados vão para um prompt de LLM — especialmente dados tabulares com múltiplas linhas.
• Use TOON se você está pedindo a um LLM para retornar dados estruturados e quer saída mais curta e mais barata.
• Use TOON se a contagem de tokens importa — pipelines de alto volume, datasets longos, pressão na janela de contexto.
• Use TOON se os dados são gerados programaticamente e nenhum humano vai editá-los diretamente.
• Use JSON (não YAML ou TOON) se você está construindo uma API REST, armazenando dados em um banco de dados, ou integrando com ferramentas de terceiros que esperam JSON.

Conclusão

YAML e TOON ocupam posições completamente diferentes em seu stack. YAML pertence ao seu repositório junto com seu código — arquivos de configuração, definições de pipeline, manifestos de infraestrutura. TOON pertence na fronteira entre seu aplicativo e APIs de LLM, onde converte seus dados estruturados na representação mais eficiente em tokens antes de enviar e converte a resposta do modelo de volta na saída. Não há sobreposição significativa entre esses trabalhos, o que é porque a questão não é "qual é melhor" mas "qual pertence aqui".

Se você está trabalhando com TOON, o TOON Formatter e TOON Validator são a forma mais rápida de inspecionar e verificar strings TOON. O conversor JSON para TOON converte payloads JSON existentes para TOON para uso em LLM, e o conversor TOON para JSON lida com a viagem de retorno quando um modelo responde em TOON e seu sistema downstream espera JSON. Veja também o artigo da Wikipedia sobre YAML para um histórico conciso do formato e um resumo de seus casos extremos conhecidos.