TOML

Getting Started

Fundamental TOML concepts and syntax for beginners.

Basic Syntax

Comments, whitespace, file format, and basic TOML structure.

Simple TOML file with comments

A basic TOML file demonstrating key-value pairs and comment usage.

Code

1
# This is a comment
2
title = "My App"
3

4
# Comments can be placed anywhere
5
version = "1.0.0"

Execution

toml-parser config.toml

Output

title: "My App"
version: "1.0.0"

Comments start with
Whitespace is ignored in most places.
Newlines separate key-value pairs.

Multi-line structure with sections

Demonstrates basic section structure and organization.

Code

1
# Configuration file
2
name = "MyApp"
3

4
# Section for database
5
[database]
6
host = "localhost"
7
port = 5432

Execution

toml-parser config.toml

Output

name: "MyApp"
database:
  host: "localhost"
  port: 5432

Sections are defined with [section_name].
Keys within sections are nested under their section.

Data Types

Overview of all TOML data types and their representations.

All primitive data types

Demonstrates each TOML primitive data type with examples.

Code

1
# String
2
name = "Alice"
3

4
# Integer
5
count = 42
6

7
# Float
8
pi = 3.14159
9

10
# Boolean
11
enabled = true
12

13
# Date
14
birth = 1990-05-27
15

16
# Time
17
alarm = 15:30:00
18

19
# DateTime
20
created = 2021-12-25T10:30:00Z

Execution

toml-parser types.toml

Output

name: "Alice"
count: 42
pi: 3.14159
enabled: true
birth: 1990-05-27
alarm: 15:30:00
created: 2021-12-25T10:30:00Z

TOML supports 7 data types: String, Integer, Float, Boolean, Date, Time, DateTime.
Type inference is automatic in TOML.

Arrays and tables

Shows how to define arrays, tables, and arrays of tables.

Code

1
# Array
2
colors = ["red", "green", "blue"]
3

4
# Nested array
5
matrix = [[1, 2], [3, 4]]
6

7
# Table
8
[owner]
9
name = "Bob"
10

11
# Array of tables
12
[[products]]
13
id = 1
14
name = "Widget"

Execution

toml-parser complex.toml

Output

colors: ["red", "green", "blue"]
matrix: [[1, 2], [3, 4]]
owner:
  name: "Bob"
products: [{ id: 1, name: "Widget" }]

Arrays are enclosed in brackets with comma-separated values.
Tables group related key-value pairs together.

Key-Value Pairs

Syntax for defining keys and values in TOML documents.

Simple key-value pairs

Demonstrates basic key-value pair syntax with different data types.

Code

1
name = "Alice"
2
age = 30
3
active = true
4
score = 92.5

Execution

toml-parser simple.toml

Output

name: "Alice"
age: 30
active: true
score: 92.5

Keys are case-sensitive.
Values must be separated from keys by an equals sign (=).

Quoted and dotted keys

Shows quoted keys and dotted key notation for nesting.

Code

1
# Quoted key with spaces
2
"physical address" = "123 Main St"
3

4
# Single-quoted key
5
'special-key' = "value"
6

7
# Dotted key (nesting)
8
database.host = "localhost"
9
database.port = 5432
10
database.credentials.user = "admin"

Execution

toml-parser keys.toml

Output

physical address: "123 Main St"
special-key: "value"
database:
  host: "localhost"
  port: 5432
  credentials:
    user: "admin"

Quoted keys can contain any character.
Dotted keys create nested tables automatically.
Keys must be unique within their scope.

Bare and quoted key combinations

Combines bare and quoted keys for flexibility in naming.

Code

1
# Bare key (unquoted)
2
name = "Project"
3

4
# Keys with special characters must be quoted
5
"api-key" = "secret123"
6
"version 2.0" = true
7

8
# Mixed dotted keys
9
app.settings."user-preferences" = { theme = "dark" }

Execution

toml-parser mixed.toml

Output

name: "Project"
api-key: "secret123"
version 2.0: true
app:
  settings:
    user-preferences:
      theme: "dark"

Bare keys can only contain A-Z, a-z, 0-9, -, and _.
Quote keys if they contain other characters.

Strings

Working with string values in TOML documents.

Basic Strings

Double-quoted strings with escape sequences and special characters.

Simple string values

Basic string values enclosed in double quotes.

Code

