JSON vs YAML vs CSV: ¿qué formato de datos deberías usar?

Si llevas más de un par de años entregando software, casi seguro que has tecleado cada uno de estos tres formatos en algún archivo. JSON brota de cada endpoint REST. YAML es la lingua franca de los manifiestos de Kubernetes, los flujos de GitHub Actions y la mitad de las CLIs que instalas. CSV es lo que marketing te envía cuando quiere "los datos en bruto". Parecen intercambiables, y herramientas como Multilities hacen que convertir entre ellos sea trivial, pero el hecho de que puedas convertir no significa que debas elegir al azar.

Este artículo recorre cómo funciona cada formato en realidad, dónde brilla, dónde se rompe y las reglas empíricas que los equipos con experiencia usan para elegir uno. Veremos el mismo conjunto de datos representado de tres formas para que los compromisos sean concretos y no abstractos.

Un modelo mental rápido

Antes de ahogarte en sintaxis, mantén los formatos en la cabeza así:

• JSON es un formato de serialización para objetos estructurados. Es lo que usas cuando una máquina necesita hablar con otra máquina y los humanos solo leen la salida ocasionalmente.
• YAML es una especie de superconjunto de JSON optimizado para que los humanos editen archivos de configuración a mano. Asume que una persona va a desplazarse, comparar diferencias y revisarlo.
• CSV es un formato tabular. Asume que cada fila tiene la misma forma y que el consumidor probablemente sea una hoja de cálculo, un comando COPY de base de datos o un read_csv rápido de pandas.

JSON: el predeterminado para APIs y JS

JSON, JavaScript Object Notation, se extrajo de JavaScript a principios de los 2000 y se estandarizó como RFC 8259. Tiene seis tipos primitivos: objeto, array, cadena, número, booleano y null. Ese es todo el vocabulario. No hay fechas, no hay comentarios, no hay comas finales y no hay referencias. El minimalismo es el punto: cualquier lenguaje puede parsear JSON en unos pocos cientos de líneas de código, razón por la cual cada API HTTP del planeta acaba asentándose en él.

Los navegadores parsean JSON de forma nativa con JSON.parse, cada stdlib de backend tiene un módulo JSON, y existen variantes amigables con binario como MessagePack y CBOR cuando superas la representación textual. Para cargas útiles de petición/respuesta, envío de logs, estado de JS persistido y bases de datos documentales, JSON es casi siempre el predeterminado correcto.

YAML: el punto óptimo para configuración

YAML, originalmente Yet Another Markup Language y luego renombrado recursivamente a YAML Ain't Markup Language, es un superconjunto estricto de JSON en la versión 1.2. Cualquier cosa legal en JSON es legal en YAML, pero YAML añade comentarios, cadenas multilínea, anclas y alias para reutilización, etiquetas de tipo explícitas y, sobre todo, una sintaxis basada en indentación que elimina la mayor parte del ruido de puntuación.

Esa legibilidad es por lo que YAML domina la configuración. Los manifiestos de Kubernetes, los charts de Helm, los playbooks de Ansible, GitHub Actions, GitLab CI, Docker Compose, las especificaciones OpenAPI, los proyectos de dbt y la mayoría de las CLIs modernas leen YAML. Cuando un humano va a editar un archivo en un editor y revisarlo en una pull request, YAML gana.

CSV: el apretón de manos universal con la hoja de cálculo

CSV, valores separados por comas, es anterior a la web y está descrito laxamente por la RFC 4180. Es muerto-simple: la primera línea suele ser una cabecera, cada línea posterior es una fila y los campos se separan por un delimitador (a menudo una coma, pero el tabulador, el punto y coma y la barra vertical también son comunes). Las cadenas que contienen el delimitador, un salto de línea o una comilla doble se envuelven en comillas dobles, y las comillas internas se escapan duplicándolas.

CSV es el formato que cada hoja de cálculo de la Tierra, cada herramienta de BI, cada cargador masivo de bases de datos y cada analista con un cuaderno de Python entiende sin ceremonia. Es un formato terrible para datos anidados y un formato maravilloso para tablas planas. Cuando el consumidor es un humano con Excel abierto, CSV es casi siempre la respuesta correcta.

Los mismos datos, tres formatos

Concretemos las diferencias con un ejemplo. Imagina una lista de tres usuarios, cada uno con un id, un nombre, un email, un rol y una lista de etiquetas. Aquí está la versión JSON.

