[解決済み] JSONの構造を記述するための構文

質問

私が書いているAPIが返すjsonのフォーマットを文書化しようとしているのですが、json構造の文書化のための一般的なフォーマットがあれば知りたいのです。

私は何かをテストまたは検証しようとしていないことに注意してください、私は単にドキュメントのためにこれを使用しています。また、非定数（常に同じ値で返される項目）にコメントを追加するいくつかの方法があるとうれしいです。

これは、私が現在使用している完全に考え抜かれたスキームではありません。

Plain names refer to identifiers or types.
Some types have type-comment
Strings that appear to be constant(always returned for that type of request) strings are "str"
Constant Numbers would be just the number
Constant null is null
Booleans are true/false for constant booleans or Boolean otherwise
[a,b,c] are lists with 3 items a,b,c
[...  ...] is a list of repeating elements of some types/constants/patterns
{a:A,b:B,c:c} and {... ...}  is the same for a dictionary.

の例です。

story          := [header,footer]
header         := {"data":realHeader,"kind":"Listing"}
realHeader     := {"after": null, "before": null, "children": [{"data": realRealHeader, "kind": "t3"}], "modhash": ""}
footer         := {"data":AlmostComments,"kind":"Listing"}
AlmostComments := {"data": {"after": null, "before": null, "children": comments, "modhash": ""}, "kind": "t1"}
comments       := [...{"data":comment, "kind":"t1"}...]

realRealHeader :=
{"author": string,
"clicked": boolean,
"created": int,
"created_utc": int,
"domain": "code.reddit.com",
"downs": int,
"hidden": boolean,
"id": string-id,
"is_self": boolean,
"levenshtein": null,
"likes": null,
"media": null,
"media_embed": { },
"name": string-id,
"num_comments": int,
"over_18": false,
"permalink": string-urlLinkToStoryStartingFrom/r,
"saved": false,
"score": int,
"selftext": string,
"selftext_html": string-html,
"subreddit": string-subredditname,
"subreddit_id": string-id,
"thumbnail": "",
"title": string,
"ups": int,
"url": "http://code.reddit.com/"
}


comments := {
"author": string,
"body": string-body_html-wout-html,
"body_html": string-html-formated,
"created": int,
"created_utc": int,
"downs": int,
"id": string-id,
"levenshtein": null,
"likes": null,
"link_id": string-id,
"name": string-id",
"parent_id": string-id,
"replies": AlmostComments or null,
"subreddit": string-subredditname,
"subreddit_id": string-id,
"ups": int
}

どのように解決するのですか？

理論的には JSON スキーマ はこの目的を果たすことができますが、実際にはそうであるかどうかはわかりません。言及する価値があると思います。

これ以外の個人的な意見としては、JSONは主にオブジェクトを転送するために使用されるので、クライアントが使用する言語（Java、C#、さまざまなスクリプト言語）で同等のオブジェクトを文書化することが最も理にかなっているかもしれません -- 結局、そのようなオブジェクトは通常JSONにマッピング/バインドされて戻ってくるのです。そして、Java用のJavadoc（Perl用のperldoc、c++用のOxygenなど）のような、利用可能なあらゆるドキュメント化ツールを使用することができます。

インターフェースを指定するために WADL (Web App Description Language) があり、これが役に立つかもしれません。