Boneyard Tools

TOML tables and arrays of tables explained

How JSON objects and arrays map onto TOML tables, inline arrays and the double-bracket array of tables syntax, with worked examples.

Tables are the backbone of a TOML file

In TOML a table is a named group of key and value pairs, written under a header in single square brackets such as [owner]. This is the direct counterpart of a JSON object, which is why the root of any document you convert must be an object rather than a list. When the converter meets a nested object it opens a new table whose header joins the parent and child names with a dot, for example [server.db]. Values that belong to a table always appear before its child tables, matching how TOML expects a section to be self contained.

Inline arrays versus arrays of tables

A JSON array can become one of two very different things in TOML. If the array holds only primitive values it is printed inline on a single line, like ports = [8001, 8002], because those values have no internal structure. If instead every element is an object, the converter switches to the array of tables form, writing a [[server]] header once for each element. The double brackets tell a TOML parser to append another table to the same named list rather than redefining it.

Why blank lines appear where they do

The converter inserts a single blank line before each table or array of tables header so the output stays readable. When a table contains no scalar values of its own and jumps straight to a child table, an extra blank line keeps headers such as [a] and [a.b] visually apart. These blank lines are cosmetic and have no effect on how a parser reads the file, but they make hand editing far easier.

Edge cases worth knowing

TOML has no null, so a JSON null is rendered as an empty string to keep the file valid, and you should strip those keys yourself if you want them gone. Keys made only of letters, digits, underscores or hyphens are left bare, while anything else is quoted as a basic string. An empty array is treated as an inline value and prints as [], not as an array of tables. Understanding these rules lets you predict the output before you even paste your JSON.

Frequently asked questions

When does an array use [[double brackets]]?

Only when the array is non-empty and every single element is an object. If even one element is a number, string or nested array, the whole thing is written as an inline array on one line instead.

Can a TOML file start with a table header?

Yes. If your root object has no top-level scalar keys, the first line can be a [table] or [[array of tables]] header. The converter simply omits the leading blank line in that case.

How deep can the nesting go?

There is no fixed limit beyond your browser memory. Each additional level of nested objects just adds another segment to the dotted table header, so [a.b.c.d] and deeper are all valid.