The future of YAML

I think a lot of people commenting on here have been in isolation too long. Look at what is currently going on in the World and put things into perspective. Chill out and keep healthy.


It always pays to remember Occam’s advice.

There are two facts, which, in combination, cause imho catastrophic results:

  1. Currently, the documentation leaves much to be desired.
    That’s of course an issue that I completely understand. It is a lot of work to properly document a project of this scale. Especially since everyone who could do that knows it so well that documentation isn’t necessary for them. Thats why many projects commercial as well as FOSS lack documentation.

  2. Currently, reviews are as you’ve mentioned rather harsh and discouraging and getting answers to questions you might have is a tedious task at best. If you can get an answer at all.
    Of course that’s also something I completely understand. There’s limited amount of time available and it’s more fun to spend that doing something you like, improving the software etc instead of interacting with newbies.

Problem is, that of these two things, only one may exist simultaneously. Otherwise people will fail to meet expectations, since they can neither look up the answer by themselves nor ask someone.

They just don’t have any other choice. It’s impossible for them to prevent unpleasant PR situations.

The only way to avoid this experience is to not contribute at all.


Well, I give now my comment on that, because there is complete wrong attention to it.
I think some did not read the full Blogpost, mostly miss the needed technical background behind that text.

First, what changes to now? Yes, nothing. The state now is, a YAML device config generates a full automated config in the background. What every you want rollback with YAML, did today not work if they use the new device/backend API, which is a lot integration today.

Because people had in on YAML, it implicit that they work as before but it did not. There was no maintainable solution for developers to make the UI user happy or the YAML user. We use the hybrid YAML/Backend (Yes, it’s not a UI config, it’s a backend thing) on many stuff like Automation but it doesn’t work for device configs.

But the problem is the community that makes the need of this change now happens. If a developer spends time to make an integration with UI/backend support, the YAML people complain, otherwise, the UI people complain. That generated all-time fire to the developers because they can’t be doing that right. Also because a device config is mostly once on an install, all the YAML fans did not register that the YAML did not work like on old days now over a year.

What we now do is remove a not working layering and clarify the situation for everybody.


I understand your frustration with this and the backlog of almost 200 open PRs wont improve that situation. I can just encourage you to be patient.

I think this discussion slightly derailed from its original topic which was about the future of YAML.


Personally I didn’t mind the elitist approach of “do it in text files like this even if it does scare off newbies who can’t read simple documentation”. But I have been configuring linux from text files since about RedHat 5.

As someone said earlier in the thread, dumbing the process down (by making it it all UI and clickety click) just brings in more dummies. And then they need supporting, because frankly you can never dumb it down enough, no one reads documentation, and even if they do it is never simple enough. No one reads the introductory Howto for the forum How to help us help you - or How to ask a good question, no one understands how to type in a terminal (WTF, if you can type in a forum, you can type in a terminal), everyone watches out of date youtube stuff, and with rare exceptions the youtube creators never post an update saying “this video is out of date, I’ve done another one, see here)”. Some people can’t even copy and paste text, and insist on posting pics of their text files (good luck to thise searching the forums for a problem if the problem is in a jpeg!).

So in my ideal world, we’d stick to the geeky text (yaml) configurations and deliberately drive away the non-savvy people. No problem to geeky me.

But I am not the only person out there. And my background as a commandline user is not the same as most people. And it ain’t my project, if I have contributed anything to github it is docs only, and if the devs want to go another way, I am gonna stick with them for the foreseeable future, because it is still a great project. And I’ll try and educate the people with skills different to mine, and hopefully we can all make home assistant even more awesome.

I must confess I set up a supervised HA in ubuntu on virtualbox this afternoon. Smooth. Lots of stuff detected on my lan and easily incorporated into the setup. I am impressed. I may even move my own setup to that instead of core on docker. It is a long time since I started from scratch, and it sure will be helping those newbies. All power to the devs.

Please community, let us keep calm and carry on.


I’m not exactly sure what you mean by this to be honest. Care to explain how it’s an “ugly workaround”?

I will give you a specific real-world example using the Apple TV integration. This is the YAML config for that integration:

  - address:
    identifier: <id>
    name: Living Room
    protocol: MRP
      mrp: <creds>
      airplay: <creds>
      dmap: <creds>

Are you going to remember the IP address of that device off the top of your head, or are you going to have to spend time looking it up on your router admin? Would anybody know how to obtain the identifier and credentials? Probably not, so it’s off to Google to find documentation on this. Do you know what generation Apple TV device you have, because depending on that the value for “protocol” will be different. Now that you figured that all out, time to restart. But maybe it’s not working because you had a minor typo in a 32 character ID, so time to restart again. Etc etc. This is too complicated and time-consuming for most people. Not a great user experience.

