Why does UI of automations delete all yaml comments

Whenever I add comments in the ‘yaml’ version (to know what I’m doing e.g. when setting up a template) and switch to UI version all the comments are deleted

Similar as Why does dashboard not allow comments in the code

The code is stored as json, and json doesn’t do comments. For automations/scripts it is a bit more complicated, but it is first stored as json, and then converted back to yaml for automations.yaml and scripts.yaml

1 Like

While there is no way to handle YAML comments for the reason TheFes said, what could be possible is adding more commenting options to the UI. Like a comment type action that does nothing but lets you insert descriptive information somewhere. Or an option to add a description to actions, conditions and triggers which is presented as a text area, as opposed to an alias which is more of a name. This would make more sense in the UI editor anyway since YAML is basically the fallback for advanced features there.

3 Likes

it’s not because the code is stored in json. It’s because it is stored the way which makes it impossible.

it comes from direct conversion from yaml to json. but who said the comment cannot be treaded as any other language object?
I have to admit it ‘must not be easy especially if there is no yaml-json converter which can do that.
but creating language which ‘eats’ comments without warning?

3 Likes

The automation editor has to parse the YAML in order to present it to you in a form-based way like it is. YAML parsers remove comments because they’re comments. By definition they are supposed to be ignored since they aren’t part of the data so why would a YAML parser do anything but ignore them?

Even if you do the “edit in YAML” option at the top its still parsing the YAML and showing you a subset. You’ll notice the if you actually look at the automations.yaml file each automation has an id field and that doesn’t appear in the UI even in the raw YAML view since changing it would break things.

The only way the automation editor could keep comments is if it didn’t parse it at all and kept it purely as text. And if that’s what you want then just don’t use the UI editor. Add a new automation block and edit your automations in the text editor of your choice.

Since the migration process is non-reversible it seems like this would be a good place for a big warning message, explicitly stating in the non-reversible migration all comments will be removed in your existing automations.yaml file.

It was quite a surprise when all my nicely commented and arranged yaml code disappeared.

6 Likes

It would be great if all objects would have a “comment” field where we could put our comments in a string. That way, they could be kept even if they would not have a functional utility.

3 Likes

There is a potential workaround though, since templates can contain comments, and these are not removed by the UI. Add a template condition at the relevant point. Make it always return true so it can’t affect subsequent command execution, then put comments in there, like so: -

condition: template
value_template: |-
  {# COMMENT BLOCK FOLLOWS #}
  {# this is a comment #}
  {# and here is another #}
  {# as many as you like #}
  {{true}}
5 Likes

Being that the YAML is converted to JSON when saved, then back again to YAML for editing, a compromised would be to store the original YAML file as-is in a text file, before converting it to JSON. When the user comes back to the YAML at a later date for editing, instead of converting the JSON back to YAML, simply retrieve the associated YAML text file and display it to the user. Nothing is going to change the JSON in the meantime, so the stored text file should always be up to date with the JSON. Readability of code is important. Dropping helpful comments which enhance the readability of config files should be avoided if possible.

4 Likes

Or simply adding fake JSON node for comment - something like 'comment':'comment from YAML'

4 Likes

The problem isn’t adding a comment or a description node to the json, it’s reading the comments in the yaml. Typical YAML parsers will not parse comments, they will just ignore them entirely, because that’s what the YAML specs say they should do:

Comments are a presentation detail and must not have any effect on the serialization tree or representation graph. In particular, comments are not associated with a particular node.

Of course that doesn’t mean a YAML parser couldn’t preserve them as an out-of-spec extension (so to facilitate format conversions or source formatting for example) and some probably do. But I guess the one HA uses doesn’t.

2 Likes