Docsbook
概要

ドキュメント向け JSON-LD:重要なスキーマタイプ

JSON-LD は HTML に埋め込まれた構造化データで、ページ上のコンテンツの種類を検索エンジンや AI エージェントに伝えます。ドキュメントでは、適切なスキーマタイプによって、ページの種類、手順、パンくずリスト、製品の識別情報を、レイアウトから暗黙的に推測させるのではなく、機械可読にできます。

この記事では、追加する価値のあるスキーマタイプを一覧にし、Google がそのリッチリザルトを後に制限したタイプを示し、実際に機能する例を紹介します。ランキングや引用を保証するものではありません。検証済みの手法であっても、いずれに対しても、プラットフォームをまたいで安定した因果効果は確認されていないためです。

要約#

スキーマ 使用対象 重要な理由
TechArticle ハウツーおよびチュートリアルページ Googleに「これは技術コンテンツです」と伝える
FAQPage Q&Aがあるすべてのページ 機械可読のQ&Aペア。ただし、ほとんどのサイトではリッチリザルトは表示されません。詳しくは以下を参照してください
HowTo 手順ガイド Googleで手順のリッチリザルトを表示
SoftwareApplication 製品概要ページ 価格、評価、OSを表示
Article ブログ記事およびお知らせ 標準的な記事のリッチリザルト
BreadcrumbList すべてのドキュメントページ 検索結果にパンくずリストを表示
WebSite サイトのルート SiteSearchActionによりGoogle検索ボックスを有効化

1つだけ行うなら、TechArticleBreadcrumbListを行ってください。Docsbookがこれらを自動的に追加します。

MicrodataやRDFaよりもJSON-LDを選ぶ理由#

JSON-LDが優れている理由:

  1. 独立した<script>ブロックであり、HTMLマークアップから分離されている
  2. Googleが明確に推奨している(ドキュメントで「推奨」と記載)
  3. 保守が容易 — レイアウトに触れずにスキーマを変更できる
  4. AIエージェントがインラインマークアップよりも確実に解析できる

MicrodataとRDFaも引き続き機能しますが、2026年時点ではレガシーです。

TechArticle: ドキュメントのデフォルト#

ほとんどのドキュメントページでは、TechArticle が適切なスキーマです:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "How to authenticate with OAuth",
  "description": "Step-by-step guide to authenticating users with OAuth 2.0",
  "author": {
    "@type": "Organization",
    "name": "Acme",
    "url": "https://acme.com"
  },
  "datePublished": "2026-01-15",
  "dateModified": "2026-03-20",
  "publisher": {
    "@type": "Organization",
    "name": "Acme",
    "logo": {
      "@type": "ImageObject",
      "url": "https://acme.com/logo.png"
    }
  },
  "mainEntityOfPage": "https://docs.acme.com/auth/oauth"
}
</script>

これにより得られること:

  • Google がそのページを権威ある技術コンテンツとして評価します
  • AI エージェントは、引用において TechArticle タグ付きのページをより高く評価する傾向があります
  • dateModified により、クローラーにページが新しいことを伝えられます

FAQPage: リッチスニペットの決定版#

ページにQ&A構造がある場合、FAQPageスキーマにより、GoogleはそのQ&Aを検索結果に直接表示します。

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "How do I revoke an API key?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Open the dashboard, navigate to API Keys, find the key, click Revoke. Revocation is immediate."
    }
  }, {
    "@type": "Question",
    "name": "Can I have multiple API keys?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Yes. Replace this answer with the real limit from your own product."
    }
  }]
}
</script>

FAQPage マークアップは現在も Google でリッチリザルトを生成しますか?#

ほぼすべてのドキュメントサイトでは、いいえ。Google は 2023 年に FAQ リッチリザルトを制限し、現在の公式ドキュメントでは、この機能は「著名で信頼性の高い政府および健康関連のウェブサイトにのみ表示される」と記載されています(Google Search Central、FAQPage 構造化データ、2026-09-03 閲覧)。プロダクトドキュメントサイトで FAQ スニペットによるクリック率向上を約束するガイドは、2023 年以前の状況について説明しているものです。

