JSON frente a CSV: ¿qué formato deberías utilizar?

Por qué escribimos esto: somos Geonode y vendemos proxies a personas que recopilan datos, por lo que vemos cómo muchos conjuntos de datos extraídos se guardan en el disco en un formato incorrecto. La aclaración es sencilla: la elección del formato no tiene nada que ver con los proxies y no obtenemos ningún beneficio económico de tu decisión al respecto. Lo que sí afecta es a tu factura de almacenamiento, a tu tiempo de procesamiento y a la cantidad de tiempo que dedicas cada semana a depurar por qué un campo que contiene una coma ha provocado un error en una importación posterior. Esos son costes reales y están totalmente bajo tu control antes de que escribas el primer registro.

La diferencia fundamental: uno es un estándar, el otro es un hábito

Esto es lo primero que hay que entender, porque todo lo demás se deriva de ello.

JSON está estandarizado. RFC 8259 es un documento de la vía de estándares de Internet. Cuenta con una gramática formal, requisitos obligatorios y existe explícitamente para eliminar «inconsistencias con otras especificaciones de JSON» y corregir «errores de especificación». Si dos analizadores de JSON no coinciden, al menos uno de ellos está equivocado y la especificación indica cuál.

CSV no lo está. RFC 4180 es un documento informativo, y así lo afirma sobre sí mismo en los términos más claros:

Aunque existen diversas especificaciones e implementaciones para el formato CSV... no existe ninguna especificación formal, lo que permite una amplia variedad de interpretaciones de los archivos CSV. Esta sección documenta el formato que parece seguir la mayoría de las implementaciones.

La expresión «parece seguir la mayoría de las implementaciones» tiene un gran peso en esa frase. El RFC 4180 es una descripción de la práctica habitual, no una definición. Si dos analizadores CSV discrepan, ambos pueden tener razón.

Por eso los problemas con el CSV tienen el carácter que tienen. No son tanto errores como discrepancias legítimas sobre un formato que nadie ha definido nunca por completo —lo cual también explica por qué surgen en los puntos de integración, meses después de que se creara el archivo, en las herramientas de otra persona.

Lo que realmente garantiza el formato CSV

El RFC 4180 recoge las convenciones comunes, y conviene conocerlas porque las desviaciones son la fuente de los problemas.

Los registros se separan mediante CRLF. El último registro puede tener o no un salto de línea al final. Puede haber una línea de encabezado opcional. Los campos se separan mediante comas, cada línea debe tener el mismo número de campos y «los espacios se consideran parte de un campo y no deben ignorarse».

El tema de las comillas es donde la cosa se pone interesante:

Cada campo puede estar o no entre comillas dobles (aunque algunos programas, como Microsoft Excel, no utilizan comillas dobles en absoluto).

Y los campos «que contengan saltos de línea (CRLF), comillas dobles y comas deben ir entre comillas dobles», y una comilla doble incrustada se escapa «anteponiéndole otra comilla doble».

Fíjate en los verbos modales. «Puede o no». «Debería». El RFC describe tendencias. Y la nota entre paréntesis sobre Excel es la forma en que el documento reconoce, en 2005, que la herramienta CSV más utilizada del mundo no sigue la convención.

Las consecuencias prácticas, en el orden en que te afectarán:

Los delimitadores varían según la configuración regional. Los países que utilizan la coma como separador decimal suelen emplear el punto y coma como delimitador de campos. Es posible que un archivo exportado por un compañero de Alemania no se pueda analizar con un lector basado en comas, y ninguno de los dos haya hecho nada mal.

La codificación no está declarada. Nada en un archivo CSV indica su codificación de caracteres. UTF-8, Latin-1, Windows-1252 y UTF-16 producen todos un archivo que parece CSV y se lee como «mojibake» en un analizador incorrecto. Las marcas de orden de bytes aparecen de forma inconsistente y rompen el análisis ingenuo de los encabezados.

Los finales de línea varían. CRLF, LF y —en campos que contienen saltos de línea incrustados— cualquiera de los dos, dentro de comillas.

No existen tipos. Todo es texto. 007 se convierte en 7, 2026-09-02 se convierte en una fecha en una herramienta y en una cadena en otra, y un + al principio desaparece. La conversión de un archivo CSV a través de una hoja de cálculo conlleva una pérdida real de información.

Y los archivos CSV pueden ejecutar código. Un campo que comience por =, +, - o @ puede ser interpretado como una fórmula por el software de hojas de cálculo. Esto se conoce como «inyección de fórmulas»; constituye una vulnerabilidad real cuando se escriben datos proporcionados por el usuario en un CSV que alguien abrirá en Excel, y la medida de mitigación consiste en anteponer una comilla simple a dichos campos o neutralizarlos de otro modo antes de escribirlos. Si tu proceso genera archivos CSV a partir de contenido extraído o enviado por los usuarios, merece la pena gestionar esto de forma deliberada.

