Document JSON format

[EricWF]

Currently we don't provide any documentation as to the format of the JSON we produce. Instead of requiring users to read the code, we should document and then stick to a format for our JSON.