O que é o Formato TOON? Uma Introdução para Desenvolvedores

A maioria dos desenvolvedores tem uma lista mental curta de formatos de dados: JSON para APIs, CSV para planilhas, YAML para arquivos de configuração, talvez XML se estiver trabalhando com sistemas legados. Mas há um formato mais recente que está silenciosamente ganhando espaço no ecossistema de ferramentas de IA e vale a pena conhecer — TOON, ou Token-Oriented Object Notation. Ele foi projetado do zero para um problema específico: passar dados estruturados para modelos de linguagem grandes sem desperdiçar seu orçamento de tokens.

O que é TOON?

TOON significa Token-Oriented Object Notation. É um formato de serialização de dados compacto, criado especificamente para minimizar o número de tokens consumidos quando dados estruturados são incorporados em prompts ou respostas de LLMs. Pense nele como JSON com toda a verbosidade removida — sem nomes de chaves repetidos em arrays, sem aspas redundantes, sem espaços em branco desnecessários — apenas o sinal com o mínimo de ruído sintático possível.

O pacote npm é @toon-format/toon, e oferece uma API simples de encode / decode que funciona em qualquer projeto Node.js ou bundler moderno. Os arquivos TOON usam a extensão .toon.

Por que não usar apenas JSON?

JSON é excelente para comunicação máquina a máquina onde a largura de banda é barata e o parsing é tratado pelo runtime. Mas quando você está enviando dados como parte de um prompt para a API da OpenAI ou a API da Anthropic, cada caractere conta — literalmente. Ambas as APIs cobram por token, e os tokens correspondem aproximadamente a 4 caracteres de texto em inglês.

Considere uma tabela de 100 registros de usuários. Em JSON, você repetiria as chaves — "id", "name", "role", "email" — uma vez por registro. Isso são 100 cópias da mesma informação estrutural. A sintaxe tabular do TOON define essas chaves uma vez e lista os valores linha por linha, da mesma forma que um CSV faz, mas com a estrutura do objeto preservada. A economia de tokens em conjuntos de dados reais pode ser de 40 a 70% em comparação com JSON compacto.

Sintaxe TOON de relance

O TOON suporta quatro formas de dados centrais: escalares (strings, números, booleanos), arrays, objetos e dados tabulares. A sintaxe de escalares e coleções parecerá familiar se você já trabalhou com JSON — o formato tabular é onde o TOON realmente se diferencia.

Um objeto simples elimina os espaços em branco das chaves externas, omite aspas desnecessárias e separa pares chave-valor com vírgulas:

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

Um array simples de escalares parece exatamente como você esperaria:

[1,2,3]

Agora é onde fica interessante — dados tabulares. Esta é a sintaxe que torna o TOON atraente para casos de uso de LLM. Em vez de repetir chaves para cada objeto em um array, você declara o esquema uma vez no cabeçalho e lista os valores linha por linha:

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

Esse bloco representa um array de 3 objetos de usuário — equivalente ao JSON abaixo — mas em uma fração dos tokens. O cabeçalho users[3]{id,name,role} diz ao parser: "esta é uma variável chamada users, tem 3 linhas, e cada linha mapeia para os campos id, name e role". As linhas são valores puros, sem repetição de chaves.

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

Instalando e usando o pacote @toon-format/toon

O pacote npm oficial lida tanto com a codificação de valores JavaScript para strings TOON quanto com a decodificação de strings TOON de volta para objetos e arrays JavaScript. Instale-o do registro npm:

npm install @toon-format/toon

O pacote exporta duas funções — encode e decode:

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}

A opção indent em encode() controla se a saída é formatada de forma legível. Para prompts de LLM, geralmente você vai querer saída compacta (sem indent) para economizar tokens. Para depuração ou arquivos .toon legíveis por humanos, { indent: 2 } fornece saída bem formatada.

Um caso de uso real: Enviando registros para um LLM

Imagine que você está construindo um recurso de análise de produtos que precisa resumir a atividade do usuário. Você busca registros de sessão recentes do seu banco de dados e quer enviá-los para um LLM para sumarização em linguagem natural. Veja como fica com TOON:

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}`;

A representação TOON desses 5 registros de sessão é significativamente mais curta que o JSON equivalente, que repetiria "userId", "action", "duration" e "page" cinco vezes cada. Em centenas de registros, a economia é substancial e se traduz diretamente em custos de API menores e tempos de resposta mais rápidos (menos tokens para processar na janela de atenção).

Tipos de dados principais em TOON

O TOON mapeia claramente para os primitivos que você já usa em JavaScript e na maioria dos outros idiomas:

• Strings — Sem aspas quando não contêm caracteres especiais. Colocadas entre aspas duplas quando incluem vírgulas, dois-pontos ou espaços em branco.
• Números — Inteiros e floats escritos como estão: 42, 3.14, -7.
• Booleanos — true e false, igual ao JSON.
• Null — Escrito como null para valores ausentes ou indefinidos.
• Arrays — Sintaxe de colchetes inline [val1,val2,val3] para listas curtas; sintaxe de cabeçalho tabular para arrays de objetos.
• Objetos — Sintaxe de chaves {key:value,key2:value2} para objetos únicos.
• Dados tabulares — A estrela do show: cabeçalho name[n]{col1,col2,...}: seguido de linhas separadas por vírgulas — ideal para qualquer coleção de registros com a mesma forma.

Quando usar TOON vs outros formatos

O TOON não está tentando substituir o JSON como formato de intercâmbio geral. Ele preenche um nicho específico. Aqui está um guia rápido de decisão:

• Use JSON quando estiver construindo APIs REST, armazenando documentos em um banco de dados ou passando dados entre serviços. JSON é universalmente suportado, bem equipado com ferramentas e legível por humanos.
• Use TOON quando dados estruturados fazem parte de um prompt ou janela de contexto de LLM e a contagem de tokens importa. O formato tabular brilha sempre que você trabalha com linhas de registros — listas de usuários, entradas de log, catálogos de produtos, eventos de análise.
• Use CSV quando você precisar apenas de dados tabulares planos e o consumidor esperar CSV (planilhas, ferramentas de BI). CSV não tem aninhamento de objetos, então TOON é mais expressivo.
• Use YAML para arquivos de configuração editados por humanos onde legibilidade e comentários importam mais que compactação.
• Use TOON para saídas de ferramentas de LLM também: se um LLM estiver chamando sua ferramenta e retornando resultados estruturados, codificar esses resultados em TOON economiza tokens tanto no lado de entrada quanto de saída da chamada de API.

Conclusão

TOON — Token-Oriented Object Notation — é um formato de serialização compacto construído para a era dos LLMs. Mantém a estrutura familiar do JSON (objetos, arrays, escalares) enquanto introduz uma sintaxe tabular que elimina a repetição redundante de chaves em registros. O resultado é um formato que pode ser 40 a 70% menor que o JSON equivalente, o que se traduz diretamente em custos de tokens mais baixos ao trabalhar com a API da OpenAI, API da Anthropic ou qualquer outro serviço de LLM cobrado por token.

Se quiser explorar o TOON na prática, temos um conjunto completo de ferramentas aqui: use o TOON Formatter para formatar e inspecionar documentos TOON, o TOON Validator para detectar erros de sintaxe, o conversor JSON para TOON para migrar payloads existentes, e o conversor TOON para JSON se precisar ir na outra direção. O pacote npm @toon-format/toon fornece encode e decode para integrar o TOON diretamente em seu código Node.js ou no lado do navegador em minutos.