When you set it up from the UI, it scans your network and automatically detects the device and has the field pre-filled with this info, you simply hit the submit button. And it works immediately with no restart. If you ask me I think the UI way is far more elegant and user-friendly. And thus it would make sense to replace that YAML code block above (9 lines) with this single line when sharing your config with others:

# Set up Apple TV integration in UI from Configuration -> Integrations

The point I was trying to make is that you can still get all the same information across when sharing, it will just have to be done in a slightly different format with a YAML comment(s) going forward. I don’t think this is an “ugly workaround” personally. Almost everybody who shares their config already uses YAML comments (including the poster that I was originally replying to @anon43302295 before he deleted his awesome/well-documented repo last year).


Small disclaimer; this response talks about contributing in ways of code/documentation PRs. Yes, we have more ways to contribute.

I wanna thank both @Hypfer and @AhmadK for their good and clam responses on my personal story. :+1:

Thanks guys!

It is my personal story, but it is not a benchmark. I want to clarify that for sure. It is now about the hours you put it, it is about the commitment one has to the project. That makes someone a core contributor. Consistency is part of that key, not hours or quantity.

We have a lot of contributors that don’t have that amount of time that I have (and I’m crazy enough to sacrifice), which is in no way a requirement.

Reviews can be harsh but are never personal. That is the whole point of PRs: Asking questions, maintaining the quality level (and raise it). Same with documentation, it became a lot stricter. And if you could compare it with 2 years ago, it made major leaps. I merge around 200-300 documentation contributions each release… @AhmadK for one, is contributing regularly small tweaks to the documentation, which I absolutely admire him for. So thank you for that sir! :heart:

IMHO, it always boils down to my motto: "How are you going to make a difference today?"

For me, today, that will not be the forum today, as this topic has been highly demotivating for me as a contributor.

Instead, I’ll be finishing what I started yesterday: Rewriting the Almond add-on. Because it needs an upgrade, I’ve migrated it to the new S6 overlay, and make it a couple of hundred MB smaller in size. Why? Because people use it, and saving disk space on someone’s SD card can make a difference for them. Not me, I have 12Tb in my machine available.

I’ll be opening a PR, and will get the same treatment by (probably) @pvizeli on the PR review. Maybe I’ll learn a thing or two, or he is able to prevent a bug from sneaking in.

That is how I am going to make a difference today.




Oh I see…and how will that work when it comes the time to setup the Modbus UI Integration? Not forgetting the Modbus Switch, Modbus Binary Sensor, Modbus Sensor and Modbus Climate UI Integrations? Not forgetting that in many cases (for many reasons that require some comment notation) you will also require Template Sensors. Will Template Sensor UI be coming as well?

And the reason why Itead have also begun releasing Sonoff branded Zigbee devices

@frenck any advice on how to handle these 3 files?
I committed all 3 yesterday, and all of them have changes since…

:man_shrugging: I don’t use Modbus integration and have no answers for you on that, you’d have to ask the codeowner of that integration about their future plans.

1 Like

What? Not sure what you are referring to.

Personally it’s my belief that the codeowner (and this applies to all codeowners IMHO) should be putting future plans regarding UI/YAML changes in a blog post which is clearly titled to alert users of these future plans. This would allow for interested people to join a dialog to try to get the best result for ALL affected users. This is a community right? All stakeholders are important right?


I would also like to have a clean separation of configuration and data/state so I can keep an overview of when something has changed - this allows me to find months after I made I change why I did it. For me this is the main motivation to keep the configuration in git so I have a history.

I like how HA is storing history into a dedicated DB which, if worst comes, can be reset and no config is lost. The .storage directory is currently used for config, state (as listed by @DudeShemesh) and caching (hacs for example tracks the github starts under .storage/ repositories). Unfortunately the separation is not in a per file basis so keeping a clean full history of config is not possible at the moment.

