When to use '-' in yaml files?

Configuration
1

Can someone please point me to a good tutorial on HA’s use of yaml and the ‘-’ dash usage. I can’t seem to figure out when one is needed or not :frowning:

thanks.

2

Hyphens indicate list items, as well as key value pairs.

Great explanation here https://www.google.co.uk/amp/s/amp.reddit.com/r/ansible/comments/5jhff3/when_to_use_dash_in_yaml/

2 Likes
3

No. Dashes/hyphens only indicate the start of a list item, no matter what type that item may be. They have nothing to do with key-value pairs (i.e., dictionary items.)

E.g.:

a:
  - b: c
  - b: d
e:
  - f
  - g

Both a’s and e’s values are lists, even though a’s list elements are dictionaries (aka maps), whereas e’s list elements are strings.

BTW, it’s important to note that the dash indicates the start of a list item. If that list item happens to be key-value pair, then it’s possible the list item may have multiple key-value pairs. E.g.:

a:
  - b: c1
    d: e1
  - d: e2
    b: c2

In this case a is a list of two items, where each item is a dictionary containing two key-value pairs. The order of the key-value pairs doesn’t matter. What matters is that a line with the dash is the start of a new list item.

6 Likes
4

Thank you! I understand that now… next will be to see if i can figure out when HA needs lists or not… which as I “play” with it more, I think i’m getting the handle of.

5

Yeah, that can also sometimes be confusing, and I almost commented on that in my previous reply. Basically, it depends on the component/platform, and it should be defined in the docs. However, …

One thing often not mentioned is, for flexibility, sometimes parameters accept more than one type of value. E.g., entity_id - this (normally) can be a single string item, a list of strings item, or a comma separated list of strings item. So, all of the following are (usually) ok:

entity_id: entity_id1
entity_id:
  - entity_id1
entity_id:
  - entity_id1
  - entity_id2
entity_id: entity_id1, entity_id2
entity_id: [entity_id1, entity_id2]

Note this last one is YAML’s alternative way to define a list (instead of putting the items on separate lines with dashes.)

Another common scenario (kind of a subset of the above) is when something accepts a list, but also accepts a single item. E.g., in sensor definitions, in automation triggers, conditions and actions, and in script sequences, when you want to define one item, you can do it with or without the dash. So, e.g., the following are both acceptable:

automation:
  - alias: Example1
    trigger:
      - platform: state
        entity_id: entity_id1
        to: 'on'
    ...
  - alias: Example2
    trigger:
      platform: state
      entity_id: entity_id1
      to: 'on'
    ...

To be clear, they are different, but they effectively do the same thing. In the first case, the trigger is a list of one dictionary, whereas the second case the trigger is a dictionary. But, for flexibility, the code accepts either.

6 Likes
6

So… reading this I’ve understood

  • what a list is
  • that you can specify lists or dictionarys in a lot of cases
  • even though the code accepts both versions, they are different
  • lists can be structured in several ways

What i still don’t understand:

  • When to use a list vs an dictionary
  • How they are different in cases where both are accepted
  • What the list exactly means to home assistant
2 Likes
7

@Davst i must admit, i’m a bit like you… and have been coding for a very long time. YAML is great, but confusing at the same time. Too bad they don’t allow JSON directly (which the YAML file is converted to anyways, so could be done).
I still do a bit of trial and error. Thankfully there are so many examples, I typically don’t have any issues.

8

@marcusone Yes… there are a few examples… though something that I’ve found frustrating is that the example parts are often not complete.

If I paste the example into the code… it lacks some structure. I do see the point of having examples that show just the bit of code that they are speaking of… but that also makes it a bit frustrating to understand as there aren’t enough complete examples.

I’d love to be able to see the tidbit and the overall code example in some way.

At the moment I find the public configs i find on github a lot more understandable than the documentations examples.

1 Like
9

As a noob, I see this a lot too. A lot of assumptions go into the examples people post. Like we’re just supposed to be born knowing this stuff.

I understand in the interest of space, it’s not always good to start from the very beginning for every example and answer.

But please, consider the newbie who just doesn’t have a clue where to put your sample code, and provide a few hints to put it in context. Thank you!!

1 Like
10

I use YAML quite a bit, personally and professionally, and usually muddle through without too much difficulty. However, it was really nice to read this plain English description you’ve laid out above. Really helped crystallize it for me.

1 Like