Định dạng TOML

Cập nhật lần cuối: tháng 4 năm 2026

Định dạng TOML là gì?

TOML (Tom's Obvious Minimal Language) là định dạng tệp cấu hình được Tom Preston-Werner tạo ra vào năm 2013. Nó ánh xạ trực tiếp sang bảng băm và sử dụng kiểu dữ liệu tường minh cho tất cả các giá trị. Một công cụ định dạng TOML nhận đầu vào thô hoặc có kiểu dáng không nhất quán rồi tuần tự hóa lại với khoảng cách đồng đều, thụt lề đúng cách và thứ tự khóa chuẩn. Kết quả là một tệp tuân theo cùng một quy ước trong toàn bộ dự án, giúp xem xét các thay đổi cấu hình trong diff dễ dàng hơn.

Đặc tả TOML v1.0.0, được hoàn thiện vào tháng 1 năm 2021, định nghĩa ngữ pháp đủ chặt chẽ để bất kỳ parser nào tuân thủ đều tạo ra cấu trúc dữ liệu giống hệt nhau từ cùng một đầu vào. Định dạng không thay đổi nội dung ngữ nghĩa của tệp TOML. Nó chỉ điều chỉnh khoảng trắng, nhóm khóa và kiểu trích dẫn. Điều này có nghĩa là bạn có thể định dạng tệp TOML tùy ý mà không lo làm ảnh hưởng đến hành vi ứng dụng.

Khác với JSON, TOML hỗ trợ chú thích, kiểu ngày-giờ gốc và nhiều dạng chuỗi (cơ bản, nguyên văn và nhiều dòng). Một công cụ định dạng tốt giữ nguyên chú thích và tôn trọng sự khác biệt giữa inline table và tiêu đề bảng chuẩn. Nó cũng xử lý đúng mảng bảng, giữ nguyên nhóm phần mục để tệp vẫn dễ đọc cho cả người dùng lẫn các parser tiêu dùng nó.

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"

Tại sao nên dùng công cụ định dạng TOML?

Các tệp cấu hình tích lũy sự lệch lạc về kiểu dáng khi nhiều thành viên trong nhóm chỉnh sửa chúng theo thời gian. Tab trộn lẫn khoảng trắng, một số khóa bị trích dẫn không cần thiết, và các phần bảng mất đi nhóm trực quan. Một công cụ định dạng TOML chuẩn hóa tất cả những điều này trong một lần xử lý.

Các trường hợp sử dụng công cụ định dạng TOML

Tham chiếu cú pháp TOML

TOML có một tập cấu trúc nhỏ. Bảng dưới đây liệt kê mọi phần tử cấu trúc được định nghĩa trong đặc tả TOML v1.0.0. Công cụ định dạng áp dụng khoảng cách và nhóm nhất quán cho tất cả những phần tử này.

TOML so với JSON và YAML

TOML, JSON và YAML giải quyết các vấn đề chồng lấp nhau nhưng đánh đổi theo những cách khác nhau.

Ví dụ mã nguồn

Các ví dụ dưới đây định dạng TOML theo chương trình trên nhiều ngôn ngữ và công cụ khác nhau. Mỗi ví dụ đọc một tệp, phân tích cú pháp và ghi phiên bản đã định dạng.

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

Câu hỏi thường gặp