メインコンテンツまでスキップ

実装 + 検証 + 運用 (架空 SaaS の完成 JSON-LD)

この章で扱うこと​

03 章 で決めた型を組み合わせて、Acme Workflow のサービス紹介ページの 完成 JSON-LD を提示します。

  • Google Rich Results Test / Schema Markup Validator での妥当性検証
  • 典型的なエラー / 警告とその修正方法
  • 実装時のハマりポイント
  • 継続運用 (Search Console 監視 / リグレッション防止 / schema.org 更新追従)

までを扱います。

完成 JSON-LD​

Acme Workflow のサービス紹介ページ (https://example.com/services/workflow/) の完成 JSON-LD です。

Acme Workflow サービス紹介ページの JSON-LD
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Acme Inc.",
      "url": "https://example.com/",
      "logo": "https://example.com/assets/logo.png",
      "sameAs": [
        "https://www.linkedin.com/company/acme-inc-example",
        "https://x.com/acme_inc_example"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com/",
      "name": "Acme Inc.",
      "publisher": { "@id": "https://example.com/#organization" },
      "inLanguage": "ja"
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/services/workflow/#webpage",
      "url": "https://example.com/services/workflow/",
      "name": "Acme Workflow — 業務担当者向けタスク管理 SaaS",
      "description": "Acme Workflow は、中小企業の業務担当者がチームのタスクを一元管理できる SaaS です。",
      "inLanguage": "ja",
      "isPartOf": { "@id": "https://example.com/#website" },
      "mainEntity": { "@id": "https://example.com/services/workflow/#service" }
    },
    {
      "@type": "Service",
      "@id": "https://example.com/services/workflow/#service",
      "name": "Acme Workflow",
      "description": "業務担当者向けのタスク管理 SaaS。チームのタスクを一元管理し、業務の見える化を支援します。",
      "serviceType": "タスク管理 SaaS",
      "provider": { "@id": "https://example.com/#organization" },
      "audience": {
        "@type": "BusinessAudience",
        "audienceType": "業務担当者",
        "name": "中小企業の業務担当者"
      },
      "areaServed": {
        "@type": "Country",
        "name": "Japan",
        "identifier": "JP"
      }
    }
  ]
}

フィールドごとの意図​

各 @graph 要素の役割を整理します。

