YAML a JSON: convertir configuraciones sin perder la cabeza

Lo que realmente hace una conversión de YAML a JSON

YAML y JSON describen las mismas formas (mapas, listas, cadenas, números, booleanos y nulos), por lo que la conversión es principalmente una cuestión de volver a serializar una sintaxis como la otra. Lo que cambia es la superficie: la sangría se convierte en llaves, los comentarios desaparecen, los anclajes se convierten en copias y las cadenas de varias líneas colapsan en escapes `\n`. Cada una de esas transformaciones tiene pérdidas de una manera importante, por lo que vale la pena realizar el paso de conversión deliberadamente en lugar de tratarlo como una ocurrencia tardía de formato.

La razón práctica para convertir es que JSON es lo que quiere la siguiente herramienta. Kubernetes acepta YAML, pero `kubectl`, jq pipelines, API llamadas y JavaScript hablan JSON más cómodamente. Convertir una vez, correctamente, es mejor que editar manualmente dos formatos en paralelo.

Multidocumento YAML: el problema silencioso del primer documento

Un archivo YAML puede contener varios documentos separados por `---`. La mayoría de los convertidores devuelven silenciosamente el primero y descartan el resto, por lo que un paquete de manifiesto con un Deployment, un Service y un ConfigMap se convierte en un solo objeto sin previo aviso. Una conversión correcta emite una serie de documentos o le pregunta explícitamente cuál desea. Si un convertidor no ofrece ese control, está perdiendo datos.

Los errores deben apuntar a una línea y columna.

La tolerancia de YAML a los espacios en blanco es exactamente la razón por la que los pequeños errores son difíciles de encontrar. Las tabulaciones son ilegales para la sangría, la falta de dos puntos convierte una asignación en una cadena y algunos analizadores aceptan claves duplicadas y otros las rechazan. Cuando falla una conversión, el único mensaje útil nombra la línea y la columna y muestra el extracto ofensivo:

                spec:
  containers:
	- name: web      # tab used for indentation
error: line 3, column 0 — tabs cannot be used for indentation
              

Las claves duplicadas son el caso peligroso: YAML los analizadores comúnmente mantienen el último valor y no dicen nada. Si `replicas: 3` aparece dos veces, el JSON que obtiene parece perfectamente válido y es el número incorrecto.

Citando reglas que sobreviven al viaje.

JSON es más estricto con las cadenas que YAML, por lo que las conversiones agregan comillas alrededor de valores que estaban vacíos. Eso es normal, pero dos peculiaridades de YAML causan errores reales: `yes`, `no`, `on` y `off` son booleanos en YAML 1.1, pero las cadenas en la semántica de JSON y los valores de cero a la izquierda, como códigos postales y números de teléfono, pierden su cero cuando se tratan como números. Si un campo debe permanecer como una cadena durante la conversión, cítelo en la fuente.

Ejecútelo localmente, especialmente para configuraciones de clúster.

Los manifiestos Kubernetes llevan habitualmente credenciales en objetos `Secret`, cadenas de conexión en ConfigMaps y tokens en archivos CI. Pegarlos en un servicio web los transfiere a un servidor que no controla. Un convertidor basado en navegador analiza y serializa en la misma pestaña que estás leyendo, por lo que no se transmite nada, y una página que sigue funcionando con la red cortada es una prueba de ello más que una promesa.

Un flujo de trabajo sensato

1. Valide el YAML primero y corrija cualquier línea, columna y extracto informado.
2. Elija cómo se deben manejar los archivos de varios documentos: una matriz o un documento específico.
3. Convierta con una sangría que coincida con el estilo de su código base (2 o 4 espacios) y ordene las claves si difiere en la salida.
4. Mantenga YAML como fuente de verdad en git y trate el JSON como un artefacto generado; los comentarios viven sólo en el YAML.