Quando você tem um array JSON de objetos e quer uma tabela Markdown a partir dele, o caminho mais confiável é passar primeiro pelo CSV e depois usar o CSV para Markdown. Existem ferramentas que convertem JSON direto em tabela, mas no momento em que aparecem valores aninhados ou chaves ausentes, a saída costuma quebrar de formas difíceis de depurar. Roteando pelo CSV, você coloca as colunas e linhas diante dos olhos, então o resultado continua previsível.
Este artigo percorre o processo do início ao fim: verificar a estrutura do JSON, convertê-lo em CSV, gerar a tabela Markdown e lidar com os casos mais difíceis, como respostas de API e JSON aninhado. Tudo roda no navegador, então colar uma resposta de API ou dados internos nunca envia nada para um servidor.
A resposta curta: roteie o JSON pelo CSV
Aqui está o fluxo inteiro logo de cara.
- Formate o JSON com o Formatador JSON e confirme que é um array de objetos
- Converta esse array em CSV — as chaves de cada objeto viram cabeçalhos de coluna, cada elemento vira uma linha
- Cole o CSV no CSV para Markdown para gerar a tabela
O FormatArc não tem um botão de "JSON para tabela" com um clique. Em vez disso, combinar o formatador com o conversor de CSV gera uma tabela compatível com GFM que renderiza igual em qualquer lugar. Usar o CSV como passo intermediário é justamente o ponto — você consegue identificar uma coluna desalinhada ou um valor ausente antes que ele acabe na tabela.
Que tipo de JSON mapeia para uma tabela Markdown
Uma tabela Markdown é uma grade bidimensional: uma linha de cabeçalho mais as linhas de dados. Então o JSON que mapeia de forma limpa é um array de objetos que compartilham o mesmo formato.
[
{ "name": "Mika", "role": "admin", "active": true },
{ "name": "Noah", "role": "viewer", "active": false }
]
As chaves de cada objeto (name / role / active) viram os cabeçalhos de coluna, e cada elemento do array vira uma linha. O JSON acima corresponde a esta tabela:
| name | role | active |
| --- | --- | --- |
| Mika | admin | true |
| Noah | viewer | false |
Um único objeto que não esteja envolvido em um array não vira uma linha sozinho. Ou transforme-o em uma tabela de duas colunas chave/valor, ou envolva-o como [ { ... } ] antes de converter.
Passos: converter JSON em tabela Markdown
Passo 1: formate o JSON e verifique a estrutura
O JSON extraído de uma resposta de API ou de um log costuma vir em uma única linha, sem quebras. Cole-o primeiro no Formatador JSON, depois confirme que ele é realmente um array de objetos e que todos os elementos compartilham as mesmas chaves.
Um erro de sintaxe vai atrapalhar tudo o que vem depois, então se a formatação falhar aqui, veja Como corrigir erros de parse de JSON. Se o payload contiver comentários //, consulte Como lidar com comentários em JSON.
Passo 2: converta o array em CSV
Quando a estrutura estiver confirmada, reorganize o array em CSV. São só duas coisas a fazer.
- Coloque as chaves na primeira linha, separadas por vírgula, como cabeçalho
- Escreva os valores de cada objeto na mesma ordem, separados por vírgula, uma linha de cada vez
Para o JSON acima, isso resulta em:
name,role,active
Mika,admin,true
Noah,viewer,false
Se um valor contiver uma vírgula ou uma quebra de linha, envolva esse valor em aspas duplas "...". Para o básico de CSV, veja O que é CSV. Para ir no sentido contrário e transformar CSV de volta em JSON, veja o guia de CSV para JSON.
Passo 3: gere a tabela com o CSV para Markdown
Com o CSV pronto, cole-o no CSV para Markdown e execute.
Uma tabela Markdown compatível com GFM aparece à direita. A linha separadora e as larguras das colunas se alinham automaticamente, então você pode copiá-la direto para um README, uma issue ou sua documentação. Para mais detalhes sobre como a conversão funciona e seus casos extremos, veja Como converter CSV em tabela Markdown.
Transformando uma resposta de API em tabela
Às vezes você quer compartilhar uma resposta de curl como tabela. O fluxo é o mesmo de antes — formate a saída do curl e roteie pelo CSV.
curl -s https://api.example.com/users | jq .
Se a resposta for um array de objetos, cole-a no Formatador JSON e continue a partir do passo 2. Se a resposta envolver o array dentro de algo como { "data": [ ... ] }, extraia apenas o array que você quer tabular (o conteúdo de data). Com o jq, jq '.data' extrai o array isoladamente.
Para formatar respostas de curl de modo geral, veja Como formatar JSON do curl, que compara jq, Python, a CLI e o navegador.
Como lidar com JSON aninhado
Respostas reais de API frequentemente carregam objetos ou arrays dentro de seus valores.
[
{ "name": "Mika", "address": { "city": "Tokyo", "zip": "100-0001" } }
]
Uma tabela Markdown é uma grade plana, então uma estrutura aninhada não cabe direto em uma célula. Há duas formas de lidar com isso.
Achate primeiro
Expanda as chaves aninhadas em notação de ponto, como address.city, achatando a estrutura antes de montar o CSV.
name,address.city,address.zip
Mika,Tokyo,100-0001
Você pode achatar manualmente, mas para payloads maiores uma função faz isso de forma confiável — o to_entries do jq, ou pandas.json_normalize() no Python. Depois de achatar, roteie o resultado pelo CSV até o CSV para Markdown, assim como antes.
Mantenha o valor aninhado como string na célula
Em vez de achatar, você pode manter um ramo aninhado como uma única string em uma célula. Coloque o valor de address em uma coluna como uma string JSON, tipo {"city":"Tokyo","zip":"100-0001"}. Nesse caso, caracteres de barra vertical | ou quebras de linha dentro da string quebrariam a tabela, então envolva o valor em aspas duplas na etapa do CSV. O CSV para Markdown escapa automaticamente as barras verticais dentro das células e substitui as quebras de linha por espaços, então você não precisa cuidar disso manualmente.
Definindo o alinhamento das colunas
As tabelas GFM permitem controlar o alinhamento por coluna adicionando : à linha separadora.
| name | count |
| :--- | ---: |
| Mika | 12 |
| Noah | 340 |
:--- alinha à esquerda, :---: centraliza e ---: alinha à direita. Alinhar à direita uma coluna numérica mantém os dígitos enfileirados. Tenha em mente que o fato de o alinhamento renderizar depende do renderizador Markdown do lado da exibição. Funciona corretamente no GitHub, mas não vai ficar idêntico em todos os ambientes. Para a sintaxe completa, incluindo alinhamento e escape, veja Sintaxe de tabelas Markdown.
Armadilhas comuns
As chaves diferem de um elemento para outro
Quando os elementos carregam chaves diferentes, o resultado depende de quais colunas você emite. Pegar a união de todas as chaves deixa células vazias onde um valor está ausente. Usar apenas as chaves do primeiro elemento descarta qualquer chave que apareça só mais adiante. Decida como alinhar as colunas enquanto monta o CSV para que a saída permaneça estável.
Booleanos, null e números
true / false / null e números são escritos como texto comum no CSV e exibidos como strings na tabela Markdown, então o significado fica claro. Um valor vazio vira uma célula vazia.
Quebras de linha e barras verticais dentro das células
Um valor que contenha uma quebra de linha ou um caractere de barra vertical vai colidir com o separador de coluna e quebrar a tabela. Envolva esses valores em aspas duplas na etapa do CSV, e o CSV para Markdown tratará as quebras de linha e as barras verticais com segurança.
Perguntas frequentes
Preciso fazer upload do JSON?
Não. Todas as conversões do FormatArc rodam dentro do seu navegador. Colar uma resposta de API ou dados internos nunca envia nada para um servidor.
Por que passar pelo CSV?
Usar o CSV como passo intermediário torna visível o mapeamento entre os cabeçalhos de coluna e as linhas. Converter JSON direto em tabela dificulta encontrar a causa quando valores aninhados ou chaves ausentes quebram a saída, mas com uma etapa de CSV no meio você consegue corrigir uma coluna desalinhada na hora.
JSON aninhado pode ir direto para uma tabela?
Não do jeito que está. Achate-o com notação de ponto, como address.city, ou mantenha o ramo aninhado como uma string JSON em uma única célula. Os passos estão na seção "Como lidar com JSON aninhado" acima.
Para finalizar
O atalho para uma tabela Markdown limpa a partir de JSON é roteá-lo pelo CSV. Verifique a estrutura com o Formatador JSON, reorganize o array em CSV, cole no CSV para Markdown, e você obtém uma tabela compatível com GFM pronta para copiar. Até os casos chatos, como dados aninhados ou respostas de API, se encaixam no mesmo fluxo depois que você adiciona uma etapa de achatamento.
Se você for alimentar a tabela Markdown resultante a um LLM como contexto, o Markdown supera o HTML em eficiência de tokens e precisão de extração. Para uma comparação medida, veja Markdown vs HTML para LLMs. Para se aprofundar na conversão a partir de CSV, veja Como converter CSV em tabela Markdown.