Los mismos datos en los dos formatos
Esta es una configuración pequeña en JSON: {"name": "shop", "port": 8080, "debug": false, "hosts": ["a.example.com", "b.example.com"]}. En YAML los mismos datos se escriben con sangría en lugar de llaves: name: shop en una línea, port: 8080 en la siguiente, debug: false, y hosts: seguido de dos líneas con sangría que empiezan por un guion.
Los dos se cargan exactamente como el mismo objeto en cualquier lenguaje de programación. La diferencia está en cómo se escriben y en qué más permite cada formato.
| JSON | YAML | |
|---|---|---|
| Estructura | Llaves y corchetes | Sangría, o llaves si lo prefieres |
| Texto | Siempre entre comillas dobles | Las comillas suelen ser opcionales |
| Comentarios | No se permiten | Líneas que empiezan por # |
| Texto de varias líneas | Solo con \n dentro de un texto | Bloques con | o > |
| Reutilizar partes | No es posible | Anclas (&nombre) y alias (*nombre) |
| Varios documentos en un archivo | No | Sí, separados por una línea de tres guiones |
| Uso típico | API, intercambio de datos, navegadores | Configuración: Docker Compose, Kubernetes, CI |
Pruébalo aquí: YAML a JSON
Abrir la herramienta completaPor qué YAML es cómodo de escribir
YAML necesita menos caracteres. No hay llaves de cierre que contar, ni comas que olvidar entre elementos, ni comillas alrededor de la mayoría del texto. Los comentarios permiten explicar por qué existe un ajuste, y por eso lo eligieron herramientas que la gente edita a diario, como Docker Compose, Kubernetes, GitHub Actions y Ansible.
Las anclas evitan repeticiones: defines un bloque una vez con &defaults y lo reutilizas con *defaults, o lo fusionas en otro bloque con <<: *defaults y cambias claves sueltas. El texto en bloque conserva los saltos de línea, lo que hace legibles los scripts y los mensajes largos dentro del archivo.
Trampas de YAML que cambian tus datos
La libertad de no poner comillas tiene un precio: YAML adivina el tipo de cada valor sin comillas, y no siempre acierta con lo que querías. La mayoría de estos problemas desaparecen cuando el texto va entre comillas.
- El problema de Noruega: en YAML 1.1, que muchas herramientas siguen usando, NO, no, yes, on y off son booleanos. Una lista de códigos de país con NO para Noruega se convierte en false.
- Números de versión: 1.10 es el número 1.1, y 3.0 puede quedar en 3. Escribe "1.10" para que siga siendo texto.
- Ceros iniciales: los códigos postales y de producto como 0123 pueden convertirse en números, y YAML 1.1 los lee como octales, así que 0123 pasa a ser 83.
- Horas: en YAML 1.1, 12:30 es un número en base 60, 750.
- Dos puntos y almohadillas: un valor que contiene ": " o " #" termina antes de tiempo o empieza un comentario. Pon ese texto entre comillas.
- Tabuladores: YAML no permite tabuladores para sangrar, y una clave con un espacio de más acaba en el bloque equivocado sin ningún error en algunos editores.
Por qué JSON es mejor para los programas
JSON tiene una sola forma de escribir cada cosa y no adivina nada: el texto siempre va entre comillas, así que "NO" sigue siendo texto y 1.10 es claramente un número. Los analizadores son pequeños, rápidos y existen en todos los lenguajes, y los navegadores leen JSON de forma nativa. Eso hace de JSON la opción más segura siempre que los datos los produce y los lee software, como las respuestas de API, los logs, las cachés y los archivos de datos.
La falta de comentarios es la queja más habitual. Algunas herramientas aceptan JSON con comentarios (a menudo llamado JSONC), pero los analizadores estándar lo rechazan, así que no es un buen formato para archivos que deben leer otros programas.
Convertir entre YAML y JSON con seguridad
YAML 1.2 se diseñó como un superconjunto de JSON, así que casi cualquier documento JSON también es YAML válido. La otra dirección necesita un analizador de verdad, porque hay que resolver las funciones de YAML: las anclas y las claves de fusión se expanden, el texto en bloque pasa a ser un texto con \n, y varios documentos se convierten en una lista. Los comentarios no se pueden trasladar, porque JSON no tiene sitio para ellos.
Al convertir JSON a YAML, hay que poner entre comillas todo valor que un lector de YAML podría malinterpretar. El convertidor de esta página revisa cada texto con las reglas de YAML 1.1 y de YAML 1.2 y solo lo pone entre comillas cuando hace falta, así yes, NO, 0123 y 1.10 vuelven sin cambios. Volver a convertir el resultado con Invertir es una forma rápida de demostrar que nada cambió.
¿Cuál deberías usar?
- Usa YAML para la configuración que las personas escriben y revisan a mano, sobre todo cuando los comentarios ayudan.
- Usa JSON para los datos que los programas intercambian, guardan o envían por la red.
- Usa JSON cuando el archivo lo genera el código, aunque después lo lea una persona.
- Si una herramienta acepta los dos, como muchas, mantén el formato que ya usa tu equipo: la coherencia importa más que las pequeñas diferencias.
- Si te quedas con YAML, pon entre comillas los textos que parecen números, fechas o yes/no, y revisa los archivos con un analizador antes de desplegarlos.