What Does Flattening a JSON Mean? O Termo Explicado (Guia 2026)

A palavra em si: o que "plano" significa em dados

Esqueça o JSON por um momento e imagine a palavra. Uma superfície plana não tem saliências, camadas nem profundidade escondida: tudo fica no mesmo nível, visível de uma vez. O pessoal de dados pegou emprestada essa imagem. Dados planos são dados sem aninhamento: cada valor fica no nível superior, um valor por espaço, nada guardado dentro de nada.

Uma linha de planilha é o exemplo mais puro de dados planos. Uma linha, um conjunto de colunas, um valor por célula. O valor na célula C4 não contém outra planilha. Contém texto, ou um número, ou nada. Isso é plano.

O JSON, em contraste, quase nunca é plano. Ele aninha: objetos guardam objetos, listas guardam objetos, objetos guardam listas. Um registro de cliente pode carregar um objeto de endereço, que carrega coordenadas, que carregam um par de números. Esse aninhamento é a razão de ser do JSON, e também é a razão de a palavra "achatamento" existir. Você não consegue despejar uma árvore em uma tabela sem fazer algo com os galhos. Achatar é o nome desse algo.

Então, quando alguém diz "achate o JSON", quer dizer: reescreva essa estrutura aninhada para que cada valor viva no nível superior, com nomes que registrem de onde ele veio. O valor em si não muda. O endereço dele muda, de um caminho através de objetos aninhados para um único nome plano.

Por que a palavra existe: JSON aninha, CSV não

Aqui está a tensão em uma imagem só. O JSON é uma árvore: galhos, subgalhos, folhas. O CSV é uma tabela: linhas e colunas, e nada mais fundo. Uma célula de CSV não pode guardar um objeto. Ela só pode guardar texto. Então qualquer conversão de JSON para CSV precisa responder à mesma pergunta: o que fazemos com o aninhamento?

Só há algumas respostas possíveis, e "achatar" é a mais comum. Pegue este registro real, do tipo que uma API pode retornar:

Nested: the address object lives inside the customer record

{
  "id": "A-101",
  "customer": { "name": "Amelia", "city": "Austin" },
  "tags": ["new", "vip"]
}

O objeto customer está um nível abaixo. A lista tags está um nível abaixo. Um CSV não tem "um nível abaixo", então a versão achatada puxa tudo para a superfície. Saída verificada do conversor desta página:

O que o achatamento realmente faz, passo a passo

Achatar não é um truque só, são quatro pequenas regras aplicadas em toda parte. Passe o registro acima pelo conversor desta página com o achatamento ativado, e aqui está exatamente o que sai, verificado na máquina de compilação:

Flattened: depth 1, one value per slot (verified converter output)

{
  "id": "A-101",
  "customer.name": "Amelia",
  "customer.city": "Austin",
  "tags": "new; vip"
}

Regra um: objetos aninhados viram colunas em notação de ponto. O caminho até o valor vira o nome: customer.name, customer.city. Os pontos são só migalhas de pão. Nada sobre o nome da Amelia mudou, só o rótulo do endereço dela.

Regra dois: listas curtas de valores simples são unidas em uma célula. "new" e "vip" viraram o texto único "new; vip". Os dois valores continuam lá, mas agora são uma string com um separador, e o fato de que eram dois não é mais legível por máquina.

Regra três: listas de objetos não podem ser unidas de forma sensata, então colapsam em texto JSON dentro de uma única célula. Uma lista de itens como [{"sku":"B1","qty":2}] vira uma longa célula entre aspas. Os dados sobrevivem, mas como texto que você teria de analisar de novo, não como estrutura.

Regra quatro: valores nulos e vazios viram células vazias. Não há como escrever "explicitamente nada" em uma tabela plana, então null simplesmente some em um branco. Guarde esta: depois de achatar, você não consegue distinguir "era null" de "era uma lista vazia" ou "estava ausente".

Compare com o achatamento desligado nos mesmos dados, e a diferença é todo o significado da palavra. Com o interruptor desligado, o objeto customer fica como uma célula de texto JSON: {"name":"Amelia","city":"Austin"}. Os dados não se perdem, mas não estão planos: ainda há aninhamento dentro da célula, e uma planilha vai mostrar um borrão ilegível. Plano significa plano até o fim, um valor por célula, sem exceções.

A confusão a desfazer: achatar não é minificar

Pergunte a cinco iniciantes o que significa "achatar um JSON" e um deles vai fazer isto: apagar todas as quebras de linha e espaços, produzindo uma linha gigante. Isso é minificar, não achatar, e a distinção importa porque as palavras parecem relacionadas, mas descrevem coisas completamente diferentes.

