Codex で行う SEO Schema JSON-LD: そのまま使える SKILL.md と検証ワークフロー

結論: Schema はページ上の事実を構造化した写しにする

SEO Schema JSON-LD 用の Codex SKILL.md プロンプトを探しているなら、この記事の後半にそのまま使えるテンプレートがあります。ただし、コードより先に守るべき原則があります。構造化データは、訪問者がページ上で確認できる事実を表現するものです。できるだけ多くのプロパティを埋めた JSON を作る場ではありません。

Codex は、型を提案したり JSON-LD を書いたりする前に、ページ、コンテンツデータ、既存のマークアップを確認できます。この順番が重要です。「入れられる Schema を全部追加して」という曖昧な依頼では、aggregateRating、価格、著者、公開日などが根拠なく出力されがちです。JSON としては正しくても、ページの内容を誤って表すことがあります。

Google は、サイトの構成で可能なら JSON-LD を推奨しています。実装と保守が比較的容易だからです。同時に、マークアップは対象ページを説明し、ユーザーに見える内容と一致し、正確でなければならないと示しています。Rich Results Test に通っても、リッチリザルトが表示される保証はありません。

補助オブジェクトより先に、ページの主な型を選ぶ

まず「訪問者はこのページで何を主に見ているのか」を考えます。その答えが主となる Schema.org 型です。パンくず、組織情報、動画は、同じページでユーザーに見えている情報を説明する場合にのみ主オブジェクトを補助できます。

Schema.org の語彙は Google のリッチリザルト機能より広範です。Google 検索向けの実装では、「Schema.org にプロパティがある」ことより、対象機能の最新 Google Search Central ドキュメントを優先してください。

まずページの目的を確認します。型は可視の事実から決まり、逆ではありません。

より安全な Codex ワークフローには 4 つの関門がある

1. 事実インベントリ: 見えているページ文面、ページ上に表示される信頼できる CMS フィールド、またはユーザーが明示的に確認したデータだけを抽出します。候補フィールドには確認済み、不明、要確認の状態を付けます。
2. 型の判断: ページの中心目的に合う主な型を一つ選びます。もっともらしい型を一つのレスポンスに積み上げるのではなく、代替案があれば理由を説明します。
3. コードと対応関係: 出力する JSON-LD の各値に情報源を付けます。不明なプロパティはプレースホルダーで埋めず、省略します。
4. 検証と公開: JSON 構文、機能固有の要件、レンダリング後の DOM、URL Inspection、該当する Search Console レポートを確認します。

以下の Skill は、この関門を明示します。Codex に先に監査し、後からコードを変更させることで、見た目だけ正しいマークアップがページ内容からずれるのを防げます。

そのままコピーできる SEO Schema JSON-LD Codex Skill (SKILL.md)

以下を自分の Skill 設定として保存してください。マシンのディレクトリ、ユーザー名、アクセストークン、環境変数の値、非公開パスは含みません。Codex に対して、出力から機密コンテキストを除外することも指示します。

---
name: seo-schema-jsonld
description: Audit visible page facts, recommend accurate Schema.org JSON-LD, implement it safely, and validate it against Google structured-data requirements.
---

# SEO Schema JSON-LD

Use this skill when a user asks to add, repair, review, or validate Schema.org JSON-LD / structured data for a website page, template, CMS entry, or component.

## Primary rule

Treat structured data as a structured representation of the page's user-visible facts. Never use it to invent, hide, exaggerate, or imply information that the page does not support.

## Privacy and output safety

- Never print absolute local paths, home directories, usernames, credentials, tokens, cookies, API keys, environment-variable values, private URLs, or repository-specific secrets.
- Refer to files with short, project-relative labels when needed, such as `src/pages/article.tsx` or `the page template`.
- Do not copy sensitive values into JSON-LD, examples, logs, commit messages, screenshots, or explanations.
- If input contains secrets or private identifiers, omit them and state that sensitive values were excluded.

## Required workflow

### 1. Inspect before generating

Read the relevant page, template, content data, and any existing structured data. Build a fact inventory using only:

- visible page text and user-visible UI;
- trusted CMS fields that are rendered on that page;
- verified product, organization, author, or breadcrumb data supplied by the user.

For every candidate property, label it `confirmed`, `missing`, or `needs human confirmation`. Do not infer missing values from brand names, URLs, conventions, or unrelated pages.

