如何维护基于JSON的特定于域的语言的文档？

Question

我们正在开发类似RPG的游戏描述语言。以前，我们使用丑陋的低级XML - 但现在我们已经切换到更高级别，几乎是人类可读的JSON（直到我们推出一个新的图形编辑器，不再需要手工编写文件;虽然我们会可能会保留它用于低级，快速和肮脏的创作）。游戏引擎是用Java编写的。

您如何记录将从Java中使用的JSON文件格式？。我们有超过50种“对象类型”，从场景到背景，对话，过渡，项目，角色等。我们希望在添加和调整功能时保持格式更新，因此易于更新非常重要。目前，JSON的一些部分被翻译成Java的许多部分 - 因此一个好的文档目标可能是执行此转换的Java“JSON Reader”模块。另一种方法可能是记录JSON格式的某种“规范”，可以用例如某种“JS API”编写。

我们可以使用的一些东西：

• jsDoc - 我们可以在JS中记录每个对象类型，作为假JS API的参数。
• Java JSON-Reader源代码中的旧JavaDoc;但JavaDoc不了解JS，AFAIK;所以我们可能需要为JS标签写一个custom JavaDoc标签。
• （您的建议在这里）

注意：这不是“什么是最好的工具”问题;我的目标只是找到一个或多个候选文档 - JSON即将从Java中使用的工作流程。

Answer 1

您有两种选择：

• 您可以选择以Java为中心，定义可以记录的java类，然后序列化为JSON：Java-first。

• 您可以选择在模式的帮助下定义JSON包含的内容（类似于与XML编组一起使用的XML模式）：JSON优先。它可以由http://www.json-schema.org定义。