Tanto JSON quanto TOON representam dados estruturados. Ambos são baseados em texto. Ambos podem descrever objetos, arrays e hierarquias aninhadas. Então se você encontrou o TOON e se perguntou se é apenas mais uma alternativa ao JSON tentando resolver um problema que não existe — é uma pergunta justa. A resposta é: eles são otimizados para trabalhos completamente diferentes, e quando você vê isso apresentado, a escolha fica óbvia.

JSON é a linguagem universal de intercâmbio de dados. É a espinha dorsal das APIs REST há mais de uma década, é suportado nativamente em todas as linguagens de programação modernas, e é o que você usa por padrão. TOON é um formato mais recente com uma missão mais estreita: minimizar o uso de tokens quando você passa dados estruturados para e de modelos de linguagem grandes. Os mesmos dados subjacentes, pegada radicalmente diferente.

O que torna o JSON excelente

O superpoder do JSON é a ubiquidade. A especificação RFC 8259 é simples o suficiente para caber em algumas páginas, razão pela qual toda linguagem, de Python a Go a Rust, tem um parser JSON de primeira classe em sua biblioteca padrão ou ecossistema. Você não precisa instalar nada. Não precisa explicar o formato para seus colegas. E as ferramentas — formatadores, validadores, validadores de esquema — estão universalmente disponíveis.

  • Universalmente suportado. Toda linguagem, todo runtime, todo serviço de nuvem fala JSON nativamente.
  • Legível por humanos. As chaves são strings entre aspas, a estrutura é explícita com chaves e colchetes.
  • Primitivos tipados. Números, booleanos, nulls, strings, arrays e objetos — todos representados sem ambiguidade.
  • Ferramentas ricas. Linters, formatadores, validadores de JSON Schema, motores de consulta JSONPath — o ecossistema é enorme.
  • Padrão de API REST. Content-Type: application/json é a expectativa padrão em praticamente toda API HTTP.

O que torna o TOON diferente

O TOON foi construído com uma restrição específica em mente: janelas de contexto de LLM e custos de tokens. Quando você chama a API da OpenAI ou qualquer outro provedor de LLM, você paga por token. Os tokens não são caracteres — são aproximadamente fragmentos de palavras, e a pontuação estrutural do JSON (aspas, dois-pontos, vírgulas, chaves) consome um número surpreendente deles. Para dados tabulares especialmente, JSON é dispendioso: cada linha repete cada nome de chave.

O TOON resolve isso com uma notação compacta. Para dados tabulares, as chaves são declaradas uma vez em um cabeçalho, e as linhas são valores simples separados por vírgulas. Para objetos únicos e arrays, usa uma sintaxe inline enxuta. O tokenizador da OpenAI é uma ferramenta útil para ver a diferença na prática — cole os mesmos dados em ambos os formatos e compare a contagem de tokens diretamente.

Lado a lado: Dataset de 10 linhas

Aqui está uma tabela de produtos com 10 linhas em JSON — o tipo de coisa que você pode passar para um LLM para pedir que analise preços ou categorize itens:

json
[
  {"id": 1,  "name": "Wireless Mouse",      "category": "Electronics", "price": 29.99, "inStock": true},
  {"id": 2,  "name": "USB-C Hub",           "category": "Electronics", "price": 49.99, "inStock": true},
  {"id": 3,  "name": "Mechanical Keyboard", "category": "Electronics", "price": 89.99, "inStock": false},
  {"id": 4,  "name": "Monitor Stand",       "category": "Furniture",   "price": 39.99, "inStock": true},
  {"id": 5,  "name": "Webcam HD",           "category": "Electronics", "price": 69.99, "inStock": true},
  {"id": 6,  "name": "Desk Mat",            "category": "Accessories", "price": 19.99, "inStock": true},
  {"id": 7,  "name": "Laptop Stand",        "category": "Furniture",   "price": 34.99, "inStock": false},
  {"id": 8,  "name": "LED Desk Lamp",       "category": "Furniture",   "price": 44.99, "inStock": true},
  {"id": 9,  "name": "Cable Organiser",     "category": "Accessories", "price": 14.99, "inStock": true},
  {"id": 10, "name": "Headphone Hook",      "category": "Accessories", "price": 12.99, "inStock": false}
]

Agora os mesmos dados em TOON. As chaves são declaradas uma vez no cabeçalho — as linhas contêm apenas valores:

text
products[10]{id,name,category,price,inStock}:
  1,Wireless Mouse,Electronics,29.99,true
  2,USB-C Hub,Electronics,49.99,true
  3,Mechanical Keyboard,Electronics,89.99,false
  4,Monitor Stand,Furniture,39.99,true
  5,Webcam HD,Electronics,69.99,true
  6,Desk Mat,Accessories,19.99,true
  7,Laptop Stand,Furniture,34.99,false
  8,LED Desk Lamp,Furniture,44.99,true
  9,Cable Organiser,Accessories,14.99,true
  10,Headphone Hook,Accessories,12.99,false
