Un objeto como {"servicio":"api","puertos":[8080,8443],"activo":true} se convierte en cinco líneas: «servicio: api», luego «puertos:» con dos guiones sangrados debajo, y «activo: true». Desaparecen las llaves, los corchetes, las comas y casi todas las comillas; lo que queda sujetando la estructura es la sangría.
El camino de vuelta apenas necesita una herramienta: desde la versión 1.2, YAML es un superconjunto de JSON, así que cualquier JSON válido ya es YAML válido y basta con pegarlo en el analizador. La dirección que sí exige decisiones es esta —cuándo poner comillas a una cadena, cómo escribir un valor con saltos de línea, qué hacer con un objeto vacío— y abajo están explicadas una por una. Si el JSON de entrada no es válido, el estado dice en qué posición se detuvo el analizador y qué hay en ese punto del texto.
El «problema de Noruega» y otras comillas
El caso famoso: en una lista de países, el código de país de Noruega es NO. Sin comillas, un analizador que siga YAML 1.1 lo lee como el booleano falso y Noruega desaparece del mapa. Lo mismo pasa con yes, on, off y con una Y o una N sueltas. YAML 1.2 redujo los booleanos a true y false, pero bibliotecas muy extendidas siguen aplicando las reglas de 1.1, de modo que estas cadenas salen entrecomilladas.
La otra trampa son los valores que parecen números sin serlo. Una versión escrita 1.10 sin comillas es el número 1.1 y el cero se pierde; 1.2.3 sobrevive porque no es un número, pero 007 se queda en 7 y +34 en 34. En YAML 1.1 una hora como 22:30 llega a leerse en base sesenta, y una fecha como 2026-08-25 deja de ser texto para convertirse en una marca de tiempo. También hay que entrecomillar la cadena vacía y las palabras null, Null y ~ cuando se quieren como texto. Ante la duda, aquí se ponen comillas: sobran a la vista, pero no cambian el dato.
Valores multilínea, vacíos y tabuladores
Un valor con saltos de línea admite tres formas: entre comillas dobles con \n, con la barra vertical, que conserva los saltos tal cual, o con el signo mayor que, que los pliega en espacios. Aquí se usa el bloque literal, sangrado un nivel más que su clave —dos o cuatro espacios, según lo que hayas elegido—, con |- cuando el valor no termina en salto de línea y con | cuando termina en uno, de manera que el texto vuelve idéntico si se convierte de nuevo a JSON. Lo que un bloque no puede llevar —un espacio al final de una línea, un retorno de carro, dos saltos finales seguidos, una primera línea ya sangrada— vuelve a las comillas dobles con \n: se lee peor, pero es exacto.
El objeto vacío y la lista vacía no tienen forma de bloque, así que se escriben {} y [] en estilo de flujo. Y la sangría se hace con espacios, nunca con tabuladores: un tabulador al principio de una línea es un error de sintaxis, no una cuestión de gusto. Por eso la única elección disponible es entre dos y cuatro espacios.
Lo que se conserva y lo que se pierde
El orden de las claves se respeta tal como venía, salvo en un caso: el de las claves numéricas. El motor de JavaScript las coloca antes que las demás y en orden ascendente, de modo que un mapa de códigos HTTP escrito 500, 200, 10 sale como 10, 200, 500 y luego el resto, y encima entrecomilladas, porque sin comillas volverían a leerse como números. Con claves de texto no se reordena nada. El contador suma un nodo por cada objeto, cada lista y cada valor escalar, el documento entero incluido: el ejemplo de arriba da seis, no siete, y sirve para comprobar de un vistazo que no se ha quedado nada por el camino.
Los comentarios son la pérdida que conviene tener presente, sobre todo en el sentido contrario: JSON no los admite, así que un YAML comentado que pase por JSON y vuelva llega sin una sola línea de comentario. La otra pérdida ocurre antes de la conversión: si el JSON repite una clave, el analizador se queda solo con la última, y {"a":1,"a":2} sale como «a: 2» sin decir nada. Esta herramienta tampoco genera anclas ni alias, no reutiliza estructuras repetidas, no produce varios documentos separados por --- y no valida contra ningún esquema. Comprueba que el JSON es válido y escribe el YAML equivalente; hasta ahí llega.