TOML Configuration Format (.toml)

TOML (Tom's Obvious, Minimal Language) is a human-readable configuration file format created by Tom Preston-Werner, co-founder of GitHub, in 2013. TOML aims to be a minimal configuration file format that's easy to read and write due to obvious semantics, while mapping unambiguously to a hash table. It has gained widespread adoption in the Rust ecosystem and is used by many modern tools and applications.

Technical Overview

TOML is designed to be a configuration file format that is easy for humans to read and write, and easy for machines to parse and generate. It supports Unicode and is case-sensitive. TOML files consist of key-value pairs organized into sections (tables) and support various data types including strings, integers, floats, booleans, arrays, and nested structures.

Key Features

• Human-Readable: Clear, obvious syntax that's easy to understand
• Minimal: Simple format with minimal syntax overhead
• Unambiguous: Maps clearly to hash tables/dictionaries
• Unicode Support: Full Unicode support for strings and comments
• Type System: Rich data types including arrays and nested tables
• Comments: Supports both inline and standalone comments

TOML Syntax and Structure

Basic Data Types

# Comments start with hash symbol
# This is a TOML configuration file

# Strings
title = "TOML Configuration Example"
description = 'Single quotes preserve literal strings'
multiline = """
This is a multiline string.
It can span multiple lines
and preserves whitespace.
"""

literal_multiline = '''
This is a literal multiline string.
Backslashes are preserved: \n \t
No escaping occurs.
'''

# Basic strings with escaping
escaped = "Line 1\nLine 2\tTabbed"
unicode = "Unicode snowman: \u2603"

# Integers
port = 8080
max_connections = 1000
negative = -42

# Hexadecimal, octal, binary
hex_value = 0xDEADBEEF
octal_value = 0o755
binary_value = 0b11010110

# Large numbers with underscores
million = 1_000_000
long_number = 9_223_372_036_854_775_807

# Floats
pi = 3.14159
scientific = 5e+22
negative_float = -0.01
infinity = inf
not_a_number = nan

# Booleans
enabled = true
debug = false

# Dates and times
date = 2023-06-14
time = 07:32:00
datetime = 2023-06-14T07:32:00
datetime_with_tz = 2023-06-14T07:32:00-08:00
datetime_utc = 2023-06-14T07:32:00Z

Arrays

# Simple arrays
numbers = [1, 2, 3, 4, 5]
colors = ["red", "green", "blue"]
mixed_types = ["string", 42, true, 3.14]

# Multiline arrays
dependencies = [
    "requests",
    "flask",
    "sqlalchemy",
    "pytest"
]

# Nested arrays
matrix = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
]

# Array of tables (covered later)

Tables (Sections)

# Root level key-value pairs
app_name = "MyApplication"
version = "1.0.0"

# Tables are defined with square brackets
[database]
host = "localhost"
port = 5432
name = "myapp_db"
user = "postgres"
password = "secret123"
ssl = true
timeout = 30

[database.connection_pool]
min_size = 5
max_size = 20
timeout = 60

# Alternative nested table syntax
[server]
host = "0.0.0.0"
port = 8080

[server.ssl]
enabled = true
cert_file = "/etc/ssl/certs/server.crt"
key_file = "/etc/ssl/private/server.key"

# Multiple tables
[logging]
level = "INFO"
format = "%Y-%m-%d %H:%M:%S - %(name)s - %(levelname)s - %(message)s"

[logging.handlers]
console = true
file = "/var/log/myapp.log"
rotate = true
max_size = "10MB"
backup_count = 5

Inline Tables

# Inline tables for simple grouped data
point = { x = 1, y = 2 }
color = { r = 255, g = 128, b = 0 }
person = { name = "John Doe", age = 30, email = "[email protected]" }

# Configuration with inline tables
redis = { host = "localhost", port = 6379, db = 0 }
cache = { type = "redis", ttl = 3600, max_size = 1000 }

# Nested inline tables
user = { profile = { name = "Alice", preferences = { theme = "dark", lang = "en" } } }

Array of Tables

# Array of tables using double brackets
[[servers]]
name = "web-1"
ip = "10.0.0.1"
role = "frontend"
active = true

[[servers]]
name = "web-2"
ip = "10.0.0.2"
role = "frontend"
active = true

[[servers]]
name = "db-1"
ip = "10.0.0.10"
role = "database"
active = true
backup = true

# More complex array of tables
[[users]]
name = "Alice"
email = "[email protected]"
roles = ["admin", "user"]
created_at = 2023-01-15T10:30:00Z

[users.preferences]
theme = "dark"
notifications = true
language = "en"

[[users]]
name = "Bob"
email = "[email protected]"
roles = ["user"]
created_at = 2023-02-20T14:45:00Z

[users.preferences]
theme = "light"
notifications = false
language = "es"

Real-World Configuration Examples

Web Application Configuration

# config.toml - Web application configuration
app_name = "MyWebApp"
version = "2.1.0"
debug = false
secret_key = "your-secret-key-here"

