質問: JSONデータの仕様書を書く場合、どのようなフォーマットやツールを使って仕様書を書くことが一般的なのでしょうか? できれば、サンプルのJSONファイルから、ある程度仕様書の雛形を自動生成できるツールを教えてもらえると嬉しいです。
回答: JSONの仕様を定めるものとして「**JSON Schema**」が有名です。これはJSONが満たすべき条件(何とかというフィールドは文字列が入っていなければいけないとか)を記述することができるフォーマットで、JSON Schema自体もJSONで記述されます。 JSON Schema自体もJSONで記述することになるため、人間が読んで理解するためのものというよりは機械が読むものという位置づけとなり、お求めの「仕様書」とは少し違うかもしれません。一応、人間が読めるようなドキュメントをJSON Schemaから生成しようという試みも存在するようです(参考1,参考2)。 入力されたJSONがJSON Schemaに合致するかどうかを検査できるライブラリも存在します。「JSON Schema generator」などの検索ワードで調べればJSON SchemaをJSONのサンプルから生成するツールも発見できます。