Elegir formatos de configuración: JSON, YAML o TOML

Qué es

JSON, según RFC 8259, admite objetos, arrays, cadenas de caracteres, números, true, false y null, y no admite comentarios. La RFC indica que los nombres dentro de un objeto DEBERÍAN ser únicos, y que el comportamiento del software receptor ante nombres duplicados es impredecible: algunos informan solo del último par, otros producen un error. YAML 1.2, según su especificación, se diseñó con el objetivo principal de ser un superconjunto estricto de JSON, y eliminó muchas de las recomendaciones problemáticas sobre tipado implícito; en el esquema núcleo (Core Schema), los escalares sin comillas se siguen resolviendo por patrón, de modo que true, True y TRUE son valores booleanos, mientras que los cargadores que siguen el modelo 1.1 más antiguo también tratan así a yes, no, on y off. TOML 1.0, conforme a su propio objetivo, pretende ser un formato de configuración mínimo, fácil de leer por su semántica evidente y que se corresponde de forma inequívoca con una tabla hash; tiene comentarios, tipos explícitos (cadena de caracteres, número entero, número de punto flotante, booleano, fecha y hora), tablas entre corchetes, claves con puntos y tablas en línea que deben ir en una sola línea.

Por qué importa

Un archivo de configuración lo escriben personas y lo leen programas; el formato determina en qué extremo ocurren los errores. Los errores de sangría y las conversiones de tipo silenciosas son la clase de error de YAML (version: 1.10 se convierte en el número 1.1; un código de país NO se convierte en false en un cargador 1.1); la falta de comentarios y las claves duplicadas son la clase de error de JSON; TOML obliga, con anidamiento profundo, a rutas de tabla largas.

Cómo aplicarlo

• Máquina a máquina (API, cachés, exportación): JSON, comprobado contra un JSON Schema.
• Configuración mantenida a mano con estructura plana a media: TOML; lo usan Python (pyproject.toml), Rust (Cargo) y muchas herramientas.
• YAML allí donde lo impone el ecosistema (pipelines de CI, Kubernetes, Compose): poner entre comillas las cadenas que parecen números, booleanos o fechas; elegir un cargador conforme al esquema núcleo de la versión 1.2; no cargar etiquetas (tags) definidas por el usuario.
• Independientemente del formato, convertir el resultado analizado en un modelo tipado, rechazar las claves desconocidas y abortar con un mensaje claro (archivo, línea, clave).
• Al cambiar de formato, conviene convertir mediante una herramienta y comparar el resultado analizado de ambos archivos, no el texto.

Trampas

Según la RFC, un analizador de JSON puede admitir extensiones; los comentarios o las comas finales que una herramienta acepta hacen fallar a la siguiente. Los anclajes de YAML y los documentos múltiples son difíciles de revisar para las personas. Las tablas en línea de TOML no toleran una coma final. 1e3 es un número de punto flotante en el esquema núcleo de YAML 1.2, y una cadena de caracteres en los cargadores 1.1: una razón más para poner comillas.