Arrays — Homogeneous Convention, Flexible in 1.0

Arrays look JSON-y, with TOML conveniences

TOML arrays are [a, b, c] — same syntax as JSON. Trailing commas are allowed (better than JSON's no-trailing-comma rule). Arrays can be multi-line for readability.

Homogeneous by convention; mixed in 1.0

TOML 0.5 required arrays to be homogeneous (all elements same type). TOML 1.0 relaxed this — mixed types are now legal. Most parsers still warn or document homogeneous-by-convention because consumer code is simpler.

Multi-line arrays

Newlines inside [ ] are allowed. Comments inside arrays work. This is exactly where TOML beats JSON for human-edited configs.

Principle: use multi-line arrays when the array has more than 3 elements or each element is non-trivial (a long path, a structured value, a value with a comment). The vertical layout makes diffs clean and review easy.

Code

Inline + multi-line arrays·toml

# Inline (short, simple)
colors = ["red", "green", "blue"]

# Multi-line (long, easier to diff)
allowed_origins = [
  "https://creativeworksofknowledge.com",
  "https://www.creativeworksofknowledge.com",
  "http://localhost:3000",     # dev only
  "http://localhost:5173",     # vite dev server
]

Trailing comma — TOML allows it·toml

fruits = [
  "apple",
  "banana",
  "cherry",   # ← trailing comma is fine
]

# Same in JSON would be a parse error.
# Same in YAML flow [a, b, c,] would also be a parse error in some parsers.
# TOML's spec is explicit: trailing comma OK.

Mixed types (TOML 1.0+)·toml

# TOML 1.0 allows mixed types — useful for variant lists
mixed = [1, "two", 3.0, true]

# Convention: keep homogeneous unless mixed is genuinely needed
# Arrays of tables (next lesson) handle structured-element cases better

Exercise

Find a long array in a YAML or JSON config you maintain. Convert it to TOML's multi-line form, with one item per line and a short comment explaining each unusual entry. Notice the diff: future-you reading this in a PR knows immediately why each entry exists. That's the human-readability tax JSON makes you pay.

Arrays — Homogeneous Convention, Flexible in 1.0

Arrays look JSON-y, with TOML conveniences

Homogeneous by convention; mixed in 1.0

Multi-line arrays

Code

External links

Exercise

Progress

Comments 0