### 2. Choose the narrowest suitable type

Identify the page's primary purpose first. Recommend one primary Schema.org type that truthfully describes it. Add supporting objects only when they also describe user-visible information on the same page.

Explain the recommended primary type, supporting types, why each applies, and types deliberately rejected.

For Google rich-result eligibility, consult the current Google Search Central documentation for the target feature. Schema.org support alone does not establish Google feature support.

### 3. Apply strict data guardrails

Never generate these values unless they are confirmed and visible or otherwise explicitly verified by the user:

- `aggregateRating`, `review`, or review counts;
- price, currency, availability, offer dates, shipping, or return policy;
- author, publisher, logo, address, phone, social profile, or `sameAs`;
- publication dates, modification dates, images, video duration, or interaction counts;
- FAQ questions and answers that are not visibly present;
- event, job, medical, financial, legal, or local-business claims.

Never add misleading `FAQPage`, fake reviews, hidden content, keyword lists, or unrelated types. Prefer fewer complete and accurate properties over many uncertain ones.

### 4. Produce the implementation

Return these sections in order:

1. `Fact inventory` - property, value or status, and visible source.
2. `Schema decision` - primary type, supporting types, assumptions, and exclusions.
3. `JSON-LD` - valid JSON inside one `application/ld+json` script block. Use placeholders only in a clearly labeled illustrative example; never present placeholders as production-ready values.
4. `Implementation note` - the safe insertion point for the site's framework or CMS, without exposing private paths.
5. `Validation checklist` - syntax, rendered-page check, Google Rich Results Test when applicable, Schema Markup Validator, URL Inspection after deployment, and Search Console monitoring.
6. `Open questions` - every field that needs a human decision.

If editing code is requested, make the smallest scoped change. Preserve existing valid markup, avoid duplicate entities, and explain any conflict before replacing it.

## JSON-LD quality checks

Before finalizing, verify all of the following:

- JSON parses and uses `https://schema.org` as `@context`.
- The main type matches the page's main user-visible purpose.
- Every emitted value has a page-level source or explicit user confirmation.
- Required fields for the intended Google feature are present and accurate.
- URLs are canonical, publicly reachable URLs when the property requires a URL.
- Dates use ISO 8601 where required.
- Multiple entities are connected deliberately, not duplicated accidentally.
- The markup remains available to crawlers in the rendered response.
- The result contains no secrets, local paths, private identifiers, or fabricated claims.

## Limitations to state plainly

Valid structured data can help search engines understand a page and make it eligible for certain search appearances. It does not guarantee rich results, rankings, traffic, citations, or inclusion in AI answers.

承認ゲートを付けて Skill を使う

「このページに Schema を追加して」だけで終わらせないでください。ページと受け入れ条件を Codex に伝えます。たとえば次のプロンプトから始められます。

Use the SEO Schema JSON-LD skill to review this article page.

Goal: add accurate Article and BreadcrumbList JSON-LD if the visible content supports them.
First return the fact inventory and schema decision. Do not edit code until I approve the decision.
Do not create ratings, reviews, author details, dates, images, or organization fields that are absent from the page.
After approval, make the smallest implementation change and provide the validation checklist.

大規模なテンプレートでは、「最初に事実インベントリと型の判断を返す」というゲートを残してください。短いレビューが一つ増えますが、誤った前提が数千 URL に広がるのを防げます。

監査から公開までの 30 分ワークフロー

公開後は、URL Inspection で Google がページを取得・解析できるか確認します。次に関連する Search Console の拡張レポートで、テンプレート、デプロイ、データソースの問題を規模で見つけます。前者は単一 URL、後者はシステム全体の故障を見つけるのに向いています。

各層で見つかる失敗は異なります。構文が有効でも、ページ事実やデプロイのチェックで失敗することがあります。

あえて最小限にした記事ページの例

これは説明用のコードであり、そのまま本番に貼り付けるオブジェクトではありません。BlogPosting と BreadcrumbList の形だけを示します。タイトル、説明、URL、著者、日付、画像にはページで確認した実際の値を使ってください。ページにその事実がなければ、オブジェクトを充実させるためだけに追加してはいけません。

この例には評価、著者、公開日、画像、発行者を意図的に入れていません。これらは任意の SEO 装飾ではなく、信頼できる情報源が必要な主張です。

