Cómo convertir YAML a JSON: Errores comunes que debes evitar
Por qué YAML y JSON no son tan intercambiables como parecen
YAML y JSON se parecen, y su relación es muy estrecha. De hecho, YAML 1.2 es un superconjunto de JSON, por lo que cualquier JSON válido también es un YAML válido. Suena genial, ¿verdad? Y lo es, hasta que conviertes un archivo YAML del mundo real y descubres tu primera corrupción silenciosa de datos. La cuestión es que los dos formatos tienen objetivos de diseño diferentes. JSON se creó para las máquinas: es estricto, inequívoco y no deja espacio para comentarios. YAML, en cambio, se creó para los humanos. Utiliza la sangría para la estructura, admite cadenas de texto multilínea, permite comentarios y cuenta con un sistema de inferencia de tipos que intenta adivinar tu intención. Este sistema de 'adivinación', que parece tan útil, es precisamente donde las conversiones empiezan a fallar. Un analizador de YAML podría leer la cadena 'yes' e interpretarla como el booleano `true`. Podría ver '1.0' y producir un número de punto flotante, no la cadena de texto que escribiste. No son errores; la especificación de YAML funciona tal como fue diseñada. El problema surge porque JSON no tiene esa ambigüedad. Una vez que tu valor YAML se convierte en un booleano en los datos procesados, la salida JSON escribirá `true`, y la cadena de texto original se perderá para siempre. Cuando estás convirtiendo archivos de configuración para un clúster de Kubernetes, una especificación de OpenAPI o un pipeline de CI/CD, estos cambios de tipo silenciosos pueden romper todo el proceso posterior sin un solo mensaje de error. Para convertir archivos de forma fiable, tienes que entender estas diferencias fundamentales.
La forma más rápida de convertir: Usando CocoConvert
Cuando solo necesitas convertir un archivo, la forma más rápida es usar una herramienta dedicada en lugar de improvisar un script. El [conversor de YAML a JSON](/convert/yaml-to-json) de CocoConvert se encarga de todo el análisis y la serialización, dándote una salida con el formato correcto y codificación UTF-8 al instante. El proceso es sencillísimo: pega tu YAML, sube un archivo .yaml o .yml y haz clic en Convertir. Tu JSON aparecerá en el panel de salida, listo para ser copiado o descargado. CocoConvert utiliza las reglas de análisis modernas de YAML 1.2, así que no te encontrarás con el viejo "Problema de Noruega" (Norway Problem), donde la cadena 'NO' se malinterpretaba como el booleano `false`. Si tu YAML de origen tiene un error de sangría, recibirás un error de análisis claro con el número de línea en lugar de una salida corrupta y silenciosa. También maneja correctamente los archivos YAML con múltiples documentos (aquellos con separadores `---`). Estos se convierten en un array de JSON, donde cada documento se convierte en un elemento del array. Este es el comportamiento estándar y esperado, pero es bueno recordarlo si ves un array inesperado en tu salida porque tu archivo comenzaba con `---`. Hay una limitación: la herramienta no es compatible con anclas y alias de YAML que hacen referencia a nodos en diferentes documentos dentro del mismo archivo. Para esos casos complejos que involucran anclas entre documentos, necesitarás resolverlas primero, ya sea a mano o con un script local, antes de subir el archivo para la conversión.
Coerción de tipos en YAML: Los errores que más duelen
La coerción de tipos es la causa número uno de pérdida de datos al convertir de YAML a JSON. Antes de convertir cualquier archivo de producción, es absolutamente necesario que revises si existen estos problemas específicos. **Booleanos a partir de cadenas inesperadas.** Los analizadores antiguos de YAML 1.1 (como PyYAML antes de la versión 6.0) interpretaban `yes`, `no`, `on` y `off` como booleanos. El YAML 1.2 moderno solo trata `true` y `false` de esta manera, pero si tu archivo de origen fue creado con una herramienta antigua, podría contener 'yes' cuando en realidad significa la cadena de texto 'yes'. Si no conoces el origen del archivo, tienes que buscar estos valores manualmente. **Enteros octales.** Este es un clásico. En YAML, un valor como `0755` se analiza como el entero octal 493. Esta es una trampa muy conocida en los manifiestos de Kubernetes para establecer permisos de archivos. Al convertirlo, tu JSON contendrá el número `493`, no la cadena de texto `'0755'`. Si un proceso posterior intenta usar ese número en una llamada a `chmod`, los permisos serán completamente incorrectos y no recibirás ningún error. **Casos límite con números de punto flotante.** YAML entiende valores especiales de punto flotante como `.inf`, `-.inf` y `.nan`. JSON, no. CocoConvert lo gestiona convirtiéndolos a las cadenas de texto 'Infinity', '-Infinity' y 'NaN'. Esta es una solución razonable, pero si tu aplicación espera solo números, podría fallar con estos valores de texto, lo que requeriría un procesamiento posterior. **Representaciones de nulos.** YAML es flexible con los nulos, aceptando `null`, `~` o incluso un valor vacío después de una clave. Todos estos se convertirán en un `null` estándar en JSON. Normalmente esto no es un problema, pero recuerda que una clave sin nada después de los dos puntos se convierte en un `null` en JSON, no en una cadena vacía `""`.
Cómo manejar cadenas multilínea y comentarios
YAML ofrece dos potentes sintaxis para cadenas multilínea que no tienen un equivalente directo en JSON: los escalares de bloque literal (`|`) y los escalares de bloque plegado (`>`). Un bloque literal (`|`) conserva cada salto de línea. Un bloque plegado (`>`) convierte los saltos de línea simples en espacios, pero mantiene los saltos de línea dobles como saltos de línea reales. Ambas sintaxis producen una única cadena de texto en JSON, pero las sutiles diferencias en el manejo de los saltos de línea son críticas para contenido incrustado como scripts de shell, consultas SQL o certificados. Por ejemplo, este YAML: ```yaml script: | echo hello echo world ``` se convierte en este JSON: ```json {"script": "echo hello\necho world\n"} ``` Fíjate en que el salto de línea final (`\n`) se conserva por defecto con el estilo literal `|`. Para eliminarlo, usarías el indicador de 'chomping' `|-`. Cualquiera que haya depurado un script de CI que falla por una sutil diferencia de espacios en blanco conoce este sufrimiento. Hacer esto mal puede romper scripts o APIs que son sensibles a los espacios en blanco. Los comentarios son un problema mucho más difícil. YAML admite comentarios usando `#`. JSON, no. Y punto. Esto significa que, durante la conversión, cada uno de los comentarios de tu archivo YAML se elimina de forma permanente. Todo el contexto crucial que explica *por qué* se establece un determinado valor —una práctica común en la infraestructura como código— desaparece de la salida JSON. No hay ninguna solución alternativa dentro de la especificación de JSON. Mi recomendación es simple: trata siempre tu YAML comentado como la fuente de verdad y el JSON generado como un artefacto de compilación desechable. Algunos equipos usan JSONC (JSON con Comentarios), pero eso solo pospone el problema de la compatibilidad.
Anclas, alias y claves de fusión
Las anclas y los alias de YAML son una característica fantástica para mantener tus archivos DRY (Don't Repeat Yourself), pero introducen complejidad durante la conversión a JSON. Defines un ancla con `&nombre-ancla` y luego la referencias con `*nombre-ancla`. Un analizador de YAML expande estos alias a medida que lee el archivo, construyendo la estructura de datos final en memoria. La salida JSON, por lo tanto, contiene el contenido completamente expandido y duplicado, sin rastro de las anclas originales. Considera este patrón común: ```yaml defaults: &defaults timeout: 30 retries: 3 production: <<: *defaults host: prod.example.com staging: <<: *defaults host: staging.example.com ``` La sintaxis `<<` es una clave de fusión de YAML. El JSON resultante será: ```json { "defaults": {"timeout": 30, "retries": 3}, "production": {"timeout": 30, "retries": 3, "host": "prod.example.com"}, "staging": {"timeout": 30, "retries": 3, "host": "staging.example.com"} } ``` La expansión es correcta, pero la concisión del YAML original se ha perdido. Si 50 servicios heredaran de esa ancla de valores por defecto, el JSON contendría 50 copias de esos datos. Para una máquina, esto está perfectamente bien. Para un humano que intenta leer el archivo, o para sistemas donde el tamaño del archivo es una preocupación, es una desventaja significativa. Ten en cuenta que el soporte para claves de fusión (`<<`) es técnicamente una extensión de YAML, no parte de la especificación principal, por lo que algunos analizadores estrictos lo rechazarán. CocoConvert maneja las claves de fusión sin problemas. Si estás programando una conversión con PyYAML de Python, debes usar `yaml.full_load()` o `yaml.safe_load()`. Evita el antiguo `yaml.load()` sin un argumento `Loader`, ya que está obsoleto desde PyYAML 5.1 debido a graves riesgos de seguridad.
Convertir YAML a JSON mediante programación
Para conversiones masivas, integraciones en pipelines de compilación o cualquier tipo de procesamiento automatizado, necesitarás una solución de línea de comandos o un script. Una herramienta web es genial para casos puntuales, pero la automatización exige código. Estas son las formas más fiables de hacerlo. **Python (la opción más portable):** ```python import yaml, json, sys with open(sys.argv[1], 'r') as f: data = yaml.safe_load(f) print(json.dumps(data, indent=2, ensure_ascii=False)) ``` Usa siempre `yaml.safe_load()`. El antiguo `yaml.load()` es una pesadilla de seguridad que puede ejecutar código arbitrario desde un archivo YAML malicioso. El argumento `ensure_ascii=False` también es una buena práctica, ya que conserva los caracteres Unicode en lugar de escaparlos. **Node.js:** ```javascript const yaml = require('js-yaml'); const fs = require('fs'); const data = yaml.load(fs.readFileSync(process.argv[2], 'utf8')); console.log(JSON.stringify(data, null, 2)); ``` La librería `js-yaml` utiliza las reglas modernas de YAML 1.2 por defecto (desde la v4.0). Si estás trabajando en un proyecto más antiguo, revisa bien tu `package.json`. Las versiones anteriores a la 4.0 usan las reglas de YAML 1.1 y coaccionarán incorrectamente cadenas como 'yes' y 'no' a booleanos. **yq (herramienta de línea de comandos):** ```bash yq -o=json eval '.' input.yaml > output.json ``` Francamente, `yq` es la mejor herramienta para este trabajo en la línea de comandos. Es un procesador de YAML diseñado específicamente para esto que maneja todo correctamente —archivos multi-documento, anclas, claves de fusión— con una simple bandera para la salida en JSON. Instálalo con Homebrew en macOS (`brew install yq`) o descarga el binario desde GitHub para Linux/Windows. Por supuesto, para una conversión rápida sin instalar nada, la [herramienta de YAML a JSON de CocoConvert](/convert/yaml-to-json) sigue siendo la forma más rápida de hacerlo.
Valida tu salida antes de usarla
Convertir un archivo sin validarlo es la receta perfecta para introducir errores sutiles en producción. Un archivo JSON puede ser sintácticamente válido, pero contener datos semánticamente incorrectos, como las coerciones de tipo que hemos discutido. Aquí tienes una lista de comprobación práctica para ahorrarte futuros dolores de cabeza. **Validación de sintaxis.** Como mínimo, pasa la salida por un linter de JSON. Tu editor de código (como VS Code o un IDE de JetBrains) probablemente lo haga automáticamente. Desde la línea de comandos, la herramienta integrada de Python `json.tool` es un caballo de batalla fiable: `python3 -m json.tool output.json > /dev/null`. Termina con código 0 si el JSON es válido y te dice exactamente dónde falló en caso de error. **Validación de esquema.** Para archivos críticos, usa un esquema. Si tu formato de destino tiene un JSON Schema (común para especificaciones de OpenAPI, AWS CloudFormation y CRDs de Kubernetes), valídalo contra él. Una herramienta como `ajv-cli` (`ajv validate -s schema.json -d output.json`) detectará incoherencias de tipo que una simple comprobación de sintaxis no puede ver. **Compara con una versión que sepas que es correcta.** Cuando tienes un archivo JSON de referencia, hacer un 'diff' es esencial. Pero primero, normaliza el orden de las claves para evitar diferencias ruidosas y sin sentido. La herramienta `jq` puede ordenar las claves de forma determinista: `jq --sort-keys . output.json > normalized.json`. Recuerda que el orden de las claves en JSON no importa, pero te volverá loco cuando intentes comparar archivos. **Revisa puntualmente si hay tipos coaccionados.** Si sospechas que tu YAML tenía valores como '1.0' o '0755', revisa la salida JSON directamente. Un rápido `grep -n "0755" output.json` te dirá al instante si tu cadena octal sobrevivió a la conversión o se convirtió en un entero inútil. En serio, tomarse cinco minutos para validar la salida antes de un 'commit' o un despliegue es siempre más rápido que depurar un incidente en producción causado por un booleano que debía ser una cadena de texto.