1
title = "Hello World"
2
description = "A simple configuration file"
3
path = "C:\\Users\\Alice\\Documents"

Execution

toml-parser strings.toml

Output

title: "Hello World"
description: "A simple configuration file"
path: "C:\\Users\\Alice\\Documents"

Strings are enclosed in double quotes.
Backslashes can be included by escaping them.

Escaped characters

Various escape sequences used in TOML strings.

Code

1
# Common escape sequences
2
tab = "Column1\tColumn2"
3
newline = "Line1\nLine2"
4
quote = "She said \"Hello!\""
5
backslash = "C:\\path\\to\\file"
6
unicode = "Café: \u00e9"

Execution

toml-parser escaped.toml

Output

tab: "Column1  Column2"
newline: "Line1\nLine2"
quote: "She said \"Hello!\""
backslash: "C:\path\to\file"
unicode: "Café: é"

Use \t for tabs, \n for newlines, \" for quotes.
Use \u for 4-digit Unicode escapes, \U for 8-digit.

Multiline Strings

Triple-quoted strings for multi-line content with literal or folded modes.

Multiline basic string

A basic multiline string using triple double quotes.

Code

1
description = """
2
This is a multiline
3
string with multiple
4
lines of text."""

Execution

toml-parser multiline.toml

Output

description: "This is a multiline\nstring with multiple\nlines of text."

Multiline strings preserve newlines.
The first newline after the opening quotes is trimmed.
Escape sequences still work in multiline strings.

Multiline literal string

Literal multiline strings preserve content exactly, no escaping needed.

Code

1
path = '''
2
C:\Users\Alice
3
C:\Users\Bob
4
'''

Execution

toml-parser literal.toml

Output

path: "C:\Users\Alice\nC:\Users\Bob"

Literal strings use triple single quotes.
No escape sequences are processed in literal strings.
Useful for paths, JSON, or other literal content.

Line folding in multiline strings

Using backslash to fold long lines without adding newlines.

Code

1
text = """
2
This is a long line \
3
that continues \
4
on the next line."""

Execution

toml-parser fold.toml

Output

text: "This is a long line that continues on the next line."

A backslash at the end of a line continues to the next without adding a newline.
This helps keep long strings readable.

String Escape Sequences

All available escape sequences in TOML strings.

Common escape sequences

Standard escape sequences for control and special characters.

Code

1
backspace = "Back\bspace"
2
tab = "Tab\there"
3
linefeed = "Line\nfeed"
4
form_feed = "Form\ffeed"
5
carriage_return = "Return\rhere"
6
quote = "Quote: \"Hello\""
7
backslash = "Backslash: \\"

Execution

toml-parser escapes.toml

Output

backspace: "Back\bspace"
tab: "Tab  here"
linefeed: "Line\nfeed"
form_feed: "Form\ffeed"
carriage_return: "Return\rhere"
quote: "Quote: \"Hello\""
backslash: "Backslash: \"

\b = backspace (U+0008)
\t = tab (U+0009)
\n = line feed (U+000A)
\f = form feed (U+000C)
\r = carriage return (U+000D)
\" = quotation mark (U+0022)
\\ = backslash (U+005C)

Unicode escape sequences

Unicode escapes for 4-digit and 8-digit code points.

Code

1
# 4-digit Unicode escape
2
emoji = "Smile: \u263A"
3

4
# 8-digit Unicode escape
5
complex = "Mathematical: \U0001D400"
6

7
# Mix with characters
8
text = "Greek: \u03B1\u03B2\u03B3"

Execution

toml-parser unicode.toml

Output

emoji: "Smile: ☺"
complex: "Mathematical: 𝐀"
text: "Greek: αβγ"

\uXXXX for 4-digit Unicode escapes (U+0000 to U+FFFF)
\UXXXXXXXX for 8-digit Unicode escapes (U+00000000 to U+7FFFFFFF)
Use for emoji and special characters not easily typed.

Tables and Nesting

Defining and organizing tables in TOML documents.

Basic Tables

Simple table headers, dot-separated keys, and subtables.

Simple table definition

Defines two tables with their respective key-value pairs.

Code

1
[owner]
2
name = "Alice"
3
email = "alice@example.com"
4

5
[database]
6
host = "localhost"
7
port = 5432

Execution

toml-parser tables.toml

Output

owner:
  name: "Alice"
  email: "alice@example.com"
database:
  host: "localhost"
  port: 5432

