$schemaは、VS Codeなどのエディターに対して、「どのバージョンのtheme.jsonのルールに従って入力補完やエラーチェックを行うか」を指定するためのものです。

たとえば、theme.json の先頭で次のように指定します。

{
  "$schema": "https://schemas.wp.org/wp/7.0/theme.json"
}

$schemaに適切なスキーマを指定しておくことで、使用できるプロパティや値の入力補完を受けられるだけでなく、対象のWordPressバージョンでは利用できない記述をした際に、エディター上で警告を表示してもらえます。

WordPressのtheme.jsonでは、主に次の2種類のスキーマが用意されています。

1. 安定版 : https://schemas.wp.org/wp/7.0/theme.json
2. 開発版 : https://schemas.wp.org/trunk/theme.json

安定版と開発版の違い

安定版

…/wp/7.0/theme.jsonは、特定のWordPressバージョンに対応した安定版のスキーマです。

たとえば「wp/7.0/theme.json」であれば、WordPress 7.0で正式に実装されているtheme.jsonの仕様をもとに定義されています。

• 対象バージョン : WordPress 7.0
• 含まれる機能 : WordPress 7.0で正式に実装されている機能
• 主な用途 : 本番環境で使用・配布するテーマの開発

安定版のスキーマを使用するメリットは、対象とするWordPressのバージョンに合わせて、利用できるプロパティや値を確認できることです。

たとえば、開発環境に最新のGutenbergプラグインをインストールしていると、次期バージョンで導入予定のプロパティが利用できる場合があります。しかし、その記述が現在のWordPress本体ではサポートされていなければ、本番環境では正常に動作しない可能性があります。

対象バージョンの安定版スキーマを指定しておけば、VS Code上でそのバージョンでは利用できないプロパティに対して警告が表示されるため、このようなミスを事前に防ぎやすくなります。

そのため一般向けに配布するテーマや、クライアントに納品する本番用テーマを開発する場合は、対象とするWordPressのバージョンに対応した安定版スキーマを指定するのがおすすめです。

開発版

一方、…/trunk/theme.jsonは、WordPressの最新の開発状況を反映した開発版のスキーマです。

「trunk（トランク）」は、ソフトウェア開発において、最新の開発内容が集約されるメインの開発ラインを指す言葉です。

開発版のスキーマには、次のメジャーバージョンで導入される予定の機能や、開発中の機能などが含まれています。

• 対象バージョン : WordPressの開発版（常に最新の仕様）
• 含まれる機能 : 次期バージョンの新機能や開発中の機能など
• 主な用途 : 最新機能のテストや、開発版を前提としたテーマ開発

特にGutenbergプラグインで先行提供されている実験的な機能を試したい場合には、開発版が適しています。

ただし、開発版の内容はWordPressの開発に合わせて更新されていきます。そのため、現在は問題なく認識されている記述が、将来的に仕様変更によって警告の対象になるなど、スキーマの内容が変化する可能性があります。

つまり開発版は「今のWordPressで安定して使える機能だけを定義したスキーマ」ではなく、これからWordPressに導入される機能も含めて、最新の仕様を確認するためのスキーマと考えると分かりやすいと思います。

どちらのスキーマを指定すべき？

基本的には、特別な理由がない限り、開発対象とするWordPressのバージョンに対応した安定版スキーマを指定するのがおすすめです。

たとえば、WordPress 7.0を対象にテーマを開発するのであれば、以下のように指定します。

{
  "$schema": "https://schemas.wp.org/wp/7.0/theme.json"
}

安定版を使うことで、対象バージョンで利用できる機能を基準に入力補完やエラーチェックを行えるため、本番環境との互換性を意識しながら開発できます。

一方で、次期WordPressの新機能を先行して試したい場合や、Gutenbergプラグインで提供されている開発中の機能を利用したい場合は、開発版を選択するとよいでしょう。

まとめると、次のように使い分けるのがおすすめです。

安定版

• 本番環境向けのテーマ開発
• 一般向けに配布するテーマ
• クライアント向けのテーマ開発

開発版

• 次期WordPressの機能を先行テストしたい
• Gutenbergの開発中機能を試したい

$schemaは単なる補完機能の設定ではなく、「どのWordPressの仕様を基準にtheme.jsonを記述するのか」をエディターに伝えるための指定でもあります。

本番環境を想定したテーマ開発では、基本的に対象バージョンの安定版を指定し、最新の開発機能を試したい場合に開発版を利用する、と使い分ければよいかと思います。