Minificar muda espaços em branco. Achatar muda a estrutura. Um arquivo JSON minificado continua aninhado, só está aninhado em uma linha. Verificado na máquina de compilação: analisar as versões minificada e formatada do mesmo registro produz estruturas byte-idênticas, e o objeto customer continua sendo um objeto de qualquer jeito. A árvore não se moveu. Só a pintura mudou.

Minified is still nested (depth 2); flattened is depth 1

# minified: no whitespace, STILL nested -> customer is an object
{"id":"A-101","customer":{"name":"Amelia","city":"Austin"},"tags":["new","vip"]}

# flattened: depth 1, nothing nested at any width
{"id":"A-101","customer.name":"Amelia","customer.city":"Austin","tags":"new; vip"}

Por que a confusão acontece? Porque na fala casual, "plano" às vezes significa "em uma linha", como em "achate isso em uma linha". Em trabalho com dados, "plano" significa "sem aninhamento". Se um tutorial manda achatar o JSON antes de importar para uma planilha, ele quer dizer o tipo estrutural: colunas em notação de ponto, listas unidas, um valor por célula. Apagar espaços em branco não vai ajudar sua importação em nada.

A mesma ideia com nomes diferentes

Depois que você sabe o que achatar significa, começa a vê-lo em toda parte, com roupas diferentes. Na biblioteca pandas do Python, a função se chama json_normalize, e "normalize" está fazendo exatamente o trabalho do achatamento: objetos aninhados viram colunas em notação de ponto. Verificado em nossos testes anteriores: ela achata customer.address em customer.city do mesmo jeito que o conversor desta página faz.

No Power Query do Excel, o botão diz "Expandir": você clica na setinha dupla em uma coluna de registros aninhados e ela os expande em novas colunas. Mesma ideia, verbo mais amigável. Em SQL, UNNEST transforma uma lista aninhada em linhas. Mesma família.

Um aviso honesto: no jq, a ferramenta de linha de comando para JSON, "flatten" significa algo mais estreito. O flatten do jq colapsa listas aninhadas em uma lista só, não transforma objetos em caminhos de notação de ponto. Se um tutorial de jq diz "flatten", confira qual significado ele quer antes de presumir. O mundo dos dados reutiliza suas palavras de forma solta, e este é o único lugar em que o termo realmente se divide.

Achatar também tem dois primos próximos que valem nomear, porque as pessoas confundem os três. Achatar mantém uma linha por registro e alarga as colunas. Explodir mantém as colunas e multiplica as linhas: uma linha por item da lista. Unir dobra uma lista em uma única célula, que é o que a regra dois acima faz com listas curtas. Nosso guia "How to Flatten the JSON Data: Explodir, Unir ou Deixar Aninhado (Guia 2026)" percorre a decisão explodir-ou-unir com exemplos reais, e nosso mergulho no interruptor, "Como Converter JSON Aninhado para CSV: O Que a Opção de Achatamento Realmente Faz (Guia 2026)", mostra o que o interruptor de achatamento do conversor faz célula por célula.

O que o achatamento custa a você

Achatar é um trabalho honesto, mas é um trabalho com perdas, e as perdas valem ser nomeadas antes de você clicar em qualquer coisa. Primeiro, a forma se foi para sempre. Depois de achatar, nada registra que city e state eram irmãos dentro de um objeto address. São só duas colunas que por acaso compartilham um prefixo.

Segundo, a notação de ponto tem uma ambiguidade sobre a qual ninguém avisa. Se seu JSON contém literalmente uma chave chamada "a.b" no nível superior E um objeto aninhado a com chave b, ambos achatam para o mesmo nome de coluna, e um valor sobrescreve o outro em silêncio. Raro na prática, brutal quando acontece.

Terceiro, listas unidas perdem sua contagem como dado. "new; vip" parece uma string só. Um programa lendo o CSV não consegue saber que eram duas tags sem dividir no separador, e se uma tag um dia contiver um ponto e vírgula, até isso quebra.

Quarto, os tipos colapsam. 101 vira os caracteres "101". true vira os caracteres "true". Quem quer que abra o CSV decide o que eles significam, e o Excel em particular adora reinterpretar seus dados: zeros à esquerda somem, IDs longos viram notação científica. Os valores sobreviveram ao achatamento; podem não sobreviver à planilha.

Nada disso significa que achatar está errado. Significa que achatar é uma viagem só de ida, e você deve guardar o JSON original como sua fonte da verdade. Achate uma cópia, trabalhe na cópia, e nunca jogue fora a árvore da qual você achatou.

Você deve achatar? Uma decisão de 60 segundos

Seu destino decide, não seus dados. Se o destino é uma planilha, uma importação de CSV ou um humano olhando linhas, achate: é para isso que essas ferramentas são feitas, e um arquivo achatado abre limpo em todo lugar.