[server]
host = "0.0.0.0"
port = 8000
workers = 4
timeout = 30
keep_alive = 2

[database]
driver = "postgresql"
host = "localhost"
port = 5432
name = "webapp_production"
user = "webapp_user"
password = "secure_password"
pool_size = 10
max_overflow = 20
echo = false

[database.options]
connect_timeout = 10
command_timeout = 30
ssl_mode = "require"

[redis]
host = "localhost"
port = 6379
db = 0
password = ""
max_connections = 20

[logging]
level = "INFO"
format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

[logging.handlers]
console = { enabled = true, level = "INFO" }
file = { enabled = true, path = "/var/log/webapp.log", level = "DEBUG", max_size = "100MB" }
syslog = { enabled = false, facility = "local0" }

[auth]
jwt_secret = "jwt-secret-key"
jwt_expiration = 3600
session_timeout = 1800
max_login_attempts = 5
lockout_duration = 900

[auth.oauth]
google = { client_id = "google-client-id", client_secret = "google-secret", enabled = true }
github = { client_id = "github-client-id", client_secret = "github-secret", enabled = false }

[features]
user_registration = true
email_verification = true
password_reset = true
two_factor_auth = false
analytics = true

[email]
provider = "smtp"
host = "smtp.example.com"
port = 587
username = "[email protected]"
password = "email_password"
use_tls = true
from_address = "MyWebApp <[email protected]>"

[storage]
provider = "local"
local_path = "/var/www/uploads"
max_file_size = "10MB"
allowed_extensions = ["jpg", "jpeg", "png", "gif", "pdf", "txt"]

[cache]
provider = "redis"
default_timeout = 300
key_prefix = "webapp:"

# Environment-specific overrides
[environments.development]
debug = true
database = { name = "webapp_dev", echo = true }
logging = { level = "DEBUG" }

[environments.testing]
database = { name = "webapp_test" }
redis = { db = 1 }

Rust Cargo.toml

[package]
name = "my-rust-project"
version = "0.1.0"
edition = "2021"
authors = ["John Doe <[email protected]>"]
description = "A sample Rust project"
documentation = "https://docs.rs/my-rust-project"
homepage = "https://github.com/johndoe/my-rust-project"
repository = "https://github.com/johndoe/my-rust-project"
license = "MIT OR Apache-2.0"
keywords = ["cli", "tool", "utility"]
categories = ["command-line-utilities"]
readme = "README.md"
include = ["src/**/*", "LICENSE-*", "README.md", "CHANGELOG.md"]

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }
clap = { version = "4.0", features = ["derive"] }
anyhow = "1.0"
thiserror = "1.0"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

[dependencies.reqwest]
version = "0.11"
features = ["json", "rustls-tls"]
default-features = false

[dev-dependencies]
criterion = "0.5"
tempfile = "3.0"
assert_cmd = "2.0"
predicates = "3.0"

[build-dependencies]
cc = "1.0"

[features]
default = ["tls"]
tls = ["reqwest/rustls-tls"]
native-tls = ["reqwest/native-tls"]
extra-debug = []

[profile.release]
opt-level = 3
lto = true
codegen-units = 1
panic = "abort"
strip = true

[profile.dev]
opt-level = 0
debug = true
overflow-checks = true

[[bin]]
name = "my-tool"
path = "src/bin/my-tool.rs"

[[bin]]
name = "helper"
path = "src/bin/helper.rs"

[lib]
name = "my_rust_project"
crate-type = ["cdylib", "rlib"]

[[bench]]
name = "performance"
harness = false

[[example]]
name = "basic_usage"
path = "examples/basic.rs"

[workspace]
members = ["crates/*"]
exclude = ["examples/large-project"]

[patch.crates-io]
# Patch a dependency to use a git version
some-crate = { git = "https://github.com/example/some-crate", branch = "main" }

Docker Compose Alternative

# docker-compose.toml (hypothetical format)
version = "3.8"

[services.web]
image = "nginx:alpine"
container_name = "web-server"
restart = "unless-stopped"
ports = ["80:80", "443:443"]
volumes = [
    "./nginx.conf:/etc/nginx/nginx.conf:ro",
    "./ssl:/etc/nginx/ssl:ro",
    "web_logs:/var/log/nginx"
]
depends_on = ["api"]

[services.web.environment]
NGINX_WORKER_PROCESSES = "auto"
NGINX_WORKER_CONNECTIONS = "1024"

[services.api]
build = { context = ".", dockerfile = "Dockerfile.api" }
container_name = "api-server"
restart = "unless-stopped"
ports = ["3000:3000"]
environment = [
    "NODE_ENV=production",
    "DATABASE_URL=postgresql://user:pass@db:5432/app",
    "REDIS_URL=redis://redis:6379"
]
volumes = ["./uploads:/app/uploads"]
depends_on = ["db", "redis"]

[services.api.healthcheck]
test = ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval = "30s"
timeout = "10s"
retries = 3

