TOML (Tom’s Obvious, Minimal Language) is a popular configuration file format designed to be easy to read and write. One of its essential components is the table, which organizes data into structured groups. Properly naming tables in TOML is crucial for ensuring clarity, consistency, and functionality in your configuration files.

In this blog, we will discover TOML table naming rules. learn syntax, best practices, and restrictions for naming tables in TOML

What Are TOML Tables?

At the core of TOML are tables, which store data in key-value pairs. A table in TOML is defined by a header enclosed in square brackets ([]). The header marks the start of a new table, and the lines following it contain key-value pairs associated with that table. Tables can also be nested within one another, creating a hierarchical structure.

Basic Table Example

Let’s start with a simple example of a TOML file:

[fruit]
apple = "red"
orange = "orange"

Here, we have a table called [fruit], which contains two key-value pairs:

• apple = "red"
• orange = "orange"

TOML tables are unordered, meaning the order of key-value pairs within a table doesn’t matter. However, it’s still best practice to organize them in a logical, consistent way to improve readability.

TOML Table Naming Rules

TOML table names follow the same rules as TOML keys. This means:

• They must be unique within the document.
• They can be quoted if they contain special characters (e.g., spaces or dots).

Example: Nested Tables with a Special Character in the Name

[dog."tater.man"]
type.name = "pug"

JSON representation:

{
  "dog": {
    "tater.man": {
      "type": {
        "name": "pug"
      }
    }
  }
}

Here,

[dog."tater.man"] (Nested Table with Quoted Key)

• dog is the top-level table.
• "tater.man" is a subtable inside dog.
• The quotes around "tater.man" are necessary because it contains a dot (.), which TOML normally treats as a separator for nested tables.

type.name = "pug" (Nested Key-Value Pair)

• Inside the "tater.man" subtable, we create another subtable type.
• Inside type, we define name = "pug".

Note: 

• Quoted table names allow you to use dots (.) as part of the name, instead of indicating nested tables.
• Without quotes, tater.man would be interpreted as two nested tables (dog → tater → man). However, by using quotes, "tater.man" is treated as a single key under dog, making it work similarly to JSON.

Whitespace and Formatting Rules

Whitespace around the key is ignored. Similarly, indentation is treated as whitespace and ignored. However, it is best practice to avoid extraneous whitespace.

[a.b.c]       # Best practice: simple and clear
[ d.e.f ]     # Same as [d.e.f] (extra spaces ignored)
[ g .  h  . i ] # Same as [g.h.i] (extra spaces ignored)
[ j . "ʞ" . 'l' ] # Same as [j."ʞ".'l'] (mixed quotes are allowed)

Here,

• Spaces don’t matter, but avoid unnecessary spaces to keep things readable.
• Quotes (" ", ' ') are allowed in table names, useful when special characters are needed.

So,

• Use dot notation (.) to create nested tables.
• Whitespace around table names is ignored, but best practice is to keep it clean.
• Quotes can be used in table names if special characters are needed.

Avoid Defining a Table More Than Once

Just like keys, tables cannot be defined more than once. Doing so is invalid and will result in an error in TOML.

Incorrect Example 1:

You can’t redefine the [fruit] table like this:

[fruit]  
apple = "red"  

[fruit]  # This is invalid!
orange = "orange"

Incorrect Example 2:

This would also be invalid if you define a table and try to redefine part of it:

[fruit]  
apple = "red"  

[fruit.apple]  # This is also invalid!
texture = "smooth"

So, how do we correct this? As we now know, if a table already exists, trying to define it again results in an error. To avoid this, we can use a different table name, like ‘fruits‘ instead of ‘fruit.’

[fruit]      # Define fruit table
apple = "red"

[fruits.apple]  # Nested table inside "fruits" for apple-specific info
texture = "smooth"

This is just an example for understanding purposes, but the key takeaway is to avoid re-defining the same table name more than once.

Defining Tables Out-of-Order (Valid but Discouraged)

Although TOML allows you to define tables in any order, it’s discouraged to do so. Organizing your tables properly makes your code more readable and maintainable.

Example (Valid but Discouraged):

You can technically define tables out of order, but it’s not considered best practice.

[fruit.apple]   # Defining fruit.apple first
color = "green"

[animal]        # Then defining animal
species = "dog"

[fruit.orange]  # Finally defining fruit.orange
color = "orange"

While this is valid TOML syntax, the recommended approach is to group related tables together in order.

Example (Recommended):

It’s better to define related tables consecutively for clarity.

[fruit.apple]   # First define fruit.apple
color = "green"

[fruit.orange]  # Then define fruit.orange
color = "orange"

[animal]        # Then define animal
species = "dog"

This way, it is easier to follow, especially for people who are reading or editing the file.

Super-Tables Not Required

In TOML, you don’t always have to specify every level of hierarchy for your tables. TOML can infer the parent tables (super tables) automatically, making things simpler for you.

Basically, TOML knows how to handle nested tables without you defining all of them:

If you specify [x.y.z.w], TOML automatically understands the hierarchy:

• x → x.y → x.y.z → x.y.z.w.
• You don’t need to declare [x], [x.y], and [x.y.z] for this to work. Just go straight to the deepest level you need.

[x.y.z.w]  # This works without needing to define [x], [x.y], or [x.y.z]

You don’t need to define [x], [x.y], or [x.y.z] in advance; TOML will infer them.

Defining a super-table afterward is fine:

• You can define a higher-level table after nested ones, and it will still work. TOML will connect them properly.

[x.y.z.w]  # Defines the deepest nested table


[x]   # This works even after defining [x.y.z.w]

Conclusion

Understanding table naming rules in TOML is essential for writing clean and well-structured configuration files. Following best practices, avoiding common pitfalls, and using meaningful table names will make your TOML files more readable and maintainable.

By adhering to these guidelines, you can ensure your TOML configurations remain error-free and easy to understand.