定義
自分のページが「何に関するものか」（製品か、価格はいくらか、この記事の著者・日付は何か）を検索エンジンに確実に理解させ、Google検索結果に星評価・価格・パンくずパスのようなリッチ結果として出したいときに使う方式である。
JSON-LD（JavaScript Object Notation for Linked Data）は、その意味情報をHTMLの中に<script type="application/ld+json">タグとして入れるデータ形式である。schema.org（Google・MSなどが共同で定めた標準の語彙辞書）の単語でWebPage（ウェブページ）、Product（製品）、Offer（販売条件・価格）、BreadcrumbList（パンくずナビゲーションのパス）といったタイプを書いておくと、検索エンジン・クローラ（ウェブを巡回して索引する bot）が人ではなく機械としてもページの意味を正確に読み取る。
なぜ必要か
価格ページ・製品詳細は、画面に文字として見せるだけでは、機械が「これがプラン名で、あれが価格で、通貨はウォンで、このページはこのカテゴリの下にある」という関係を安定して抽出しにくい。JSON-LDはこの関係を露骨に明示する。画面UIがclient component（ブラウザで実行されるReactコンポーネント）であっても、**サーバーで実行されるpage.tsx**でビルダー関数でこのデータの束（graph）を作れば、SEO用データと画面UIをきれいに分離できる。
動作原理
*JsonLd.tsのような純粋ビルダーで@context、@graph、@type、@idを組み立てる。- サイト全体のOrganization/WebSiteは
@id参照だけにし、ページごとに全体を再定義しない。 - localeごとのcanonical URL・名前を反映する。
page.tsx（Server Component）で:
- Offerは実際の販売価格があるtierのみ; 問い合わせ型のenterprise tierは除外する。
実務での適用
- 静的な価格テーブル・i18n文字列をビルダー入力に — ランタイムDBなしでも決定的なgraphを生成する。
- Vitestで
@graphの長さ、Offerの数、必須@typeをassertする。 - ゲスト/ログインUIの分岐はclient; JSON-LDは公開情報を基準にサーバーでのみ生成する。
トレードオフ
| 選択 | 利得 | コスト |
|---|---|---|
| Server script inject | クローラが初期HTMLから即座にパース | ビルダー・テスト維持 |
| Client-only graph | UIと1ファイル | クローラ・SSRの利点減少 |
| 巨大なsingle graph | 1つのscriptで関係を表現 | ページごとの保守負担 |
使ってはいけない場合
- 非公開・個人化データをgraphに入れる必要がある場合（公開JSON-LDは不適）。
- 価格がクライアントでのみ決定されサーバーが知り得ない場合 — graphがstale・不正確になる。
よくある間違い
JSON.stringifysanitizeなしでuser-controlledな文字列を挿入する。- Organization/WebSiteをページごとに重複定義してgraphが不整合になる。
- UIのclientコンポーネント内でのみgraphを生成する — 初期HTMLにない。
- 問い合わせ型プランに価格のないOfferを含める。
関連概念
- single-source-of-truth-content-metadata — frontmatter・メタのSSOT
- critical-rendering-path — scriptのパースとレンダー（一般にnon-blocking）