JSON frente a YAML en archivos de configuración

JSON y YAML suelen representar el mismo modelo de datos: objetos, arrays, cadenas, números, booleanos y valores null. La diferencia está en cómo se comportan en archivos editados por humanos y en flujos generados por máquina.

Elige el formato según quién lo edita y qué tan estricto debe ser el pipeline.

JSON es estricto y predecible

JSON encaja bien cuando las máquinas producen o consumen el archivo:

• Ejemplos de peticiones y respuestas de API.
• Metadatos de paquetes.
• Configuración generada.
• Intercambio de datos entre servicios.
• Fixtures de prueba que deben parsearse igual en todas partes.

La sintaxis estricta puede parecer ruidosa, pero reduce ambigüedad. Las cadenas necesitan comillas, las comas importan y los parsers suelen coincidir.

Usa Formateador JSON cuando necesites validar, inspeccionar o normalizar un payload JSON rápidamente.

YAML es amigable para config editada a mano

YAML es popular para archivos que mantienen humanos:

• Manifests de Kubernetes.
• Workflows de GitHub Actions.
• Archivos Docker Compose.
• Configuración de aplicaciones.
• Ejemplos en documentación.

Es más fácil de leer cuando el anidamiento es profundo y los comentarios importan. La contrapartida es que la indentación, el tipado implícito y los archivos multi-documento pueden sorprender.

Usa Formateador / Validador YAML antes de aplicar o commitear YAML importante.

Dónde YAML falla

Problemas habituales de YAML incluyen:

• Tabulaciones donde se esperan espacios.
• on, yes o no interpretados de forma inesperada.
• Dos documentos pegados en un solo archivo.
• Indentación que parece correcta pero cambia la estructura.
• Comentarios perdidos durante conversión automatizada.

Son manejables, pero son riesgos operativos reales.

Dónde JSON falla

Problemas habituales de JSON incluyen:

• Comas finales copiadas desde JavaScript.
• Comentarios añadidos a archivos que parsers JSON estrictos rechazan.
• Cadenas escapadas difíciles de leer.
• Archivos grandes que se vuelven difíciles de editar a mano.

JSON es más seguro para máquinas, no siempre más amable con humanos.

Regla práctica

Usa JSON cuando importe un intercambio estricto. Usa YAML cuando los humanos necesiten configuración legible con comentarios. Convierte con cuidado, valida antes del despliegue y no asumas que los dos formatos preservan cada detalle en ambas direcciones.