What Does Flattening a JSON Mean? Qué significa el término, explicado (Guía 2026)

La palabra misma: qué significa "plano" en datos

Olvida el JSON por un momento y mira la palabra. Una superficie plana no tiene bultos, ni capas, ni profundidad oculta: todo está al mismo nivel, visible a la vez. La gente de datos tomó prestada esa imagen. Los datos planos son datos sin anidado: cada valor está en el nivel superior, un valor por casilla, nada metido dentro de nada más.

Una fila de hoja de cálculo es el ejemplo más puro de datos planos. Una fila, un conjunto de columnas, un valor por celda. El valor de la celda C4 no contiene otra hoja de cálculo. Contiene texto, o un número, o nada. Eso es plano.

El JSON, en cambio, casi nunca es plano. Se anida: los objetos contienen objetos, los arrays contienen objetos, los objetos contienen arrays. Un registro de cliente puede llevar un objeto de dirección, que lleva coordenadas, que llevan un par de números. Ese anidado es todo el sentido de JSON, y también es la razón por la que la palabra "aplanar" existe. No puedes verter un árbol en una tabla sin hacer algo con las ramas. Aplanar es el nombre de ese algo.

Así que cuando alguien dice "aplana el JSON", quiere decir: reescribe esta estructura anidada para que cada valor viva en el nivel superior, con nombres que registren de dónde vino. El valor en sí no cambia. Lo que cambia es su dirección, de una ruta a través de objetos anidados a un único nombre plano.

Por qué existe la palabra: JSON se anida, CSV no

Esta es la tensión en una sola imagen. JSON es un árbol: ramas, subramas, hojas. CSV es una tabla: filas y columnas, y nada más profundo. Una celda CSV no puede contener un objeto. Solo puede contener texto. Así que cualquier conversión de JSON a CSV debe responder la misma pregunta: ¿qué hacemos con el anidado?

Solo hay unas pocas respuestas posibles, y "aplanar" es la más común. Toma este registro real, del tipo que podría devolver una API:

Nested: the address object lives inside the customer record

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

El objeto customer está un nivel más abajo. La lista tags está un nivel más abajo. Un CSV no tiene "un nivel más abajo", así que la versión aplanada saca todo a la superficie. Salida verificada del conversor de esta página:

Qué hace realmente aplanar, paso a paso

Aplanar no es un truco, son cuatro reglas pequeñas aplicadas en todas partes. Pasa el registro de arriba por el conversor de esta página con el aplanado activado, y esto es exactamente lo que sale, verificado en la máquina de compilación:

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

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

Regla uno: los objetos anidados se convierten en columnas con notación de punto. La ruta hasta el valor se convierte en el nombre: customer.name, customer.city. Los puntos son solo migas de pan. Nada del nombre de Amelia cambió, solo cambió su etiqueta de dirección.

Regla dos: las listas cortas de valores simples se unen en una celda. "new" y "vip" se convirtieron en el texto único "new; vip". Los dos valores siguen ahí, pero ahora son una cadena con un separador, y el hecho de que fueran dos ya no es legible por una máquina.

Regla tres: las listas de objetos no se pueden unir de forma sensata, así que colapsan en texto JSON dentro de una sola celda. Una lista de artículos como [{"sku":"B1","qty":2}] se convierte en una celda larga entre comillas. Los datos sobreviven, pero como texto que tendrías que analizar de nuevo, no como estructura.

Regla cuatro: null y los valores vacíos se convierten en celdas vacías. No hay forma de escribir "explícitamente nada" en una tabla plana, así que null simplemente desaparece en un blanco. Recuerda esto: después de aplanar, no puedes distinguir "era null" de "era una lista vacía" o "faltaba por completo".

Compáralo con el aplanado desactivado sobre los mismos datos, y la diferencia es todo el significado de la palabra. Con el interruptor desactivado, el objeto customer queda como una celda de texto JSON: {"name":"Amelia","city":"Austin"}. Los datos no se pierden, pero tampoco están planos: sigue habiendo anidado dentro de la celda, y una hoja de cálculo te mostrará una masa ilegible. Plano significa plano hasta el fondo, un valor por celda, sin excepciones.

La confusión que hay que aclarar: aplanar no es minificar

Pregunta a cinco principiantes qué significa "aplanar un JSON" y uno de ellos hará esto: borrar todos los saltos de línea y espacios, produciendo una única línea gigante. Eso es minificar, no aplanar, y la distinción importa porque las palabras suenan relacionadas pero describen cosas completamente distintas.

