Toml: Plural vs singular naming convention for arrays vs inline arrays of tables

[mqudsi]

I've been a long-time advocate of TOML for user-editable configuration files, but I have a recurring problem caused by the visual differences between tables and inline tables that I believe naming conventions could help with, mainly by strongly suggesting one option over the other so the developer doesn't have to be burdened/tortured with the choice.

The problem: I believe it is more natural to express the key for an inline array of tables as plural, but the key for an "expanded" array of tables in singular, e.g.

products = [
    { name = "foo", price = 42.00 },
    { name = "bar", price = 42.00 },
]

and

[[product]]
name = "foo"
price = 42.00

[[product]]
name = "bar"
price = 42.00

I don't know if it's on purpose to avoid coming across as making a recommendation one way or the other, but the documentation (as of 1.0.0-rc.3) uses both styles when demonstrating array-of-table notation:

plural key:

[[products]]
name = "Hammer"
sku = 738594937

[[products]]

[[products]]

and singular keys (for both fruit¹ and variety):

[[fruit]]
  name = "apple"

  [fruit.physical]  # subtable
    color = "red"
    shape = "round"

  [[fruit.variety]]  # nested array of tables
    name = "red delicious"

  [[fruit.variety]]
    name = "granny smith"

[[fruit]]
  name = "banana"

  [[fruit.variety]]
    name = "plantain"

¹ Technically the choice of "fruit" here makes it all the more ambiguous as both "fruit" and "fruits" may be used for the plural, depending on whether it is being treated as a collective noun or not. However, "variety" would always have to be "varieties", so there's that.

---

When ultimately expressed as code (or viewed as JSON), it's clear that the plural key makes the most sense. However, when viewing/editing the TOML directly, I feel the singular notation has the upper hand as it is referring to one member of the array at a time. Of course, the two notations are directly convertible to one-another (apart from the ergonomics of how long an inline table can be), so therein lies the rub.

Some options (not necessarily endorsed or recommended by this developer):

• Leave things as they are with a mix of both expressed in the documentation so we don't have to make an official recommendation. Each developer that thinks deeply enough about the semantics of their TOML files will need to make this decision for their self. This results in one of the notations being less intuitive.
• Make a suggestion one way or the other to ease the decision making process for any developers adopting TOML. This results in one of the notations being less intuitive.
• Suggest that inline arrays be expressed in plural and expanded arrays be expressed in the singular. This results in the most intuitive syntax for both users dealing with the text file and developers dealing with the serialized object, but at the cost of non-negligibly complicating both serialization and deserialization routines (unless the unlikely case that all libraries provide some sort of overload accepting the "singular key" and "plural key" values).

FWIW, this isn't the first time I've run into this issue with TOML. The two different notations for expressing an array of tables always throw me off, usually enough to make me wish there were only one way even if it wasn't the way that I prefer.

[eksortso]

@mqudsi Thanks for your comments. I think this sort of thing is important (although it isn't exclusive to TOML) because proper configuration design ought to take good name choices into account. My only complaint is there's no such thing as an "inline array" of anything. An array of inline tables, that makes sense.

What do people here think? Should we modify the examples in README.md and toml.md to take singular vs. plural into account? And if so, what changes need to be made?

[pradyunsg]

Let's change all examples to be of the plural form -- fruits, varieties, products etc.

[eksortso]

Got it. Please review PR #784.