Qué garantiza JSON y en qué aspectos sigue presentando problemas

La especificación de JSON es más estricta y, en consecuencia, las garantías son más sólidas.

La codificación está definida. RFC 8259 §8.1: «El texto JSON intercambiado entre sistemas que no forman parte de un ecosistema cerrado DEBE codificarse utilizando UTF-8». También establece que las implementaciones «NO DEBEN añadir una marca de orden de bytes» al texto JSON transmitido por red, aunque permite que los analizadores la ignoren. Toda la clase de problemas relacionados con la deducción de la codificación que afecta al CSV simplemente no existe aquí.

Existen tipos. Las cadenas, los números, los valores booleanos, el valor nulo, los objetos y las matrices se distinguen en la gramática. "007" y 7 son valores diferentes y siguen siéndolo.

El anidamiento es nativo. Los datos jerárquicos tienen una representación obvia, en lugar de requerir una convención sobre la que nadie se haya puesto de acuerdo.

Dos aspectos en los que JSON es menos absoluto de lo que la gente supone:

Las claves duplicadas solo se desaconsejan. La especificación dice: «Los nombres dentro de un objeto DEBERÍAN ser únicos» — DEBERÍAN, no DEBEN. Y es sincera sobre la consecuencia: cuando los nombres no son únicos, «el comportamiento del software que recibe dicho objeto es impredecible. Muchas implementaciones solo devuelven el último par nombre/valor. Otras implementaciones devuelven un error o no logran analizarlo».

La precisión numérica es una recomendación, no una regla. La especificación permite que las implementaciones establezcan límites en el rango y la precisión, y señala que una buena interoperabilidad se consigue sin esperar más de lo que ofrece el estándar IEEE 754 binary64. Nombra directamente el caso de fallo: «Un número JSON como 1E400 o 3,141592653589793238462643383279 puede indicar posibles problemas de interoperabilidad».

En la práctica, se trata de un error silencioso que se distribuye con el código. Los identificadores grandes de 64 bits pierden precisión al analizarse como números en JavaScript, no se produce ningún error y dos registros distintos pueden acabar teniendo el mismo valor. La medida de mitigación estándar consiste en serializar los números enteros grandes como cadenas de caracteres, lo cual conviene hacer en el momento de escribir los datos, en lugar de descubrirlo más adelante en el proceso. Analizamos el aspecto relacionado con el analizador sintáctico en nuestra guía sobre JSON.parse.

Tamaño y velocidad

La disyuntiva es real, y el resultado no siempre es el que la gente espera.

El formato CSV ocupa menos espacio para datos tabulares planos, normalmente por un amplio margen, ya que los nombres de los campos aparecen una sola vez en el encabezado en lugar de en cada registro. Un millón de filas de cinco campos almacena cinco nombres de campo en CSV y cinco millones en JSON.

La compresión reduce drásticamente la diferencia. Las claves repetidas se comprimen muy bien. Tras la compresión con gzip, la penalización de JSON en registros uniformes suele reducirse a algo modesto —en ocasiones, a nada—. Si almacenas datos comprimidos, como deberías hacer, el argumento del tamaño a favor del CSV es mucho más débil de lo que sugieren las cifras brutas.

El CSV se analiza más rápido en casos sencillos y más lento en los correctos. Un analizador ingenuo de tipo «split(',')» es muy rápido, pero erróneo. Un analizador conforme que gestione correctamente las comillas, los saltos de línea incrustados y las comillas escapadas se acerca más al coste del análisis de JSON. La mayoría de las comparaciones de velocidad de CSV están comparando, sin decirlo, un analizador erróneo con uno correcto.

El verdadero coste de JSON es la memoria, no la CPU. Por lo general, para analizar un único documento JSON de gran tamaño es necesario mantenerlo en memoria. Un CSV se puede procesar fila por fila a partir de un flujo con un consumo de memoria constante. Para un archivo de diez gigabytes, esa diferencia no es un simple detalle de rendimiento; es la diferencia entre lo posible y lo imposible en una máquina determinada.

Y ese es precisamente el problema que resuelve la siguiente sección.

El término medio: JSON Lines

JSON Lines —también conocido como NDJSON o JSON delimitado por saltos de línea— consiste en un documento JSON por línea, sin matriz envolvente. Es el formato que la mayoría de la gente debería utilizar y que, sin embargo, muy pocos conocen.

