Plural or singular names for nested data types

[JPBergsma]

During the discussion on PR#480, the issue came up that it was not clear how the data type of fields with nested values should be described. In the text, we seem to always use the plural form, e.g. list of lists of integers. But in the type field of the attribute descriptions, we sometimes use the singular form like "list of list of float" instead of the plural form "list of lists of floats". To be consistent, it would be good to use one form consistently. My preference would be to use the plural form, but @rartino prefers the singular form. I am therefore curious to hear what the opinions of others are.

Some more examples from the specification: line 2113: query-support-operators: List of Strings 2537: - Type: list of strings 2583: list of floats 2717: list of integers 2757: list of list of floats 2811: list of list of floats 2848: list of strings 2871: list of dictionary

[vaitkus]

Copying the relevant comment of @rartino for context:

My personal preference (which perhaps comes a bit from a programmer-first perspective) is to not mess around with pluralization in a declarative statement like this, just use the type name as we have defined them. So, for the above IMO it should be "Array of Object". However, in the bulk text where one uses full sentences I would write, e.g., "The value should be an array of objects". But I don't feel very strongly either way, so if no one backs me up on this view, <...>.

_Originally posted by @rartino in https://github.com/Materials-Consortia/OPTIMADE/pull/480#discussion_r1285513778_

[vaitkus]

After some though, I am probably with @JPBergsma on this one. Since the specification is mainly intended for a human reader, the full plural does seem a bit nicer. My priority list:

list of lists of floats > list of list of float > list of list of floats.

[rartino]

To clarify my position a little bit:

• To me, the formal type of the container is, e.g., list of list of float.

• When I write in human readable flowing text about what the thing contains (i.e., not just formally stating its type), I would say, e.g., "this thing is a list of lists of floats".

But, if we go with list of lists of floats for the specification, does that also apply to the info pages generated from the new property definitions under https://schemas.optimade.org? They do not yet recurse into container type declarations to provide nested types, but it is a simple fix I've been meaning to do for a long time. Should, e.g., https://schemas.optimade.org/defs/v1.2/properties/optimade/structures/lattice_vectors state "Type: list of lists of floats" (or should it be: "Type: list of list of float"?)

[JPBergsma]

But, if we go with list of lists of floats for the specification, does that also apply to the info pages generated from the new property definitions under https://schemas.optimade.org/? They do not yet recurse into container type declarations to provide nested types, but it is a simple fix I've been meaning to do for a long time. Should, e.g., https://schemas.optimade.org/defs/v1.2/properties/optimade/structures/lattice_vectors state "Type: list of lists of floats" (or should it be: "Type: list of list of float"?)

I think that it would be nice if you could make it "Type: list of lists of floats". To me, list and float are something countable, so I think the plural form should be used.

[JPBergsma]

We have discussed this further during the online optimade meeting on the 25th of August. The conclusion was that none of those present had a very strong opinion on this and that if someone would apply either of these two options consistently throughout the specification we would accept that change.