Tables are headers enclosed in brackets [table_name].
Keys after a table belong to that table.
Whitespace in table names is allowed only in quoted names.

Nested tables with dot notation

Shows both dot notation and explicit table headers for nesting.

Code

1
# Using dot notation for subtables
2
database.connection.host = "localhost"
3
database.connection.port = 5432
4
database.connection.ssl = true
5

6
[database.credentials]
7
user = "admin"
8
password = "secret"

Execution

toml-parser nested.toml

Output

database:
  connection:
    host: "localhost"
    port: 5432
    ssl: true
  credentials:
    user: "admin"
    password: "secret"

Dotted keys create nested tables automatically.
Can mix dotted keys with explicit table headers.
Parent tables are created automatically if needed.

Nested subtables

Hierarchical nesting of tables using bracket notation.

Code

1
[server]
2
host = "0.0.0.0"
3
port = 8080
4

5
[server.ssl]
6
enabled = true
7
cert = "/path/to/cert"
8

9
[server.ssl.options]
10
min_version = "TLSv1.2"

Execution

toml-parser subtables.toml

Output

server:
  host: "0.0.0.0"
  port: 8080
  ssl:
    enabled: true
    cert: "/path/to/cert"
    options:
      min_version: "TLSv1.2"

[parent.child] defines subtables of parent.
Each table must be defined only once (no redefinition).

Array of Tables

Using [[array.of.tables]] syntax for multiple table items.

Simple array of tables

Creates an array of table elements with multiple items.

Code

1
[[products]]
2
id = 1
3
name = "Widget"
4
price = 9.99
5

6
[[products]]
7
id = 2
8
name = "Gadget"
9
price = 19.99

Execution

toml-parser array_tables.toml

Output

products:
  - id: 1
    name: "Widget"
    price: 9.99
  - id: 2
    name: "Gadget"
    price: 19.99

[[table_name]] appends a new table to an array.
Each [[table_name]] block creates a new element.
All elements have the same structure.

Nested array of tables

Array of tables nested within a parent table.

Code

1
[package]
2
name = "my-package"
3

4
[[package.dependencies]]
5
name = "requests"
6
version = "2.28.0"
7

8
[[package.dependencies]]
9
name = "flask"
10
version = "2.0.0"

Execution

toml-parser nested_array.toml

Output

package:
  name: "my-package"
  dependencies:
    - name: "requests"
      version: "2.28.0"
    - name: "flask"
      version: "2.0.0"

[[parent.child]] creates an array within the parent table.
Each child table is a separate element in the array.

Multiple arrays of tables

Multiple independent arrays of tables in the same document.

Code

1
[[users]]
2
name = "Alice"
3
role = "admin"
4

5
[[users]]
6
name = "Bob"
7
role = "user"
8

9
[[projects]]
10
title = "Project A"
11
owner = "Alice"
12

13
[[projects]]
14
title = "Project B"
15
owner = "Bob"

Execution

toml-parser multiple_arrays.toml

Output

users:
  - name: "Alice"
    role: "admin"
  - name: "Bob"
    role: "user"
projects:
  - title: "Project A"
    owner: "Alice"
  - title: "Project B"
    owner: "Bob"

Each [[name]] creates a separate array.
Arrays can be defined independently.

Nested Structures

Complex deeply nested tables and hierarchical data.

Deeply nested tables

Demonstrates multiple levels of nesting with different branches.

Code

1
[server.http.handlers.api]
2
endpoint = "/api/v1"
3
timeout = 30
4

5
[server.http.handlers.websocket]
6
endpoint = "/ws"
7
timeout = 0
8

9
[server.https.ssl]
10
cert = "/path/to/cert"
11
key = "/path/to/key"

Execution

toml-parser deep_nesting.toml

Output

server:
  http:
    handlers:
      api:
        endpoint: "/api/v1"
        timeout: 30
      websocket:
        endpoint: "/ws"
        timeout: 0
  https:
    ssl:
      cert: "/path/to/cert"
      key: "/path/to/key"

TOML supports unlimited nesting depth.
Use clear naming to avoid confusion in deeply nested structures.
Dotted keys can simplify defining deeply nested values.

Complex hierarchical structure

Combines tables, arrays of tables, and nested structures.

Code

1
[app]
2
name = "MyApp"
3
version = "1.0.0"
4

5
[app.features]
6
auth = true
7
api = true
8
websocket = false
9

