JSON frente a YAML: diferencias, cuándo usar cada uno y cómo convertir

JSON y YAML son dos formas de escribir el mismo tipo de datos: nombres con valores, listas y grupos anidados. JSON es lo que intercambian las API y las aplicaciones web. YAML es lo que la gente edita a mano en archivos de configuración: Docker Compose, Kubernetes, GitHub Actions, especificaciones OpenAPI y muchos más. Conocer los dos, y saber pasar de uno a otro, ahorra muchas pruebas y errores.

Los mismos datos en los dos formatos

Este es un pequeño archivo de configuración en JSON:

{
  "name": "devitools",
  "version": "1.10",
  "enabled": true,
  "port": 8080,
  "country": "NO",
  "zip": "007",
  "tags": ["web", "tools"],
  "database": { "host": "localhost", "user": "admin" },
  "note": ""
}

Y los mismos datos en YAML, convertidos con el conversor gratuito JSON a YAML:

name: devitools
version: "1.10"
enabled: true
port: 8080
country: "NO"
zip: "007"
tags:
  - web
  - tools
database:
  host: localhost
  user: admin
note: ""

YAML prescinde de las llaves, de casi todas las comillas y de las comas, y usa la sangría para indicar qué va con qué.

Las diferencias principales

• Estructura: JSON usa llaves, corchetes y comas; YAML usa sangría y guiones. En YAML la sangría importa, y no se permiten tabuladores para ella, solo espacios.
• Comentarios: YAML admite comentarios con #; JSON no tiene comentarios. Solo por eso la mayoría de archivos de configuración son YAML.
• Legibilidad: YAML es más fácil de leer y editar para las personas; JSON es más fácil de generar y comprobar para los programas, y más difícil de estropear sin darse cuenta.
• Rigor: JSON tiene una sola forma de escribir cada cosa. YAML tiene muchas (varios estilos de texto, anclas, texto de varias líneas), lo que da flexibilidad pero también sorpresas.
• Compatibilidad: YAML 1.2 se diseñó para que un JSON válido sea también YAML válido, así que casi todas las herramientas de YAML leen archivos JSON directamente.

Cuándo usar cada uno

• Usa JSON para datos que se intercambian los programas: API, aplicaciones web, datos guardados, todo lo que se genera automáticamente.
• Usa YAML para archivos que escriben y mantienen personas: configuración, despliegue e integración continua, metadatos de documentación, sobre todo cuando los comentarios ayudan.
• Sigue a la herramienta: si un programa espera un formato, usa ese. Los ejemplos de Kubernetes y GitHub Actions son YAML; el package.json de npm es JSON.

Las trampas de YAML que rompen configuraciones

YAML adivina el tipo de los valores sin comillas, y los lectores de YAML 1.1, todavía frecuentes, adivinan sin miramientos:

country: NO      # read as false by many YAML readers
version: 1.10    # read as the number 1.1
zip: 007         # may lose its zeros

Se conoce como el “problema de Noruega”, porque el código de país de Noruega se convierte en false. Palabras como yes, no, on y off, los números de versión y los valores con ceros a la izquierda están en riesgo. La solución es sencilla: ponerlos entre comillas. El conversor de JSON a YAML lo hace solo. En el ejemplo de arriba, "NO", "1.10", "007" y la note vacía quedan entre comillas, mientras que los true/false reales y los números como 8080 se escriben tal cual.

Cómo convertir JSON a YAML, paso a paso

1. Abre JSON a YAML y pega tu JSON en Entrada JSON, haz clic en Abrir archivo o suelta un archivo .json en el recuadro. Ejemplo carga uno de muestra.
2. Elige la Sangría: 2 espacios (lo más habitual, como en los ejemplos de Kubernetes y GitHub Actions) o 4 espacios.
3. Haz clic en Convertir a YAML y luego en Copiar o Descargar.

Si el JSON tiene un error, el conversor muestra la línea y la columna exactas. Consulta cómo formatear y validar JSON para ver los fallos típicos. Después de convertir, puedes añadir comentarios con # al YAML para explicar tus ajustes.

Más herramientas JSON

• Formateador de JSON: haz el JSON legible y encuentra errores.
• JSON a CSV y JSON a XML: otros formatos para hojas de cálculo y sistemas antiguos. Lee también cómo convertir JSON a CSV.

¿Se sube mi JSON?

No. La conversión se hace en tu navegador, así que tus datos nunca salen de tu dispositivo. Nuestro servidor solo registra que hubo una conversión, para el límite diario.

Preguntas frecuentes

¿YAML es un superconjunto de JSON?

Casi. YAML 1.2 se diseñó para que los documentos JSON sean YAML válido, y en la práctica las herramientas de YAML leen archivos JSON normales sin cambios.

¿Puedo convertir YAML de vuelta a JSON aquí?

Todavía no. Esta herramienta solo convierte de JSON a YAML.

¿Por qué algunos valores van entre comillas en el YAML?

Porque sin comillas YAML podría leerlos como otra cosa: NO como false, 1.10 como 1.1, 007 como 7. Las comillas los mantienen exactamente como estaban en el JSON.