Proposal: allow numeric segments in dotted keys to represent array indexes

[danielb2]

TOML allows dotted keys to construct nested hash tables:

foo.bar.baz = 1

This proposal suggests allowing unquoted numeric segments in dotted keys to represent array indexes.

Example:

foo.0.bar = 1
foo.1.bar = 2

This would produce the same structure as the existing TOML syntax:

[[foo]]
bar = 1

[[foo]]
bar = 2

Resulting data structure:

{
  "foo": [
    { "bar": 1 },
    { "bar": 2 }
  ]
}

Proposed semantics

Unquoted numeric segments in a dotted key represent array indexes.

Example:

foo.3.bar = 1

This expands the array to index 3. Missing indexes are created as empty tables.

Equivalent structure:

[[foo]]
[[foo]]
[[foo]]
bar = 1

Resulting structure:

{
  "foo": [
    {},
    {},
    {},
    { "bar": 1 }
  ]
}

Disambiguation

Quoted numeric segments remain literal keys.

Example:

foo."0".bar = 1

Here "0" is a string key, not an array index.

Type consistency

If a key is first used with a numeric segment, it becomes an array. Other uses that treat it as a table are invalid.

Example:

foo.0.bar = 1
foo.bar = 2   # invalid

This preserves TOML’s existing rule that a key cannot change type once defined.

Motivation

Many tools and programming environments represent hierarchical data using path semantics where arrays and objects share the same path model. Examples include JSON Pointer, jq, and yq.

Supporting numeric segments in dotted keys would:

• make TOML easier to generate programmatically
• improve interoperability with JSON/YAML tooling
• allow arrays of tables to be expressed using the same dotted-key mechanism already used for nested tables

Compatibility

This change would break existing TOML documents that rely on numeric bare keys such as:

foo.0.bar = 1

which currently means the string key "0".

Such cases would need to be written using quoted keys to preserve their current meaning:

foo."0".bar = 1

In practice, numeric bare keys appear to be uncommon in configuration files, but this proposal would still represent a backwards-incompatible change.

[arp242]

I don't think adding an entire new syntax alternative to create arrays really make things easier for anyone.

Also, incompatible changes are not really an option. It would have to be one[0]two = "val" or something else that won't break existing documents.