Minificar cambia los espacios en blanco. Aplanar cambia la estructura. Un archivo JSON minificado sigue anidado, solo que anidado en una línea. Verificado en la máquina de compilación: analizar las versiones minificada y con formato legible del mismo registro produce estructuras idénticas a nivel de byte, y el objeto customer sigue siendo un objeto en ambos casos. El árbol no se movió. Solo cambió la pintura.

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 qué ocurre la confusión? Porque en el habla casual, "plano" a veces significa "una línea", como en "aplana esto en una línea". En el trabajo con datos, "plano" significa "sin anidado". Si un tutorial te dice que aplanes el JSON antes de importarlo a una hoja de cálculo, quiere decir la clase estructural: columnas con notación de punto, listas unidas, un valor por celda. Borrar los espacios en blanco no ayudará en nada a tu importación.

La misma idea usa nombres distintos

Una vez que sabes qué significa aplanar, empiezas a verlo en todas partes, con ropa distinta. En la biblioteca pandas de Python, la función se llama json_normalize, y "normalize" está haciendo exactamente el trabajo de aplanar: los objetos anidados se convierten en columnas con notación de punto. Verificado en nuestras pruebas anteriores: aplana customer.address en customer.city igual que lo hace el conversor de esta página.

En Power Query de Excel, el botón dice "Expandir": haces clic en la flechita doble de una columna de registros anidados y los expande en columnas nuevas. Misma idea, verbo más amable. En SQL, UNNEST convierte un array anidado en filas. Misma familia.

Una advertencia honesta: en jq, la herramienta de línea de comandos para JSON, "flatten" significa algo más estrecho. El flatten de jq colapsa arrays anidados en un solo array, no convierte objetos en rutas con notación de punto. Si un tutorial de jq dice "flatten", comprueba qué significado quiere decir antes de suponer. El mundo de los datos reutiliza sus palabras con soltura, y este es el único lugar donde el término realmente se divide.

Aplanar también tiene dos primos cercanos que vale la pena nombrar, porque la gente mezcla los tres. Aplanar mantiene una fila por registro y ensancha las columnas. Explotar mantiene las columnas y multiplica las filas: una fila por elemento de lista. Unir pliega una lista en una sola celda, que es lo que la regla dos de arriba hace con las listas cortas. Nuestra guía How to Flatten the JSON Data: explotar, unir o dejar anidado (Guía 2026) recorre la decisión de explotar o unir con ejemplos reales, y nuestro análisis del interruptor, Cómo aplanar JSON a CSV: qué hace realmente esa opción (Guía 2026), muestra lo que hace el propio interruptor de aplanado del conversor celda por celda.

Lo que te cuesta aplanar

Aplanar es trabajo honesto, pero es trabajo con pérdidas, y las pérdidas vale la pena nombrarlas antes de hacer clic en nada. Primera, la forma desaparece para siempre. Después de aplanar, nada registra que city y state eran hermanos dentro de un objeto address. Son solo dos columnas que casualmente comparten un prefijo.

Segunda, la notación de punto tiene una ambigüedad de la que nadie te avisa. Si tu JSON contiene literalmente una clave llamada "a.b" en el nivel superior Y un objeto anidado a con clave b, ambas se aplanan al mismo nombre de columna, y un valor sobrescribe silenciosamente al otro. Raro en la práctica, brutal cuando ocurre.

Tercera, las listas unidas pierden su conteo como dato. "new; vip" parece una cadena. Un programa que lea el CSV no puede saber que fueron dos etiquetas sin dividir por el separador, y si una etiqueta contiene alguna vez un punto y coma, incluso eso se rompe.

Cuarta, los tipos colapsan. 101 se convierte en los caracteres "101". true se convierte en los caracteres "true". Lo que abra el CSV decide qué significan, y a Excel en particular le encanta reinterpretar tus datos: los ceros iniciales desaparecen, los ID largos se convierten en notación científica. Los valores sobrevivieron al aplanado; puede que no sobrevivan a la hoja de cálculo.

Nada de esto significa que aplanar esté mal. Significa que aplanar es un viaje de ida, y deberías conservar el JSON original como tu fuente de verdad. Aplana una copia, trabaja sobre la copia, y nunca deseches el árbol del que partiste.

¿Deberías aplanar? Una decisión de 60 segundos

Tu destino decide, no tus datos. Si el destino es una hoja de cálculo, una importación CSV o un humano revisando filas, aplana: esas herramientas están hechas para consumir eso, y un archivo aplanado se abre limpio en todas partes.

Si el destino es otro programa, una API o un viaje de vuelta a JSON más tarde, no aplanes. Conserva el anidado, porque cada pérdida del aplanado listada arriba se convierte en un error que tendrás que deshacer en el camino de vuelta.

