JSON vs YAML: diferencias y cuándo usar cada uno

JSON y YAML resuelven el mismo problema —— representar datos estructurados como texto —— pero hacen trade-offs opuestos. JSON optimiza para parseo de máquina sin ambigüedades; YAML optimiza para autoría humana. Desde YAML 1.2, todo documento JSON válido es también YAML válido. Esta guía compara su sintaxis, tipos y funcionalidades, y explica cuándo usar cada uno.

La respuesta corta

Usa JSON para datos intercambiados entre programas —— respuestas de API, payloads de mensajes, cualquier cosa generada por máquina. Usa YAML para archivos que humanos escriben y editan a mano —— pipelines de CI, manifiestos de Kubernetes, config de aplicación —— donde los comentarios y la legibilidad importan.

Sintaxis lado a lado

Los mismos datos en ambos formatos:

# YAML
service: api
replicas: 3
ports:
  - 8080
  - 8443
env:
  LOG_LEVEL: info
  DEBUG: false

// JSON
{
  "service": "api",
  "replicas": 3,
  "ports": [8080, 8443],
  "env": {
    "LOG_LEVEL": "info",
    "DEBUG": false
  }
}

YAML usa indentación en vez de llaves y corchetes, descarta la mayoría de las comillas y permite comentarios. JSON es más verboso pero no tiene espacios en blanco significativos, lo que lo hace muchísimo más fácil de parsear y generar de forma fiable.

YAML es un superconjunto de JSON

Desde YAML 1.2 (2009), YAML es un superconjunto estricto de JSON —— todo documento JSON válido es YAML válido, porque YAML adoptó directamente la sintaxis «flow» de JSON. Por eso puedes pegar JSON en un archivo YAML y simplemente funciona. Para la historia detrás de esto, ve YAML 1.2 y compatibilidad con JSON.

# Esto es YAML válido —— también es JSON válido
{"service": "api", "replicas": 3}

Comparación de funcionalidades

Manejo de tipos: las aristas afiladas de YAML

Las ganas de YAML de inferir tipos causan sorpresas que las comillas explícitas de JSON evitan:

# El "Norway problem" —— estos se vuelven booleanos en parsers YAML 1.1
countries:
  - NO   # → false (!)
  - SE
  - true # → booleano, no el string "true"

version: 1.20   # → el número 1.2, el cero final se pierde
zip: 01234      # → 668 (parseado como octal) en algunos parsers

JSON no tiene ninguna de estas ambigüedades: "NO" es siempre el string NO, y "01234" es siempre ese string. Cuando un valor YAML debe ser un string, pon comillas explícitas.

Dónde encajan TOML y JSON5

Otros dos formatos de config «amigables con humanos» comunes que aparecen en la misma conversación:

• TOML —— estilo section/key, diseñado para configuración de app editada a mano (Cargo, Poetry, Hugo). Más estricto que YAML, sin indentación significativa, valores tipados nativos (datetime, entero, float, array, tabla inline). Mejor cuando los datos son mayormente tablas planas.
• JSON5 —— JSON con relajaciones amigables para desarrollador: comentarios, comas finales, keys sin comillas, comillas simples, strings multilínea. No es algo que un parser JSON estándar aceptará; haces opt-in con una librería JSON5 (o un parser JSONC para el subconjunto de comentarios + comas finales, p. ej. tsconfig.json).

Encaje aproximado: JSON para intercambio entre máquinas, YAML para config profundamente anidada editada por humanos, TOML para config plana de app/herramienta, JSON5/JSONC cuando quieres JSON-con-comentarios para configs de editor sin adoptar las reglas de espacios de YAML.

Cuándo usar cuál

• Usa JSON para: APIs REST/GraphQL, colas de mensajes, localStorage del navegador, package.json, cualquier cosa generada o consumida por código.
• Usa YAML para: GitHub Actions / GitLab CI, Kubernetes y Docker Compose, playbooks de Ansible, config de app que humanos editan y quieren comentar.

Un patrón común: autorar la config en YAML por legibilidad, luego convertir a JSON en build o load para que tu aplicación solo parsee JSON.

Convertir entre JSON y YAML

# Python —— YAML a JSON
import yaml, json
data = yaml.safe_load(open('config.yaml'))
print(json.dumps(data, indent=2))

# Línea de comandos con yq
yq -o=json '.' config.yaml      # YAML → JSON
yq -P '.' config.json           # JSON → YAML

O convierte al instante en tu navegador con el conversor YAML ⇄ JSON de fixjson —— pega YAML, obtienes JSON (o al revés), sin enviar datos a ningún servidor.

Preguntas frecuentes

¿Es YAML mejor que JSON?

Ninguno es «mejor» —— están afinados para trabajos distintos. YAML es mejor para config editada por humanos (comentarios, legibilidad); JSON es mejor para intercambio de datos entre máquinas (parseo simple, rápido, sin ambigüedades).

¿Es JSON YAML válido?

Sí. Desde YAML 1.2, YAML es un superconjunto estricto de JSON, así que cualquier documento JSON válido es también YAML válido. Lo contrario no es cierto —— la mayoría del YAML no es JSON válido.

¿Por qué YAML convierte «NO» en false?

YAML infiere tipos a partir de escalares sin comillas, y algunos parsers leen NO, yes, on, off como booleanos (el «Norway problem»). Pon comillas al valor ("NO") para forzar un string. JSON evita esto por completo con comillas obligatorias.

¿Debería usar YAML o JSON para archivos de config?

Usa YAML si humanos editan el archivo y se benefician de comentarios y strings multilínea; usa JSON si lo genera o consume tooling. Muchos equipos escriben YAML y convierten a JSON al cargar.

Convierte y valida en tu navegador

• Conversor YAML ⇄ JSON —— convierte en cualquier dirección, en el lado del cliente
• Formateador de YAML —— formatea, re-indenta y valida YAML
• ¿Qué es JSON? —— el formato del que YAML es superconjunto
• Cómo formatear JSON —— pretty-print de la salida convertida
• YAML 1.2 y compatibilidad con JSON —— cómo YAML se volvió un superconjunto de JSON