YAML vs JSON — cuándo usar cuál, y por qué la mayoría de equipos usan ambos

Si alguna vez has abierto un manifiesto de Kubernetes, un flujo de trabajo de GitHub Actions o un archivo docker-compose, has usado YAML. Si alguna vez has llamado a una REST API o escrito un archivo de configuración para un proyecto Node.js, has usado JSON. Ambos son formatos de serialización. Ambos describen los mismos tipos de estructuras de datos — mapas, arreglos, cadenas, números, booleanos, nulo. Entonces, ¿por qué tenemos dos?

La respuesta corta: YAML optimiza para humanos, JSON optimiza para máquinas. La respuesta larga involucra unas pocas décadas de experiencia de desarrollo, unas pocas reuniones de comité y una cantidad sorprendente de casos límite. Vamos a recorrerlo.

En qué es bueno JSON

JSON (JavaScript Object Notation) se popularizó a principios de los 2000 como formato de carga para solicitudes AJAX. Fue deliberadamente pequeño — seis tipos de valores, sin comentarios, sin comas finales, sin ambigüedad. Esa rigidez es su superpoder en la red:

• Los analizadores son pequeños y rápidos. JSON.parse viene con cada navegador y cada lenguaje de ejecución. No hay nada que pensar.
• Los errores son inequívocos. Cuando JSON está roto, el analizador te dice exactamente en qué línea y columna.
• Las máquinas están de acuerdo en la semántica. Un número es un número, una cadena es una cadena, true es true. No hay debate de “¿es yes un booleano o una cadena?”

Por eso JSON es la lingua franca de las APIs. Cuando dos servicios están hablando, quieres el formato con menos sorpresas.

En qué es bueno YAML

YAML (YAML Ain’t Markup Language) fue diseñado para archivos de configuración escritos por humanos. Intercambió parte de la rigidez de JSON por legibilidad:

• Sin llaves, sin corchetes. La estructura es la indentación. Un docker-compose.yml se lee de arriba a abajo como una lista.
• Comentarios. Un # inicia un comentario. JSON no tiene sintaxis de comentarios — y la falta de comentarios es la razón más común por la que los equipos migran de JSON a YAML para archivos de configuración.
• Anclas y referencias. &anchor y *reference te permiten definir un valor una vez y reutilizarlo. JSON no tiene equivalente; tienes que copiar y pegar.
• Cadenas de múltiples líneas. Los bloques literales (|) y los bloques plegados (>) manejan texto y código sin malabarismos de escape.

Por eso YAML domina en lugares donde los humanos leen y escriben a mano: Kubernetes, GitHub Actions, GitLab CI, libros de Ansible, docker-compose, CloudFormation, especificaciones OpenAPI y la oleada de archivos de configuración de agentes de IA de la era 2025 (.github/agents.yml, manifiestos de servidores MCP, arneses de evaluación).

La asimetría

Aquí está el secreto sucio: YAML es un superconjunto del modelo de datos de JSON. Cada archivo JSON válido puede expresarse como YAML, pero lo contrario no es cierto. YAML tiene funciones que JSON simplemente no tiene — comentarios, anclas, archivos multi-doc, etiquetas personalizadas. Una vez que escribes YAML con anclas, no puedes convertirlo sin pérdidas a JSON. Las anclas desaparecen.

Esto importa para las herramientas. Si tienes un archivo YAML con &defaults *defaults, convertir a JSON expansionará las referencias (produciendo silenciosamente un archivo más grande) o las eliminará (produciendo silenciosamente un archivo más pequeño). Lo mismo aplica para los comentarios. JSON no tiene dónde ponerlos.

Cuándo usar cuál

Usa JSON cuando:

• Estás enviando datos a través de la red (APIs, colas de mensajes, cargas de eventos).
• El archivo es leído por código, no por humanos.
• Quieres mensajes de error inequívocos de analizadores estrictos.
• Estás optimizando para la velocidad de análisis en dispositivos restringidos.

Usa YAML cuando:

• Un humano es el autor y lector principal del archivo.
• Quieres comentarios para explicar la intención.
• Quieres reutilizar fragmentos de configuración con anclas.
• Las herramientas en tu dominio lo esperan (Kubernetes, CI, etc.).

La respuesta pragmática para la mayoría de los equipos: JSON para la red, YAML para configuración, ambos para intercambio de datos. En caso de duda, almacena la versión canónica en JSON (sin pérdidas) y emite YAML para consumo humano (con comentarios y anclas) solo cuando la audiencia es un desarrollador abriendo un editor de texto.

Errores comunes al convertir entre ambos

1. Los números y booleanos se escriben automáticamente en YAML. port: 8080 es un número. port: "8080" es una cadena. Olvidar las comillas puede cambiar tu tipo.
2. Las anclas y comentarios se eliminan en JSON. No hay forma de evitarlo — el formato no tiene dónde ponerlos.
3. El null de YAML es ambiguo. key: (valor vacío) es null. key: null también es null. key: "" es una cadena vacía. Tres cosas diferentes.
4. Los tabuladores rompen YAML. La indentación debe ser espacios. Los tabuladores son un error.
5. YAML 1.1 vs 1.2 vs 1.2.2. YAML 1.1 trataba yes, no, on, off como booleanos. YAML 1.2 (la especificación usada por js-yaml, PyYAML y la mayoría de los analizadores en 2026) no lo hace. La versión de mantenimiento 1.2.2 en 2025 ajustó algunos casos límite alrededor de marcadores de fin de documento y manejo de BOM — la mayoría de los analizadores adoptaron las correcciones silenciosamente. Si estás migrando de una base de código de la era 2018, tu configuración podría romperse de formas sutiles.

Herramientas que ayudan

Cuando estás moviéndote entre ambos — y lo harás, porque cada equipo usa ambos — un convertidor rápido del lado del cliente es tu amigo. Las herramientas YAML a JSON y JSON a YAML de DevSpeedTools se ejecutan completamente en tu navegador, por lo que los archivos de configuración con secretos nunca salen de tu máquina. Abre DevTools → Network y no verás solicitudes con tus datos.

Para YAML que se ha vuelto desordenado con el tiempo, el formateador YAML normalizará la indentación a dos espacios y corregirá la citación inconsistente. Para archivos que no se analizan, el validador YAML te muestra la línea y columna exacta de cada error.

La conclusión: deja de tratar YAML y JSON como formatos competidores. Son complementarios. El formato correcto depende de quién esté leyendo el archivo — una máquina, o un desarrollador cansado a las 11pm tratando de descubrir por qué su despliegue está roto.