Se o destino é outro programa, uma API, ou uma viagem de volta para JSON depois, não achate. Mantenha o aninhamento, porque cada perda de achatamento listada acima vira um bug que você vai ter de desfazer no caminho de volta.

Se estiver em dúvida, achate uma cópia e olhe. Abra o CSV, confira se as colunas em notação de ponto fazem sentido, se as listas unidas parecem certas, se nada importante virou um borrão ilegível. Sessenta segundos olhando vencem uma hora depurando uma importação ruim.

Planilha, importação de CSV, revisão humana: achate, é o que essas ferramentas esperam.
API, banco de dados, viagem de volta para JSON: mantenha o aninhamento, as perdas do achatamento viram bugs.
Em dúvida: achate uma cópia, abra e confira as colunas antes de se comprometer.

Teste nesta página

O conversor no topo desta página achata por padrão. Cole qualquer JSON aninhado nele e observe a prévia: objetos aninhados viram colunas em notação de ponto, listas se unem com "; ", e cada célula guarda exatamente um valor. Desligue o achatamento e cole o mesmo JSON para ver a diferença que a palavra faz: borrões aninhados nas células versus uma tabela plana limpa. Esse lado a lado, nos seus próprios dados, é o jeito mais rápido de fazer o termo grudar.

Se seu JSON tem listas de objetos que você quer mesmo como linhas, só achatar não resolve: isso é explodir, uma operação diferente, e nosso guia "How to Flatten the JSON Data: Explodir, Unir ou Deixar Aninhado (Guia 2026)" cobre exatamente quando explodir em vez disso.

Guias relacionados

Perguntas frequentes

O que significa achatar um JSON em termos simples?

Significa reescrever um JSON aninhado para que nada fique aninhado. Objetos dentro de objetos viram nomes em notação de ponto como customer.city, listas curtas viram uma célula unida, e cada valor fica no nível superior, um por célula. O resultado é uma tabela plana, que é o que arquivos CSV e planilhas precisam.

Achatar um JSON é o mesmo que minificá-lo?

Não, e esta é a confusão mais comum. Minificar remove espaços em branco, produzindo uma linha longa que continua totalmente aninhada. Achatar muda a própria estrutura, puxando valores aninhados para o nível superior. Um arquivo minificado é analisado como a mesma árvore; um arquivo achatado é uma forma diferente, mais rasa.

Achatar um arquivo JSON muda meus dados?

Muda a forma, não os valores. Cada valor folha sobrevive, mas o aninhamento vira colunas em notação de ponto, listas viram texto unido, tipos colapsam para texto e null vira uma célula vazia. Guarde o JSON original como sua fonte da verdade e trate o arquivo achatado como uma cópia de trabalho.

Qual é a diferença entre achatar e explodir um JSON?

Achatar mantém uma linha por registro e alarga as colunas: caminhos aninhados viram novas colunas. Explodir mantém as colunas e multiplica as linhas: cada item de uma lista ganha sua própria linha, com o resto do registro repetido. Achate um cliente com três tags e você tem uma linha com uma célula "tag1; tag2; tag3"; exploda e você tem três linhas. Nosso guia "How to Flatten the JSON Data: Explodir, Unir ou Deixar Aninhado (Guia 2026)" cobre quando escolher qual.

Por que arquivos CSV precisam de dados planos?

Porque um CSV só tem linhas, colunas e texto. Não há onde colocar aninhamento: uma célula não pode conter um objeto, só caracteres. Então estruturas aninhadas precisam ser achatadas (ou empacotadas como texto JSON em uma célula) antes de poderem viver em um CSV.

Consigo desachatar um CSV de volta para JSON aninhado?

Só aproximadamente. Colunas em notação de ponto como customer.city podem ser reagrupadas em objetos aninhados por um script, e algumas ferramentas fazem isso, mas a informação que o achatamento destruiu se foi: listas unidas não podem ser divididas de volta em listas de forma confiável, tipos são palpite, e null versus ausente é impossível de saber. Se você precisar do aninhamento de volta, guarde o JSON original.

O conversor de JSON para CSV desta página achata automaticamente?

Sim, o achatamento vem ativado por padrão: cole um JSON aninhado e a prévia mostra colunas em notação de ponto na hora. Você pode desligá-lo, e aí objetos e listas aninhados ficam como texto JSON dentro de células únicas. Para trabalho em planilha, deixe ativado.

Veja o achatamento acontecer ao vivo

Cole JSON aninhado no conversor e veja o achatamento transformá-lo em colunas com notação de ponto. Grátis, sem cadastro, roda inteiramente no seu navegador.

Abrir o conversor de JSON para CSV

Todos os guias