YAML

Dos formatos, trabajos que se solapan

JSON (JavaScript Object Notation) y YAML (YAML Ain’t Markup Language) representan ambos datos estructurados: objetos anidados, listas, cadenas, números y booleanos. Aparecen en APIs, archivos de configuración, pipelines de CI, manifiestos de Kubernetes y ejemplos de documentación. Elegir entre ellos no es tanto qué es «mejor», sino quién edita el archivo, qué herramientas lo consumen y cuán estricto debe ser el análisis.

Si ya tienes JSON y quieres inspeccionarlo como indentación YAML, conviértelo con JSON a YAML.

JSON en breve

JSON nació de la sintaxis de literales de objeto de JavaScript y se convirtió en un formato de intercambio agnóstico respecto al lenguaje. Un documento JSON se construye con:

• Objetos: { "key": "value" }
• Arrays: [1, 2, 3]
• Cadenas entre comillas dobles
• Números
• true, false y null

Restricciones notables: sin comentarios, sin comas finales en JSON estándar, las claves deben ser cadenas y las cadenas usan una sintaxis de escape limitada. Esas restricciones hacen los parsers simples y estrictos—valiosos cuando las máquinas intercambian datos.

El JSON formateado es legible en documentos pequeños. Las configuraciones grandes con anidación profunda se vuelven ruidosas por llaves, corchetes y claves entre comillas en cada línea.

YAML en breve

YAML prioriza la edición humana. La estructura se transmite sobre todo por indentación, no por llaves. Incluye:

• Comentarios que empiezan con #
• Cadenas sin comillas en muchos casos
• Anchors y alias para reutilizar
• Varios flujos de documentos separados por ---
• Etiquetas de tipo explícitas en usos avanzados

Un mapeo pequeño se ve así:

service:
  name: api
  replicas: 3
  ports:
    - 8080
    - 8443

La misma estructura en JSON repite puntuación y comillas. Para operadores que editan manifiestos a diario, la brevedad de YAML resulta atractiva.

Solapamiento del modelo de datos

En el núcleo, ambos formatos pueden expresar árboles de mapas y secuencias con hojas escalares. El round-trip suele ser posible para el subconjunto común: objetos, arrays, cadenas, números, booleanos y null.

Las diferencias aparecen en los bordes:

• YAML puede producir claves que no son cadenas; JSON no.
• YAML tiene más formas de escribir cadenas (bloques literales, bloques folded).
• El «Norway problem» de YAML y otros quirks de tipado implícito pueden convertir NO, on o tokens con aspecto de versión sin comillas en booleanos o números según la versión de YAML y el parser.
• Los números JSON son directos; YAML puede interpretar enteros grandes o timestamps de forma especial en algunos loaders.

Cuando importa la interoperabilidad, prefiere entrecomillar en YAML las cadenas que parecen booleanos, números o fechas, o genera YAML desde una estructura tipada en lugar de editar a mano escalares ambiguos.

Comentarios y documentación

JSON no tiene comentarios estándar. Los equipos a veces abusan de campos "_comment", que ensucian los schemas. Los comentarios # de YAML documentan la intención junto a los datos—por qué el conteo de réplicas es 3, qué equipo posee una etiqueta—sin cambiar el modelo de información.

Si tu audiencia principal son máquinas (APIs, cuerpos de fetch del navegador), la falta de comentarios de JSON rara vez es un problema. Si humanos mantienen el archivo durante meses, los comentarios YAML reducen la pérdida de conocimiento tribal.

Herramientas y ecosistema

Fortalezas de JSON

• Parsers ubicuos en casi todos los lenguajes mainstream
• Soporte de primera clase en el navegador (JSON.parse / JSON.stringify)
• Ecosistemas de schema (JSON Schema) ampliamente adoptados
• Diffs orientados a líneas que, aunque llenos de llaves, resultan familiares
• Parsers en streaming para payloads grandes

Fortalezas de YAML

• Dominante en DevOps (Kubernetes, Ansible, muchos sistemas de CI)
• Merges y anchors (potentes, a veces sobreusados)
• Archivos multi-documento para agrupar recursos relacionados
• Más amable para configuración poco anidada

Riesgos de YAML

• Complejidad de la especificación (diferencias YAML 1.1 vs 1.2)
• Errores de indentación difíciles de ver
• Funciones (custom tags, merge keys) que reducen la portabilidad
• Ejecución accidental de código en loaders inseguros históricamente—usa siempre APIs de carga segura

Rendimiento y tamaño

En protocolos de red, JSON suele ser más barato de parsear en bibliotecas nativas optimizadas y evita el coste de la indentación. JSON y YAML comprimidos convergen en tamaño. Para configuración que se lee de vez en cuando y se edita a menudo, la velocidad de parseo rara vez es el cuello de botella; sí lo es la tasa de error humano.

Los primos binarios (MessagePack, CBOR, Protobuf) superan a ambos cuando domina el throughput. No son formatos humanos de sustitución directa.

Estrategias de conversión

Convertir JSON → YAML suele ser sin pérdida para el subconjunto común y útil en revisiones de legibilidad. Convertir YAML → JSON puede perder comentarios, anchors y tipos no JSON. Trata la conversión como una proyección, no como un archivo perfecto de la intención del autor.

Consejos de flujo de trabajo:

1. Mantén una única fuente de verdad (a menudo JSON Schema o un modelo tipado en el lenguaje).
2. Genera el formato que cada consumidor necesita.
3. Si humanos deben editar YAML, valida contra un schema en cada cambio.
4. Evita mantener a mano dos copias del mismo documento.

El convertidor from-json de Tool Plaza te ayuda a previsualizar cómo se ve un payload JSON con sintaxis basada en indentación.

Cuándo elegir JSON

• APIs HTTP públicas y cuerpos de webhooks
• Clientes de navegador y móviles
• Intercambio estricto entre máquinas con mínima ambigüedad
• Registrar eventos estructurados en agregadores que esperan JSON lines
• Embebido en lenguajes donde los literales JSON mapean limpio a tipos nativos

Cuándo elegir YAML

• Manifiestos de despliegue e infraestructura editados por personas
• Archivos de configuración que se benefician de comentarios
• Ecosistemas que ya estandarizan en YAML
• Documentos donde la claridad de indentación supera el emparejamiento de llaves para tu equipo

Enfoques híbridos

Algunos proyectos guardan JSON canónico en el control de versiones y generan YAML para una herramienta concreta. Otros aceptan entrada YAML, normalizan a un AST interno y emiten JSON para APIs. Ambos funcionan si el pipeline está automatizado y probado.

Ten cuidado con las extensiones «JSON5» o «JSONC» (JSON con comentarios): mejoran la ergonomía pero no son universales. Documenta el dialecto si adoptas uno.

Higiene de edición y revisión

• Usa editores que resalten indentación y espacios finales en YAML.
• Haz fallar la CI ante sintaxis inválida antes del merge.
• Prefiere indentación de 2 espacios de forma consistente en equipos YAML.
• Mantén las líneas razonablemente cortas; las cadenas inline enormes pertenecen a bloques literales o archivos externos.
• No pegues secretos en ninguno de los formatos en repos públicos—usa gestores de secretos y referencias.

Resumen

JSON es el formato de intercambio estricto y ubicuo; YAML es el dialecto de configuración amigable con comentarios y con sintaxis más rica—y más arriesgada. Comparten un modelo de datos anidado para mapas y listas cotidianas. Elige JSON para APIs y máquinas, YAML para archivos de infra operados por humanos, y convierte deliberadamente cuando necesites ambas vistas de la misma estructura.