OD Structured Data で WordPress の構造化データを投稿ごとに管理する
WordPress サイトを運用していると、構造化データをどう扱うか悩む場面があります。
SEO プラグインに任せる方法もありますし、テーマ側で JSON-LD を直接出力する方法もあります。ただ、投稿ごとに少しだけ内容を調整したい、でも完成済みの JSON を毎回手入力するのは避けたい、というケースもあるのではないでしょうか。
そういう時に使えるように作っているのが、OD Structured Data です。
このプラグインは、WordPress がすでに持っている投稿タイトル、URL、公開日、更新日、著者、アイキャッチ画像、サイト情報などをもとに、Schema.org に沿った JSON-LD を出力するためのプラグインです。
バージョン0.2.0では、Article 系の構造化データを生成するだけでなく、「なぜ出力されるのか」「どの情報を使っているのか」「ほかのプラグインと重複しないか」を確認しながら運用できるように機能を追加しました。
バージョン0.2.0で変わったこと
今回の更新で大きく変わったのは、構造化データの出力を細かく制御し、編集画面で状態を確認しやすくなった点です。
- 投稿タイプごとに「無効」「原則無効」「原則有効」を設定できる
- 投稿単位で、投稿タイプ設定の継承・個別有効・個別無効を選べる
- Article、WebPage、WebSite、サイト主体など、プラグインが出力を担当する Schema を選べる
- 検証結果を、出力を止めるエラー、推奨項目、情報の不一致に分けて確認できる
- サイト主体を
Organization、Person、出力なしから選べる - サイト主体の名称、正式 URL、ロゴ、
sameAsを管理できる - canonical URL や
dateModifiedの扱いを調整できる - 各項目の取得元、自動取得値、上書き値、最終出力値を確認できる
- 保存前のタイトル、抜粋、アイキャッチ画像を JSON-LD プレビューへ反映できる
- WordPress のページ階層から
BreadcrumbListを生成できる
構造化データを増やすことよりも、ページ上の情報と矛盾しない状態を保ち、出力元を把握できることを優先した更新です。
OD Structured Data でできること
OD Structured Data は、構造化データをゼロから全部入力するためのフォームではありません。
どちらかというと、WordPress 内にある情報を使って JSON-LD を組み立て、必要なところだけ投稿ごとに上書きできるようにするプラグインです。
主にできることは、以下の通りです。
- 投稿タイプごとに構造化データの出力方針を設定できる
- 投稿ごとに出力方針を継承・上書きできる
- Schema ごとに OD Structured Data が出力を担当するか選べる
- 新規コンテンツで構造化データを最初から有効化できる
- 既存コンテンツをまとめて有効化できる
ArticleとBlogPostingを投稿ごとに選べる- 投稿タイトル、URL、公開日、更新日、著者、アイキャッチ画像、サイト名、サイト URL を自動取得できる
- 見出し、説明文、画像、著者名を投稿ごとに上書きできる
- ブロックエディター上で JSON-LD のプレビューを確認できる
- PHP 側で生成した結果をもとに、エラー、推奨項目、整合性警告を編集画面に表示できる
- 各項目の取得元と最終出力値を編集画面で確認できる
- サイト主体として
Organization、Person、出力なしを選べる - WordPress の階層から
BreadcrumbListを生成できる - フロントエンドの
wp_headに JSON-LD を出力できる - Yoast SEO、Rank Math、All in One SEOが有効な場合に、重複出力の可能性を警告できる
- フィルターを使って、対象投稿タイプや生成データ、出力可否を調整できる
現在の対応範囲は、Article、BlogPosting、WebPage、WebSite、Organization、Person、BreadcrumbList を含む @graph 出力です。詳しい仕様は プラグイン設計・仕様 にまとめています。
出力される @graph の中身
構造化データの説明で @graph という言葉が出てくると、少し難しく感じるかもしれません。
ざっくり言うと、@graph は複数の Schema ノードをひとまとまりで表現するための形です。記事そのもの、記事が掲載されているページ、サイト全体、運営組織などを別々のノードとして出しつつ、@id で関係づけることができます。
OD Structured Data では、以下のような役割で @graph を組み立てます。
| Schema タイプ | このプラグインでの役割 |
|---|---|
Article | 投稿や固定ページの本文コンテンツを表します。通常の記事、ニュース、読み物など広めの記事コンテンツに使う想定です。 |
BlogPosting | ブログ記事として扱いたい投稿に使います。Schema.org 上では Article 系のより具体的なタイプとして位置づけられています。 |
WebPage | その投稿が表示されている Web ページ自体を表します。Article ノードの mainEntityOfPage から参照される対象になります。 |
WebSite | サイト全体を表します。サイト名やサイト URL をもとに、ページや運営組織との関係を示します。 |
Organization | 組織として運営するサイトの発行元・運営元を表します。名称、URL、ロゴ、公式プロフィールをサイト設定で管理できます。 |
Person | 個人を主体とするサイトの発行元・運営元を表します。Organization の代わりに選択できます。 |
BreadcrumbList | 固定ページの親子関係やカスタム投稿タイプのアーカイブなど、WordPress から確定できるサイト階層を表します。 |
例えば、Article ノードは「この記事はどのページの主な内容なのか」を mainEntityOfPage で示し、発行元は publisher でサイト主体を参照します。WebPage ノードは WebSite ノードに属し、パンくずを出力する場合は BreadcrumbList ノードも参照します。
こうして分けておくと、1つの JSON-LD の中で「記事」「ページ」「サイト」「運営元」「サイト内の階層」を混ぜずに表現できます。
また、すべてのノードを OD Structured Data が出力する必要はありません。SEO プラグインなどが WebSite や Organization を出力している場合は、設定画面で Schema ごとの出力担当を選べます。ほかのプラグインの出力を勝手に止めるのではなく、OD Structured Data 側が担当する範囲を狭める考え方です。
なお、ここで紹介している各タイプの説明は、あくまでもこのプラグイン内での使い方に寄せたものです。正確な定義や利用できるプロパティは、各 Schema.org 公式ページを確認してください。
公式ドキュメント:
- Schema.org Article
- Schema.org BlogPosting
- Schema.org WebPage
- Schema.org WebSite
- Schema.org Organization
- Schema.org Person
- Schema.org BreadcrumbList
完成済み JSON-LD を保存しない設計
個人的にこのプラグインで大事にしているのは、「完成済みの JSON-LD そのものを保存しない」という点です。
投稿ごとの設定は _od_structured_data という投稿メタに保存されます。ただし、そこに保存されるのは JSON-LD 全体ではなく、出力方針、Schema タイプ、上書き値、機能フラグといった設定差分です。
例えば、保存されるデータは以下のような形になります。
{
"enabled": true,
"outputMode": "enabled",
"schemaType": "BlogPosting",
"overrides": {
"headline": "",
"description": "",
"imageId": 0,
"authorName": ""
},
"features": {
"article": true,
"faqFromBlocks": false
}
}outputMode には、投稿タイプの設定を引き継ぐ inherit、この投稿だけ有効にする enabled、この投稿だけ無効にする disabled のいずれかが保存されます。以前のバージョンで保存した enabled も引き続き読み取れるようにしています。
実際の JSON-LD は、フロントエンド表示時や編集画面のプレビュー時に、PHP 側で組み立てます。
この形にしておくと、投稿タイトルやアイキャッチ画像、著者情報などが変わった時にも、保存済み JSON を手で直す必要がありません。WordPress 側の現在の情報を使って、出力時に再生成できるからです。
もちろん、すべてのサイトでこの設計が最適というわけではありません。構造化データをかなり細かく手入力したい場合や、商品・レビュー・イベントなど多様な Schema を一括管理したい場合には、別の方法を検討したほうが良い場面もあります。
ただ、投稿や固定ページの Article 系 Schema を、WordPress の標準データを活かしながら管理したい場合には、扱いやすい設計だと考えています。
基本的な使い方
使い方はシンプルです。
- WordPress 管理画面で OD Structured Data を有効化します。
- 「設定」>「OD Structured Data」で、投稿タイプごとの出力方針を選びます。
- OD Structured Data が出力を担当する Schema を選びます。
- サイト主体を
Organization、Person、出力なしから選び、必要な情報を設定します。 - 必要に応じて、
dateModifiedに WordPress の更新日時を使うか、省略するか選びます。 - 対象投稿タイプの編集画面を開きます。
- 投稿設定サイドバーにある「構造化データ」パネルを開きます。
- 投稿タイプの設定を継承するか、この投稿だけ有効・無効にするか選びます。
- 必要に応じて Schema タイプを
ArticleまたはBlogPostingから選びます。 - 見出し、説明文、画像、著者名を必要な場合だけ上書きします。
- 検証結果、情報源、最終出力値、JSON-LD プレビューを確認します。
- 投稿を保存します。
保存後、対象投稿のフロントエンドを表示すると、条件を満たしている場合に wp_head から JSON-LD が出力されます。
投稿タイプごとの出力方針は、次の3種類です。
- 無効
- 原則無効・投稿ごとに有効化
- 原則有効・投稿ごとに無効化
例えば、基本的にはすべての記事で出力し、特定の記事だけ除外したい場合は「原則有効・投稿ごとに無効化」が使えます。反対に、必要な記事だけ選びたい場合は「原則無効・投稿ごとに有効化」が向いています。
新規コンテンツのデフォルト有効化と、既存コンテンツの一括有効化も引き続き利用できます。以前のバージョンで保存した設定との互換性を保ちながら、投稿タイプの方針を継承できるようにしています。
管理画面では「今、何が自動取得されていて、どこだけ上書きしているのか」に加えて、「なぜ出力されるのか」「どの Schema をこのプラグインが担当するのか」も確認できます。構造化データは見えない情報になりがちなので、編集画面で現在の出力内容と判断理由を確認できることは、運用面でも大事だと思っています。
詳しい操作手順や REST API の内容は 使い方と機能詳細 にまとめています。
自動取得される情報と上書きできる情報
このプラグインでは、以下のような情報を WordPress から自動取得します。
| Schema プロパティ | 主な取得元 |
|---|---|
headline | 投稿タイトル |
description | 抜粋、または本文から生成した説明文 |
image | アイキャッチ画像 |
datePublished | 公開日時 |
dateModified | 更新日時。サイト設定で省略可能 |
author.name | 投稿者の表示名 |
author.url | 投稿者アーカイブ URL |
mainEntityOfPage | canonical URL。取得できない場合は投稿 URL |
publisher | サイト主体の設定 |
一方で、投稿ごとに調整したくなりやすい項目は上書きできます。
- 見出し
- 説明文
- 画像
- 著者名
画像の上書きは、WordPress 標準のメディア選択 UI から行えます。保存されるのは画像 URL ではなく、attachment ID です。上書き画像を削除すると、アイキャッチ画像からの自動取得に戻ります。
サイト主体の情報は投稿ごとではなく、サイト共通設定として管理します。組織のサイトなら Organization、個人を主体とするサイトなら Person を選び、名称、正式 URL、ロゴ、公式プロフィールの URL を設定できます。空の項目は、WordPress のサイト名、ホーム URL、サイトアイコンから補います。
個人的には、この「基本は自動取得、必要なところだけ上書き」というバランスが、日々の運用では扱いやすいと感じています。毎回 JSON を編集する運用は、どうしても属人化しやすいですし、後から見直す時にも少し怖さがあります。
編集画面で検証とプレビューができる
OD Structured Data では、編集画面で JSON-LD プレビューを確認できます。
ここで表示されるプレビューは、JavaScript だけでそれっぽく作っているものではありません。REST API 経由でサーバー側に設定を送り、PHP の Graph_Builder が生成した結果を表示しています。
つまり、編集画面で見ている JSON-LD と、フロントエンドで実際に出力される JSON-LD の処理が大きく分かれないようにしています。バージョン0.2.0では、保存前のタイトル、抜粋、アイキャッチ画像もプレビューへ渡すようにしました。
また、PHP 側の検証結果も編集画面に表示します。
検証結果は、次の3種類に分けています。
| 分類 | 扱い |
|---|---|
| エラー | JSON-LD を安全に生成できない問題です。該当する graph の出力を止めます。 |
| 推奨項目 | 説明文や画像など、品質上確認したい項目です。不足していても、生成可能な graph 全体は止めません。 |
| 整合性警告 | 上書き値と WordPress の取得値、canonical URL とパーマリンクなどの違いを知らせます。 |
現在の主な検証内容は以下です。
headlineが空の場合はエラーmainEntityOfPage.@idが空の場合はエラーdatePublishedが空の場合はエラーdescriptionが空の場合は推奨項目imageが空の場合は推奨項目- 見出し、説明文、著者名の上書き値が WordPress の取得値と異なる場合は整合性警告
- canonical URL と WordPress のパーマリンクが異なる場合は整合性警告
エラーがある場合、該当する JSON-LD graph は空になります。一方で、推奨項目や整合性警告だけなら、生成できる構造化データは出力します。以前は検証結果の役割がまとまっていましたが、軽微な不足と出力不能な問題を分けたほうが、実際の運用では判断しやすいと考えたためです。
さらに、見出し、説明文、画像、著者、公開日、更新日、URL について、取得元、自動取得値、上書き値、最終出力値を分けて表示します。JSON-LD 全文は必要な時だけ詳細表示を開いて確認できます。
テーマ上に表示されている著者やパンくずを、プラグインが推測で解析することはしていません。自動確認できない部分については、編集画面の最終出力値と公開ページを見比べて確認する必要があります。
構造化データは、出せば必ず良いというものではありません。出力する以上は、できるだけ意味の通る状態で出したいところです。
SEO プラグインとの併用について
すでに Yoast SEO、Rank Math、All in One SEO などを使っているサイトでは、それらのプラグインが Article、WebPage、WebSite、Organization、BreadcrumbList などを出力している場合があります。
OD Structured Data は、ほかの SEO プラグインが出力する JSON-LD を勝手に削除したり、停止したりしません。その代わり、該当するプラグインが有効な場合は、編集画面に重複出力の可能性を警告します。
バージョン0.2.0では、Article、WebPage、WebSite、サイト主体、BreadcrumbList ごとに、OD Structured Data が出力を担当するか選べるようにしました。例えば、WebSite と Organization は SEO プラグインへ任せ、Article だけを OD Structured Data で管理する、といった使い分けができます。
投稿単位で全体を止めたい場合は、投稿の出力設定を「この投稿だけ無効」にします。さらに独自条件が必要な場合は、od_structured_data_should_render フィルターでも出力可否を制御できます。
このあたりはサイトごとに判断が必要です。既存の SEO プラグインで十分に管理できているなら、無理にこのプラグインへ寄せる必要はありません。一方で、投稿ごとに Article 系 Schema を明示的に調整したい場合には、使い分ける価値があると思います。
開発者向けに拡張できるポイント
テーマや別プラグインから調整できるように、いくつかのフィルターを用意しています。
ただし、フックは今後の機能追加に合わせて増えたり、引数の扱いを見直したりする可能性があります。そのため、この記事では実務で使う場面が想像しやすく、今後も大きく変わりにくそうなものだけ紹介します。
まず、対象投稿タイプを変更したい場合は od_structured_data_post_types を使います。
add_filter(
'od_structured_data_post_types',
static function ( array $post_types ): array {
$post_types[] = 'news';
return $post_types;
}
);初期状態では対象投稿タイプは無効です。通常は「設定」>「OD Structured Data」で投稿タイプごとの出力方針を選びます。コード側で追加・調整したい場合は、このフィルターで対象を変更できます。
新規コンテンツの初期有効化や既存コンテンツの一括有効化は、管理画面の設定・操作として扱います。フィルターで対象投稿タイプを追加した場合も、一括有効化は最終的に対象として解決された投稿タイプに対して実行される想定です。
もうひとつ、出力可否をサイト独自の条件で制御したい場合は od_structured_data_should_render を使えます。
add_filter(
'od_structured_data_should_render',
static function ( bool $should_render, int $post_id, array $result ): bool {
unset( $result );
if ( has_category( 'no-schema', $post_id ) ) {
return false;
}
return $should_render;
},
10,
3
);例えば、特定カテゴリーでは SEO プラグイン側の出力を優先したい、特定の投稿だけ構造化データを止めたい、という運用で使いやすいと思います。
パンくずの階層をサイト独自のルールで変更する場合は、od_structured_data_breadcrumb_items を利用できます。固定ページと階層型カスタム投稿タイプは親子関係、非階層型カスタム投稿タイプは公開アーカイブを使いますが、カテゴリーなど曖昧な階層はプラグイン側で勝手に選びません。
他にも、以下のような用途に応じたフィルターを用意しています。
od_structured_data_post_typesod_structured_data_allowed_article_typesod_structured_data_post_settingsod_structured_data_resolved_post_dataod_structured_data_article_schemaod_structured_data_breadcrumb_itemsod_structured_data_graphod_structured_data_should_render
それぞれの詳しい引数や利用例は、記事内で追いかけるよりもマニュアル側を見てもらうほうが安全だと思います。最新の内容は フック一覧 を参照してください。
インストールと更新について
インストールは、GitHub Release から配布される od-structured-data.zip を使う想定です。
WordPress 管理画面の「プラグイン」>「新規追加」>「プラグインのアップロード」から ZIP ファイルをアップロードして、有効化します。
このリポジトリを直接配置する場合は、プラグインディレクトリ名を od-structured-data にしてください。また、依存ライブラリが必要になるため、配置後に以下を実行します。
composer install --no-dev --prefer-dist --optimize-autoloaderプラグイン更新については、GitHub Releases を使って WordPress 管理画面から更新できるようにしています。内部的には inc2734/wp-github-plugin-updater を利用しています。
現時点での注意点
現時点では、Article 系 Schema、サイト主体、BreadcrumbList を中心に対応しています。
そのため、以下のような用途は今後の拡張候補です。
LocalBusinessEventProductReview- SEO プラグイン個別 API との連携
- E2E テスト
- より詳細な Google の検索機能向け検証
FAQPage は、AI 検索対策として追加する予定はありません。ページ上の質問と回答を継続して管理できる具体的な利用要件が生じた時に、あらためて検討します。
また、現在の検証はプラグイン内で定義しているチェックです。検索エンジン側のすべての要件を完全に代替するものではありません。公開前には、必要に応じて外部の検証ツールでも確認すると良いでしょう。
まとめ
OD Structured Data は、WordPress の投稿や固定ページに Article 系の構造化データを追加し、出力内容と情報源を確認しながら管理するためのプラグインです。
完成済み JSON-LD を手で保存するのではなく、WordPress の既存データをもとに PHP 側で生成し、必要なところだけ投稿ごとに上書きする。そこを軸にしています。
構造化データを細かく作り込みたい場面では、まだ足りない部分もあります。ただ、投稿単位で Article 系 Schema を管理したい、ほかのプラグインとの担当範囲を分けたい、編集画面で取得元や警告を確認しながら運用したい、という場合には試しやすい形になってきたと思います。
WordPress サイトで構造化データの扱いを少し整理したい方の参考になれば嬉しいです。