{"id": 1, "name": "Ada", "tags": ["engineer"]}
{"id": 2, "name": "Grace", "tags": ["engineer", "admiral"]}

Ventajas:

Transmisión en tiempo real. Cada línea se analiza de forma independiente, por lo que puedes procesar un archivo de cien gigabytes utilizando una cantidad constante de memoria. Esto elimina la mayor desventaja práctica de JSON.

Escritura solo de anexión. Los nuevos registros se añaden al final. No hay que cerrar ningún array envolvente, lo que significa que no hay que reescribir el archivo y no se produce una salida corrupta si un proceso se interrumpe a mitad de la escritura.

Recuperación parcial. Un archivo truncado sigue proporcionando todas las líneas completas. Un array JSON truncado no proporciona nada en absoluto: basta con que falte un corchete para que todo el documento sea imposible de analizar. Para cualquier cosa escrita por una tarea de larga duración, esto por sí solo justifica la elección.

Paralelismo trivial. Se divide por líneas y se procesan los fragmentos de forma independiente. No hay estado entre líneas.

Semántica JSON completa. Se conservan los tipos, el anidamiento y la codificación sin ambigüedades.

Los inconvenientes son mínimos: ocupa algo más de espacio que el CSV, no se puede abrir directamente en una hoja de cálculo y cada registro lleva sus propias claves. Para datos extraídos, salidas de registro, flujos de eventos y cualquier cosa que se añada de forma incremental, es la opción predeterminada adecuada, y es lo que recomendaríamos a cualquiera que escriba la salida de una recopilación en el disco.

Más allá de ambos: Parquet y demás

Vale la pena conocerlo, porque para las cargas de trabajo analíticas la disyuntiva «JSON frente a CSV» a veces es, en realidad, una pregunta totalmente errónea.

Parquet es un formato columnar y binario. Almacena cada columna de forma contigua, lo que significa que una consulta que afecte a tres columnas de cuarenta lecturas solo leerá esas tres. Incluye un esquema, se comprime mucho mejor que el texto orientado a filas porque los valores similares se agrupan, y conserva los tipos con exactitud.

Donde destaca: consultas analíticas sobre grandes conjuntos de datos, almacenamiento a largo plazo de cualquier volumen considerable y cualquier canalización que alimente un almacén de datos. Las tasas de compresión respecto al CSV suelen ser varias veces superiores, y las diferencias en el rendimiento de las consultas son aún mayores.

Donde sale perdiendo: no es legible para los humanos, no admite añadidos de la misma forma que JSON Lines y requiere una biblioteca en lugar de un editor de texto. Para el streaming, para el intercambio con personas y para datos pequeños, los formatos de texto siguen siendo la opción adecuada.

Una arquitectura habitual y sensata: recopilar en JSON Lines, ya que permite añadir datos fácilmente y es tolerante a la pérdida de datos, y luego convertirlo a Parquet por lotes para su análisis y archivo. Cada formato se utiliza allí donde sus propiedades resultan más útiles.

Elección según el uso

Tres reglas que resuelven la mayoría de los casos sin necesidad de la tabla.

Si los datos son planos, uniformes y se van a introducir en una hoja de cálculo o en un cargador masivo, utiliza CSV. Estas son, sin duda, las fortalezas del CSV y ningún otro formato las ofrece con tanta comodidad. La importación masiva a bases de datos, en particular, supone una ventaja real: la mayoría de los motores cuentan con una ruta rápida para el CSV, pero no para el JSON.

Si los datos están anidados, tienen una estructura variable o contienen cualquier texto introducido por el usuario, utiliza JSON o JSON Lines. Aplanar datos anidados en CSV requiere inventar una convención, y todas las convenciones inventadas para ello han sido fuente de errores. Por otra parte, el texto del usuario contiene comas, comillas y saltos de línea, que es precisamente lo que el CSV maneja de forma menos fiable.

Si estás escribiendo registros de forma continua, utiliza JSON Lines. No CSV, porque el CSV carece de tipos y los perderás. Tampoco un array JSON, porque no se le pueden añadir elementos de forma segura y, si el proceso se bloquea, deja un archivo imposible de analizar.

Preguntas frecuentes

¿Es JSON mejor que CSV?

Depende del uso que se le dé: sí y no. JSON es un estándar formal con tipos, anidamiento y codificación UTF-8 obligatoria. El CSV ocupa menos espacio para datos tabulares planos, se transmite de forma natural y se abre en hojas de cálculo. El argumento más sólido es que el CSV carece de una especificación formal —el RFC 4180 lo indica explícitamente—, lo que lo hace menos predecible entre diferentes herramientas.

¿Por qué mi archivo CSV no se abre correctamente en Excel?