[
  {
    "id": 1,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "role": "admin",
    "tags": ["founder", "math"]
  },
  {
    "id": 2,
    "name": "Linus Torvalds",
    "email": "linus@example.com",
    "role": "maintainer",
    "tags": ["kernel", "git"]
  },
  {
    "id": 3,
    "name": "Grace Hopper",
    "email": "grace@example.com",
    "role": "admin",
    "tags": ["compiler", "navy"]
  }
]

La misma carga útil como YAML

Fíjate en cómo cae la puntuación. La estructura se transmite enteramente por indentación, y la lista de etiquetas puede escribirse en línea (estilo flow, idéntico a JSON) o como bloque. Los comentarios son legales y a menudo útiles.

# Seed users for the staging environment
- id: 1
  name: Ada Lovelace
  email: ada@example.com
  role: admin
  tags:
    - founder
    - math
- id: 2
  name: Linus Torvalds
  email: linus@example.com
  role: maintainer
  tags: [kernel, git]   # flow style is fine for short lists
- id: 3
  name: Grace Hopper
  email: grace@example.com
  role: admin
  tags:
    - compiler
    - navy

Y como CSV

CSV no puede expresar nativamente el array anidado de etiquetas, así que tenemos que aplanarlo. Una convención común es unir la lista con un delimitador secundario como una barra vertical o un punto y coma y documentar esa elección en algún sitio. La fila de cabecera reemplaza los nombres de campo y cada registro va en su propia línea.

id,name,email,role,tags
1,Ada Lovelace,ada@example.com,admin,founder|math
2,Linus Torvalds,linus@example.com,maintainer,kernel|git
3,Grace Hopper,grace@example.com,admin,compiler|navy

Tres formatos, tres tamaños

El tamaño de archivo importa más de lo que la gente admite. Los pipelines de logging, los bundles del navegador y las facturas de almacenamiento se preocupan por ello. Para el ejemplo anterior, los conteos aproximados de bytes son: JSON unos 410 bytes con formato y 290 minimizado; YAML unos 320 bytes; CSV unos 200 bytes. CSV gana cómodamente con datos planos porque amortiza los nombres de campo a través de cada fila en lugar de repetirlos.

Una vez que empiezas a anidar, la imagen se voltea. JSON y YAML se mantienen aproximadamente constantes por registro, mientras que CSV o tiene que aplanar con convenciones que tú inventas o explotar en múltiples hojas. Para un único usuario profundamente anidado con veinte campos, JSON y YAML serán más pequeños y claros que cualquier CSV que puedas construir.

Dónde gana cada formato en la práctica

Patrones de lo que usan los equipos reales:

• JSON para APIs HTTP, cargas útiles de WebSocket, localStorage del navegador, líneas de log (especialmente JSON Lines), bases de datos documentales como MongoDB y cualquier contrato entre servicios.
• YAML para Kubernetes, Helm, Argo, espacios de trabajo de Terraform Cloud, pipelines de GitHub o GitLab CI, especificaciones OpenAPI y AsyncAPI, configuración de aplicaciones que editan humanos e infraestructura como código donde la legibilidad le gana a la velocidad de parseo.
• CSV para exportaciones de analítica, importaciones de CRM, tablas de staging en ETL, conjuntos de datos de machine learning, informes financieros y cualquier cosa destinada a Excel o Google Sheets.
• No recurras a ninguno de los tres si tus datos son binarios, de muy alto rendimiento o fuertemente tipados entre servicios. Protobuf, Avro o Parquet suelen ser la respuesta correcta ahí.

Las trampas de JSON que muerden

El minimalismo de JSON es una virtud, pero crea unas cuantas trampas. La especificación prohíbe los comentarios, así que los archivos de configuración escritos en JSON no pueden explicarse a sí mismos. Las comas finales tras el último elemento de un array u objeto son ilegales aunque cualquier lenguaje moderno las acepte. Los números son flotantes de 64 bits por defecto, así que cualquier entero mayor que 2 elevado a 53 pierde precisión silenciosamente, razón por la cual muchas APIs serializan los IDs grandes como cadenas.

JSON tampoco tiene un tipo de fecha nativo. Las cadenas ISO 8601 son la convención de facto, pero tú y tu consumidor tenéis que poneros de acuerdo. Y las claves duplicadas en el mismo objeto están técnicamente permitidas por la gramática, pero producen comportamiento indefinido entre parsers, así que no dependas de ellas.