[services.db]
image = "postgres:15-alpine"
container_name = "database"
restart = "unless-stopped"
environment = {
    POSTGRES_DB = "app",
    POSTGRES_USER = "user",
    POSTGRES_PASSWORD = "password"
}
volumes = [
    "postgres_data:/var/lib/postgresql/data",
    "./init.sql:/docker-entrypoint-initdb.d/init.sql:ro"
]
ports = ["5432:5432"]

[services.redis]
image = "redis:7-alpine"
container_name = "cache"
restart = "unless-stopped"
command = "redis-server --appendonly yes"
volumes = ["redis_data:/data"]

[volumes]
postgres_data = {}
redis_data = {}
web_logs = {}

[networks.default]
driver = "bridge"

Parsing and Generation

Python Example

import tomllib  # Python 3.11+
# or: import tomli as tomllib (for older versions)

# Reading TOML
def load_config(filename):
    with open(filename, "rb") as f:
        config = tomllib.load(f)
    return config

# Example usage
config = load_config("config.toml")
print(f"App name: {config['app_name']}")
print(f"Database host: {config['database']['host']}")

# Writing TOML (using tomli_w)
import tomli_w

data = {
    "app_name": "MyApp",
    "version": "1.0.0",
    "database": {
        "host": "localhost",
        "port": 5432,
        "credentials": {
            "username": "user",
            "password": "pass"
        }
    },
    "servers": [
        {"name": "web-1", "ip": "10.0.0.1"},
        {"name": "web-2", "ip": "10.0.0.2"}
    ]
}

with open("output.toml", "wb") as f:
    tomli_w.dump(data, f)

Rust Example

use serde::{Deserialize, Serialize};
use std::fs;

#[derive(Debug, Serialize, Deserialize)]
struct Config {
    app_name: String,
    version: String,
    database: Database,
    servers: Vec<Server>,
}

#[derive(Debug, Serialize, Deserialize)]
struct Database {
    host: String,
    port: u16,
    name: String,
    ssl: bool,
}

#[derive(Debug, Serialize, Deserialize)]
struct Server {
    name: String,
    ip: String,
    role: String,
    active: bool,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Reading TOML
    let content = fs::read_to_string("config.toml")?;
    let config: Config = toml::from_str(&content)?;
    
    println!("App: {} v{}", config.app_name, config.version);
    println!("Database: {}:{}", config.database.host, config.database.port);
    
    // Writing TOML
    let new_config = Config {
        app_name: "NewApp".to_string(),
        version: "2.0.0".to_string(),
        database: Database {
            host: "localhost".to_string(),
            port: 5432,
            name: "newapp_db".to_string(),
            ssl: true,
        },
        servers: vec![
            Server {
                name: "server-1".to_string(),
                ip: "192.168.1.10".to_string(),
                role: "web".to_string(),
                active: true,
            }
        ],
    };
    
    let toml_string = toml::to_string(&new_config)?;
    fs::write("new_config.toml", toml_string)?;
    
    Ok(())
}

Tools and Ecosystem

Validation and Linting

# Install TOML validators
pip install toml-validator
npm install -g @taplo/cli

# Validate TOML files
toml-validator config.toml
taplo check config.toml

# Format TOML files
taplo format config.toml

Editor Integration

Most modern editors support TOML syntax highlighting and validation:

• VS Code: Built-in support, extensions like "Better TOML"
• Vim/Neovim: vim-toml plugin
• Emacs: toml-mode
• IntelliJ/PyCharm: Built-in support
• Sublime Text: TOML package

Best Practices

Configuration Structure

# Use clear, descriptive keys
database_connection_timeout = 30  # Good
db_conn_to = 30                   # Poor

# Group related settings
[database]
host = "localhost"
port = 5432

[database.pool]
min_size = 5
max_size = 20

# Use comments for complex configurations
[server]
# Maximum number of worker processes
# Set to 0 for auto-detection based on CPU cores
workers = 0

# Request timeout in seconds
# Requests exceeding this limit will be terminated
timeout = 30

# Use environment-specific sections
[environments.production]
debug = false
log_level = "INFO"

[environments.development]
debug = true
log_level = "DEBUG"

Data Type Usage

# Use appropriate data types
port = 8080          # Integer, not "8080"
enabled = true       # Boolean, not "true"
timeout = 30.5       # Float for decimal values

# Use arrays for lists
allowed_ips = ["192.168.1.1", "10.0.0.0/8"]
# Not: allowed_ips = "192.168.1.1,10.0.0.0/8"

# Use inline tables for simple groupings
endpoint = { host = "localhost", port = 3000, ssl = false }

# Use regular tables for complex configurations
[endpoint]
host = "localhost"
port = 3000
ssl = false
certificate = "/path/to/cert.pem"

File Format Details

• MIME Type: text/plain (no official MIME type)
• File Extension: .toml
• Character Encoding: UTF-8
• Line Endings: Platform-independent
• Case Sensitivity: Case-sensitive keys and values

TOML provides an excellent balance between human readability and machine parsing, making it ideal for configuration files in modern applications. Its clear syntax and rich data type support have made it a popular choice in the Rust ecosystem and beyond.