10
[[app.features.modules]]
11
name = "Auth"
12
enabled = true
13

14
[[app.features.modules]]
15
name = "API"
16
enabled = true
17

18
[app.logging]
19
level = "info"
20
format = "json"

Execution

toml-parser complex_nested.toml

Output

app:
  name: "MyApp"
  version: "1.0.0"
  features:
    auth: true
    api: true
    websocket: false
    modules:
      - name: "Auth"
        enabled: true
      - name: "API"
        enabled: true
  logging:
    level: "info"
    format: "json"

Mix different structure types for flexibility.
Organize by functionality or domain.

Data Types

Detailed coverage of TOML data types and representations.

Numbers

Integers, floats, scientific notation, and underscores in numbers.

Integer number formats

TOML supports decimal, hexadecimal, octal, and binary integers.

Code

1
# Decimal integers
2
count = 42
3
negative = -17
4

5
# Hexadecimal (0x prefix)
6
hex_value = 0xDEADBEEF
7

8
# Octal (0o prefix)
9
octal = 0o755
10

11
# Binary (0b prefix)
12
binary = 0b11010110

Execution

toml-parser integers.toml

Output

count: 42
negative: -17
hex_value: 3735928559
octal: 493
binary: 214

Integers are 64-bit signed numbers.
Leading zeros are not allowed in decimal notation.
Hex, octal, and binary integers have specific prefixes.

Float number formats

TOML supports standard floats, scientific notation, and special values.

Code

1
# Standard float
2
pi = 3.14159
3

4
# Negative float
5
temperature = -40.0
6

7
# Scientific notation
8
large = 5e+22
9
small = 1.47e-12
10

11
# Special float values
12
infinity = inf
13
neg_infinity = -inf
14
not_number = nan

Execution

toml-parser floats.toml

Output

pi: 3.14159
temperature: -40.0
large: 5e+22
small: 1.47e-12
infinity: Infinity
neg_infinity: -Infinity
not_number: NaN

Floats are 64-bit (IEEE 754 double precision).
Scientific notation uses 'e' or 'E'.
Special values inf, -inf, nan represent infinity and NaN.

Numbers with underscores

Underscores improve readability of large numbers.

Code

1
# Readable large numbers
2
million = 1_000_000
3
phone = 555_123_4567
4
binary = 0b1010_1010
5

6
# Floats with underscores
7
pi = 3.14_159_265
8
scientific = 1.602_176_634e-19

Execution

toml-parser underscores.toml

Output

million: 1000000
phone: 5551234567
binary: 170
pi: 3.14159265
scientific: 1.602176634e-19

Underscores can be placed between digits for readability.
Leading/trailing underscores are not allowed.
Underscores are ignored during parsing.

Booleans and Null

Boolean true/false values and null representation in TOML.

Boolean values

TOML uses lowercase true and false for boolean values.

Code

1
# Boolean values are lowercase
2
enabled = true
3
debug = false
4

5
[features]
6
auth = true
7
logging = false
8
updates = true

Execution

toml-parser booleans.toml

Output

enabled: true
debug: false
features:
  auth: true
  logging: false
  updates: true

Boolean values are lowercase (true, false).
No yes/no or on/off alternatives in TOML.
Booleans are distinct from strings.

Representing null or absence

TOML doesn't have a null type; use conventions or omit keys.

Code

1
# TOML doesn't have a native null type
2
# Options for representing absence:
3

4
# 1. Omit the key entirely
5
# optional_field = (not present)
6

7
# 2. Use empty string
8
empty = ""
9

10
# 3. Use special marker values
11
null_marker = "null"
12
unset = "unset"
13
none = "none"

Execution

toml-parser null.toml

Output

empty: ""
null_marker: "null"
unset: "unset"
none: "none"

TOML does not have a native null or None value.
Omit the key entirely to represent absence.
Use empty string or special marker strings if needed.

Dates and Times

ISO 8601 formatted dates, times, and datetimes with timezone support.

Date and time formats

Basic date, time, and local datetime formats in ISO 8601.

Code

1
# Date (RFC 3339 profile of ISO 8601)
2
birthday = 1990-05-27
3

4
# Time (no date)
5
alarm = 15:30:00
6

7
# Local DateTime (date and time, no timezone)
8
meeting = 2021-12-25T10:30:00

Execution

toml-parser dates.toml

Output