Economia de tokens na prática: A versão JSON acima registra cerca de 420 tokens no tokenizador da OpenAI. A versão TOON é aproximadamente 195 tokens — menos da metade. Em escala (milhares de chamadas de API por dia, ou datasets com centenas de linhas), essa diferença se torna dinheiro real.

Usando TOON em JavaScript / TypeScript

O pacote npm @toon-format/toon lida com codificação e decodificação. Instale uma vez e a API é simples:

bash
npm install @toon-format/toon
ts
import { encode, decode } from '@toon-format/toon';

const products = [
  { id: 1, name: 'Wireless Mouse', category: 'Electronics', price: 29.99, inStock: true },
  { id: 2, name: 'USB-C Hub',      category: 'Electronics', price: 49.99, inStock: true },
  // ...mais linhas
];

// Codificar para TOON antes de enviar para um LLM
const toonString = encode(products);
// products[2]{id,name,category,price,inStock}:
//   1,Wireless Mouse,Electronics,29.99,true
//   2,USB-C Hub,Electronics,49.99,true

// Decodificar TOON de volta para um array JS simples quando o LLM retornar
const decoded = decode(toonString);
console.log(decoded[0].name); // "Wireless Mouse"

Você também pode codificar um único objeto inline. A notação de objetos do TOON usa chaves sem colocar chaves entre aspas, e sua notação de array é simplesmente valores separados por vírgulas em colchetes:

text
// TOON object
{name:Alice,age:30,role:admin}

// TOON array
[1,2,3,4,5]

Quando usar TOON

  • Prompts de LLM com dados estruturados. Alimentando uma tabela, lista de registros ou catálogo de produtos em uma chamada GPT-4 / Claude / Gemini. A economia de tokens reduz diretamente sua conta de API.
  • Parsing de saída de LLM. Se você instruir um LLM a responder em TOON, as respostas são mais curtas e mais baratas tanto em tokens de entrada quanto de saída.
  • Dados tabulares especificamente. A estrutura cabeçalho-uma-vez-depois-linhas do TOON é dramaticamente mais compacta que JSON para qualquer coisa em forma de tabela.
  • Pipelines de processamento em lote. Rodando milhares de registros por um LLM diariamente? Mesmo uma redução de 40% nos tokens acumula rapidamente.
  • Pressão na janela de contexto. Quando você está batendo no limite de contexto de um modelo, o TOON permite que você caiba mais dados na mesma janela.

Quando ficar com JSON

  • APIs REST. Todo cliente HTTP, todo framework de servidor, todo gateway de API fala JSON. Não quebre a convenção.
  • Arquivos de configuração. package.json, tsconfig.json, settings.json — JSON é o padrão para configuração na maioria dos ecossistemas.
  • Armazenamento em banco de dados. jsonb do PostgreSQL, documentos MongoDB, DynamoDB — estes são nativos de JSON. TOON não pertence aqui.
  • Comunicação entre serviços. Quando dois serviços se comunicam, use JSON. É o que suas ferramentas de logging, rastreamento e monitoramento entendem.
  • APIs públicas. Se desenvolvedores externos estão consumindo sua API, JSON é o contrato esperado. TOON é uma otimização interna, não um formato de interface pública.
  • Parsing nativo do navegador. JSON.parse() está integrado em todo navegador. TOON requer uma biblioteca.

Guia de decisão

Uma lista de verificação rápida para resolver a questão:

  • Os dados vão para um prompt de LLM? Use TOON.
  • Espera-se que o LLM retorne dados estruturados? Use TOON.
  • Os dados são tabulares (mesmas chaves em muitas linhas)? Considere fortemente TOON.
  • É uma requisição ou resposta de API REST? Use JSON.
  • É um arquivo de configuração? Use JSON (ou YAML).
  • Está armazenado em um banco de dados? Use JSON.
  • Ferramentas não-LLM vão consumir esses dados? Use JSON.
  • Não tem certeza se os custos de tokens importam para seu caso de uso? Comece com JSON, otimize depois.

Ferramentas úteis

Se você está trabalhando com ambos os formatos, estas ferramentas vão poupar seu tempo. Use o conversor JSON para TOON para pegar dados JSON existentes e produzir uma representação TOON compacta pronta para entrada de LLM. O conversor TOON para JSON vai na outra direção — útil quando um LLM retorna TOON e você precisa alimentar o resultado em um sistema downstream nativo de JSON. O TOON Formatter vai limpar e validar strings TOON, e o JSON Formatter continua sendo o favorito para formatar blobs JSON brutos.

Conclusão

JSON e TOON não são competidores no sentido tradicional — eles têm como alvo partes diferentes do seu stack. JSON é dono da camada de API, arquivos de configuração e armazenamento de dados. TOON é dono da camada de LLM, onde a contagem de tokens é dinheiro e o espaço da janela de contexto é precioso. A boa notícia é que você pode usar ambos no mesmo projeto sem atrito: armazenar e transferir dados como JSON, codificar para TOON imediatamente antes de qualquer chamada de LLM, e decodificar de volta para JSON ou um objeto nativo na saída. Uma vez que você configurou esse padrão, a economia de tokens é automática.

← All TOON articles Browse all categories →