What is the correct way to use the data in YAML - e.g. duration in a timer

Configuration
1

Hi
I have been working on using a timer in a light automation. It is all working fine after reading the documentation combined with some examples from this forum

I have a generic question to the use of the data key on YAML

I have these two working examples of starting a timer in an action in an automation

  action:
    - service: timer.start
      data:
        entity_id: timer.office_light
        duration: '00:05:00'

  action:
    - service: timer.start
      entity_id: timer.office_light
      data:
        duration: '00:05:00'

This example does not work.

  action:
    - service: timer.start
      entity_id: timer.office_light
      duration: '00:05:00'

The duration clearly must be under a data or data_template

My question is a generic question about YAML in Home Assistant and not related to timer. It does work for me. I just want to understand better so I and others reading this can become more effective writing correct configs the first time

Why do the first two examples both work? When do I need to put the entity_id under data and when do I not? And when do I need the data key? Is there a good document I have overlooked that explains this?

Of my two examples - is one considered preferred? I’d like to submit a document update PR to add the duration override example to the timer documentation.

2

See my answer to a similar question a while ago…

3

maybe this one?

imho the first one (with everything inside data) looks more consistent

4

Thanks for two good answers

And each of you point to different answers. :wink:

I personally ended up with both under data based on taste. But it is not clear from the answers if one is more correct than the other. The official documentation that Ahmad point to suggests the entity_id to be outside the data. And then Ahmad suggests it is nice inside.

mf_social suggests the outside form is a shortcut. But yes the documentation suggests it as normal even with data

So far i’d say they are both equal. Any other answers?

At the moment I lean on making my PR for adding the duration example to timer documentation as the example from the service calls doc.

I would love to understand why both work but I guess that means understanding how HA parses the configs and that is probably not easy to explain in words

5

They’re both exactly the same as far as homeassistant is concerned, I’ve explained it as best I can in the other thread.

If you type

service: homeassistant.turn_on 
entity_id: light.cabinet

Homeassistant sees

service: homeassistant.turn_on 
data:
  entity_id: light.cabinet

Being able to ‘level up’ the entity_id is for convenience and neatness as in the majority of cases when you run a service the only data you are sending is the entity_id.

1 Like
6

My interpretation has been this:

It’s all about the service. Anything else supplied is information (data) for the service.

So this is the ‘formal’ version:

service: do.something
data:
  entity_id: some.thing
  option_a: foo
  option_z: foobar

However, very often the only data required is the entity_id so, being near and dear to the service’s heart, it gets a pass on formality and this is acceptable:

service: do.something
entity_id: some.thing

or this:

service: do.something
entity_id: some.thing
data:
  option_a: foo
  option_z: foobar

BTW, although the following is functional, it looks like hell and reminds me of Reverse Polish Notation (RPN). Avoid this like the plague:

entity_id: some.thing
data:
  option_a: foo
  option_z: foobar
service: do.something
2 Likes
7

I agree.

It used to be the same way with the output from the automation editor (it may still be that way since I don’t use it).

the output as it was put in the config was alphabetical order so when you read it it was:

action:
  entity_id:
  data:
  service:
condition:
trigger:
  entity_id:
  platform: