Dot/Period at start of line in YAML - Not a YAML feature, so what does it do?

ImaginaryTango · January 5, 2025, 7:15am

In this good answer about using anchors and aliases, there’s an example in YAML that includes a block where the line starts with a period, then an anchor name. I can’t find anything in YAML about that and asked about it on Stack Exchange and was informed that YAML doesn’t use that kind of notation.

So apparently the dot at the start of the line is an ESPHome thing. Here’s part of the code used in the answer I link to:

.number: &AnchorDelay
    optimistic: true
    min_value: 0
    max_value: 600
    step: 1
    initial_value: 0
    web_server: &AnchorDelayWebServer
      sorting_group_id: sorting_group_switchmain
      sorting_weight: 30

number:
  - platform: template
    <<: *AnchorDelay
    id: "SwitchMainDelay"
    name: "Main Switch Delay"

What is it called and where can I find more information about using this technique to provide a name for an anchor and a data structure that will be used as a source for objects that are created later?

Mahko_Mahko · January 5, 2025, 10:12am

Well that is very interesting. News to me.

ImaginaryTango · January 5, 2025, 11:31am

And, as best I can tell, undocumented anywhere - but I’d need to know the name of this kind of function to be sure. Kind of hard to search for it when you don’t know the name of what it is!

juergenjw · January 5, 2025, 11:47am

ImaginaryTango · January 5, 2025, 12:42pm

Thanks, @juergenjw. That’s under Anchors and Aliases, though, and well documented. What I can’t find is the use of a dot or period to create a name for a section to be used as an anchor. I asked about it on SE here, but the closest to an answer was a very short discussion in the comments.

juergenjw · January 5, 2025, 1:36pm

I did some tests with your example and i think that for esphome it is a key that is ignored/hidden and is used as placeholder for the keys:values to be used by the merge.
You can name the key .anything or use only a single dot as key.

ImaginaryTango · January 5, 2025, 6:46pm

I was thinking that, but had not tested it. Still, I was hoping to find more about it, in case there were more uses for it or some behaviors I had not seen. And it’d be nice to know if there’s a name for it.

Really? Interesting. It had not occurred to me to check that.

neel-m · January 5, 2025, 7:45pm

Yes, it certainly seems this is not well documented. I did find this issue where someone was trying to to use this:

github.com/esphome/issues

YAML anchors undefined in included yaml

opened 08:07PM - 23 Jan 20 UTC

closed 06:54PM - 24 Jul 20 UTC

DerFlob

**Operating environment/Installation (Hass.io/Docker/pip/etc.):**  Generic Linux distro, Python 3.8, pip **ESP (ESP32/ESP8266, Board/Sonoff):**  ESP8285-based switch power sockets, Gosund SP111 **Affected component:**  None, general configuration mechanism **Description of problem:** I have several switched power sockets (Gosund SP111), which have a HLW8012 built-in to measure output voltage/current/power and so on. For them to show sensible values, they have to be adjusted. I use a `calibrate_linear`-filter for that. Since the filter values are the only part the individual plugs' config don't share, I would like to have a base-yaml, which I include in a device-specific yaml and somehow substitute the filter values. The `substitutions` mechanism does not work, as it does not allow to specify lists as its value. Instead I was trying to use yaml anchors and references to solve the problem. See the (shortened) example configuration. **Problem-relevant YAML-configuration entries:** base.yaml ```yaml esphome: name: ${name} platform: ESP8266 board: esp8285 wifi: networks: !secret known_networks time: - platform: sntp sensor: - platform: hlw8012 sel_pin: number: GPIO12 inverted: true cf_pin: GPIO05 cf1_pin: GPIO04 change_mode_every: 2 update_interval: 1s voltage: name: ${name}_voltage unit_of_measurement: V accuracy_decimals: 1 filters: - calibrate_linear: *voltage_adjustment - delta: 0.2 ``` plug00.yaml ```yaml substitutions: name: plug00 .voltage: &voltage_adjustment - 709.80157 -> 231 - 719.60889 -> 234 - 721.24341 -> 235 <<: !include base.yaml ``` **Logs (if applicable):**  ``` $ esphome plug00.yaml compile INFO Reading configuration plug00.yaml... ERROR Error while reading config: Invalid YAML syntax: found undefined alias 'voltage_adjustment' in "sp111.yaml", line 66, column 29: - calibrate_linear: *voltage_adjustment ``` **Additional information and things you've tried:** The `name` substitutions works fine, but `voltage_adjustment` is undefined. I tried pasting the base.yaml into the plug00.yaml, which works fine and die references are substituted with the values for the `calibrate_linear`-filter. I don't prefer substitutions or yaml anchors. But having at least one of the mechanisms work, would help quite a bit in reducing duplicated configuration. Right now I have to change ten files, whenever I want to do a change and have them for all sockets. I had a quick look into the source and it seems currently included yamls, are loaded independent of the context from the original file.

I did find this about yaml anchors:
https://juju.is/docs/sdk/yaml-anchors-and-aliases

I believe this is one of a few methods that are available to reuse bits of configuration.

Most of the examples show the “simple” (to explain, but not necessarily use) way of doing things, where each device has all the configuration for everything.

There are several ways to make everything the same (that needs to be the same) while still allowing things to be different (that need to be different). All of these methods require some means of indirection and some means of overwriting (what needs to be different).

I am not an esphome expert and don’t know what is the One True Way, but discovered these ways:

It seems anchor is an older or at least less well described solution to the problem. I did not see anything describing the pros and cons of the various options and currently don’t know enough about them to write one. I am currently using substitutions and packages (even with a single device).

It looks like the leading dot in the YAML is an esphome thing that is not documented (at least not clearly).

ImaginaryTango · January 6, 2025, 7:24am

Thank you for some good information on this issue! I’ve found info on anchors in YAML, but much of it was simple or simplistic examples that left me with more questions than answers. (Which is one reason it was so hard to find out this isn’t a YAML thing.)

Thank you - yes, that’s what I thought, but confirmation is always good. When I have time, I’ll have to check on Discord and see if I can get a good answer from a developer.