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

YAML vs JSON, en resumen: ambos son formatos de texto para los mismos datos (objetos, listas, cadenas, números, booleanos y null). JSON es estricto, usa llaves y comillas, y domina en las API web. YAML usa sangría, admite comentarios, anclas y varios documentos por archivo, y es popular para configuración. YAML 1.2 es casi un superconjunto de JSON.

Pruébalo gratis: Convertidor de YAML a JSON Gratis y sin necesidad de cuenta.

JSON (JavaScript Object Notation, definido en el RFC 8259) se diseñó para que los programas intercambien datos. Entonces, ¿qué es YAML? Su nombre significa "YAML Ain't Markup Language" y se diseñó para que las personas lean y editen datos a mano. Esta guía muestra los mismos datos en ambos formatos, los compara y repasa las trampas de cada uno. Para ver cómo queda cualquier archivo en el otro formato, pégalo en el Convertidor de YAML a JSON gratuito o en el Convertidor de JSON a YAML.

Los mismos datos en JSON y en YAML

Esta es una pequeña configuración de aplicación en JSON:

{
  "name": "web-app",
  "version": "2.4.1",
  "replicas": 3,
  "debug": false,
  "database": {
    "host": "db.example.com",
    "port": 5432
  },
  "features": ["login", "search"],
  "maintainer": null
}

Y los mismos datos en YAML, con un comentario añadido, algo que JSON no puede contener:

# Settings for the web app
name: web-app
version: 2.4.1
replicas: 3
debug: false
database:
  host: db.example.com
  port: 5432
features:
  - login
  - search
maintainer: null

Ambos se analizan exactamente como el mismo objeto. JSON marca la estructura con {}, [], comas y comillas; YAML la marca con sangría, pares key: value y - para los elementos de una lista. La mayoría de las cadenas en YAML no necesitan comillas, por eso se lee más como un archivo de ajustes que como código.

YAML vs JSON: diferencias clave

Algunos formatos aceptan ambos: las descripciones OpenAPI pueden escribirse en cualquiera de los dos, y kubectl apply lee manifiestos JSON además de YAML. En general, JSON gana cuando son los programas quienes escriben y leen los datos; YAML gana cuando las personas los mantienen a mano y necesitan comentarios.

¿YAML es un superconjunto de JSON?

Casi. La especificación YAML 1.2 (2009) se propuso convertir YAML en un superconjunto estricto de JSON y, en la práctica, un parser de YAML 1.2 lee casi cualquier documento JSON y devuelve los mismos datos. Hay dos salvedades:

• Claves duplicadas. El RFC 8259 solo dice que las claves de un objeto deberían ser únicas, pero YAML lo exige, así que un parser YAML estricto rechaza {"a": 1, "a": 2}.
• Parsers de YAML 1.1. Muchas bibliotecas muy utilizadas siguen aplicando las reglas antiguas de YAML 1.1. PyYAML, por ejemplo, solo reconoce como float los números que contienen un punto, así que el número JSON 1e3 se devuelve como la cadena "1e3".

Lo contrario no se cumple: la mayor parte del YAML no es JSON válido.

Trampas de YAML que conviene conocer

El problema de Noruega (Norway problem): NO se convierte en false

En YAML 1.1, las palabras sin comillas yes, no, on y off (en minúsculas, con mayúscula inicial o en mayúsculas) son booleanos, junto con true y false. Así, esta lista de códigos de país:

countries:
  - GB
  - NO
  - SE

se carga como ["GB", false, "SE"] en un parser de YAML 1.1 como PyYAML. La misma regla convierte la clave on: de un flujo de trabajo de GitHub Actions en el booleano True cuando cargas el archivo con PyYAML. El esquema core de YAML 1.2 lo corrigió: solo true y false (también escritos True o TRUE) son booleanos, así que un parser 1.2 mantiene NO como cadena. Como rara vez controlas qué parser leerá tu archivo, lo más seguro es poner esos valores entre comillas: - "NO".

Números que no deberían ser números

