Formateador TOML

Última actualización: abril de 2026

¿Qué es el formateo de TOML?

TOML (Tom's Obvious Minimal Language) es un formato de archivo de configuración creado por Tom Preston-Werner en 2013. Se asigna directamente a una tabla hash y utiliza tipado explícito para todos los valores. Un formateador TOML toma TOML sin procesar o con estilos inconsistentes y lo re-serializa con espaciado uniforme, indentación adecuada y ordenación canónica de claves. El resultado es un archivo que sigue las mismas convenciones en todo tu proyecto, haciendo que los cambios de configuración sean más fáciles de revisar en los diffs.

La especificación TOML v1.0.0, finalizada en enero de 2021, define la gramática con suficiente rigor como para que cualquier analizador compatible produzca una estructura de datos idéntica a partir de la misma entrada. El formateo no cambia el contenido semántico de un archivo TOML. Solo ajusta el espacio en blanco, la agrupación de claves y el estilo de las comillas. Esto significa que puedes formatear archivos TOML libremente sin preocuparte por romper el comportamiento de tu aplicación.

A diferencia de JSON, TOML admite comentarios, tipos de fecha y hora nativos, y múltiples formas de cadenas (básica, literal y multilínea). Un buen formateador preserva los comentarios y respeta la distinción entre tablas en línea y encabezados de tabla estándar. También gestiona correctamente los arrays de tablas, manteniendo la agrupación de secciones intacta para que el archivo siga siendo legible tanto para las personas como para los analizadores que lo consumen.

title="My App"
version="1.0.0"
debug=false
[database]
host="localhost"
port=5432
name="mydb"
[database.pool]
max_connections=25
timeout=30
[[servers]]
name="web"
host="web.example.com"
[[servers]]
name="api"
host="api.example.com"

title = "My App"
version = "1.0.0"
debug = false

[database]
host = "localhost"
port = 5432
name = "mydb"

[database.pool]
max_connections = 25
timeout = 30

[[servers]]
name = "web"
host = "web.example.com"

[[servers]]
name = "api"
host = "api.example.com"

¿Por qué usar un formateador TOML?

Los archivos de configuración acumulan inconsistencias de estilo a medida que distintos miembros del equipo los editan con el tiempo. Los tabuladores se mezclan con espacios, algunas claves se citan innecesariamente y las secciones de tablas pierden su agrupación visual. Un formateador TOML normaliza todo esto en una sola pasada.

Casos de uso del formateador TOML

Referencia de sintaxis TOML

TOML tiene un conjunto pequeño de construcciones. La tabla a continuación lista todos los elementos estructurales definidos en la especificación TOML v1.0.0. Un formateador aplica espaciado y agrupación consistentes a todos ellos.

TOML frente a JSON frente a YAML

TOML, JSON y YAML resuelven problemas similares pero con compromisos distintos.

Ejemplos de código

Los ejemplos a continuación formatean TOML mediante programación en distintos lenguajes y herramientas. Cada uno lee un archivo, lo analiza y escribe una versión formateada.

import { parse, stringify } from '@iarna/toml'
import fs from 'fs'

const raw = fs.readFileSync('config.toml', 'utf-8')
const doc = parse(raw)
const formatted = stringify(doc)
// stringify() outputs canonical TOML with consistent spacing
fs.writeFileSync('config.toml', formatted)

// Quick one-liner with npx:
// npx taplo fmt config.toml

import tomllib   # Python 3.11+ (read-only)
import tomli_w   # pip install tomli-w (write)

# Parse and re-serialize to format
with open("config.toml", "rb") as f:
    data = tomllib.load(f)

formatted = tomli_w.dumps(data)
# tomli_w produces sorted keys, consistent quoting, and
# proper whitespace around = signs
print(formatted)

# CLI alternative: taplo fmt config.toml

package main

import (
    "fmt"
    "os"
    "github.com/BurntSushi/toml"
    "bytes"
)

func main() {
    var data map[string]interface{}
    _, err := toml.DecodeFile("config.toml", &data)
    if err != nil {
        fmt.Fprintln(os.Stderr, err) // parse error with line number
        os.Exit(1)
    }
    var buf bytes.Buffer
    enc := toml.NewEncoder(&buf)
    enc.Indent = "  "
    enc.Encode(data) // re-serialized with consistent formatting
    fmt.Print(buf.String())
}

# Install taplo — the standard TOML toolkit
cargo install taplo-cli
# or: npm install -g @taplo/cli

# Format a single file in place
taplo fmt config.toml

# Format all .toml files in a project
taplo fmt

# Check formatting without modifying (CI-friendly)
taplo fmt --check

# Validate TOML syntax without formatting
taplo lint config.toml

Preguntas frecuentes