Convertir YAML a JSON

La sangría es la sintaxis

En JSON las llaves te dicen dónde termina una estructura. En YAML lo hace el margen izquierdo, y esa sola decisión causa la mayoría de los errores con los que la gente se topa. Tres reglas que conviene conocer antes de depurar nada:

• Las tabulaciones son ilegales como sangría. No desaconsejadas: prohibidas por la especificación. Un editor que inserta una tabulación produce un archivo que ningún parser conforme va a leer, y el mensaje de error rara vez lo dice. Este sí lo dice.
• Una secuencia bajo una clave puede estar a la misma sangría que la clave. Las dos formas significan lo mismo, algo que sorprende a quien viene de otros formatos: una línea steps: seguida de guiones con dos espacios de sangría, y la misma línea seguida de guiones en el mismo margen que steps.
• Cuánta sangría usas es cosa tuya, pero tiene que ser consistente dentro de un bloque. Dos espacios es la convención. Mezclar dos y cuatro dentro de un mismo mapeo es donde los archivos cambian de forma en silencio.

YAML 1.2 es un superconjunto estricto de JSON, así que cualquier documento JSON válido también es YAML válido. Eso resulta útil más de una vez: cuando necesitas pegar un fragmento en un archivo de configuración y no quieres pelearte con la sangría.

Escalares que no son lo que parecen

Los valores sin comillas se resuelven por patrón, y esos patrones tienen víctimas famosas. La más conocida es el problema de Noruega: en YAML 1.1, no es un booleano, así que una lista de países escrita como - no te da false donde esperabas "NO". Lo mismo pasa con y, yes, on y off.

También pasa con las claves, que es la versión con la que la mayoría se topa primero: con las reglas de 1.1, la línea on: del comienzo de un workflow de GitHub Actions es el booleano verdadero, no la palabra "on". Activa la casilla de arriba y mira cómo le pasa al ejemplo.

YAML 1.2 eliminó todo eso. Solo true y false son booleanos, que es lo predeterminado aquí. Muchos parsers reales — el cargador por defecto de PyYAML entre ellos — siguen comportándose como los de 1.1, así que la casilla te deja ver el archivo como lo van a ver ellos. Si un valor se puede confundir con otra cosa, ponlo entre comillas. Las comillas son la solución a todas las ambigüedades de esta sección.

Los números tienen sus propias trampas. version: 1.0 es el flotante 1, así que se vuelve a imprimir como 1 y ya no coincide con la cadena "1.0". 1.2.3 tiene dos puntos y se queda como cadena. Los ceros a la izquierda se conservan en YAML, pero el valor sigue siendo un número, y en YAML 1.1 un valor como 08:30 se leía como aritmética en base 60. Un valor vacío, ~ y null significan todos null. Nada de esto se puede adivinar, y por eso los archivos de configuración que importan tienden a poner comillas en todo.

Escalares de bloque

Las dos piezas más útiles de YAML para las que JSON no tiene respuesta. | conserva los saltos de línea tal como se escribieron, que es lo que quieres para un script de shell o un certificado incrustado. > pliega las líneas en un párrafo, uniéndolas con espacios, que es lo que quieres para una descripción larga. Los dos quitan la sangría común, así que el texto no se lleva consigo la sangría del archivo hasta dentro del valor.

El carácter final controla qué pasa con el último salto de línea. | a secas conserva exactamente uno, |- no conserva ninguno y |+ conserva todas las líneas en blanco del final. Esa distinción importa más de lo que suena: una clave con un salto de línea final accidental es una causa frecuente de que una firma o un token no se validen.

Lo que este conversor rechaza

Cubre mapeos de bloque, secuencias de bloque, colecciones de flujo, comentarios, comillas, escalares de bloque, escalares planos plegados y los tipos escalares básicos. Se detiene en las características que no se pueden representar con honestidad:

• Anclas y alias (&base y *base) y claves de fusión (<<). Duplican o comparten estructura, y expandirlas cambia el significado del documento de maneras que deberías decidir tú, no una página web.
• Etiquetas como !!str o etiquetas propias de una aplicación. JSON no tiene anotaciones de tipo donde ponerlas.
• Varios documentos. Solo se convierte el primero, y se te dice cuántos había.
• Claves complejas (la sintaxis ? key) y claves que no son cadenas. Los nombres de los objetos JSON son cadenas, así que 1: one se vuelve "1": "one".

Cada una de esas cosas lanza un error con un número de línea en lugar de producir un resultado de apariencia plausible. Ese es el compromiso deliberado: un conversor que descarta un ancla en silencio es peor que uno que se detiene.

Dos cosas más para tener en cuenta. Los números pasan por JavaScript, así que un entero por encima de 9.007.199.254.740.991 pierde precisión en el camino — pon entre comillas los identificadores largos. Y .inf y .nan se dejan como las cadenas que se escribieron, porque JSON no tiene forma de escribir ninguno de los dos.

Una cosa que obtienes gratis: este parser solo produce datos simples. Algunas bibliotecas de YAML en otros lenguajes pueden construir objetos arbitrarios a partir de una etiqueta del archivo, y por eso cargar YAML no confiable con la función equivocada ha sido una fuente real de ejecución remota de código. Aquí nada puede hacer más que construir cadenas, números, arrays y objetos.

Última actualización 19 de septiembre de 2026