• Ceros a la izquierda. YAML 1.1 lee 0755 como un número octal, 493. YAML 1.2 lo lee como el decimal 755 y escribe los octales como 0o755. Un código postal como 01234 se convierte en 668 o en 1234, según el parser. Ponlo entre comillas.
• Números de versión. python-version: 3.10 es el float 3.1, no "3.10". Escribe "3.10".
• Ceros finales. 1.0 es un float, así que se convierte en 1 al pasarlo a JSON en JavaScript.

Tabulaciones y espacios significativos

La especificación de YAML prohíbe los caracteres de tabulación para la sangría, así que una tabulación al principio de una línea es un error de sintaxis, no una cuestión de estilo. La sangría además tiene significado: mover una clave dos espacios a la izquierda la traslada a otro objeto padre, y el archivo puede seguir siendo perfectamente válido aunque signifique otra cosa.

Cadenas multilínea: | y >

Un bloque literal (|) conserva los saltos de línea; un bloque plegado (>) une las líneas con espacios:

literal: |
  Line one
  Line two
folded: >
  This long sentence is
  folded into one line.

literal se convierte en "Line one\nLine two\n" y folded en "This long sentence is folded into one line.\n". Ambos conservan un salto de línea final; escribe |- o >- para eliminarlo.

Anclas, alias y claves de fusión

YAML permite definir un bloque una vez y reutilizarlo:

defaults: &defaults
  adapter: postgres
  port: 5432
production:
  <<: *defaults
  host: db.example.com

&defaults da nombre al bloque, *defaults hace referencia a él y << fusiona sus claves, de modo que production termina con adapter, port y host. JSON no tiene nada equivalente: al convertir a JSON, los valores se copian en cada lugar donde se usan. Las claves de fusión provienen de YAML 1.1 y no forman parte del esquema core de 1.2, pero la mayoría de los parsers más utilizados siguen admitiéndolas.

Trampas de JSON que conviene conocer

JSON es estricto, y tres reglas provocan la mayoría de los errores:

• Sin comentarios. // y /* */ son errores de sintaxis.
• Sin comas finales. ["a", "b",] no es válido.
• Solo comillas dobles. Las claves deben ir entre comillas y no se permiten comillas simples.

Por eso este archivo falla con JSON.parse:

{
  // port for local development
  'port': 8080,
  "tags": ["api", "v2",],
}

Para archivos escritos a mano existen variantes más flexibles: JSONC ("JSON with comments") se usa en los ajustes de VS Code y en tsconfig.json, y JSON5 permite además comillas simples, claves sin comillas y comas finales. Ningún parser JSON estándar acepta ninguno de los dos. El Formateador JSON acepta entradas en JSON5, las marca como «JSON5 válido — convertido a JSON estricto» y te devuelve JSON estándar.

.yaml vs .yml

YAML vs YML no es una cuestión de formato: ambas extensiones corresponden al mismo formato y a los parsers les da igual cuál uses. El RFC 9512, que registró el tipo de medio application/yaml en 2024, considera .yaml la extensión preferida y señala que .yml se sigue usando. Las FAQ del proyecto YAML también recomendaban .yaml, y Docker Compose busca compose.yaml antes que compose.yml. GitHub Actions acepta ambas en .github/workflows. Elige una por proyecto y no mantengas config.yaml y config.yml uno al lado del otro.

Seguridad: carga YAML no confiable de forma segura

Los cargadores YAML completos pueden construir objetos específicos del lenguaje a partir de etiquetas. En Python, yaml.load(data, Loader=yaml.UnsafeLoader) puede crear objetos Python arbitrarios y, con un archivo manipulado, ejecutar código. Usa siempre yaml.safe_load() con archivos que no hayas escrito tú; solo construye dicts, listas, cadenas, números, booleanos y null simples. Desde PyYAML 6.0, yaml.load() se niega a ejecutarse sin un Loader explícito. Ten cuidado también con los alias anidados en profundidad (archivos "billion laughs") que se expanden en estructuras enormes. JSON no tiene etiquetas ni alias, así que JSON.parse y json.loads de Python solo devuelven datos simples.