birthday: 1990-05-27
alarm: 15:30:00
meeting: 2021-12-25T10:30:00

Dates follow YYYY-MM-DD format.
Times follow HH:MM:SS or HH:MM:SS.ffffff format.
LocalDateTime combines date and time without timezone.

Datetime with timezone

Datetime values with timezone information and fractional seconds.

Code

1
# UTC timezone (Z suffix)
2
created = 2021-12-25T10:30:00Z
3

4
# With offset
5
eastern = 2021-12-25T10:30:00-05:00
6

7
# With positive offset
8
tokyo = 2021-12-25T10:30:00+09:00
9

10
# Milliseconds precision
11
precise = 2021-12-25T10:30:00.123Z

Execution

toml-parser datetimes.toml

Output

created: 2021-12-25T10:30:00Z
eastern: 2021-12-25T10:30:00-05:00
tokyo: 2021-12-25T10:30:00+09:00
precise: 2021-12-25T10:30:00.123Z

Z suffix indicates UTC (Zulu) time.
Offset format is ±HH:MM.
Fractional seconds support up to nanosecond precision.

Advanced Features

Advanced TOML features for complex configurations.

Inline Tables

Compact single-line table syntax with {key = value} format.

Simple inline table

Inline tables provide a compact way to define tables on a single line.

Code

1
point = { x = 1, y = 2 }
2
color = { r = 255, g = 128, b = 0 }
3
person = { name = "Alice", age = 30 }

Execution

toml-parser inline.toml

Output

point:
  x: 1
  y: 2
color:
  r: 255
  g: 128
  b: 0
person:
  name: "Alice"
  age: 30

Inline tables are enclosed in curly braces.
Keys and values are separated by equals with optional spaces.
Inline tables cannot span multiple lines.

Nested inline tables

Inline tables can be nested and used in arrays.

Code

1
# Inline table containing inline table
2
config = {
3
  database = { host = "localhost", port = 5432 },
4
  cache = { host = "redis", ttl = 3600 }
5
}
6

7
# Array of inline tables
8
points = [
9
  { x = 0, y = 0 },
10
  { x = 1, y = 2 },
11
  { x = 3, y = 4 }
12
]

Execution

toml-parser nested_inline.toml

Output

config:
  database:
    host: "localhost"
    port: 5432
  cache:
    host: "redis"
    ttl: 3600
points:
  - x: 0
    y: 0
  - x: 1
    y: 2
  - x: 3
    y: 4

Inline tables cannot be redefined or extended later.
Useful for simple, fixed data structures.

Advanced DateTime

Offset datetimes, local datetimes, and time precision handling.

All datetime variants

Examples of all TOML datetime type variants.

Code

1
# Offset DateTime (with timezone)
2
utc_time = 2021-12-25T10:30:00Z
3
eastern_time = 2021-12-25T10:30:00-05:00
4

5
# Local DateTime (no timezone)
6
local_meeting = 2021-12-25T10:30:00
7

8
# Local Date (no time)
9
deadline = 2021-12-31
10

11
# Local Time (no date)
12
opening_time = 09:00:00

Execution

toml-parser all_datetime.toml

Output

utc_time: 2021-12-25T10:30:00Z
eastern_time: 2021-12-25T10:30:00-05:00
local_meeting: 2021-12-25T10:30:00
deadline: 2021-12-31
opening_time: 09:00:00

Offset DateTime includes timezone information.
Local DateTime is timezone-naive.
Local Date and Local Time can exist independently.

Fractional seconds and precision

Demonstrates various precision levels in fractional seconds.

Code

1
# Milliseconds
2
ms_precision = 2021-12-25T10:30:00.123Z
3

4
# Microseconds
5
us_precision = 2021-12-25T10:30:00.123456Z
6

7
# Nanoseconds
8
ns_precision = 2021-12-25T10:30:00.123456789Z
9

10
# Trailing zeros
11
long_precision = 2021-12-25T10:30:00.1Z

Execution

toml-parser precision.toml

Output

ms_precision: 2021-12-25T10:30:00.123Z
us_precision: 2021-12-25T10:30:00.123456Z
ns_precision: 2021-12-25T10:30:00.123456789Z
long_precision: 2021-12-25T10:30:00.1Z

Fractional seconds are optional and can be 1-9 digits.
No precision loss; values are preserved as specified.

Comments and Formatting

Effective commenting and formatting practices in TOML.

Effective commenting