だからといって、マークアップを削除する理由にはなりません。FAQPage は今でも 1 つのことをうまく行います。それは、このブロックが質問であり、あのブロックがその回答であることを、パーサーが誤読できない形式で示すことです。ページが実際に質問と回答の一覧になっている場合はそのまま維持し、Google 上で見た目に変化がないことを想定してください。

HowTo: ステップバイステップガイド#

番号付きのステップバイステップガイドがある場合は、HowToを使用してください:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Set up a custom domain for documentation",
  "step": [{
    "@type": "HowToStep",
    "text": "Open the dashboard and go to Settings → Domain"
  }, {
    "@type": "HowToStep",
    "text": "Enter your subdomain (docs.yourcompany.com)"
  }, {
    "@type": "HowToStep",
    "text": "Add a CNAME record in DNS pointing to cname.vercel-dns.com"
  }, {
    "@type": "HowToStep",
    "text": "Wait for SSL to provision (under 5 minutes)"
  }]
}
</script>

結果:Google では、各ステップが展開されたステップバイステップのリッチリザルトが表示される場合があります。

SoftwareApplication:製品ページ#

製品概要ページにはSoftwareApplicationタグを付ける必要があります:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Acme",
  "applicationCategory": "DeveloperApplication",
  "operatingSystem": "Web",
  "offers": {
    "@type": "Offer",
    "price": "150",
    "priceCurrency": "USD"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "ratingCount": "247"
  }
}
</script>

これにより、Googleのリッチリザルトに価格と評価が表示されます。評価については正直でいてください — Googleは水増しされたaggregateRatingにペナルティを科します。

すべてのページには、JSON-LDでパンくずリストを設定する必要があります。Googleは検索結果にパンくずリストを表示し、AIエージェントは階層構造を理解するために利用します。

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{
    "@type": "ListItem",
    "position": 1,
    "name": "Docs",
    "item": "https://docs.acme.com"
  }, {
    "@type": "ListItem",
    "position": 2,
    "name": "Authentication",
    "item": "https://docs.acme.com/auth"
  }, {
    "@type": "ListItem",
    "position": 3,
    "name": "OAuth",
    "item": "https://docs.acme.com/auth/oauth"
  }]
}
</script>

ホームページで、サイト検索を宣言します:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://docs.acme.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://docs.acme.com/search?q={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}
</script>

これにより、Googleの検索結果のすぐ下に検索ボックスが表示されます。

1ページに複数のスキーマ#

スキーマは重ねて記述できます。ドキュメントページには次のようなものを含めることができます。

  • コンテンツタイプ用のTechArticle
  • ナビゲーション用のBreadcrumbList
  • Q&Aセクションがある場合はFAQPage

これら3つを、それぞれ別の<script type="application/ld+json">ブロックに記述します。Googleはこれらすべてを読み取ります。

AIエージェントがJSON-LDで行うこと#

観察された3つの動作:

  1. タイプによるフィルタリング — チュートリアルを探すエージェントは、Article よりも TechArticleHowTo を優先する
  2. 抽出のショートカットFAQPage スキーマは、ほぼそのまま抽出される
  3. 信頼シグナル — 適切な Organizationpublisher を備えたスキーマは、より高く評価される

DocsbookがJSON-LDを提供する仕組み#

Docsbookは自動的に以下を追加します:

  • すべてのドキュメントページにTechArticle
  • すべてのページにBreadcrumbList
  • Q&Aパターンを検出したページにFAQPage
  • メタデータが提供されている場合、ホームページにSoftwareApplication
  • サイトのルートにSearchAction付きのWebSite

設定は不要です。スキーマは既存のMarkdownとフロントマターから構築されます。

検証#

2つのツール:

  • Google リッチリザルト テストhttps://search.google.com/test/rich-results
  • Schema.org バリデーターhttps://validator.schema.org/

ドキュメントのページで両方を実行してください。警告があれば修正してください。エラーはブロック要因ですが、警告はそうではありません。


DocsbookはすべてのページにJSON-LDを自動的に追加します。ドキュメントを公開 →

Updated

このページは役に立ちましたか?