Conversor de JSON a CSV

Por qué la conversión JSON-a-CSV es un flujo de trabajo tan habitual

JSON es el formato de carga útil dominante para las API web modernas; CSV es el formato de mínimo común denominador para datos tabulares. Excel, Google Sheets, SQL LOAD DATA, R, Pandas, Tableau, Power BI y casi todo pipeline ETL ingieren CSV de fábrica. Así que cuando la salida de una API tiene que aterrizar en una hoja de cálculo para un interlocutor, o en una base de datos para análisis, alguien tiene que aplanar el JSON en filas. Esta herramienta hace ese aplanado en tu navegador, sin ida y vuelta al servidor y sin subir datos potencialmente sensibles.

El formato CSV (RFC 4180)

No existe una única norma CSV formal, pero la RFC 4180 (octubre de 2005, «Common Format and MIME Type for Comma-Separated Values (CSV) Files») es lo más cercano a una referencia canónica que tiene la industria. Las reglas en las que todos coinciden:

• Un registro por línea, separados por saltos de línea. La RFC especifica CRLF; la mayoría de parsers modernos aceptan también LF.
• Los campos de un registro se separan con un solo carácter delimitador, una coma en la forma canónica, pero un punto y coma, una tabulación o un pipe es habitual en variantes regionales e históricas.
• Cada registro debe tener el mismo número de campos. Los valores faltantes pasan a celdas vacías; los delimitadores de más son un error.
• La fila de cabecera es opcional; si está, es la primera línea.
• Los campos que contienen comas, saltos de línea o comillas dobles deben ir entre comillas dobles.
• Las comillas dobles dentro de un campo entrecomillado se escapan duplicándolas: "She said ""hello""".
• El tipo MIME registrado para CSV es text/csv.

Por qué cuatro delimitadores en lugar de uno

El defecto es la coma, pero cada delimitador resuelve un problema específico:

• Coma (,), el estándar en EE. UU., el Reino Unido y otras locales anglosajonas. Excel lee CSV con comas cuando el ajuste regional del SO es inglés. Defecto para application/csv en el ecosistema de herramientas amplio.
• Punto y coma (;), el defecto de hecho en Europa continental, América Latina y otras regiones donde la coma es el separador decimal. Excel usa el separador de listas del SO, así que un Excel en locale francesa o alemana produce CSV separado por punto y coma.
• Tabulación, TSV (tab-separated values) es habitual en datos científicos, bioinformática y cualquier contexto en el que los datos contienen comas (campos de texto libre, direcciones).
• Pipe (|), preferido en algunos sistemas empresariales antiguos donde los datos pueden contener comas, puntos y comas Y tabulaciones. Rara vez es la primera elección correcta pero útil cuando nada más funciona.

Aplanar JSON anidado: tres estrategias

JSON es jerárquico; CSV es plano. No hay un mapeo de propósito general sin pérdidas entre ambos. Cuando la entrada contiene objetos o arrays anidados, todo conversor tiene que elegir:

1. Incrustar como cadena JSON. La parte anidada se reserializa a JSON y se coloca en una sola celda CSV. Enfoque por defecto de esta herramienta. Sin pérdidas; ida-y-vuelta segura; el consumidor necesita parsear el JSON interno si quiere la estructura.
2. Aplanado con claves punteadas. {address: {street, city}} pasa a columnas address.street y address.city. El json_normalize de Pandas hace esto. Más limpio para analistas, pero el número de columnas explota con datos muy anidados.
3. Explosión de filas. Un array pasa a varias filas, con los campos padre repetidos. {name: "Alice", tags: ["a", "b"]} pasa a dos filas, ambas con name=Alice. Lo mejor para relaciones uno-a-muchos; pierde el modelo mental «un registro por fila».

Si necesitas salida con claves punteadas o filas explotadas, preprocesa el JSON antes de pegarlo, ya sea con un pequeño script Python/Node o con el json_normalize de Pandas.