技術的に有効でも失敗する 5 つの理由

JSON が解析できても、事実が正しいとは限らない

JSON バリデータは構文が解析できるかを確認できます。しかし、ページに本当にレビュー、価格、著者があるか、Product が単なるサービス説明ページではないかは判断できません。事実インベントリはこの種の失敗の多くを早い段階で防ぎます。

オブジェクトを増やしてもマークアップは良くならない

動画が見えるレシピページなら Recipe、VideoObject、パンくずを正当に含められます。それでも主目的は明確であるべきです。一般的なコンテンツページに Article、Product、FAQPage、HowTo をすべて追加すると、通常は保守作業と不整合のリスクが増えます。

可視性と鮮度には同じ責任者が必要

Google の一般ガイドラインは、構造化データがページを表し、時間に敏感な情報を最新に保つことを求めます。価格、在庫、イベント日、求人、評価を一度だけ貼り付けた値にしてはいけません。動的な事実は管理されたデータソースにつなぎ、テンプレート変更時に再テストしてください。

FAQPage は汎用的な Q&A 装飾ではない

実際にユーザーが見られる質問と回答だけが FAQ マークアップに属します。Google の機能には追加の適格条件がある場合もあります。まず本物で完全な FAQ を公開し、それから最新の機能ガイドを確認してください。結果表示だけを狙って質問リストを逆算しないでください。

Schema はクロール、インデックス、ページ品質を迂回しない

重要なページが noindex、アクセス制御、クロールルールでブロックされている場合、JSON-LD があっても検索結果の対象にはなりません。Schema はテクニカル SEO の一層です。クロール可能性、有用なコンテンツ、ページ体験の代わりにはなりません。サイト全体を確認する場合は、 Auspia の SEO ツール一覧 から適した監査ワークフローを選べます。

公開前チェックリスト

• [ ] ページの主な型が明記され、一文で根拠を説明できる。
• [ ] JSON-LD のすべての値に、可視ページまたは信頼できる表示済みデータの根拠がある。
• [ ] 評価、レビュー、価格、在庫、著者、日付、画像、組織情報を捏造していない。
• [ ] CMS、プラグイン、別コンポーネントが出力するエンティティと重複しない。
• [ ] JSON が解析でき、デプロイ後の DOM にマークアップが残っている。
• [ ] 対象 Google 機能の必須プロパティを最新の公式ドキュメントで確認した。
• [ ] 該当する場合は Rich Results Test と Schema Markup Validator を使った。
• [ ] 公開後の URL Inspection と Search Console レビューを予定した。
• [ ] 有効なマークアップは適格性と理解を与えるもので、リッチリザルトや順位を約束するものではないとチームが理解している。

FAQ

SKILL.md でサイトに必要な Schema を決められますか？

ページ上の事実から提案し、不明点を洗い出すことはできます。しかし事実確認の代わりにはなりません。製品価格、レビュー、組織情報、著者、公開日は、信頼できるページデータソースまたは担当者から取得してください。

JSON-LD は <head> と <body> のどちらに置くべきですか？

Google は HTML の <head> と <body> のどちらの JSON-LD もサポートしています。フレームワークまたは CMS がページ内容と同期し続けられる安定した場所を使ってください。重要なのは、Google がレンダリングされたページと一致する有効なマークアップをクロールできることです。

Rich Results Test に通ったのに何も変わらないのはなぜですか？

テスト成功は技術的な適格性シグナルを確認するもので、Google にリッチリザルトの表示を義務付けるものではありません。Google はクエリ、デバイス、地域、ページ自体など多くのシグナルで結果表示を選びます。根拠のないプロパティを追加するのではなく、コンテンツの一致とインデックス可能性を確認してください。

Codex に見つかるすべての Schema.org プロパティを埋めさせるべきですか？

いいえ。Google は、不完全または不正確なプロパティを大量に追加するより、少数でも完全で正確な推奨プロパティを重視します。この制約は一度きりのプロンプトではなく、Skill に入れるべきです。

公式リファレンス

• Google Search Central: Introduction to structured data markup
• Google Search Central: General structured data guidelines
• Google Rich Results Test
• Schema.org

著者: Auspia の 14-Year Technical SEO Practitioner、Julian Mercer。クロール可能性、レンダリング、構造化データ、チームが安定して運用できる技術システムについて執筆しています。