I generally find that the biggest problem with human friendly formats like YAML, which I think this also has, is that they tend to decouple readability from wri

I generally find that the biggest problem with human friendly formats like YAML, which I think this also has, is that they tend to decouple readability from writability, and this encourages all sorts of complexity and polymorphism that seem superficially expressive, but end up just being difficult to work with. I've seen so many cases where YAML schemas turn into a quasi-DSL, because the developer thought that it was more important to have a clean looking configuration than one that is easy to edit. The result is that things like indentation get really weird, because the developer didn't optimize for having a sane underlying model. A great comparison for this is CircleCI's config syntax and that used by GitHub Actions. The Circle format is extremely error prone; about half the time when I'm modifying a Circle config, I'll end up pushing a broken config, even though the YAML syntax itself is valid. With the GitHub Actions format, I almost never screw it up. I don't think it's a coincidence that if you convert a Circle configuration to JSON, it looks twisted and bizarre, whereas if you do the same with a GHA config, it looks perfectly ordinary and sensible. If you think of YAML as "a prettier version of JSON", and design as if your users will work primarily with JSON, you can do fine with it. If you think of it as a medium for building your own configuration language, you'll make something awful. The problem is that any human friendly format is going to inherently encourage the latter.