So I am wondering if there is consensus about the desire to split the information in .storage into config (that would only change based on user triggered actions - including updating HA) and state/cache (that can change at any time any could potentially get reset. This could be implemented in different ways such as a subfolder or a prefix for each type so .gitignore rules can be simple. If there is consensus we could start working on such split - I would personally look at contributing a PR to some that I use so I am not asking others if I can help but I would like to avoid spending time in a PR that does not meet consensus from the community.

So looking for feedback supporting the idea or alternative ways to have a history of configuration changes. @frenck - mentioning you since you have been involved in this subtopic - maybe worth moving into a dedicated forum topic?

And in general - thanks to the HA community - I just moved from a different automation 4 months ago and I really like how open this community is, how easy to find information and the huge amount of integrations and examples and options. I am an IT architect so I have a job-influenced way of doing things in big projects that I apply to home automation but I am not feeling frustrated at any time - home assistant is a great balance of easy and poweful base for programing my automation (I love appdaemon for that) and be reliable on my kubernetes cluster :slight_smile:


Flattery will get you nowhere :stuck_out_tongue_winking_eye:

1 Like

I just meant that Itead (who makes Sonoff devices) have now also started making and selling several Zigbee based devices under the Sonoff brand, (and yesterday they even launched a Zigbee to WiFi bridge as well as announced more Zigbee based devices), and all such Zigbee devices can easily can be integrated into Home Assistant without using the Sonoff integration.

FYI, listed today on Itead website is Sonoff ZBBridge Zigbee Bridge (“pre-order”), BASICZBR3 Smart Switch, S31 Lite zb Smart Plug, SNZB-01 Wireless Switch (“coming soon”), SNZB-02 Temp. & Hum. Sensor (“coming soon”), SNZB-03 Motion Sensor (“coming soon”), SNZB-04 Wireless Door/Window Sensor (“coming soon”)

Making HASS configuration more user friendly via UI is a great idea. Also it’s great to be able to make config changes without need to restart. Unfortunately it doesn’t feel like correctly implemented.

I don’t understand why it’s not completely redesigned instead of switching to generating JSON files in weird .storage directory from UI and having this UI-generated vs YAML clash.

Why not having external store for configuration (SQLite, etc.) and option to enforce config via REST API like most mature services does? So purely UI users could utilize UI and users with Git-backed configuration, etc. could use their YAML files similar way as they do now and enforce configuration by calling curl against HASS API.
It could also support export/import of config objects back to YAML for backup purposes, etc. Could also handle schema changes during updates.

I don’t think that design decision is well thought and IMO it’s only making things worse.


At least JSON is human readable when issues that can’t be rectified via the UI occur. SQL would be a nightmare.

1 Like

A lot to catch up on so here goes…

I see a lot of references to the need to “restart” for changes to take effect instead of “reloading” as a motivation to do away with yaml. But I don’t think those are necessarily valid concerns. Or at least they are self-imposed limitations causing those concerns.

There are way fewer reasons to have to do a restart now than there were before.

We have a lot more availability of doing “reloads” of more things now than we used to that required a restart. At one time we could only reload customizations, scripts, automations and groups. And if any of those things were included in packages you also had to do a restart then because a reload wouldn’t work.

Now we can reload all of the above in packages too, input_* entities, and all of the Lovelace stuff (even if it is written completely in YAML like mine).

I’m not really sure if there was some sort of technical limitation that has changed to allow the newer “reload” functions instead of requiring a restart on those. But the question is then why can’t that same modification be made to allow all of the other stuff to be reloaded instead of needing a restart?

IOW, what’s the technical difference between an input_boolean defined in yaml and a sensor defined in yaml that allows the former to be “reloaded” and the latter required to be restarted?

The people who would want that type of solution already have those options. There are many, many commercial options that are “dumbed down” and made for the masses. HA has always been for those who want to “do more” than most commercial options allow.

You can make HA easy or you can make HA powerful but you can’t have both.

I see no real benefit for HA to just become just another appliance geared toward the least common denominator aside from the future profit it might bring to nabu casa. And if eventual profit isn’t the motivation then why do the devs want to dumb it down to bring in more users to the possible detriment of advanced users?


This is a great community. People here are extremely generous with their time to help other people.

Just because we have disagreements over important topics like this doesn’t take away from that. I’d say that it’s a sign that we have a passionate user base that knows what it wants and is willing to say something when things are being done to impede that. To me that’s a positive.

yep and HA has grown into what it is over the years in spite of (or more likely because of) the flexibility that the yaml programming provided. How many have come to HA from other more restrictive platforms (like Domoticz)? It has to mean that HA, even with it’s “confusing and hard” yaml, was better.

Do you have any data that suggests that there are droves of integrations that aren’t being maintained simply because of the need to use yaml? If that was the case then there wouldn’t be over 1500 integrations right now because until recently everything used yaml and all of those integrations have always been maintained

Just because we don’t have a “flag” doesn’t mean we don’t contribute in many other ways. And it especially doesn’t mean that our opinions don’t count.

Generally speaking, yes.

How many times do we all tell new people to “post your config in text and not in screenshots” because nobody wants to be required to type all of the code out to correct/modify their code to be able to help them? I know I’ve said it a bunch. we all know it’s way easier for us to copy/paste/edit text than it is to write it all by scratch from a screen shot.

And for those reasons you will never really be able to use HA for it’s full potential.

But why should others who do use those things and, frankly, have been around for a lot longer than you have be deprived of the advanced possibilities/functionalities to cater to someone who won’t and doesn’t want to ever use those things?

And the exact reason for that potential is because HA is flexible/powerful and hasn’t been intentionally hamstrung by trying to cater to “the masses”.

No, it doesn’t “unlock” any other functionality other than remote access and easier voice integration.