I started building a tool that simplifies video scripting [1] and the first version worked from JSON. Although this was aimed at a technical audience, people really struggled with it. it's difficult to add comments, and ended up being very error prone. My second choice was YAML, but this ended up even more error prone due to whitespace issues.

My lesson is that JSON and YAML are great for machine-consumption when people just need to do something once and leave it (eg config files), but far from ideal for stuff people need to edit over and over (such as script files).

I converted the input to markdown (with some small extensions) and it made a huge difference. it's less fiddly, much easier for humans to edit, and the parser can point out errors much better. for some nice examples check out https://github.com/videopuppet/examples/

In conclusion, YAML and JSON are great for machine-to-machine communication or human-to-machine for things that do not change often and aren't complex. for human-to-machine that is more frequent, we should be kinder to our users.

[1] - https://www.videopuppet.com

"Consume YAML, emit JSON". I've been using this pattern for the last several years on most projects, ever since someone else on the internet recommended it. Since YAML is a superset of JSON, people can input either JSON or YAML (or mostly just JSON with JS style comments, like I do most of the time) and have simple JSON output.

JSON is really unfriendly for human editing. Notably, lack of comments, and trailing commas being strictly forbidden.

JSON5 seems like a decent alternative to either.

Anything that's going to be handwritten shouldn't be using json, it's unnecessarily verbose to read and produce

I personally prefer toml

It took some looking but I think DTS=Device Tree Spec. https://elinux.org/Device_Tree_Usage