TOON vs JSON vs CSV — Escolhendo o Formato Certo

Três formatos entram em uma reunião de planejamento. JSON diz que pode lidar com tudo. CSV diz que é rápido e enxuto. TOON diz que está aqui para falar com a IA. Todos estão certos — para trabalhos diferentes. A parte frustrante não é que esses formatos existem, é que escolher o errado para seu caso de uso tem custos reais e concretos: payloads verbosos, importações quebradas, contas de LLM caras, ou dores de cabeça com parsing. Este guia dá a você um framework claro para escolher.

Um retrato rápido de cada formato

JSON (JavaScript Object Notation) emergiu do JavaScript no início dos anos 2000 e tornou-se o formato dominante para APIs web graças à sua simplicidade e expressividade. Lida com estruturas aninhadas nativamente, distingue entre strings, números, booleanos e nulls sem cerimônia extra, e é especificado pela RFC 8259. Toda linguagem moderna tem uma biblioteca JSON de primeira classe.

CSV (Comma-Separated Values) é mais antigo que a web. É definido pela RFC 4180 e é essencialmente a língua franca dos dados tabulares planos. Abra qualquer CSV no Excel, Google Sheets ou Numbers e simplesmente funciona. Para tabelas planas puras, é o formato mais compacto e universalmente importável que existe.

TOON é um formato mais recente construído especificamente para fluxos de trabalho de LLM. Inspira-se em ambos — como CSV usa uma estrutura cabeçalho-uma-vez-depois-linhas para dados tabulares, mas como JSON também pode codificar objetos e arrays aninhados. Seu design inteiro é orientado para minimizar a contagem de tokens ao passar dados para e de modelos de linguagem grandes.

Os mesmos dados nos três formatos

Para tornar isso concreto, vamos usar um catálogo de produtos que inclui um objeto specs aninhado — uma forma do mundo real que exercita os três formatos de forma significativa. Aqui estão quatro produtos de uma loja eletrônica:

JSON — expressivo, lida com aninhamento naturalmente, mas verboso para dados de linhas repetitivas:

[
  {
    "id": "P001",
    "name": "Wireless Headphones",
    "category": "Audio",
    "price": 79.99,
    "inStock": true,
    "specs": { "weight": "250g", "connectivity": "Bluetooth 5.2", "battery": "30h" }
  },
  {
    "id": "P002",
    "name": "USB-C Docking Station",
    "category": "Peripherals",
    "price": 129.99,
    "inStock": true,
    "specs": { "ports": 11, "maxPower": "100W", "display": "4K@60Hz" }
  },
  {
    "id": "P003",
    "name": "Mechanical Keyboard",
    "category": "Input",
    "price": 94.99,
    "inStock": false,
    "specs": { "layout": "TKL", "switches": "Cherry MX Red", "backlight": "RGB" }
  },
  {
    "id": "P004",
    "name": "27" IPS Monitor",
    "category": "Display",
    "price": 299.99,
    "inStock": true,
    "specs": { "resolution": "2560x1440", "refreshRate": "165Hz", "panel": "IPS" }
  }
]

CSV — compacto, amigável ao Excel, mas o objeto specs aninhado precisa ser achatado. Não há forma padrão de representá-lo, então ou perdemos o aninhamento ou o convertemos em uma string:

id,name,category,price,inStock,specs_weight,specs_ports,specs_layout,specs_resolution
P001,Wireless Headphones,Audio,79.99,true,250g,,,
P002,USB-C Docking Station,Peripherals,129.99,true,,11,,
P003,Mechanical Keyboard,Input,94.99,false,,,TKL,
P004,27" IPS Monitor,Display,299.99,true,,,,2560x1440

TOON — cabeçalho declarado uma vez, linhas são compactas, objetos aninhados codificados inline:

products[4]{id,name,category,price,inStock,specs}:
  P001,Wireless Headphones,Audio,79.99,true,{weight:250g,connectivity:Bluetooth 5.2,battery:30h}
  P002,USB-C Docking Station,Peripherals,129.99,true,{ports:11,maxPower:100W,display:4K@60Hz}
  P003,Mechanical Keyboard,Input,94.99,false,{layout:TKL,switches:Cherry MX Red,backlight:RGB}
  P004,27" IPS Monitor,Display,299.99,true,{resolution:2560x1440,refreshRate:165Hz,panel:IPS}

Onde cada formato falha

Entender os modos de falha é tão importante quanto conhecer os pontos fortes.