Shows effective use of comments for documentation.

Code

1
# Main application configuration
2
# Last updated: 2025-02-28
3

4
title = "MyApp"  # Application title
5
version = "1.0.0"
6

7
# Database connection settings
8
[database]
9
host = "localhost"  # Database server hostname
10
port = 5432         # Standard PostgreSQL port
11
ssl = true          # Enable SSL for secure connections

Execution

toml-parser commented.toml

Output

title: "MyApp"
version: "1.0.0"
database:
  host: "localhost"
  port: 5432
  ssl: true

Comments start with
Inline comments are allowed after values.
Comments help clarify non-obvious configuration.

Organized file structure

Well-organized file structure with clear section headers.

Code

1
# ============================================================================
2
# Application Configuration
3
# ============================================================================
4

5
[metadata]
6
name = "MyApp"
7
version = "1.0.0"
8
author = "Team"
9

10
# ============================================================================
11
# Server Configuration
12
# ============================================================================
13

14
[server]
15
host = "0.0.0.0"
16
port = 8080
17

18
[server.ssl]
19
enabled = true
20
cert = "/path/to/cert"
21

22
# ============================================================================
23
# Database Configuration
24
# ============================================================================
25

26
[database]
27
url = "postgresql://localhost/mydb"

Execution

toml-parser organized.toml

Output

metadata:
  name: "MyApp"
  version: "1.0.0"
  author: "Team"
server:
  host: "0.0.0.0"
  port: 8080
  ssl:
    enabled: true
    cert: "/path/to/cert"
database:
  url: "postgresql://localhost/mydb"

Use visual separators (comment lines) for clarity.
Group related configurations into sections.
Maintain consistent formatting throughout the file.

Best Practices

Best practices for writing effective TOML configurations.

Common Patterns

Patterns used in real-world TOML files and package manifests.

Cargo.toml (Rust) style

Standard structure of Cargo.toml for Rust projects.

Code

1
[package]
2
name = "my-app"
3
version = "0.1.0"
4
edition = "2021"
5
description = "My awesome application"
6
authors = ["Me <me@example.com>"]
7

8
[dependencies]
9
serde = { version = "1.0", features = ["derive"] }
10
tokio = { version = "1.0", features = ["full"] }
11

12
[dev-dependencies]
13
pytest = "0.13"
14

15
[profile.release]
16
opt-level = 3

Execution

cargo build

[package] section contains metadata.
[dependencies] lists production dependencies.
[dev-dependencies] for testing dependencies.
Feature specifications are common.

pyproject.toml (Python) style

Standard structure of pyproject.toml for Python projects.

Code

1
[project]
2
name = "my-package"
3
version = "0.1.0"
4
description = "A Python package"
5
authors = [{name = "Alice", email = "alice@example.com"}]
6
requires-python = ">=3.8"
7

8
[project.dependencies]
9
requests = ">=2.0"
10
flask = ">=2.0"
11

12
[build-system]
13
requires = ["setuptools", "wheel"]
14
build-backend = "setuptools.build_meta"

Execution

pip install .

[project] contains package metadata.
Author details use inline table format.
[build-system] specifies build requirements.

Application config file pattern

Typical application configuration file structure.

Code

1
# [app.toml] - Server configuration
2
[app]
3
name = "MyService"
4
environment = "production"
5
debug = false
6

7
[server]
8
host = "0.0.0.0"
9
port = 8080
10
workers = 4
11

12
[database]
13
url = "postgresql://user:pass@localhost/db"
14
pool_size = 20
15

16
[logging]
17
level = "info"
18
format = "json"
19
file = "/var/log/myservice.log"
20

21
[[services]]
22
name = "auth"
23
url = "http://auth-service:8000"
24

25
[[services]]
26
name = "cache"
27
url = "redis://localhost:6379"

Execution

myapp --config app.toml

Metadata in [app] section.
Server/database settings in dedicated sections.
External services in array of tables.

Readability and Style

Organizing keys and maintaining consistent formatting.

Well-organized TOML file

Configuration organized for clarity and maintainability.

Code

1
# Services Configuration
2
# Well-organized with logical grouping
3

4
[metadata]
5
version = "1.0.0"
6
updated = 2025-02-28
7

8
[api]
9
# Core API settings
10
host = "0.0.0.0"
11
port = 8000
12
timeout = 30
13