Cabeceras, ida y vuelta de tipos y la trampa de auto-formato de Excel

JSON tiene un sistema de tipos real (número, cadena, booleano, null, array, objeto); CSV solo tiene cadenas. La convención es que el consumidor infiera tipos por contexto. La herramienta genera filas de cabecera con la unión de todas las claves de todos los objetos de entrada, deja los campos ausentes como celdas vacías, escribe los booleanos como true/false y escribe el null JSON como celda vacía.

Excel «ayuda» de formas que a veces hacen daño:

• Eliminación de ceros iniciales. Una columna de códigos postales como 01234 se abre como el número 1234. Solución: prefijar con un apóstrofe ('01234) dentro del CSV, o usar el asistente de importación de Excel y fijar explícitamente el tipo Texto.
• Conversión automática a fechas. Las cadenas con forma de fecha (3/4/5, Mar-23) se convierten silenciosamente. Mismas soluciones.
• Notación científica. Los IDs numéricos largos (números de tarjeta de crédito, enteros grandes) se convierten a 1.23E+15 y pierden precisión. JSON puede preservar números hasta 2⁵³−1 con exactitud; para mayores, transmite el valor como cadena en JSON.
• Desajuste UTF-8 BOM. Excel en Windows usa Windows-1252 por defecto; abrir un CSV UTF-8 sin BOM corrompe los caracteres no ASCII (é, ü, å se convierten en mojibake). Añadir un BOM UTF-8 () al inicio del archivo lo arregla. Google Sheets gestiona UTF-8 sin BOM correctamente, así que el BOM es específico de plataforma.

Inyección CSV, una nota de seguridad útil

Si un CSV va a abrirse en Excel o Google Sheets, una celda que empieza con =, +, - o @ se interpreta como fórmula. La página de CSV Injection de OWASP documenta la clase de ataque, una cadena maliciosa como =cmd|' /c calc'!A0 en un campo enviado por usuario puede ejecutar comandos cuando un administrador abre el export. Práctica defensiva: prefija toda celda que empiece por uno de esos cuatro caracteres con una comilla simple, o envuélvela en comillas con apóstrofe delante. Importante si exportas contenido generado por usuarios.

Casos límite habituales gestionados

• Campo que contiene el delimitador, entrecomillado automáticamente. San Francisco, CA en CSV de coma pasa a "San Francisco, CA".
• Campo con un salto de línea literal, entrecomillado; el contenido multilínea es legal entre comillas según la RFC 4180.
• Campo con una comilla doble, entrecomillado, con la comilla interna duplicada: She said "yes" pasa a "She said ""yes""".
• Arrays y objetos vacíos, serializados respectivamente como [] y {} en sus celdas.
• Registros con claves distintas, la unión de todas las claves forma la fila de cabecera; los campos faltantes son celdas vacías.
• Objeto único frente a array, un objeto JSON único se convierte en CSV de una sola fila.

Cuándo usar esta herramienta

• Exportar respuestas de API para interlocutores que quieren una hoja para ordenar y filtrar.
• Importar masivamente JSON a una BD SQL vía LOAD DATA INFILE (MySQL) o COPY (PostgreSQL). Ambos esperan entrada con forma CSV.
• Análisis rápido de datos en Excel, Google Sheets, Pandas, R, Tableau o Power BI.
• Generar listas de correo a partir de una respuesta JSON de API de contactos.
• Migrar datos entre sistemas que no comparten API pero ambos hablan CSV.
• Revisar un archivo JSON a ojo cuando es demasiado repetitivo para leerlo directo, la vista de hoja suele ser más fácil.

Privacidad

Los exports CSV casi siempre contienen PII, registros de clientes, datos de empleados, logs de transacciones, listas de contactos. La conversión en servidor envía cada registro por la infraestructura de un tercero, donde vive en logs de tránsito, logs de servidor y posiblemente caches. La conversión basada en navegador mantiene los datos en tu máquina. Todo el paso de aplanar y entrecomillar sucede aquí en JavaScript dentro de tu navegador; nada se sube.

Errores comunes

1. Delimitador equivocado para el público. Enviar un CSV con comas a un usuario de Excel francés produce un archivo de una sola columna. Iguala el delimitador a la locale del destinatario.
2. Pegar un objeto único en lugar de un array. Un objeto único se convierte en CSV de una fila con cabeceras a partir de las claves. Para varios registros, envuélvelos en un array.
3. Esperar aplanado al estilo Pandas. Los objetos anidados en esta herramienta se serializan como cadenas JSON dentro de las celdas. Si quieres columnas address.street, aplana antes.
4. Usar CSV para números muy grandes. JSON representa de forma segura enteros hasta 2⁵³−1 (~9 cuatrillones de escala corta). Más allá, transmite como cadena. Excel estropeará los IDs numéricos largos incluso cuando el CSV los preserve.
5. Abrir en Excel sin pensar en la codificación. Los caracteres no ASCII necesitan BOM UTF-8 para Excel en Windows; Google Sheets y el Excel moderno para web no lo necesitan.
6. Exportar texto generado por usuario sin sanear prefijos de fórmula. Las celdas que empiezan por =, +, - o @ son fórmulas en Excel y Sheets. La inyección CSV es un ataque real contra los administradores que abren archivos exportados.

Preguntas frecuentes

Mi JSON tiene objetos anidados. ¿Cómo se gestionan?

Cada objeto o array anidado se serializa como cadena JSON dentro de su celda CSV. Así {user: {name: "Alice", role: "admin"}} pasa a una columna user con {"name":"Alice","role":"admin"}. Esto hace ida y vuelta sin pérdidas. Si quieres columnas user.name y user.role separadas, preprocesa con json_normalize de Pandas o un pequeño script de aplanado.

¿Por qué mis caracteres no ingleses se ven mal en Excel?

Excel en Windows abre CSV en Windows-1252 por defecto. Un CSV UTF-8 sin Byte Order Mark se ve como mojibake (é → é). Solución: o guardar el archivo con BOM UTF-8, o usar el asistente Datos → Desde texto de Excel y seleccionar explícitamente UTF-8, o abrirlo en Google Sheets, que gestiona UTF-8 sin BOM correctamente.

¿La herramienta gestiona las comas dentro de los campos?

Sí. Según la RFC 4180, los campos que contienen el delimitador, saltos de línea o comillas dobles se entrecomillan automáticamente. Las comillas dobles internas se escapan duplicándolas. Así San Francisco, CA pasa a "San Francisco, CA" y She said "hi" pasa a "She said ""hi""".

¿Se envía mi JSON a un servidor?

No. La conversión corre íntegramente en tu navegador. El contenido del área de texto no se transmite, registra ni almacena en ningún sitio. Importa porque los registros exportados contienen a menudo PII, datos de clientes, información de empleados, historiales de transacciones, que no quieres que pase por la infraestructura de otra persona.

¿Puedo obtener salida separada por tabulaciones (TSV)?

Sí, elige «Tab» en el desplegable de delimitador. TSV es la opción adecuada cuando tus datos contienen comas (direcciones, campos de texto libre, datos financieros con separadores de miles) y no quieres entrecomillar una de cada dos celdas. Muchos formatos de bioinformática y de datos científicos son TSV por defecto.

¿Cuál es el límite de tamaño?

Lo que pueda manejar tu navegador. No hay límite de servidor porque no hay servidor. Decenas de megabytes de JSON se convierten en uno o dos segundos en un equipo moderno; cargas de cientos de megabytes empiezan a ralentizarse. Para conjuntos muy grandes, divídelos por lotes o pasa a un conversor en streaming en línea de comandos.

Herramientas relacionadas