独自YAMLファイルをJSON SchemaでLSP補完する

Podbardはpodbard.yamlに設定を記述するが、これをエディタで補完したりヒントを出せたりするようにした。

yaml-language-serverとJSON Schema

普段vimで開発してて、GitHub ActionsのYAMLを触ってるときなどに、エディタが適切にヒントを出してくれるのを便利に感じつつ「多分LSPがうまいことやってくれてるんだろうな」くらいに考えて深く追いかけていなかった。これは、JSON Schemaで実現されていることを、今回podbard.yamlの仕様をJSON Schemaで記述している過程で発見した。

GitHub ActionsのJSON Schemaは https://json.schemastore.org/github-action.jsonやhttps://json.schemastore.org/github-workflow.json で公開されており、YAMLファイルを編集するときに、yaml-language-serverが、それをいい感じに読み込んで支援してくれる。LSPなので当然VSCodeやその他エディタでも利用できる。

JSON Schema Store

このいい感じにスキーマを読み込むための、世界共通のスキーマ類を管理しているのが、JSON Schema Storeというサイト。ここで、https://raw.githubusercontent.com/SchemaStore/schemastore/master/src/api/json/catalog.jsonという大きなJSONファイルが公開されており、どういったファイルがどのスキーマに対応するか、という情報が記述されている。以下はGitHub ActionsのWorkflowの例。

{
  "name": "GitHub Workflow",
  "description": "YAML GitHub Workflow",
  "fileMatch": [
    "**/.github/workflows/*.yml",
    "**/.github/workflows/*.yaml",
    "**/.gitea/workflows/*.yml",
    "**/.gitea/workflows/*.yaml",
    "**/.forgejo/workflows/*.yml",
    "**/.forgejo/workflows/*.yaml"
  ],
  "url": "https://json.schemastore.org/github-workflow.json"
}

yaml-language-server に yaml.schemaStore.enable という設定があり、これがtrueだとこのサイトから自動でスキーマを引っ張ってきてくれる。デフォルトでtrue。

独自のJSON Schema

もちろん独自のJSON Schema設定も記述できる。README.mdに詳細に書かれているが、 主に、yaml.schemas 設定と、YAMLファイル内にモードラインコメントを記述する方法がある。モードラインコメントは、プロジェクトのリポジトリ内で、チームメンバーに共通でスキーマを読み込んでもらいたい場合に重宝しそうです。これは至極単純で、YAMLファイル内に以下のようなコメントを記述するだけです。

# yaml-language-server: $schema=<urlToTheSchema>

$schema に指定する文字列は公開URL、絶対・相対パス形式、いずれも可能です。ちなみに、JSON Schemaは本来JSONで記述しますが、YAMLで記述したものを直接読み込ませることも可能でした。

今回のPodbardの場合、以下のコメントを書けばLSPの支援が効くようになった。GitHubのrawコンテンツを指定するだけでお手軽。

# yaml-language-server: $schema=https://raw.githubusercontent.com/Songmu/podbard/main/schema.yaml

JSON Schema Storeへの登録

さて、今回のPodbardの場合、できればモードラインコメントせずとも補完が効くようにしたい。これは https://github.com/SchemaStore/schemastore の catalog.json を編集してpull requestを送れば良いようだ。

しかし、ここにマイナーOSSの設定ファイルのスキーマを登録するのは少し気後れする。そこで、直近のpull requestをいくつか観察してみると、割と個人レベルでのOSSであっても、快く迅速に取り込んでくれている様子だったので、以下のpull requestを送ったら半日程度でシュッとマージしてくれてありがたかった。

https://github.com/SchemaStore/schemastore/pull/4091

{
  "name": "podbard.yaml",
  "description": "Configuration file for Podbard - a podcast site generator",
  "fileMatch": ["podbard.yaml"],
  "url": "https://raw.githubusercontent.com/Songmu/pokkdbard/main/schema.yaml"
}

変更内容は上記で、スキーマのURLにyamlを直接指定する暴挙にでているが、すでに登録されている設定でもYAMLを直接しているものもあったので、いけるかな思って恐る恐るpull requestを出してみたが取り込んでもらえた。まあ、podbard.yamlはYAMLでしか設定ファイルを提供するつもりは無いので、スキーマもYAMLで良いでしょというところ。

vim-lsp-settingsへの対応

これはおまけだが、大変お世話になっているvim-lsp-settingsでは、上記のJSON Schema Storeのcatalog.json をリポジトリ内に同期して保持し、それを読み込むようになっている。yaml-language-serverは前述の通り、実はJSON Schema Storeを直接見に行くようになっていたので対応不要だったが、このスキーマ情報は当然 json-languageserverやその他LSPでも使われるものなので、更新しておく価値はある。ということで以下のpull requestで取り込んでもらった。

https://github.com/mattn/vim-lsp-settings/pull/774

この記事で書いたように、このcatalog.jsonは結構カジュアルに更新されるものなので、自動更新の仕組みが入っても良いとも思ったが、そこまではやらなかった。

まとめ

YAML設定ファイルに対してJSON Schemaを書いておくことで簡単にエディタの支援が効くようになるのは、今更の話かもしれないが、かなりお役立ち情報だった。

また、JSON Schema Storeへの登録は割と気軽にできることが分かったのも収穫だった。当然節度は必要だが、皆さんも機会があれば自作OSS等定義した有用なスキーマを登録してみてはいかがだろうか。