14
[api.auth]
15
# Authentication configuration
16
enabled = true
17
jwt_secret = "your-secret-key"
18
token_expire_hours = 24
19

20
[api.cors]
21
# CORS settings
22
allowed_origins = ["http://localhost:3000"]
23
allowed_methods = ["GET", "POST", "PUT"]
24

25
[database]
26
host = "localhost"
27
port = 5432
28
name = "myapp"
29
pool_size = 20
30

31
[logging]
32
level = "info"
33
format = "json"

Execution

app --config config.toml

Use descriptive section names.
Add comments explaining purpose of sections.
Keep related items grouped together.
Use consistent indentation (though not required).

Naming conventions

Demonstrates consistent naming conventions.

Code

1
# ✓ Good naming conventions
2
[database]
3
connection_timeout = 10
4
max_pool_size = 20
5
retry_attempts = 3
6

7
[cache]
8
redis_host = "localhost"
9
redis_port = 6379
10
ttl_seconds = 3600
11

12
[service]
13
api_key = "secret"
14
api_version = "v1"
15
api_timeout = 30

Execution

app --validate-config

Output

Configuration is valid

Use snake_case for key names.
Use descriptive suffixes (_host, _port, _timeout, etc.).
Keep names consistent across similar settings.
Avoid ambiguous abbreviations.

Validation and Usage

Loading and parsing TOML files in programming languages.

Python - Loading TOML with tomllib

Python example using the built-in tomllib module (Python 3.11+).

Code

1
[app]
2
name = "MyApp"
3
debug = false
4

5
[database]
6
url = "postgresql://localhost/myapp"
7
pool_size = 20

Execution

1
import tomllib
2

3
with open('config.toml', 'rb') as f:
4
    config = tomllib.load(f)
5

6
print(config['app']['name'])
7
print(config['database']['pool_size'])

Output

MyApp
20

tomllib requires opened file in binary mode ('rb').
For older Python, use the 'tomli' package.
Returns a dictionary with nested structure.

Rust - Loading TOML with toml crate

Rust uses the toml crate to parse TOML files.

Code

1
[server]
2
host = "0.0.0.0"
3
port = 8080
4

5
[server.ssl]
6
cert = "/path/to/cert.pem"
7
key = "/path/to/key.pem"

Execution

cargo run

Output

Server listening on 0.0.0.0:8080

Rust has strong typing for TOML values.
Use serde for deserializing into structs.
Includes validation through type checking.

TOML validation and schema

Validation ensures TOML matches expected structure.

Code

1
# Configuration that should be validated
2
[app]
3
name = "Service"
4

5
# Required fields: app.name, server.port
6
# Optional fields: debug, logging.level
7

8
[server]
9
port = 8080
10
# host must be an IP or hostname
11
host = "0.0.0.0"
12

13
[logging]
14
level = "info"  # must be: debug, info, warn, error

Execution

validate-toml --schema config.schema.json config.toml

Output

Configuration is valid

JSON Schema can define TOML structure.
Type checking during deserialization.
Document required vs optional fields.

TOML

Getting Started

Basic Syntax

Accessibility

Best Practices

Common Errors

Keywords

Simple TOML file with comments

Multi-line structure with sections

Data Types

Accessibility

Best Practices

Common Errors

Keywords

All primitive data types

Arrays and tables

Key-Value Pairs

Accessibility

Best Practices

Common Errors

Keywords

Simple key-value pairs

Quoted and dotted keys

Bare and quoted key combinations

Strings

Basic Strings

Accessibility

Best Practices

Common Errors

Keywords

Simple string values

Escaped characters

Multiline Strings

Accessibility

Best Practices

Common Errors

Keywords

Multiline basic string

Multiline literal string

Line folding in multiline strings

String Escape Sequences

Accessibility

Best Practices

Common Errors

Keywords

Common escape sequences

Unicode escape sequences

Tables and Nesting

Basic Tables

Accessibility

Best Practices

Common Errors

Keywords

Simple table definition

Nested tables with dot notation

Nested subtables

Array of Tables

Accessibility

Best Practices

Common Errors

Keywords

Simple array of tables

Nested array of tables

Multiple arrays of tables

Nested Structures

Accessibility

Best Practices

Common Errors

Keywords

Deeply nested tables

Complex hierarchical structure

Data Types

Numbers

Accessibility

Best Practices

Common Errors

Keywords

Integer number formats

Float number formats

Numbers with underscores