JSON Toolkit

Guia do formato TOON: aliviar o JSON antes de entregá-lo a um LLM

Resumo: Ao passar um array uniforme para um modelo de linguagem em JSON, os nomes de chave repetidos e os colchetes consomem tokens. O TOON declara a estrutura uma única vez com objetos indentados e arrays tabulares, e despeja os dados linha por linha. Benchmarks oficiais mostram cerca de 40% menos tokens com maior precisão de análise. Este guia cobre a sintaxe, quando a economia se aplica, quando não vale converter e como conectar encode e decode.

Intermediário~6 min de leituraPublicado em 2026-11-10Atualizado em 2026-11-10
Sintaxe do array tabular TOON: cabeçalho de campos declarado uma vez, linhas de dados despejadas linha a linha

A sobrecarga sintática do JSON é irrelevante numa transferência entre máquinas, mas do lado de entrada de um LLM cobrado por tokens é dinheiro real: o mesmo array uniforme repete seus nomes de chave dezenas de vezes, e cada chave e cada aspas ocupam uma fatia do orçamento. O TOON não inventa um novo modelo de dados — ele reescreve o modelo de dados JSON numa notação mais barata.

O que é o TOON: outra codificação do JSON, não um concorrente

TOON (Token-Oriented Object Notation) é um formato aberto surgido em 2025, e o posicionamento oficial cabe numa frase: uma codificação compacta, sem perdas e legível do modelo de dados JSON. Ele não introduz tipos novos — objetos, arrays, strings, números, booleanos e null correspondem um a um ao JSON, e decode(encode(x)) é estritamente igual aos dados originais (tipos fora do JSON como Date ou NaN precisam ser normalizados antes). O vai-e-vem é sem perdas e determinístico: a mesma entrada produz sempre a mesma saída, o que importa para construir prompts reproduzíveis.

Como ele codifica exatamente o modelo de dados JSON, o jeito certo de usar o TOON é como formato de fronteira: a aplicação continua funcionando em JSON internamente, converte para TOON pouco antes de colocar os dados num prompt e volta a converter ao receber a resposta do modelo. A documentação oficial chama isso de "translation layer". A extensão de arquivo convencional é .toon; para transporte HTTP, o tipo de mídia provisório é text/toon, em UTF-8.

Um aviso sobre ruído de busca: não confunda com os Toon Shaders dos gráficos 3D. Eles só dividem a palavra.

Por que o JSON é especialmente caro no lado de entrada de um LLM

Pegue uma lista de pedidos, um cadastro de usuários ou um resumo de logs escritos como array JSON. Os tokens vão para três lugares:

  1. Nomes de chave repetidos. Cinquenta registros de pedidos escrevem "id", "amount" e "status" cinquenta vezes cada um. Dobre os dados e dobre a sobrecarga.
  2. Pontuação estrutural. Chaves, colchetes, dois-pontos e vírgulas consomem tokens, e o aninhamento os empacota mais densos.
  3. Aspas. Quase toda chave e todo valor string vêm envoltos em aspas duplas.

Somando tudo: o custo da API cobrado por token sobe direto; entradas longas batem antes no teto da janela de contexto; e em entradas muito longas o modelo omite ou desalinha campos com mais frequência. O benchmark da página oficial: sobre um conjunto de teste de estruturas mistas e quatro modelos, cerca de 40% menos tokens com a precisão de análise subindo de 70% (JSON) para 74% (TOON). Economia e precisão não são um trade-off aqui, porque a estrutura mais enxuta torna as fronteiras mais visíveis para o modelo.

A sintaxe: objetos indentados + arrays tabulares

Os mesmos dados de previsão do tempo em três formas. Versão JSON, cerca de 117 tokens:

{
  "location": { "city": "Berlin", "country": "DE", "units": "metric" },
  "alerts": ["frost", "wind"],
  "forecast": [
    { "day": "Mon", "temp": { "min": -2, "max": 4 }, "condition": "snow", "rainChance": 80 },
    { "day": "Tue", "temp": { "min": 1, "max": 7 }, "condition": "cloudy", "rainChance": 20 },
    { "day": "Wed", "temp": { "min": 3, "max": 11 }, "condition": "sunny", "rainChance": 5 }
  ]
}

Versão TOON, cerca de 66 tokens:

location:
  city: Berlin
  country: DE
  units: metric
alerts[2]: frost,wind
forecast[3]{day,temp{min,max},condition,rainChance}:
  Mon,-2,4,snow,80
  Tue,1,7,cloudy,20
  Wed,3,11,sunny,5

Três formas cobrem tudo, e o serializador as escolhe automaticamente pela forma dos dados:

Forma Serve para Equivalente JSON
Objeto indentado Objetos aninhados { "location": { ... } }, a indentação substitui as chaves
Array em linha Arrays de primitivos ["frost","wind"], [2] declara o comprimento
Array tabular Arrays de objetos uniformes Os nomes de campo aparecem uma única vez no cabeçalho {day,temp{min,max},...}; cada linha contém só valores separados por vírgulas

Objetos aninhados uniformes (temp{min,max}) se dobram no cabeçalho como grupo de campos aninhado, e as linhas de dados continuam planas. A regra de aspas é mínima: strings só recebem aspas se contêm delimitadores, caracteres especiais ou podem ser lidas como números — uma das razões pelas quais o TOON vence o "JSON compacto" na contagem de tokens. A diferença chave do YAML: o TOON tem declarações de comprimento explícitas e cabeçalhos de campos que máquinas podem validar; do CSV: ele mantém o aninhamento e os tipos.