• JSON falha em tabelas. Repetir cada nome de chave em cada linha é genuinamente desperdiçador. Um dataset de 1000 linhas onde cada linha tem 8 chaves significa "id", "name", "price" e assim por diante escritos 1000 vezes cada. Para entrada de LLM isso se traduz diretamente em custo de tokens; para inspeção humana é apenas ruído.
• CSV falha em dados aninhados. O formato não tem conceito de aninhamento. Você pode serializar um objeto aninhado em uma célula, mas então o consumidor precisa saber para analisar essa célula — você apenas moveu o problema. CSV também não tem sistema de tipos nativo: true é uma string, 42 é uma string, null é ambíguo. Ferramentas lidam com isso de forma inconsistente.
• TOON falha fora de contextos de LLM. É um formato de nicho com um ecossistema mais estreito. Você não encontrará suporte nativo a TOON no PostgreSQL, em seu framework REST, ou no Excel. O pacote npm cobre fluxos de trabalho JavaScript/TypeScript bem, mas se você está alcançando TOON em um contexto que não tem nada a ver com IA, provavelmente está sobre-engenheirando.
• CSV falha em valores contendo vírgulas ou novas linhas. As regras de citação da RFC 4180 lidam com isso, mas muitos produtores e consumidores de CSV as implementam de forma inconsistente. Um nome de produto como 27" IPS Monitor, Black ou uma descrição com quebras de linha se torna um risco de confiabilidade.

Matriz de decisão

Aqui está um guia prático. Corresponda sua situação ao formato apropriado:

• Seus dados vão para um prompt de LLM → TOON. Especialmente se for tabular. Use JSON para TOON para converter antes da chamada de API.
• Seus dados voltam de um LLM e precisam ser processados → TOON (para saída), então decodifique para JSON ou um objeto nativo para uso downstream com TOON para JSON.
• Seus dados são puramente tabulares planos (mesmas chaves em cada linha) e vão para/de planilhas → CSV. É a representação menor e universalmente importável.
• Seus dados são tabulares planos mas serão transformados por código (não planilhas) → CSV ou JSON. JSON é mais seguro se os tipos importam (você não quer "true" em vez de true).
• Seus dados têm objetos ou arrays aninhados → JSON. Não lute contra a limitação apenas-plano do CSV. Se o aninhamento vai para um LLM, codifique para TOON depois de construir a estrutura.
• Seus dados vão para uma API REST ou armazenados em um banco de dados → JSON. Sempre.
• Seus dados são um arquivo de configuração → JSON ou YAML. Nem CSV nem TOON pertencem aqui.
• Você precisa de máxima portabilidade e um parser sem dependências → JSON ou CSV. Ambos têm suporte nativo ou quase nativo em todo lugar.

Usando os três em um pipeline

Um pipeline realista pode usar os três. Imagine um fluxo de trabalho de e-commerce que enriquece dados de produtos com descrições geradas por IA:

import { encode, decode } from '@toon-format/toon';

// Step 1: Products arrive as JSON from your REST API
const products = await fetch('/api/products').then(r => r.json());

// Step 2: Encode to TOON to minimise tokens before the LLM call
const toonInput = encode(products);

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [
    {
      role: 'user',
      content: `Here is our product catalogue in TOON format:\n\n${toonInput}\n\n
                For each product, write a one-sentence marketing description.
                Return results as TOON with fields: id, description`
    }
  ]
});

// Step 3: Decode the LLM's TOON response back to objects
const enriched = decode(response.choices[0].message.content);

// Step 4: Export to CSV for the marketing team's spreadsheet
const csvRows = enriched.map(row => `${row.id},"${row.description}"`);
const csv = ['id,description', ...csvRows].join('\n');

JSON para a camada de API, TOON através da camada de LLM, CSV para a saída consumível por humanos. Cada formato está fazendo exatamente o trabalho para o qual foi projetado.

Referência rápida de ferramentas

Se você está se movendo entre esses formatos, estas ferramentas cobrirão as conversões comuns. O TOON Formatter é a forma mais rápida de validar e limpar strings TOON. O conversor JSON para TOON lida com a etapa de preparação para LLM. Indo na outra direção depois que um LLM retorna TOON, TOON para CSV pode produzir uma exportação pronta para planilha diretamente, e CSV para JSON é o favorito para normalizar importações do Excel ou provedores de dados de terceiros. Para detalhes específicos do TOON, o pacote oficial está no npm.

Conclusão

JSON, CSV e TOON têm cada um um domínio claro. JSON é o formato universal para intercâmbio de dados estruturados — aninhados ou planos, APIs, configuração, armazenamento. CSV é o formato universal para dados tabulares planos que precisam viajar entre sistemas e humanos — planilhas, importações, exportações. TOON é o formato para passar dados estruturados por sistemas de IA de forma eficiente, onde cada token conta. O erro que a maioria dos desenvolvedores comete é usar JSON por padrão para tudo, incluindo prompts de LLM, ou usar CSV por padrão e então descobrir requisitos de aninhamento no meio do projeto. Conheça a forma de seus dados, saiba para onde eles vão, e o formato certo geralmente se escolhe sozinho.

Para uma análise mais profunda da troca entre JSON e TOON especificamente, confira a comparação TOON vs JSON. Para contexto sobre a especificação CSV e suas peculiaridades, o artigo da Wikipedia sobre CSV cobre bem o histórico e as variações de formato.