JSON vs YAML: Elegir el formato de configuración correcto

JSON y YAML parecen la misma cosa con diferentes disfraces hasta que intentas mantener un archivo de configuración de mil líneas en cualquiera de los dos. Las diferencias importan, y la mayoría de ellas no son sobre la sintaxis — son sobre lo que hace cada formato cuando estás ligeramente equivocado.

El mismo ejemplo en ambos

La forma más rápida de sentir la diferencia es leer datos idénticos lado a lado.

JSON

{
  "name": "convertitive",
  "version": "1.4.0",
  "ports": [80, 443],
  "features": {
    "darkMode": true,
    "telemetry": false
  },
  "owners": ["[email protected]", "[email protected]"]
}

YAML

name: convertitive
version: 1.4.0
ports:
  - 80
  - 443
features:
  darkMode: true
  telemetry: false
owners:
  - [email protected]
  - [email protected]

El YAML es aproximadamente un 30% más corto y posiblemente más legible para un humano que nunca ha visto ninguno de los dos. El JSON es inequívoco para una máquina, amigable con los analizadores, y sobrevive copiar y pegar a través de cualquier editor de texto en cualquier sistema operativo sin daños de caracteres invisibles.

En qué gana YAML

Comentarios

YAML admite # comentarios de línea en cualquier parte. JSON no — RFC 8259 los excluye deliberadamente. Para un archivo de configuración que los humanos van a leer y editar, los comentarios no son un lujo; son cómo documentas por qué una bandera está desactivada o qué rango de valores acepta realmente una configuración.

# fijar a una versión de parche específica; no actualizar automáticamente
version: 1.4.0

ports:
  - 80
  # el 443 está aquí para que funcione el health check del LB; no eliminar
  - 443

Cadenas multilínea

YAML tiene dos estilos de bloque escalar para cadenas multilínea. | preserva las nuevas líneas, > las dobla en espacios.

description: |
  Convertitive es un sitio de herramientas.
  Carga rápido y no tiene popups.

summary: >
  Una oración única escrita en
  múltiples líneas para comodidad del editor.

Anclas y alias

YAML te permite etiquetar un nodo con & y referenciarlo en otro lugar con *. Las claves de fusión (<<) extienden un mapeo con otro:

defaults: &defaults
  retries: 3
  timeout_ms: 5000

production:
  <<: *defaults
  endpoint: api.example.com

staging:
  <<: *defaults
  endpoint: staging.api.example.com
  timeout_ms: 30000  # sobreescribe el predeterminado

JSON no tiene equivalente. La solución es plantillas (Jinja, Helm) o post-procesamiento en tiempo de carga.

Legibilidad visual

La indentación-como-estructura es la razón principal por la que los equipos eligen YAML. Un documento profundamente anidado se lee de arriba a abajo; no pierdes el lugar contando llaves. Por eso todos los manifiestos de Kubernetes son YAML y todos los playbooks de Ansible son YAML.

En qué gana JSON

Análisis inequívoco

JSON tiene una gramática de cinco páginas. Dos analizadores correctos estarán de acuerdo en todos los documentos. YAML tiene una gramática de noventa páginas con múltiples interpretaciones válidas del mismo documento según la versión del analizador. La estrictez de JSON es la característica.

Ubicuidad de herramientas

Cada lenguaje incluye un analizador JSON en su biblioteca estándar. YAML requiere una dependencia de terceros en la mayoría de los entornos — PyYAML, js-yaml, snakeyaml, go-yaml.

El problema de Noruega — literalmente

El error de YAML más famoso: en YAML 1.1, la cadena NO se analiza como el booleano false. Las listas de países que incluyen el código ISO de Noruega (NO) se convierten en [false, ...] a menos que estén entre comillas. Lo mismo ocurre con YES, ON, OFF, y varias capitalizaciones. YAML 1.2 corrige esto tratando solo true y false en minúsculas como booleanos, pero una cantidad sorprendente de herramientas usa 1.1 por defecto en 2026.

Valores predeterminados de seguridad

La especificación de YAML incluye etiquetas de tipo que permiten que un documento indique al analizador que instancie clases arbitrarias. Varios bindings de lenguaje honraron esto por defecto durante años, lo que significa que cargar un documento YAML controlado por un atacante podría ejecutar código arbitrario. La solución es usar un cargador “safe” (yaml.safe_load en Python, YAML.safe_load en Ruby).

Problemas compartidos

Precisión numérica en JSON

La especificación de JSON dice que los números pueden ser de magnitud y precisión arbitrarias. El JSON.parse de JavaScript y la mayoría de las implementaciones no-JS los deserializa en doubles IEEE 754, que solo pueden representar enteros exactamente hasta 2^53 - 1 (aproximadamente 9,007 × 10^15). Un ID snowflake de Twitter, un ID de cargo de Stripe, o cualquier entero de 19 dígitos se redondeará silenciosamente. La solución es codificar enteros grandes como cadenas, o usar un analizador con soporte BigInt.

Deriva de versión de YAML

YAML 1.1 (2005) y YAML 1.2 (2009) son las dos versiones en uso. 1.2 es un superconjunto estricto de JSON, corrigió el problema de Noruega y ajustó considerablemente la especificación. Muchos analizadores siguen usando 1.1 en silencio. Lo primero que debes hacer con una nueva base de código YAML es establecer qué versión está usando el analizador y escribir la respuesta en el README.

Un árbol de decisión

Para proyectos nuevos donde controlas el consumidor:

1. ¿Formato de cable máquina a máquina? Usa JSON. Todos los lenguajes lo analizan, los comentarios no importan, y la estrictez elimina toda una clase de errores de integración.
2. ¿Configuración editada por humanos de menos de 100 líneas? Usa YAML si el consumidor espera YAML, TOML en caso contrario.
3. ¿Configuración editada por humanos de más de 100 líneas, profundamente anidada? Las anclas y los bloques escalares de YAML empiezan a ser rentables a ese tamaño.
4. ¿Entrada no confiable? JSON es más seguro por defecto. Si debes aceptar YAML, usa el cargador seguro y un esquema.
5. ¿El consumidor está fijado (Kubernetes, npm)? Coincide con el consumidor. No luches contra el ecosistema.

Conversión entre ellos

La conversión es mecánica porque YAML 1.2 es un superconjunto de JSON. JSON de entrada, YAML de salida es siempre sin pérdida. YAML de entrada, JSON de salida es sin pérdida solo si el YAML usa tipos primitivos y no hay anclas/alias que requieran expansión.

Nuestro convertidor JSON ↔ YAML maneja ambas direcciones en el navegador y te muestra la línea donde falla el análisis si la entrada es inválida. Para trabajo puro de JSON — formateo, validación, minificación — el formateador JSON es una herramienta más precisa.

La conclusión honesta

JSON es el predeterminado correcto para cualquier cosa en la que dos programas necesiten estar de acuerdo. YAML es el predeterminado correcto para cualquier cosa que un humano vaya a editar extensamente. La mayoría de los sistemas de producción terminan con ambos: YAML en la frontera humana (charts de Helm, workflows de GitHub Actions, configuración de aplicaciones), JSON a través del cable y en reposo en bases de datos.