Las trampas de YAML que muerden más fuerte

La flexibilidad de YAML es su debilidad. La indentación es significativa, así que mezclar tabuladores y espacios o perder dos caracteres de espacio en blanco al inicio cambia silenciosamente el significado de tu archivo. El infame problema de Noruega sigue apareciendo en parsers de YAML 1.1: el token sin comillas NO se parsea como el booleano false, lo que ha arruinado listas de códigos de país más de una vez. YAML 1.2 lo arregla, pero mucho instrumental sigue enviando semántica de 1.1.

Las cadenas que parecen números, fechas o booleanos se coercionan a menos que las pongas entre comillas. Las anclas y alias (la sintaxis &foo y *foo) son potentes pero invitan a denegaciones de servicio al estilo de las "mil millones de risas" si aceptas YAML no confiable. Parsea siempre YAML proporcionado por el usuario con un cargador seguro.

Las trampas de CSV que muerden en silencio

CSV es el formato con más probabilidades de parecer correcto mientras está sutilmente roto. No hay un estándar para el delimitador; las localizaciones europeas exportan con punto y coma porque la coma es separador decimal, y tu importador tiene que detectarlo. Los saltos de línea dentro de campos entrecomillados son legales, pero tropiezan a los divisores de líneas ingenuos. Excel reformateará alegremente números de teléfono e IDs largos como notación científica al abrir un CSV, destrozando tus datos antes de que un humano los vea siquiera.

La codificación es la otra mina enterrada. CSV no tiene declaración de codificación, así que un archivo que se abre limpio en macOS puede mostrar mojibake en Windows por culpa de UTF-8 frente a Windows-1252. Cuando dudes, escribe un BOM UTF-8, documenta el delimitador y entrecomilla todos los campos de cadena.

Convertir entre ellos con seguridad

La mayoría de los sistemas reales viven en más de uno de estos formatos. Ingieres un CSV de un proveedor, lo transformas en JSON para una API y emites YAML para configurar el worker que procesa el resultado. Hacer esas conversiones a mano es de donde salen los bugs, razón por la cual Multilities incluye conversores dedicados.

Si alternas entre JSON y YAML, el conversor /tools/yaml-json maneja ambas direcciones y preserva los comentarios cuando puede. Para datos tabulares, /tools/csv-json convierte exportaciones de CSV en arrays JSON que puedes pegar directamente en un archivo de fixtures o una petición de Postman, y de vuelta cuando necesites entregar una hoja de cálculo a finanzas. Y cuando solo quieres que un blob JSON se lea como si lo hubiera escrito un humano, /tools/json-formatter ordena claves, arregla la indentación y valida la estructura en una sola pasada.

Una checklist de decisión

Cuando no estés seguro, recorre esta lista de arriba abajo y detente en el primer sí.

• ¿El consumidor es una hoja de cálculo o un cargador masivo de SQL y los datos son planos? Usa CSV.
• ¿Va un humano a editar este archivo en un editor de código y revisarlo en una pull request? Usa YAML.
• ¿El consumidor es un programa, especialmente a través de la red, y quieres mínima ceremonia y máximo instrumental? Usa JSON.
• ¿Estás serializando millones de registros con alto rendimiento y un esquema fijo? Sáltate los tres y recurre a Protobuf, Avro o Parquet.

Cerrando

Los tres formatos no son tanto competidores como especialistas. JSON es el formato universal de intercambio, YAML es el lenguaje de configuración amigable para humanos y CSV es el apretón de manos con la hoja de cálculo que se niega a morir porque ningún otro está tan universalmente entendido por personas no desarrolladoras. Saber para qué trabajo se diseñó cada uno y conocer las trampas es lo que separa a los equipos que entregan pipelines de datos limpios de los que pelean con bugs de escapado cada viernes por la tarde.

Mantén las herramientas de conversión guardadas en marcadores, anota qué delimitador y codificación usan tus CSV, entrecomilla tus cadenas YAML cuando dudes y nunca confíes en que un ID de 64 bits sin signo sobreviva un viaje de ida y vuelta por JavaScript. Haz eso y el formato que elijas en su mayor parte desaparecerá hacia el fondo, que es exactamente lo que se supone que hace un buen formato de datos.