Normalmente se debe a la codificación o al delimitador. Los archivos CSV no declaran su codificación de caracteres, por lo que Excel la deduce; además, las configuraciones regionales que utilizan la coma como separador decimal esperan un delimitador de punto y coma. Ambos problemas son inherentes a un formato que nunca especificó ninguno de los dos. Exportar en UTF-8 con un BOM suele ayudar específicamente en Excel, a costa de confundir a otros analizadores sintácticos.

¿Qué es JSON Lines y cuándo debo utilizarlo?

Un documento JSON por línea sin matriz envolvente. Úsalo siempre que escribas registros de forma incremental: datos extraídos, registros de sistema, flujos de eventos. Se procesa en memoria constante, se añade de forma segura, sobrevive al truncamiento manteniendo intacta cada línea completa y conserva todos los tipos JSON y el anidamiento.

¿Es el CSV más pequeño que el JSON?

Sin comprimir y para datos planos y uniformes, normalmente por un amplio margen, ya que los nombres de los campos aparecen una sola vez en lugar de en cada registro. Tras la compresión, la diferencia se reduce drásticamente, ya que las claves repetidas se comprimen muy bien. Si almacenas datos comprimidos, el argumento del tamaño a favor del CSV es mucho menos sólido de lo que sugieren las cifras brutas.

¿Puede el CSV gestionar datos anidados?

No de forma nativa. Cualquier anidamiento requiere una convención que debas inventar tú mismo: aplanar los datos con nombres de columna separados por puntos, cadenas JSON dentro de las celdas o múltiples archivos relacionados. Todas estas opciones funcionan, pero implican que tu CSV ya no será legible para herramientas genéricas sin tu convención específica, lo cual es precisamente la principal razón para utilizar CSV en primer lugar.

¿Qué es más rápido de analizar, JSON o CSV?

El CSV, en casos sencillos, pero la comparación suele ser injusta: un analizador rápido de «split(',')» no es un analizador de CSV correcto, y uno que gestione correctamente las comillas y los saltos de línea incrustados se acerca mucho más al JSON en cuanto a coste. La diferencia más importante es la memoria: el CSV se procesa fila por fila, mientras que un documento JSON generalmente necesita cargarse en su totalidad, algo que soluciona JSON Lines.

¿Se permiten claves duplicadas en JSON?

La especificación dice que los nombres «DEBERÍAN ser únicos» en lugar de «DEBEN», por lo que técnicamente están permitidos. También advierte de que el comportamiento es impredecible cuando no lo son: algunos analizadores conservan el último, otros dan error y otros fallan por completo. Trata los duplicados como un error en lo que sea que haya generado el documento.

¿Qué formato debo utilizar para los datos extraídos?

JSON Lines, en la mayoría de los casos. Los registros extraídos suelen estar anidados y tener formas variables, algo que el CSV gestiona mal, y la recopilación es incremental, algo que los arrays de JSON gestionan mal. Si los datos son realmente planos y están destinados a una hoja de cálculo o a una carga masiva, el CSV está bien; y si generas un CSV a partir de texto extraído, neutraliza los campos que empiecen por =, +, - o @ para evitar la inyección de fórmulas.

Conclusión

El enfoque que facilita esta decisión no es «estructurado frente a sencillo». Se trata de que uno de estos formatos cuenta con una especificación y el otro, con una descripción de la práctica habitual. El RFC 8259 establece lo que debe hacer JSON; el RFC 4180 describe lo que suelen hacer los archivos CSV y lo expresa con sus propias palabras.

Esa diferencia es la fuente de prácticamente todos los problemas del CSV: codificaciones no declaradas, delimitadores que dependen de la configuración regional, comillas inconsistentes, tipos que se pierden silenciosamente al pasar por una hoja de cálculo y campos que se convierten en fórmulas. Ninguno de estos es un error en el analizador sintáctico de nadie. Son el resultado previsible de un formato que nunca se definió por completo.

Para la mayoría de las personas que escriben datos en lugar de leerlos, JSON Lines es la solución, aunque su uso está infravalorado. Mantiene los tipos, el anidamiento y la codificación establecida de JSON, al tiempo que elimina su única debilidad real: permite la escritura en flujo, añade datos de forma segura y sobrevive a una escritura truncada con todos los registros completos intactos. Reserva el CSV para las dos tareas en las que realmente destaca: entregar una tabla plana a alguien que la abrirá en una hoja de cálculo y cargar datos a gran escala en una base de datos. Y si el conjunto de datos es grande y de carácter analítico, ninguno de los dos formatos de texto es el destino final adecuado; conviértelo a un formato columnar y deja que cada formato haga el trabajo para el que está diseñado.