[mumblemumble]

All fair points.

I had forgotten about the YAML format; I probably skipped over it because I am not a fan of YAML. As far as the description features go, they're something, but the lack of ability to stick extra information just anywhere in the file for the JSON format severely hampers the story for high-level documentation. I'm not a fan of the "the whole is just the sum of the parts" approach to documentation; not every important thing to know can sensibly be attached to just one property or resource.