JSON vs YAML: diferencias y cuando usar cada uno

YAML es un superconjunto del modelo de datos de JSON: todo documento JSON valido es tambien YAML valido, palabra por palabra. La diferencia no es lo que cada formato puede representar, sino como se escribe cada uno y que tan comodo es para edicion manual.

Los mismos datos, dos maneras

{
  "name": "web-app",
  "version": "1.0.0",
  "scripts": { "build": "vite build", "test": "vitest" },
  "dependencies": ["react", "vite"]
}

name: web-app
version: 1.0.0
scripts:
  build: vite build
  test: vitest
dependencies:
  - react
  - vite

Mismo documento, mismos datos una vez analizados. YAML elimina las llaves, los corchetes, las comillas en cadenas simples y la mayoria de las comas, y usa la sangria para mostrar el anidamiento en su lugar.

Donde realmente difieren

Comentarios. YAML los tiene, # asi. JSON no tiene ninguno, por disenio; un archivo de configuracion .json con una explicacion junto a un ajuste debe poner esa explicacion en otro lugar, usualmente un README, porque el analizador rechazara una linea con // o # de inmediato. Esto solo es razon por la que la configuracion mantenida a mano (tuberias de CI, Docker Compose, manifiestos de Kubernetes) usa YAML por defecto: la persona que lo edite un ano despues necesita saber por que un ajuste es como es, y un comentario es el unico lugar que sobrevive junto al valor.

Sensibilidad al espaciado. La sangria de YAML es estructural, igual que la de Python. Dos espacios en vez de cuatro, o una tabulacion donde se esperaba un espacio, cambia lo que el documento significa o lo rompe de inmediato, y el mensaje de error para una sangria mala es a menudo menos especifico que el “token inesperado en linea 4, columna 12” de un analizador JSON. Las llaves y corchetes de JSON son explicitos, por lo que la sangria es solo cosmética, lo que es parte de la razon por la que JSON es el formato que las maquinas generan y consumen: un script no se preocupa por la legibilidad y prefiere delimitadores sin ambiguedad.

Multiples maneras de escribir el mismo valor. YAML tiene un escalar simple, una cadena entre comillas simples, una cadena entre comillas dobles, escalares de bloque para texto multi-linea, anclajes y alias para repetir un valor por referencia, y algunas conversiones de tipo implicitas (yes y no se analizaban como booleanos en YAML 1.1, que es exactamente el tipo de sorpresa que convirtio al “problema de Noruega”, un codigo de pais NO leyendose como falso booleano, en un error conocido de YAML). JSON tiene una forma de escribir una cadena, una forma de escribir un numero, y ninguna conversion implicita. Menos formas de escribir lo mismo son menos formas de escribirlo mal, que es el verdadero argumento para JSON en una carga entre maquinas.

Tamanio aparte de la verbosidad y los comentarios. Una vez que se elimina el espaciado, JSON y YAML se comprimen a tamanios comparables para los mismos datos; la ventaja de YAML es la legibilidad cuando lo edita una persona, no el conteo de bytes en bruto.

Cuando usar cada uno

• JSON para todo lo que un programa genera y otro programa consume sin que una persona lo lea en el medio: cargas de API, intercambio de datos, cualquier cosa serializada y deserializada en el mismo ciclo de peticion-respuesta.
• YAML para todo lo que una persona edita regularmente a mano y necesita comentarios o cadenas multi-linea para mantenerse: configuracion de CI, manifiestos de Kubernetes, archivos de configuracion de aplicaciones que incluyen documentacion en linea.

Buenas herramientas aceptan ambos y convierten internamente, lo que normalmente es mas util que elegir un lado permanente: escriba la configuracion en el formato que prefieran las personas que la mantienen, y convierta a JSON en el punto donde algo mas necesite consumirla programaticamente.

Convirtiendo entre ellos

El Convertidor JSON a YAML funciona en ambas direcciones: escribe anclajes, alias y flujos multi-documento correctamente en vez de aplanar todo a escalares simples, y al leer YAML de vuelta pone entre comillas cualquier cosa que no regresaria como el tipo con el que empezo (una cadena de version como "1.0" sigue siendo cadena, no el numero 1). Nada de lo que convierta se sube; la conversion se ejecuta en su navegador igual que cada herramienta de este sitio.