Guia de Sintaxe TOON — De Escalares a Dados Tabulares

A maioria dos formatos de dados foi projetada para um público: humanos ou máquinas. JSON pende para humanos. Formatos binários como MessagePack pendem para máquinas. TOON é explicitamente projetado para um terceiro público que não existia quando esses formatos foram inventados: modelos de linguagem grandes. Cada decisão de sintaxe no TOON prioriza a eficiência de tokens — caber o máximo de dados estruturados no mínimo de tokens para que você possa passar mais contexto para uma IA sem estourar seu orçamento. Este guia cobre cada recurso de sintaxe TOON, de escalares simples à notação tabular que o torna genuinamente diferente.

O que torna o TOON diferente

TOON significa Token-Optimised Object Notation. A ideia central é simples: formatos de serialização de dados como JSON foram projetados muito antes de preços de API por token existirem. JSON é ótimo para comunicação máquina a máquina, mas quando seu payload é um dataset de 200 linhas indo para um prompt gpt-4o, você está pagando por cada marca de aspas, cada chave e cada nome de chave repetido. TOON elimina esse desperdício. Instala como um único pacote npm — @toon-format/toon — e os arquivos usam a extensão .toon.

Valores escalares — Strings, Números, Booleanos

Escalares TOON parecem muito semelhantes aos seus equivalentes JSON, com uma diferença importante: os valores de string não requerem aspas a menos que contenham caracteres especiais como vírgulas, dois-pontos ou colchetes. Isso sozinho corta uma parte significativa de tokens de datasets com muito texto.

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

Quando uma string contém vírgula, dois-pontos ou colchete, envolva-a entre aspas duplas como no JSON. Então "New York, NY" precisa de aspas, mas London não. Regra simples, grande economia.

Objetos — Pares Chave:Valor Sem o Ruído

Objetos TOON usam chaves com sintaxe chave:valor. As chaves nunca são colocadas entre aspas — isso sozinho economiza dois caracteres por chave em comparação com JSON. Os pares são separados por vírgulas. Sem vírgulas finais, sem dois-pontos após o último par.

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

Compare com o JSON equivalente:

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

Mesmos dados, menos caracteres, e a economia de tokens acumula dramaticamente quando você trabalha com arrays de objetos. Falando nisso...

Arrays — Listas Ordenadas de Valores

Arrays em TOON usam colchetes com valores separados por vírgulas — exatamente como JSON, apenas sem aspas em valores de string simples.

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

Arrays de objetos funcionam, mas é aqui que o recurso matador do TOON aparece. Se você tem mais do que dois ou três linhas de dados estruturados, a notação tabular é dramaticamente mais eficiente.

Notação Tabular — O Recurso que Muda Tudo

A notação tabular é o recurso principal do TOON. É projetada para o cenário que você encontra constantemente no trabalho real: uma lista de objetos similares — produtos, usuários, transações, entradas de log — onde repetir as chaves em cada linha é puro desperdício. A sintaxe é:

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

Decompondo: name é o rótulo do dataset, [count] é o número de linhas de dados (obrigatório — diz ao parser exatamente quantas linhas ler), {col1,col2,...} é a linha de cabeçalho, os dois-pontos : terminam o cabeçalho, e cada linha indentada subsequente é uma linha de valores. Aqui está um exemplo real de produtos:

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

Agora imagine esses mesmos dados como um array de objetos JSON. Você escreveria "id", "name", "price", "inStock" e "category" cinco vezes cada — mais todas as chaves, colchetes e aspas ao redor. A representação TOON tabular é aproximadamente 60% menor na contagem de tokens para essa forma de dados.

Um dataset de usuários segue o mesmo padrão:

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

Aninhamento — Objetos, Arrays e Tabulares Juntos

TOON suporta aninhamento nos lugares que você esperaria. Um objeto pode conter um valor de array. Uma linha tabular pode conter um objeto. Isso permite representar dados do mundo real que não se encaixam perfeitamente em linhas planas.

Objeto contendo um array:

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

Dados tabulares com um objeto embutido em uma coluna (útil para dados de endereço, metadados, etc.):

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}

Mantenha o aninhamento raso quando possível. Dois ou três níveis de profundidade é onde o TOON ainda vence na contagem de tokens. Estruturas profundamente recursivas são melhor atendidas pelo JSON, que tem ferramentas mais ricas para validação de esquema — veja a referência MDN JSON se precisar disso.

Trabalhando com o pacote npm

Instale com npm ou qualquer gerenciador de pacotes compatível. TOON funciona em Node.js e navegadores modernos.

npm install @toon-format/toon

O pacote exporta duas funções: encode e decode. Essa é toda a API pública — intencionalmente mínima.

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

A opção { indent: 2 } controla o recuo dos valores de linha. Você também pode usar encode em objetos simples e valores primitivos, não apenas arrays — ele escolhe automaticamente a representação TOON mais compacta. Cole a saída no TOON Formatter para inspecionar e formatar.

Erros comuns

Estes são os erros que afetam desenvolvedores novos no TOON, geralmente na primeira hora:

• Contagem de linhas errada na notação tabular. Escrever products[3] mas incluir 4 linhas de dados causará um erro de parse ou descartará silenciosamente a última linha dependendo da versão do parser. Conte suas linhas e mantenha o número atualizado. O TOON Validator detecta isso imediatamente.
• Colocar chaves de objetos entre aspas. {"name":Alice} é TOON inválido — as chaves nunca são colocadas entre aspas. Remova as aspas: {name:Alice}.
• Esquecer os dois-pontos após o cabeçalho. products[2]{id,name} seguido de uma nova linha irá falhar. Você precisa dos dois-pontos finais: products[2]{id,name}:.
• Usar espaços ao redor dos dois-pontos em pares chave:valor. {name : Alice} não é válido. Sem espaços: {name:Alice}.
• Incorporar vírgulas em valores de string sem aspas. Se um nome de produto é "Bolts, Nuts & More", você deve colocá-lo entre aspas em linhas tabulares: 101,"Bolts, Nuts & More",4.99,true.
• Esperar saída JSON de decode em escalares. decode("42") retorna o número JavaScript 42, não um objeto JSON. TOON decodifica para tipos JS nativos.

Convertendo entre TOON e JSON

TOON e JSON são totalmente interconvertíveis — TOON é um superconjunto do mesmo modelo de dados lógico que JSON serializa. Use JSON para TOON para reduzir um dataset existente antes de enviá-lo para um LLM, e TOON para JSON para converter de volta quando precisar alimentar o resultado em um sistema downstream apenas-JSON. As funções encode e decode lidam com isso programaticamente se você estiver automatizando o fluxo de trabalho em Node.js. A especificação da estrutura de dados subjacente está intimamente relacionada aos conceitos de o global JSON em JavaScript.

Conclusão

A sintaxe TOON é intencionalmente compacta. Sem chaves entre aspas, sem nomes de chaves repetidos em tabelas, sem aspas obrigatórias em valores de string simples. Uma vez que você escrever um bloco tabular manualmente, verá imediatamente o porquê — um dataset que leva 40 linhas de JSON cabe em 8 linhas de TOON. O pacote npm em npmjs.com/@toon-format/toon mantém a superfície da API pequena: encode e decode, mais nada para aprender. Use o TOON Formatter para formatar, TOON Validator para detectar erros de sintaxe, JSON para TOON para converter seus dados existentes, e TOON para JSON quando precisar do resultado de volta no formato padrão.