Si no estás seguro, aplana una copia y mírala. Abre el CSV, comprueba que las columnas con notación de punto tengan sentido, que las listas unidas se vean bien, que nada importante se haya convertido en una masa ilegible. Sesenta segundos mirando valen más que una hora depurando una mala importación.

Hoja de cálculo, importación CSV, revisión humana: aplana, es lo que esas herramientas esperan.
API, base de datos, viaje de vuelta a JSON: conserva el anidado, las pérdidas del aplanado se convierten en errores.
Sin decidir: aplana una copia, ábrela y revisa las columnas antes de comprometerte.

Pruébalo en esta página

El conversor en la parte superior de esta página aplana por defecto. Pega cualquier JSON anidado y mira la vista previa: los objetos anidados se convierten en columnas con notación de punto, las listas se unen con "; " y cada celda contiene exactamente un valor. Desactiva el aplanado y pega el mismo JSON para ver la diferencia que hace la palabra: masas anidadas en las celdas frente a una tabla plana y limpia. Ese lado a lado, con tus propios datos, es la forma más rápida de que el término se te quede grabado.

Si tu JSON tiene listas de objetos que quieres como filas, aplanar solo no bastará: eso es explotar, una operación distinta, y nuestra guía How to Flatten the JSON Data: explotar, unir o dejar anidado (Guía 2026) cubre exactamente cuándo explotar en su lugar.

Guías relacionadas

Preguntas frecuentes

¿Qué significa aplanar un JSON, en términos simples?

Significa reescribir el JSON anidado para que nada quede anidado. Los objetos dentro de objetos se convierten en nombres con notación de punto como customer.city, las listas cortas se convierten en una celda unida, y cada valor queda en el nivel superior, uno por celda. El resultado es una tabla plana, que es lo que necesitan los archivos CSV y las hojas de cálculo.

¿Aplanar un JSON es lo mismo que minificarlo?

No, y esta es la confusión más común. Minificar elimina los espacios en blanco, produciendo una línea larga que sigue totalmente anidada. Aplanar cambia la estructura en sí, sacando los valores anidados al nivel superior. Un archivo minificado se analiza como el mismo árbol; un archivo aplanado es una forma distinta y menos profunda.

¿Aplanar un archivo JSON cambia mis datos?

Cambia la forma, no los valores. Cada valor hoja sobrevive, pero el anidado se convierte en columnas con notación de punto, las listas se convierten en texto unido, los tipos colapsan a texto y null se convierte en una celda vacía. Conserva el JSON original como tu fuente de verdad y trata el archivo aplanado como una copia de trabajo.

¿Cuál es la diferencia entre aplanar y explotar un JSON?

Aplanar mantiene una fila por registro y ensancha las columnas: las rutas anidadas se convierten en columnas nuevas. Explotar mantiene las columnas y multiplica las filas: cada elemento de una lista obtiene su propia fila, con el resto del registro repetido. Aplana un cliente con tres etiquetas y obtienes una fila con una celda "tag1; tag2; tag3"; explótalo y obtienes tres filas. Nuestra guía How to Flatten the JSON Data: explotar, unir o dejar anidado (Guía 2026) cubre cuándo elegir cada una.

¿Por qué los archivos CSV necesitan datos planos?

Porque un CSV solo tiene filas, columnas y texto. No hay dónde poner el anidado: una celda no puede contener un objeto, solo caracteres. Así que las estructuras anidadas deben aplanarse (o empaquetarse como texto JSON en una celda) antes de poder vivir en un CSV.

¿Puedo desaplanar un CSV de vuelta a JSON anidado?

Solo de forma aproximada. Las columnas con notación de punto como customer.city se pueden reagrupar en objetos anidados con un script, y algunas herramientas lo hacen, pero la información que destruyó el aplanado desapareció: las listas unidas no pueden volver a dividirse en arrays de forma fiable, los tipos son una adivinanza y null frente a ausente es incognoscible. Si necesitas el anidado de vuelta, conserva el JSON original.

¿El conversor de JSON a CSV de esta página aplana automáticamente?

Sí, el aplanado está activado por defecto: pega JSON anidado y la vista previa muestra columnas con notación de punto de inmediato. Puedes desactivarlo, en cuyo caso los objetos y arrays anidados quedan como texto JSON dentro de celdas individuales. Para trabajar en hojas de cálculo, déjalo activado.

Mira el aplanado en vivo

Pega JSON anidado en el conversor y mira cómo el aplanado lo convierte en columnas con notación de puntos. Gratis, sin registro, todo se ejecuta en tu navegador.

Abrir el conversor de JSON a CSV

Todas las guías