Organization (Acme Inc.)​

  • @id: サイト全体で一意 (https://example.com/#organization)。他ページから @id で参照する想定
  • name / url / logo: ナレッジパネルの基礎情報
  • sameAs: 関連 URL の配列。Google が「これらは同じ組織」と認識しやすくなる

WebSite​

  • @id: サイト全体で一意 (https://example.com/#website)
  • publisher: Organization を @id で参照
  • inLanguage: サイトの言語

WebPage​

  • @id: このページに固有 (https://example.com/services/workflow/#webpage)
  • name / description: ページ自体の情報
  • isPartOf: 親 WebSite を @id で参照
  • mainEntity: このページの主題 Service を @id で参照

Service (Acme Workflow)​

  • @id: このページに固有 (https://example.com/services/workflow/#service)
  • name / description / serviceType: サービスの基礎情報
  • provider: Organization を @id で参照 (= Acme Inc. が提供)
  • audience: BusinessAudience で対象を表現
  • areaServed: Country (Japan) で提供地域を表現

HTML への埋め込み​

完成した JSON-LD は <head> 内に <script> タグで埋め込みます。

services/workflow/index.html (該当部分のみ)
<!DOCTYPE html>
<html lang="ja">
<head>
  <meta charset="UTF-8">
  <title>Acme Workflow — 業務担当者向けタスク管理 SaaS</title>
  <meta name="description" content="Acme Workflow は、中小企業の業務担当者がチームのタスクを一元管理できる SaaS です。">
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@graph": [
      ...
    ]
  }
  </script>
</head>
<body>
  ...
</body>
</html>
フレームワーク別の実装

  • Next.js (App Router): app/services/workflow/page.tsx で次の script タグを return する (公式推奨。metadata export は JSON-LD 非対応)

    <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />

  • Nuxt 3: useHead({ script: [{ type: 'application/ld+json', innerHTML: JSON.stringify(jsonLd) }] })

  • 静的サイト (Astro / Hugo / Jekyll): テンプレートで直接 <script> 出力

実装言語に依存する詳細は各 FW のドキュメントを参照してください。本ガイドは JSON-LD の構造に集中します。

検証ステップ 1: Schema Markup Validator (schema.org 公式)​

Schema Markup Validator (確認: 2026-05) は schema.org 公式の妥当性検証ツールです。schema.org の語彙的に正しいか だけを検証します (Google 固有の要件は次の Rich Results Test で確認)。

使い方​

  1. ツールを開く
  2. Code Snippet タブを選択
  3. 上記の JSON-LD を貼り付ける
  4. Run Test をクリック
  5. 結果として、検出された型と各プロパティが一覧表示される

確認ポイント​

  • 各 @type が正しく認識されているか
  • プロパティが型の値域に合っているか
  • "Errors" / "Warnings" が出ていないか

Schema Markup Validator のエラーは schema.org 仕様違反 なので必ず修正します。Warnings は推奨事項なので、可能な範囲で対応します。

検証ステップ 2: Google Rich Results Test​

Google Rich Results Test (確認: 2026-05) は Google 固有の リッチリザルト対象として有効か を検証します。

使い方​

  1. ツールを開く
  2. コードスニペット タブを選択 (もしくは URL を直接指定)
  3. JSON-LD を含む HTML を貼り付ける (<script> タグごと)
  4. テスト実行 をクリック
  5. 結果として、Google がリッチリザルト対象として認識した型が一覧表示される
本ガイドの JSON-LD では Organization のみ検出される

Rich Results Test の対象型リストには Organization が含まれるため、本ガイドの完成 JSON-LD をテストすると Organization が検出されます。一方、WebPage / Service / Audience / Country は対象外のため一覧には現れませんが、これはエラーではありません。構文・語彙の妥当性は前段の Schema Markup Validator で担保します。

Rich Results Test と Schema Markup Validator の違い​

ツール検証範囲主な用途
Schema Markup Validatorschema.org 語彙の妥当性構造化データが規格通りか
Google Rich Results TestGoogle が解釈する範囲 + リッチリザルト要件Google での表示可能性

両方で検証 するのが推奨です。Schema Markup Validator で構造的に正しいことを確認し、Rich Results Test で Google 視点での表示可能性を確認します。

典型的なエラー / 警告と修正方法​

エラー 1: 値域違反 (ツールは検出しないことがある)​

"audience": "業務担当者" のように文字列で書くのは schema.org の値域違反ですが、Schema Markup Validator はこれを寛容に解釈し、エラーを出さないことがあります (実測)。Product など Google のリッチリザルト対象型を Rich Results Test にかけた場合は、次のような "Invalid value type" 系のエラーが出ます。

The value of property "audience" should be of type "Audience" but got "Text"

本ガイドの型では ツールが沈黙していても値域違反は修正が必要 です。値域は schema.org の各型ページで確認し、Audience オブジェクトに変換します。

"audience": {
  "@type": "BusinessAudience",
  "audienceType": "業務担当者",
  "name": "中小企業の業務担当者"
}

エラー 2: "Unknown property"​

Property "providor" not recognized

→ プロパティ名のタイポ (例: providor ではなく provider)。schema.org のプロパティ名は camelCase で厳密です。

エラー 3: "Missing required field"​

Rich Results Test 固有の警告で、Google がリッチリザルトに必要と判断するフィールドが欠けている場合に出ます。

例えば Product で offers / aggregateRating / review が無いと「レビュー / 価格情報が無いためリッチリザルト非対象」と警告されます。

落とし穴: @id の重複はエラーにならず「静かにマージ」される​

@graph 内で同じ @id を持つオブジェクトが複数あっても検証ツールはエラーを出しません。JSON-LD では同一 @id = 同一ノードであり、プロパティが混ざった 1 つのエンティティとして解釈されます (実測: validator.schema.org はエラー 0 件でマージ)。意図しない使い回しはツールで検出できない設計ミスになるため、@id の一意化は 03 章 の規約に従い自分で担保します。

実装時の落とし穴​

落とし穴 1: @context の version 指定​

"@context": "https://schema.org/version/13.0"

のように version を固定したくなりますが、schema.org の context は 特定 version を固定しない のが慣習です。"https://schema.org" のままにします。Google も version 指定を要求しません。

落とし穴 2: @id の URL がページ URL と一致しない​

WebPage の @id は そのページの URL ベース に合わせます。

"@id": "https://example.com/services/workflow/#webpage"

ページ URL が /services/workflow/ なら、@id も同じパスを使います。https://example.com/#workflow-page のようにルートにフラグメントを付けると、ページとオブジェクトの対応が曖昧になります。

落とし穴 3: ネストの過剰深化​

{
  "@type": "WebPage",
  "mainEntity": {
    "@type": "Service",
    "provider": {
      "@type": "Organization",
      "publisher": {
        "@type": "Organization",
        ...
      }
    }
  }
}

のように深くネストすると、可読性とメンテ性が損なわれます。@graph + @id 参照に書き直すと、各オブジェクトが独立して見える構造になります。

落とし穴 4: 動的データの埋め込みエスケープ漏れ​

CMS や DB から取得した値をテンプレートに埋め込むとき、JSON エスケープが甘いと " や改行で JSON が壊れます。必ず JSON.stringify (またはサーバー言語の同等関数) を経由 します。

// Good
const html = `<script type="application/ld+json">${JSON.stringify(jsonLd).replace(/</g, "\\u003c")}</script>`;

// Bad - テンプレート文字列で直接埋め込み (壊れる可能性)
const html = `<script type="application/ld+json">
  { "name": "${page.title}" }
</script>`;

加えて、CMS 由来の文字列に </script> などが含まれると script ブロックの破壊や XSS の原因になるため、< を \u003c に置換するのが公式推奨です (JSON 文字列として有効なまま HTML パーサーから無害化されます)。

落とし穴 5: Audience を Service 外に置く​

{
  "@type": "WebPage",
  "audience": { "@type": "BusinessAudience", ... },
  "mainEntity": {
    "@type": "Service",
    ...
  }
}

のように audience を WebPage 直下に置くケースがありますが、audience は 主題 (Service) の対象 なので、Service 内に置くのが意味的に正しいです。WebPage.audience は「このページ自体の対象読者」になり、意味がずれます。

運用節 — 「実装して終わり」ではない​

構造化データは 継続運用が必要 です。CMS 更新 / サイトリニューアル / Google アルゴリズム変更 / schema.org 更新で陳腐化します。実装後の運用規範を整理します。

規範 1: Search Console のリッチリザルト レポート監視 (対象型がある場合)​

Search Console の リッチリザルト レポート は、サポート対象のリッチリザルト型 (パンくずリスト / 商品スニペット / レビュー スニペット 等) の有効なマークアップを検出した場合に、タイプ別にエラー / 警告 / 有効アイテム数を表示します。一方、本ガイドの WebPage / Service / Audience / Country のような意味付けのみの型は対象外で、Search Console には表示されません。これらの監視は規範 5 の手動検証や CI での構文チェックが主手段になります。

リッチリザルト対象型を併用しているサイトでは、レポートの 2 区分を次のように読みます。

  • エラー (赤): リッチリザルト非対象になる重大問題。即修正
  • 警告 (黄): リッチリザルトは出るが推奨フィールドが欠けている。可能な範囲で改善
対象型がある場合の推奨運用
  • 週次または月次でリッチリザルト レポートを確認する習慣をつける
  • Search Console の通知設定を有効化していれば、新規エラー検出時に通知を受け取れる
  • 大規模サイトの場合は、レポートを定期的に CSV エクスポートして変化を追跡

規範 2: PR テンプレで JSON-LD 確認チェックボックス​

JSON-LD を含むページのコード変更時、レビューで構造化データの整合性確認を忘れがちです。PR テンプレに以下のようなチェックボックスを入れます。

PR テンプレ例 (.github/pull_request_template.md)
## 構造化データチェック (該当時)

- [ ] JSON-LD の `name` / `description` が表示テキストと一致している
- [ ] 削除した本文コンテンツに対応する構造化データ要素も削除した
- [ ] Rich Results Test (https://search.google.com/test/rich-results) で検証済み
- [ ] `@id` の URL がページ URL と整合している

規範 3: schema.org 更新追従の workflow​

schema.org は年に複数回 version update があり、新規型の追加 / 既存プロパティの deprecation 等が発生します。

推奨運用
  • 年 1 回 (例: 各年 4 月) に schema.org の Release History を確認
  • 使用中の型 / プロパティが deprecated になっていないか確認
  • 重要な追加機能 (例: 新しい Audience サブタイプ等) があれば適用検討

deprecation 通知は突然来ることはなく、長い猶予期間が設けられるのが通例ですが、計画的に追従するほうが安全です。

規範 4: コンテンツとマークアップの整合性維持​

サイトリニューアルや CMS 移行時に、構造化データだけ古いまま放置されるケースがあります。

  • 表示テキストが変わったら、構造化データの該当値も同時に更新
  • Audience / Country / Service 内容が変わったら、型も含めて再検討
  • リニューアル時は 構造化データの再設計 をスコープに含める

規範 5: 定期的なリグレッションテスト​

検証ツールでの妥当性検証を CI に組み込む のが理想ですが、Rich Results Test には公式の公開 API がありません。CI に組み込むなら schema-dts による型レベル検証や、構造化データ検証用の OSS ライブラリを使うのが現実的です。

簡易策として、月次で代表ページ数件を手動 Rich Results Test にかける運用も実用的です。

このガイドのまとめ​

ここまでの内容を振り返ります。

  • 構造化データと JSON-LD の基礎
  • Google ガイドラインの規範
  • 型選定の判断プロセス
  • 実装 / 検証 / 運用

を一通り扱いました。Acme Workflow の例を自サイトの文脈に置き換えれば、サービス紹介ページの JSON-LD は実装できるはずです。

振り返り
  • 型を選ぶ前にまず ページの主題 を 1 つに絞る
  • 公式仕様 (schema.org / Google Search Central) を一次ソースとして都度参照する
  • 実装後は検証ツールで必ず妥当性を確認する
  • 継続運用を計画に含める

他の型 (Article / Product / FAQPage / BreadcrumbList 等) の網羅解説、Microdata / RDFa の詳細、国際化 (inLanguage の多言語サイト) などは本ガイドのスコープ外です。必要になったら本ガイドの判断プロセスを下敷きにして、該当型の公式ドキュメントを参照してください。