¿Qué es un archivo TOML?

TOML es un formato de texto plano que se abre en cualquier editor. Se usa para la edición.

La extensión es .toml y el nombre completo, Tom's Obvious Minimal Language. Ambos importan menos que lo que el archivo puede contener, y de eso trata el resto de esta página.

Se remonta a 2013. La especificación es TOML 1.0.

La edad interesa por un motivo práctico: cuanto más antiguo es un formato, más programas han tenido tiempo de aprenderlo.

Está publicada entera, así que cualquiera puede implementarla leyendo el documento en vez de a base de inspeccionar archivos. Por eso aparece en tantos programas, y por eso los archivos escritos hace veinte años siguen abriéndose hoy. Publicada no quiere decir libre de regalías: cuando un formato envuelve un códec, la licencia de las patentes es un asunto aparte que la norma no resuelve.

TOML guarda su contenido exactamente. Volver a guardarlo no cambia nada, así que puedes abrirlo, editarlo y guardarlo tantas veces como quieras sin acumular daño; eso es lo que lo convierte en un formato de trabajo y no de entrega.

TOML tiene sintaxis de comentarios, que es la diferencia entre un archivo que mantiene una persona y uno que escribe un programa. Los comentarios son lo primero que se pierde al convertir a un formato que no los tiene, y nada te avisa.

Visual Studio Code lo lee, y también la mayoría de programas del mismo tipo.

Cuando un archivo no se abre, el formato rara vez es el problema: lo más habitual es que el programa sea anterior al formato. Convertir a algo más antiguo es la salida fiable, y para eso está el resto de este sitio.

Ningún navegador lo lee.

Ese es el motivo más frecuente para convertirlo: no que el formato sea malo, sino que el sitio donde quieres mostrar el archivo no sabe leerlo.

TOML está pensado para abrirse y cambiarse. Guarda el archivo en este formato mientras el trabajo siga en marcha y exporta desde él cada vez que haga falta una copia terminada.

TOML se parece a un INI y se comporta como un formato de datos. Un valor escrito como 30 es un entero, 30.0 es un decimal, true es un booleano, "30" es una cadena y 2026-08-05 es una fecha — el formato define todos ellos, así que cualquier analizador coincide y ningún programa tiene que adivinar qué quiso decir quien escribió el archivo.

Esa sola propiedad explica gran parte de su existencia. Los errores de configuración se concentran justo en esa ambigüedad: un interruptor leído como la cadena "false" que resulta ser verdadero, un número de versión convertido en decimal sin avisar, un puerto que llega como texto. Un formato con tipos elimina la clase entera de problemas.

YAML es más capaz y mucho más fácil de estropear, y TOML se escribió como respuesta directa a eso. En YAML la estructura se expresa con la sangría, de modo que un espacio mal puesto cambia el significado del documento sin producir un error: el archivo sigue analizándose, pero como otra cosa.

Y luego está la inferencia de tipos. Las versiones antiguas leen no como un booleano, así que un código de país, un campo de idioma o una columna de respuestas acaba valiendo falso. Un número de versión como 1.20 se convierte en 1.2. Una cadena con pinta de hora se vuelve un número en base sesenta. Cada uno de esos casos ha provocado caídas reales. TOML no tiene ninguno: la estructura es explícita y un valor es lo que dice su sintaxis.

Rust lo puso en todas partes primero: todo proyecto con Cargo tiene su Cargo.toml. Python siguió de forma decisiva, y pyproject.toml es hoy el sitio estándar de la configuración de compilación, con un lector de TOML incluido en la biblioteca estándar del lenguaje.

Más allá de esos dos: Hugo y varios generadores de sitios estáticos, Netlify, Poetry, Ruff y un goteo constante de herramientas nuevas que querían una configuración editable a mano sin el riesgo de la sangría. Se ha convertido en la opción por defecto para la configuración que leen personas que programan, más o menos como YAML lo es para la infraestructura.

Una cabecera entre corchetes es una tabla, que es como TOML llama a una sección. El anidamiento se escribe con un punto: [tool.ruff.lint] declara una tabla dentro de una tabla dentro de otra, y los puntos son estructura y no parte de un nombre. Ahí es exactamente donde INI se detiene y TOML sigue.

Conviene recordar que todo lo que va debajo de una cabecera pertenece a esa tabla hasta la siguiente. Una clave escrita por encima de la primera cabecera aterriza en el nivel raíz y, con muchísima frecuencia, no la lee nadie: la herramienta la busca dentro de su sección y allí no está.

Escribir [[bin]] tres veces no redefine tres veces la misma tabla: declara un array de tablas, es decir, tres entradas de una lista. Es la forma de expresar «varias cosas del mismo tipo» — tres ejecutables, cuatro dependencias, una lista de autores.

Y es la causa habitual de un síntoma muy reconocible: bloques de configuración repetidos que parecen pisarse unos a otros en vez de sumarse. Cuando solo sobrevive el último, casi siempre hay corchetes simples donde tenían que ir dobles.

TOML entiende fechas y horas directamente: una fecha suelta, una hora suelta y una marca temporal con o sin desfase horario. Son valores igual que lo es un entero, no cadenas que algo tenga que interpretar después.

Es una función pequeña que quita una molestia persistente. Una configuración con una fecha de publicación, una caducidad, un corte o un calendario deja de necesitar un formato de cadena acordado en un comentario y reimplementado en cada programa que lo lea. Lo especifica el formato, y el analizador devuelve una fecha.

Los datos muy anidados. TOML está pensado para ser plano y legible, y en cuanto la estructura baja tres o cuatro niveles los nombres de las cabeceras se alargan y el archivo se sigue peor que el JSON al que pretendía sustituir. Si tu configuración tiene forma de árbol documental, probablemente quiera ser un árbol documental.

El otro caso son los datos generados por máquinas. TOML es para archivos que edita una persona; JSON es para archivos que se intercambian los programas, y es más pequeño, más rápido de analizar y compatible con todo. Usar TOML como formato de intercambio se puede y no gana nada: la legibilidad que optimiza solo compensa cuando hay alguien leyendo.

Una cosa desaparece siempre y conviene decirla antes: los comentarios. Ni TOML, ni YAML, ni INI, ni XML los conservan al pasar por aquí, porque el archivo se analiza hasta convertirlo en valores y en esa representación no hay ningún sitio donde guardar una línea que empieza por almohadilla. En un archivo de configuración eso suele ser justamente lo que explicaba por qué un valor era ese y no otro, así que copia los comentarios aparte si te importan. El orden de las claves, en cambio, sí se mantiene: nada en el conversor ordena nada.

Del resto, el destino manda. Hacia JSON, YAML o XML el árbol llega entero. Hacia INI no, y la conversión se marca como aproximada por ese motivo: INI no tiene anidamiento ni tipos, así que una tabla dentro de otra se aplana y un booleano se vuelve texto que algún programa decidirá interpretar más adelante. Todo esto se ejecuta dentro de tu navegador, sin subir el archivo a ninguna parte y sin cupos, con un tope de 100 MB por archivo y 100 archivos por tanda.