Time to read this if you haven’t already

ruudvanasseldonk.com/…/the-yaml-document-from-hel…

The yaml document from hell

As a data format, yaml is extremely complicated and it has many footguns. In this post I explain some of those pitfalls by means of an example, and I suggest a few simpler and safer yaml alternatives.

The json spec is not versioned. There were two changes to it in 2005 (the removal of comments

See, this is why we can’t have nice things.

I can kind of understand it after having to work with an XML file where users encoded data into comments for no good reason. But yeah, it does make JSON awkward for lots of potential use-cases.
Anything can be abused. That’s not a legitimate reason to take away perfectly reasonable features. Looking at you, Java (unsigned integers).
Well, I assume they had other concerns, too. For example, it adds a bunch of complexity for reformatting a JSON from single-line to pretty-print, if comments can appear in there. I’m certainly not saying that I’m always best friends with the decision to remove comments, just that I can somewhat understand it.

Their stated justification is that people would abuse comments, using them to carry semantic or syntactic information. That’s a shit justification IMO.

As far as the additional complexity that comments bring, I understand that from a technical perspective but from an engineering-for-real-humans-in-the-real-world perspective that’s the kind of thing you just have to deal with if you want to design a good format.