TOML Cheatsheet - Tables, Arrays & Cargo.toml

[table] declares one named block of keys and may appear only once for a given name, while [[array]] declares one element of an array — repeating the header appends another entry, and the keys that follow belong to that element rather than to the container. Practically: use [[array]] when the structure repeats and the entry count follows the content (a set of dependencies, a group of CI jobs), and [table] when the shape is fixed and you are simply naming a group of parameters (package metadata, a dependency table). Declaring an array table as if it were a plain table produces a duplicate-key error as soon as it repeats.

It depends on whether the value needs escapes or special characters interpreted. key = "value" is a basic string and interprets sequences such as \n, \t, backslash and double quote — use it when the value spans lines or contains special characters. key = 'value' is a literal string and is taken exactly as written, with no escape processing at all. Windows paths are the canonical case: the backslashes in C:\Users must be doubled in a basic string or they open an escape sequence, while a literal string takes them verbatim. The multi-line forms follow the same split: triple-double-quote keeps escapes, triple-single-quote keeps the content raw.

It becomes a string, not a boolean. Quoted "true" is an ordinary string and is a distinct type from the bare keyword true — a difference that surfaces immediately during config validation or at read time, where the program receives text instead of a switch. TOML booleans are the lowercase true and false only, with no quotes. A related trap is underscore-separated numerals: num = 1_000_000 is a valid integer written for readability, but mixing such forms carelessly yields a float where an integer was intended.

They are structurally equivalent but written differently. physical.color = "orange" is a dotted key: it can appear anywhere in the file, and the dots in the key are hierarchy separators. [physical.color] is a sub-table and occupies its own line. Both produce the same nested structure and do not conflict, but readability differs — a group of related settings reads more compactly as consecutive dotted keys, while a block that needs several lines is clearer as a sub-table. The inline table inline = { key1 = "value1", key2 = 2 } is a third form, suited to small structures that fit on one line.

Decide by whether timezone information is needed. date = 2026-07-19 is a local date, time = 14:30:00 a local time, and datetime = 2026-07-19T14:30:00 a local date-time without a zone; a trailing Z marks UTC and an offset such as +08:00 marks an explicit zone. Any timestamp crossing system boundaries should carry an offset or be expressed in UTC, because a zone-less value resolves to different instants depending on the host or container timezone — and that implicit conversion is very hard to trace back.