JSON y CSV describen datos tabulares desde perspectivas distintas. JSON diferencia cadenas, booleanos, números, null, propiedades ausentes, matrices y objetos anidados. CSV solo contiene registros y campos: no ofrece un sistema de tipos estándar ni una estructura anidada. Una conversión útil exige decidir qué información será columna, cuál se serializará y qué diferencias no pueden sobrevivir al cambio.
Esta guía exporta una lista sintética con la herramienta JSON a CSV. El ejemplo incluye identificadores con ceros iniciales, una propiedad ausente, null, datos anidados y valores que una hoja de cálculo podría interpretar como fórmulas. También explica qué revisar antes de entregar el archivo descargado.
Definir la tabla antes de descargarla
La entrada debe ser una matriz JSON cuyos elementos sean objetos. La herramienta crea una unión estable de nombres de propiedad: las columnas aparecen en el orden en que se encuentran al recorrer todos los registros. Una propiedad ausente en el primer objeto puede convertirse en una columna posterior. Por eso no basta con mirar una sola fila para anticipar toda la cabecera.
CSV no conserva todas las diferencias de JSON. Una propiedad ausente y un null explícito producen una celda vacía. Un objeto o una matriz anidados se guardan como texto JSON dentro de una celda, sin aplanar rutas ambiguas como address.city. Una hoja de cálculo verá ese contenido como texto. Son transformaciones deliberadas y documentadas; no demuestran que ambos formatos sean equivalentes.
Un ejemplo fijo con valores incómodos
Usa exactamente esta entrada en las comprobaciones:
[
{
"id": "0012",
"name": "Ana",
"note": "=SUM(A1:A2)",
"profile": { "tier": "pro" },
"tags": ["docs", "qa"],
"active": true,
"score": null
},
{
"id": "0013",
"name": "Bela",
"note": "+441234",
"tags": [],
"active": false
}
]
Con coma, sin BOM y con protección de fórmulas, la cabecera es id,name,note,profile,tags,active,score. Los identificadores siguen siendo texto. profile y tags se serializan como JSON. En la segunda fila, profile queda vacío porque falta; las dos celdas score quedan vacías porque una procede de null y otra de una ausencia. Las notas que parecen fórmulas reciben un apóstrofo inicial y la herramienta avisa del cambio.
Convertir, inspeccionar y reimportar
Pega el ejemplo y mantén activada la protección de fórmulas. Elige coma cuando el consumidor pida datos separados por comas; punto y coma si su configuración regional lo espera; o tabulador únicamente si admite TSV. El delimitador forma parte del contrato con el importador, no es una preferencia visual.
Convierte y revisa la vista previa. Esta muestra como máximo 100 registros para mantener la página manejable, pero la descarga contiene todas las filas válidas, hasta el límite de 10.000. Abre primero el CSV descargado en un editor de texto. Comprueba el orden de las cabeceras, las comillas duplicadas de los JSON anidados y el apóstrofo de ambas notas. Después impórtalo indicando UTF-8 y el mismo delimitador.
Activa BOM solo si la aplicación receptora lo necesita para reconocer acentos. El BOM es metadato al principio del archivo; no es una columna. Finalmente, reimporta el CSV siguiendo la guía de CSV a JSON. Compara identificadores, booleanos, celdas serializadas y vacíos con la política de conversión, sin esperar recuperar automáticamente la estructura JSON original.
Por qué el resultado tiene esa forma
RFC 8259 define los valores JSON y RFC 4180 documenta la convención habitual de CSV: registros, campos, comas, finales CRLF y comillas internas duplicadas. Ninguna norma define un mapeo universal entre ambos. El conversor hace explícitas sus decisiones: unión estable de columnas, serialización JSON de valores anidados y celdas vacías para propiedades ausentes y null.
La protección de fórmulas pertenece a otra capa. Algunas hojas interpretan una celda que empieza por =, +, - o @ como una expresión. Al proteger, el exportador antepone un apóstrofo y avisa. No garantiza que cualquier archivo sea seguro, pero evita presentar texto no confiable con apariencia de fórmula como si no se hubiera modificado. Desactívala solo si el receptor exige texto exacto y esos datos ya se controlan por otra vía.
Las comillas de CSV son estructura. Un campo con delimitador, comillas o salto de línea debe entrecomillarse; cada comilla interna se escribe dos veces. No las elimines aunque un editor muestre muchas alrededor de {"tier":"pro"}: permiten que un parser recupere la celda completa.
Diagnosticar fallos de conversión
El error «matriz de objetos» indica que la raíz no es una matriz o que algún elemento es primitivo o null. Envuelve un objeto solo si realmente representa una fila. Si la matriz mezcla tipos, normaliza los registros antes de exportar.
Las entradas mayores de 2 MiB UTF-8, con más de 10.000 registros o cuya cuadrícula supere un millón de celdas se rechazan en vez de truncarse. Divide por una frontera significativa y conserva un identificador de lote si luego deben recomponerse. El límite de 100 filas afecta solo a la vista previa.
Si un valor anidado parece dañado, inspecciona primero el CSV y después analiza el texto de esa celda como JSON. Una hoja puede eliminar ceros iniciales por inferir un formato numérico; importa esa columna como texto. Si aparecen fórmulas, verifica la opción de protección y el apóstrofo inicial. JSON con enteros no seguros puede haber perdido precisión al analizarse; la herramienta avisa, pero conviene enviar identificadores grandes como cadenas desde el origen.
Hacer reproducible la entrega
Registra delimitador, BOM, protección, lista de cabeceras, recuento y significado de los vacíos. El destinatario no puede deducir si una celda vacía significaba null, propiedad ausente o cadena vacía. Si importa, crea una columna de estado explícita antes de convertir o elige un formato con un modelo que mantenga esa diferencia.
Considera las celdas JSON anidadas una vía documentada, no un esquema cómodo para edición manual. Funcionan cuando otro programa las analizará. Para personas quizá sean mejores columnas separadas o una tabla relacionada. No aplanes sin acordar nombres y colisiones.
La conversión ocurre en el navegador y no requiere subir el conjunto para procesarlo. La descarga sí entra en el almacenamiento habitual del navegador y del sistema. Usa datos sintéticos al probar y aplica las reglas de acceso y retención. La guía sobre privacidad de herramientas amplía estas medidas.
Límites que conviene asumir
CSV no tiene esquema universal, tipos, marcador de nulos, sintaxis anidada ni estándar de seguridad de fórmulas. Descargar correctamente no demuestra que Excel, LibreOffice, una base de datos y un parser propio interpreten igual cada campo. La herramienta no evalúa fórmulas, infiere números regionales, aplana valores ni conserva la diferencia entre ausencia y null.
Escapar fórmulas modifica deliberadamente el texto. Los valores anidados exigen un segundo análisis. La vista previa termina en 100 filas; la descarga usa todas. La entrada admite 2 MiB, 10.000 registros y una cuadrícula de un millón de celdas; la salida JSON estimada también se limita para evitar resultados enormes. En procesos regulados usa un flujo con esquema, validación y pruebas del destino.
Lista final de exportación
Confirma que la raíz sea una matriz de objetos y respete tamaño, filas y celdas. Revisa la unión de cabeceras, incluidas propiedades tardías. Elige el delimitador del importador, BOM cuando sea necesario y protección de fórmulas salvo requisito expreso contrario.
Inspecciona el archivo descargado. Cuenta todas las filas, comprueba 0012, profile, tags y los apóstrofos de =SUM(A1:A2) y +441234. Documenta que ausencia y null se volvieron vacíos. Reimporta con UTF-8 y el mismo delimitador y compara el resultado con la política antes de distribuirlo.
Fuentes: RFC 8259: JSON, RFC 4180: formato CSV y OWASP CSV Injection.