概要

今回は開発ツールとして便利な JSON Schema をご紹介。けっこう以前からある仕組みなのですが、私は今回初めて知って大興奮。

設定ファイルはよくJSON（package.json, .prettierrc, .stylelintrc, firebase.json...)やYAMLで作られているんですが、使えるパラメーターなどはリファレンスサイトを読み込む必要があります。
JSONなのでTypeScriptみたいな型定義があるわけない……と思っていた時代が私にもありました。

JSON SchemaというのはそのJSONの定義書にあたるものです。YAMLにも対応してます。

これを対応するエディターで読み込めれば、設定を記載する際、バリデーションやオートコンプリート、そしてドキュメントの参照が可能になります。

JSON Schemaを覗いてみる

ここで例としてpackage.jsonのauthorのJSON Schemaを確認します。

※下記のJSONは実際は1つのSchemaファイルです。ここでは見やすくするために分割で表記

{
  "author": {
    "$ref": "#/definitions/person"
  }
}

authorは定義personを持っています（上記の$refはpersonへの参照）。

{
  "person": {
    "description": "A person who has been involved in creating or maintaining this package.",
    "type": [
      "object",
      "string"
    ],
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string"
      },
      "url": {
        "type": "string",
        "format": "uri"
      },
      "email": {
        "type": "string",
        "format": "email"
      }
    }
  }
}

personの内訳です。

description: 定義の説明。ドキュメントを参照する際にはこのテキストが表示される
type: 何の型でプロパティを設定できるのか（プロパティそのものの型ではない）
required: 必須項目（ただしobjectで設定しているときのみ）
properties: object型で設定する際のキー名とバリューの型一覧
※他にも様々なメタ情報が存在します

例えば下記のようにobjectで設定する場合、nameの記載がないとバリデーションエラーが指摘されます。

WebStormの場合、バリデーションエラーが発生しているとSchemaファイルへの定義ジャンプが効かなくなります。エラーがなくなるように修正し、確認する必要があります。

オートコンプリート

package.jsonを編集する際、authorの項目の入力時にいつものオートコンプリートのリストが表示されます。

ドキュメント

authorのドキュメントをポップアップで表示したところ。

JSON Schemaを探す

JSON Schema Storeというサイトがあり、スキーマファイルへのリンク集になっています。有名どころはだいたい確認できます。

また、サイトに登録してあるURL一覧がAPIとして公開されており、自分たちで活用可能です。

では、ここに掲載されていない場合どうするか？
自分で作るかGitHub等で誰かが作っているものを探す必要があります。

TypeScriptの定義からJSON Schemaを生成する方法もあるようです（使ったことないので紹介のみ）。他の言語もありそう。

WebStorm（IntelliJ）での設定

WebStormは元からJSON Schema設定が用意されています。
先に紹介したJSON Schema Storeから自動（おそらくAPIのfileMatchを見て）でスキーマをダウンロードします。
また、自分でURLやローカルのJSON Schemaファイルの指定も可能です。

画像はdocker-compose.ymlの設定画面です。
デフォルトではdocker-compose.ymlのスキーマが紐付けされていなかったので、ステータスバーから読み込みました。

この画像の中心あたりにあるのが使用しているJSON Schema名を表示しています。JSON Schemaが存在しない場合No JSON Schemaと表示されます。

VSCodeでの設定

VSCodeでJSON Schema対応する場合、JSONとYAMLで別々のプラグインがあります。

まずはJSON向けのプラグインJSON Schema Store Catalogです。設定は不要です。

JSONファイルを開く際、JSON Schema Storeに対応ファイルがあれば自動でスキーマファイルを取得します。
記載時のオートコンプリート、ドキュメント表示に対応しています。

続いてYAML向けのYAML。こちらはそもそもYAML言語自体のサポートプラグインです。
言語向けの設定はあるようですが、JSON Schemaを使用するに当たっての設定不要です。

基本的にはJSON Schema Store Catalogと同じです。
YAMLファイルを開いたとき、自動でJSON Schema Storeからスキーマファイルを取得します。
記載時のオートコンプリート、ドキュメント表示に対応しています。
こちらのプラグインは、キーにカーソルを合わせると参照先のスキーマへのリンクを表示してくれます。

ただ、残念ながらどちらのプラグインも参照しているスキーマファイル自体をVSCode上で開く方法は存在しないようです。

以上

今回は大興奮のJSON Schemaを紹介しました。
めっちゃ便利なのでゼヒ使ってみてください。