JSON vs YAML — Diferencias explicadas

Probablemente hayas notado que algunos proyectos usan archivos .json para la configuración mientras que otros usan .yaml o .yml. Ambos formatos representan datos estructurados. Ambos son legibles para humanos. Entonces, ¿cuál es la diferencia real, y cuándo deberías optar por uno u otro?

He usado ambos extensamente — JSON es mi formato diario para APIs e intercambio de datos, YAML es mi opción para manifiestos de Kubernetes, GitHub Actions, y Docker Compose. Resuelven problemas similares pero tienen personalidades muy distintas.

Lado a lado: la misma config en ambos formatos

Aquí tienes un objeto de configuración de base de datos escrito en JSON:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp",
    "ssl": true,
    "pool": {
      "min": 2,
      "max": 10
    },
    "replicas": ["replica1.db", "replica2.db"]
  }
}

Y aquí está la misma config en YAML:

database:
  host: localhost
  port: 5432
  name: myapp
  ssl: true
  pool:
    min: 2
    max: 10
  replicas:
    - replica1.db
    - replica2.db

YAML es visiblemente más limpio. Sin comillas en la mayoría de strings, sin llaves, sin comas. Para un archivo de configuración que los humanos editan con frecuencia, esa claridad se nota. Pero YAML lo logra siendo significativamente más complejo por dentro.

Dónde brilla YAML

• Archivos de config editados por humanos. Pipelines CI/CD (GitHub Actions, GitLab CI), manifiestos de Kubernetes, Docker Compose, playbooks de Ansible. Todo en YAML. No es casualidad — son archivos que los humanos escriben a mano.
• Comentarios. YAML soporta comentarios con #. Esto es enorme para archivos de configuración donde quieres explicar por qué un ajuste tiene ese valor. JSON no soporta comentarios en absoluto.
• Strings multilínea. YAML tiene escalares en bloque para contenido multilínea que se lee de forma natural. JSON requiere secuencias de escape \n.
• Menos ruido visual. No hace falta entrecomillar la mayoría de strings, sin llaves de cierre, sin preocuparte por comas finales.
• Anclas y alias. YAML te permite definir un valor una vez y referenciarlo en otro lugar con &anchor y *alias — muy útil para archivos de config DRY.

Dónde gana JSON

• Estrictez. JSON tiene una única representación válida para cualquier estructura de datos. YAML tiene una docena de formas de escribir lo mismo, lo que crea inconsistencias entre equipos.
• Sin trampas de indentación. JSON usa llaves y corchetes. YAML usa indentación, lo que significa que un solo espacio mal puesto puede romper silenciosamente toda tu config.
• Rendimiento de parseo. Los parsers JSON son rápidos y simples. Los parsers YAML son complejos — YAML 1.1 tiene reglas de coerción de tipos implícitos notoriamente complicadas.
• Soporte universal de librerías. Todos los lenguajes tienen un parser JSON robusto, sin dependencias. Las librerías YAML varían en calidad y cumplimiento de la spec.
• Tooling. Linters, formateadores, validadores de schema — el tooling de JSON es más maduro y ampliamente disponible.
• Payloads de API. JSON es el lenguaje universal de las APIs web. Enviar YAML por HTTP sería poco convencional y generaría fricción.

Los gotchas de YAML que te van a quemar

YAML tiene comportamientos genuinamente sorprendentes que han causado incidentes reales en producción. La mayoría vienen de las reglas de tipos implícitos en YAML 1.1, que YAML 1.2 ajustó. Conoce estos antes de depender de YAML para algo crítico:

# YAML 1.1 implicit type coercion — all of these become booleans:
enabled: yes   # → true
disabled: no   # → false
country: NO    # → false (!)  ← the Norway Problem

# Safe practice: quote strings that look like booleans
country: "NO"
enabled: "yes"

• Enteros octales. En YAML 1.1, 010 se parsea como 8 (octal), no 10. Relevante para cosas como permisos de archivos.
• Tabs vs espacios. YAML prohíbe los tabs para la indentación. Mezcla un tab de un editor de código y tu archivo se rompe silenciosamente o lanza un error críptico.
• Nulls implícitos. Un valor vacío en YAML se convierte en null. Fácil de pasar por alto al editar a mano.
• Ambigüedad string vs número. port: 8080 te da un entero. version: 1.0 podría darte un float. A veces quieres el string "1.0". Pon siempre comillas cuando importe.

Guía de decisión práctica

Usa YAML cuando:

• Escribes archivos de config que los humanos editan directamente: CI/CD, Kubernetes, Docker Compose, Ansible
• El archivo tendrá comentarios explicando los ajustes
• Los valores de string multilínea son frecuentes
• El ecosistema en el que trabajas ya usa YAML (no luches contra la convención)

Usa JSON cuando:

• Envías o recibes datos a través de una API
• Los datos se generan y consumen de forma programática (sin edición humana)
• Necesitas consistencia garantizada en el parseo entre distintas herramientas y lenguajes
• Trabajas en un ecosistema que estandariza en JSON: npm (package.json), VS Code (settings.json), Angular, TypeScript

Convertir entre los dos

¿Necesitas convertir config YAML a JSON para una herramienta que no habla YAML? Usa el conversor YAML a JSON. ¿Al revés? El conversor JSON a YAML lo hará. El Formateador YAML también es útil cuando pegas YAML que se ha desalineado. Y si tu YAML no parsea, el Validador YAML te dirá exactamente dónde está el problema.

Conclusión

JSON y YAML son complementarios, no competidores. Usa JSON para intercambio de datos — APIs, almacenamiento de datos programático, serialización. Usa YAML para archivos de config que los humanos leen y editan. La mayoría de proyectos maduros usan ambos: package.json para dependencias, .github/workflows/*.yml para CI. Una vez que entiendes para qué está optimizado cada formato, la elección se vuelve obvia.