Convertir entre YAML y JSON

Ambos convertidores se ejecutan íntegramente en tu navegador y usan la biblioteca de código abierto yaml para JavaScript.

El Convertidor de YAML a JSON analiza YAML 1.2, expande anclas y alias, aplica las claves de fusión << y convierte un archivo con varios documentos --- en un array JSON. Puedes elegir 2, 3 (el valor predeterminado) o 4 espacios, tabulaciones o salida minificada, ordenar las claves alfabéticamente y descargar el resultado como converted.json. Los errores de sintaxis, como una tabulación usada para la sangría, se muestran con su línea y columna. Los comentarios se pierden, porque JSON no puede almacenarlos.

El Convertidor de JSON a YAML lee JSON estándar y JSON5, así que acepta comentarios y comas finales en la entrada, aunque no los traslada a la salida. Genera YAML con sangría de dos espacios y no tiene opciones. La salida sigue YAML 1.2: las cadenas como "0755" y "true" van entre comillas, pero NO, yes u on quedan sin comillas porque en 1.2 son cadenas normales. Si una herramienta de YAML 1.1 como PyYAML va a leer el archivo, añade tú mismo las comillas a esos valores.

En la línea de comandos, yq de Mike Farah convierte en ambas direcciones, y jq valida y formatea JSON:

yq -o json config.yaml
yq -P -oy config.json
jq . config.json

Cuándo usar YAML y cuándo usar JSON

La elección JSON vs YAML suele depender de quién escribe el archivo:

• Usa JSON para datos que intercambian los programas: peticiones y respuestas de API, mensajes entre servicios, logs, almacenamiento del navegador y todo lo que genere el código. Es inequívoco y está soportado en todas partes.
• Usa YAML para la configuración que editan y revisan las personas: manifiestos de despliegue, pipelines de CI, archivos de Compose. Los comentarios y una sintaxis más ligera hacen que los diffs sean más fáciles de leer.
• Sigue a la herramienta. Si una plataforma espera YAML (GitHub Actions) o JSON (package.json), usa ese formato en lugar de convertir.

Si eliges YAML, mantenlo aburrido: sangría de dos espacios, comillas en todo lo que pueda leerse como booleano o número y un linter como yamllint en CI.

Preguntas frecuentes

¿Es YAML mejor que JSON?

Ninguno es mejor en general. JSON es más simple y más estricto, lo que lo convierte en la opción más segura para datos que se intercambian entre programas. YAML es más fácil de leer y editar para las personas y admite comentarios, por eso lo usan tantos archivos de configuración.

¿Puedo usar JSON dentro de un archivo YAML?

Sí. El estilo flow de YAML usa los mismos corchetes y llaves que JSON, así que ports: [80, 443] o db: {"host": "localhost"} funcionan dentro de un archivo YAML, y un parser de YAML 1.2 acepta casi cualquier documento JSON completo. Las claves duplicadas son la principal excepción.

¿JSON puede tener comentarios?

No en JSON estándar: el RFC 8259 no tiene sintaxis de comentarios y JSON.parse falla con // o /* */. Algunas herramientas aceptan JSONC o JSON5, que permiten comentarios, pero debes eliminarlos antes de pasar el archivo a un parser estricto.

¿Cuál es la diferencia entre YAML y YML?

En el contenido no hay ninguna: .yaml y .yml son dos extensiones de archivo para el mismo formato. El RFC 9512 indica .yaml como la preferida, pero a los parsers de YAML no les importa la extensión.

¿Por qué YAML convierte NO u on en false o true?

Porque YAML 1.1 trata yes, no, on y off como booleanos. YAML 1.2 solo trata true y false como booleanos, pero muchos parsers, incluido PyYAML, siguen usando las reglas de 1.1. Pon esos valores entre comillas, por ejemplo country: "NO", y cualquier parser los leerá como cadenas.

Pruébalo gratis: Convertidor de YAML a JSON Gratis y sin necesidad de cuenta.