[N] e {fields}: guarda-corpos estruturais para o modelo

[3] e {day,...} não servem só para economizar tokens — são um contrato verificável entregue ao modelo:

  • O comprimento do array permite ao modelo responder diretamente "quantos registros tem o conjunto de dados" e expõe imediatamente um truncamento quando o número de linhas não bate.
  • O cabeçalho de campos declara os nomes uma vez; o modelo alinha os valores pela posição em vez de re-adivinhar a correspondência das chaves em cada linha.

Isso é prevenção, o oposto do resgate posterior. Um reparador de JSON (veja a pipeline de reparo) recupera os dados depois que o modelo cospe JSON quebrado; as declarações de comprimento e campos do TOON reduzem, na entrada, a probabilidade de dados quebrados. Faça as duas coisas e a taxa de falhas de análise no meio da pipeline cai.

Quando não usar TOON

A seção oficial "When Not to Use TOON" é refrescantemente franca. Quatro cenários, que vale copiar como está:

Cenário Por que evitar Melhor opção
Estruturas profundamente aninhadas, não uniformes Elegibilidade tabular ≈ 0%; o JSON compacto costuma ganhar JSON compacto
Arrays semi-uniformes Campos irregulares, a economia quase desaparece Manter a pipeline JSON
Dados puramente tabulares O TOON custa 5–10% de overhead frente ao CSV CSV
Sensível à latência (modelos locais/quantizados) Menos tokens ≠ inferência mais rápida Medir o TTFT primeiro

O semi-uniforme se julga pela elegibilidade tabular (tabular eligibility): oficialmente, com 40–60% de elegibilidade a economia já é marginal. Uma migração de formato tem custo real — parsers, validadores e scripts a jusante mudam todos — então, se o ganho for menor que dez por cento, nem mexa.

Colocando em prática: encode / decode e a CLI

A biblioteca TypeScript oficial, nos dois sentidos:

npm install @toon-format/toon
# A conversão em lote também passa pela CLI
npx @toon-format/cli input.json -o output.toon
import { encode, decode } from '@toon-format/toon'

const data = {
  users: [
    { id: 1, name: 'Ada', role: 'admin' },
    { id: 2, name: 'Bob', role: 'user' },
  ],
}

const toon = encode(data)
// users[2]{id,name,role}:
//   1,Ada,admin
//   2,Bob,user

const back = decode(toon)  // estritamente igual aos dados originais

Existem implementações em Python, Go, Rust e .NET; consulte a lista de implementações do repositório oficial da especificação antes de adotar uma, e confirme que ela cobre as características de sintaxe que você usa. Antes da produção, rode uma asserção de vai-e-vem: decode(encode(originais)) precisa ser profundamente igual ao original; se não for, a implementação ou os dados têm um problema.

Como encaixar na sua cadeia JSON existente

O TOON não muda nada na sua pipeline JSON; adiciona uma conversão de fronteira. Ordem recomendada:

  1. Garanta primeiro que o JSON está limpo. JSON quebrado produz TOON quebrado. A validação sintática e o reparo ficam cobertos no Guia de reparo de JSON.
  2. Confira a forma dos dados. Os objetos do array têm todos os campos? Normalize primeiro, ou conclua que a conversão não vale a pena.
  3. Converta e faça amostragem. Depois de converter, compare uma linha de dados com o JSON original para confirmar que o alinhamento dos campos não desviou.
  4. Estime o benefício. Para listas uniformes, o raciocínio linha a linha do manual de JSONL se aplica à conversão em fluxo; para a relação entre tamanho e custo, a verdadeira relação entre JSON minify e gzip dá a mesma lição: medir primeiro, converter depois.

O TOON vai substituir o JSON?

Não. O TOON codifica o modelo de dados JSON; seu lugar é a fronteira do prompt, enquanto o armazenamento e a troca entre programas continuam sendo território do JSON. Use o TOON no segmento "entregar ao modelo" e deixe o resto da cadeia intacta.

Qual a relação do TOON com YAML e CSV?

Os objetos lembram o YAML (indentação em vez de chaves); os arrays uniformes lembram o CSV (cabeçalho declarado uma vez, linhas em fluxo). Mas o TOON tem declarações de comprimento explícitas que o YAML não tem, e mantém o aninhamento e os tipos que o CSV não tem — ele fica entre os dois, com guarda-corpos verificáveis por máquina.

A conversão de TOON para JSON perde dados?

Não: objetos, arrays, strings, números, booleanos e null correspondem um a um, e decode(encode(x)) é estritamente igual. A única cautela é normalizar antes os tipos fora do JSON como Date e NaN; caso contrário, a igualdade só se cumpre depois do vai-e-vem.

Como verifico se o TOON convertido está correto?

Duas checagens: uma asserção de vai-e-vem (encode e depois decode, igualdade profunda com o original) e uma inspeção visual do cabeçalho — o número de [N] precisa igualar o número de linhas, e os campos de {fields} precisam alinhar um a um com os valores separados por vírgulas de cada linha. Do lado do modelo, você também pode pedir que ele informe o comprimento do array antes de responder.