developers.home-assistant "Configuration variables" description standard clarity

Firstly, everything about configuration variables description IMO should be collected in one place (here, I suggest) and be referenced, where needed.

Secondly, there are some things that writers interpret differently. I see a lot of various formattings in the "components" section. This is how I interpret the documentation (although example Template sensor is formatted different way):

map type is a YAML mapping, where all key names are definite:
```
position:
  latitude: 12.345
  longitude: 32.123
```
position (map) (Required) Your position.

latitude (string) (Required) Latitude. longitude (string) (Required) Longitude.
(string is because float is not allowed)
list type is a YAML mapping, containing indefenite amount of similar objects with indefenite key names corresponding to them: Here Paul and Sarah are indefinite keys.
```
my_friends:
  Paul:
    second_name: "Johnson"
    age: 32
  Sarah:
    second_name: "Connor"
    age: 59
```
my_friends (list) (Optional) Your friends.

second_name (string) (Required) Your friend's second name. age (int) (Required) Your friend's age.

The documentation says nothing about YAML lists

prime_numbers:
  - 23
  - 7
  - 13

This leads to confusion. For example, repeat variable here is described as (int | list):

repeat:
  - 15
  - 30
  - 60

Here is another example to help you understand my point:

key_name:
  - name: Dave
    age: 21
    city: New York
  - name: Nathan
    age: 35
    city: Washington

Also, the exampled template sensor has a variable with device_class type, which is not listed in the standard.

Oct 03 '18 07:10 WofWca

Thank you!

One thing for sure, we need to add float as a type. Easy.
A list doesn't have to be a YAML mapping, it can be a non-associative array type of thing as well.

The (int | list) variant is actually correct, the field can accept an integer or a list of integers. I'm not sure how to make the definition any clearer on this (suggestions welcome of course).

The problem seems to be mainly around the following:

How to define a list of maps?
How to deferentiate between a list and a named list?

Right?

Oct 03 '18 09:10 frenck

Not quite. Considering what you said, the questions are:

How do we deal with indefinite key values? For example, how do we define my_friends here:
```
my_friends:
  Paul:
    second_name: "Johnson"
    age: 32
  Sarah:
    second_name: "Connor"
    age: 59
```
In fact, it is a map, but the number of keys and their names are indefenite. It can't be this:

my_friends (map) (Optional) Your friends.

second_name (string) (Required) Your friend's second name. age (int) (Required) Your friend's age.

Because what corresponds to this definition is, for example:
```
my_fiends:
  second_name: asd
  age: 123
```
What if the value is only allowed to be an array? How do we define the type of its elements in that case? Is it like (integer | list)? But it correlates with the definition of a value that can be either a list or an integer?

Oct 03 '18 10:10 WofWca