JSON y YAML representan el mismo modelo de datos (mapas, listas, cadenas, números, booleanos y null) con sintaxis muy distinta, y convertir entre ambos manualmente es una fuente frecuente de errores de tipo: un booleano escrito sin comillas en YAML puede colapsar a `false` por el problema de Noruega, y un número con ceros a la izquierda cambia de significado según el parser. Este conversor JSON/YAML traduce en ambas direcciones conservando los tipos nativos siempre que sea posible, y es el complemento natural del validador JSON y del validador YAML de este sitio: conviene validar el documento de origen antes de convertir, y el resultado después, para descartar que la conversión introdujo una ambigüedad nueva.
Qué se conserva y qué se pierde al convertir de YAML a JSON
YAML admite comentarios (#), anclas y alias para reutilizar bloques, y varios documentos en un mismo fichero separados por ---. Ninguna de esas tres características tiene equivalente en JSON: los comentarios se descartan sin aviso, las anclas y alias se expanden a su valor final (perdiendo la referencia compartida), y un fichero con varios documentos YAML debe convertirse en un array JSON o en ficheros separados, porque JSON no admite varios documentos raíz en un mismo archivo. Es importante revisar el fichero de origen antes de convertir para saber si alguna de estas características se está usando y decidir cómo tratarla.
Qué se conserva y qué se pierde al convertir de JSON a YAML
La conversión inversa es más directa porque JSON es un subconjunto sintáctico válido de YAML: cualquier documento JSON ya es, técnicamente, un YAML válido en su forma de flujo (flow style). El riesgo aparece al reformatear a bloque (block style) para mejorar la legibilidad: cadenas que coinciden con literales especiales de YAML (yes, no, null, NO) deben quedar entrecomilladas explícitamente en la salida, o al recargar ese YAML se obtendrá un tipo distinto al original. Un buen conversor añade esas comillas de forma automática cuando detecta ambigüedad, en vez de dejarlo a interpretación del parser de destino.
Booleanos: dos alfabetos distintos
JSON reconoce exactamente dos literales booleanos: true y false, en minúsculas y sin comillas. YAML 1.1 reconoce un conjunto mucho más amplio: true/false, yes/no, on/off, y/n, en cualquier combinación de mayúsculas. Al convertir JSON a YAML no hay ambigüedad, porque solo existen true/false. Al convertir YAML a JSON sí la hay: un YAML con activo: yes debe interpretarse primero según las reglas de YAML (como true) antes de escribirlo en JSON; si el conversor trata yes como cadena literal por error, el JSON resultante tendrá "activo": "yes" en vez de `"activo": true", cambiando el tipo del campo para cualquier aplicación que lo consuma.
Números: notación científica, octales y ceros a la izquierda
YAML 1.1 interpreta 010 como un número en base octal (equivalente a 8 en decimal) en algunos parsers, mientras que JSON no admite ceros a la izquierda en absoluto y los rechaza como error de sintaxis o los trata como cadena si vienen entrecomillados. Al convertir un YAML con códigos postales o de producto que empiezan por cero (codigo: 007), la única conversión segura a JSON es como cadena ("codigo": "007"), nunca como número, porque JSON perdería el cero inicial al normalizarlo. Es responsabilidad de quien diseña el esquema de datos declarar estos campos como cadena desde el origen, entrecomillándolos en el propio YAML.
Fechas: YAML las tipa, JSON siempre las trata como texto
YAML define un tipo nativo para fechas en formato ISO 8601 sin comillas: fecha: 2024-03-15 se carga como un objeto date (o datetime) en Python o en otros lenguajes con soporte YAML completo, no como una cadena. JSON no tiene tipo fecha: cualquier fecha debe representarse como cadena ("fecha": "2024-03-15") y la aplicación que la consuma es responsable de volver a parsearla. Al convertir de YAML a JSON, un conversor correcto debe serializar la fecha como cadena en formato ISO 8601, y al convertir de vuelta de JSON a YAML, esa cadena seguirá siendo texto salvo que se fuerce explícitamente el tipo fecha en el YAML de salida.
Claves no textuales y estructuras que YAML permite y JSON no
YAML permite teóricamente claves que no son cadenas (un número o incluso un mapa como clave), aunque es una práctica extremadamente rara en configuración real. JSON exige que toda clave de un objeto sea una cadena entre comillas dobles, sin excepción. Un conversor debe forzar la conversión a cadena de cualquier clave numérica del YAML de origen; si no lo hace, el JSON resultante puede ser inválido o el parser de destino puede rechazarlo con un error de tipo de clave.
Flujo de trabajo recomendado: validar, convertir, validar
El orden que minimiza sorpresas es: primero pasar el documento de origen por su validador correspondiente (el validador YAML o el validador JSON de este sitio) para descartar errores de sintaxis previos a la conversión; después convertir con esta herramienta; y finalmente validar la salida con el validador del formato de destino, revisando en particular los campos booleanos, numéricos y de fecha que son los tres puntos de fricción reales entre ambos formatos.
Salidas reales de ejemplo
nombre: Ana
activo: yes
codigo_postal: "08001"El campo activo usa "yes", literal booleano válido en YAML 1.1 pero inexistente en JSON.
{
"nombre": "Ana",
"activo": true,
"codigo_postal": "08001"
}"yes" se traduce a true (booleano real) y el código postal conserva el cero inicial por ir entrecomillado en origen.
{"pais": "Noruega", "region": "NO"}
# YAML de salida:
pais: Noruega
region: "NO"El conversor entrecomilla "NO" en la salida para que no se reinterprete como booleano al recargarlo.
$ yq '.activo | type' salida.yml
!!boolyq muestra el tipo real de cada campo, útil para verificar que un booleano no quedó como cadena.
Diferencias clave entre JSON y YAML al convertir
| Aspecto | JSON | YAML | Riesgo en la conversión |
|---|---|---|---|
| Booleanos | Solo true/false | true/false/yes/no/on/off | Interpretación incorrecta de "yes"/"no" como texto |
| Comentarios | No soporta | Soporta con # | Se pierden al convertir a JSON |
| Fechas | Sin tipo nativo (cadena) | Tipo nativo ISO 8601 | Cambio de tipo si no se serializa como cadena |
| Anclas y alias | No existen | Referencias reutilizables (&, *) | Se expanden y se pierde la referencia compartida |
| Ceros a la izquierda | No admitidos como número | Pueden leerse como octal en algunos parsers | Pérdida del cero si se trata como número |
Puntos de fricción habituales al pasar datos de un formato a otro.
Casos de uso comunes
- Migrar un fichero de configuración de Kubernetes (YAML) a JSON para consumirlo desde una API que solo acepta ese formato.
- Convertir la respuesta JSON de una API a YAML para documentarla de forma más legible en un README.
- Adaptar un `docker-compose.yml` a JSON para procesarlo con herramientas de línea de comandos orientadas a JSON como `jq`.
- Revisar si una conversión automática entre formatos cambió el tipo de algún campo booleano o numérico.
- Preparar datos de prueba en JSON y exportarlos a YAML para un fichero de fixtures legible por humanos.
Buenas prácticas
- Valida siempre el documento de origen antes de convertir, con el validador JSON o el validador YAML según corresponda.
- Entrecomilla en el YAML de origen cualquier código, versión o campo que pueda confundirse con un booleano o un número.
- Revisa el JSON resultante buscando específicamente campos booleanos y numéricos, que son el punto de fricción real entre formatos.
- No confíes en anclas y alias de YAML si el destino final es JSON: expándelos y documenta la duplicación de forma explícita.
- Serializa siempre las fechas como cadenas ISO 8601 al convertir a JSON, nunca como objetos de fecha nativos.
- Vuelve a validar la salida con el validador del formato de destino antes de usarla en producción.