How to maintain documentation on a JSON-based domain-specific-language?

We are developing an RPG-like game description language. Previously, we used ugly low-level XML -- but now we have switched to a higher-level, almost-human-readable JSON (until we roll out a new graphical editor and no longer need to write files by hand; although we would probably keep it for low-level, quick&dirty authoring). The game-engine is written in Java.

How would you document a JSON file format that will be consumed form Java?. We have upwards of 50 "object types", from scenes to backgrounds, conversations, transitions, items, characters and the like. We would like to keep the format updated as we add and tweak features, so ease of update is important. Currently, some bits of JSON are translated into a lot of bits of Java -- so a good documentation target may be the Java "JSON Reader" module that does this translation. An alternative may be to document some kind of "spec" of the JSON format, which could be written in, for example, some sort of "JS API".

Some of the things we could use:

jsDoc - we can document each object type in JS, as parameters a fake JS API.
good old JavaDoc in the Java JSON-Reader source-code; but JavaDoc does not understand JS, AFAIK; so we may need to write a custom JavaDoc tag for our JS tags.
(your suggestion here)

NOTE: this is not a "what is the best tool" question; my goal is only to find one or more candidate documentation-workflows for JSON-to-be-consumed-from-Java.

Solution

You have two options:

You can choose to be java-focused and define java classes that you can document and then serialize to JSON: Java-first.
You can choose to define what your JSON contains with the help of a schema (similar to XML Schemas which are used with... XML marshalling): JSON-first. It can be defined by http://www.json-schema.org.