There is some surprising behavior with some of the features of yaml, mostly arising from the fact that it looks nice to read. Here's a list of things that you can avoid to avoid a lot of the pitfalls: https://hitchdev.com/strictyaml/why/ . I haven't actually used strictyaml, but the arguments it presents are pretty solid and some are things I've run into in real environments

YAML is way too bloated of a standard and has a ton of inconsistencies between implementations, despite the widespread reputation of simplicity. It is easy to read as long as you limit yourself to a fraction of its capabilities and err on the side of caution when it comes to escaping characters (especially when number literals are involved, or booleans for that matter). As far as alternatives go, I prefer TOML for simple key=value configs, but it has its own issued and is nowhere near as featureful, for better or worse.

JSON was never meant for configuration.

YAML has a ton of footguns.

If you're just reading configs then yeah, it's superior. If you're maintaining big complex configurations, possibly for multiple machines, you need something to reduce boilerplate. Jsonnet, nickel or nix are excellent here. So the best way is to use one of those, generate yaml, and deploy. Saves you a lot of headaches but it's one more moving thing in your pipeline which can break.