JSON-LD ビューアと構造化データチェッカー

JSON-LD とは何か、なぜグラフなのか

JSON-LD は、<script type="application/ld+json"> タグの中に JSON で書かれた構造化データです。schema.org の語彙でページを説明します（これは Blue Mug という Product で、24 USD で、この Organization が販売しています）。検索エンジンや AI アシスタントが、レイアウトから推測しなくて済みます。Google は JSON-LD、Microdata、RDFa を読み、JSON-LD を推奨しています。

すべてのオブジェクトに @type があります。@id もあることがあります。識別子で、通常はページ URL にフラグメントを足したものです。例: https://example.com/#organization。他のオブジェクトは、繰り返さずにその @id で指せます。こうして 1 ページが言えます。この WebPage はこの WebSite に属し、WebSite はこの Organization が公開し、ページ上の Product は同じ Organization が作っている、と。

参照が揃うと、ページはつながった一つの事実の集まりを説明します。@id の打ち間違いや、ホームページにしか出ない Organization への参照があると、各ブロックは解析できても、つながりは静かに失われます。プロパティの一覧では分かりません。グラフなら分かります。つながるべきエンティティが単独で置かれるか、矢印が破線のカードで終わります。

グラフの読み方

• 各カードは 1 つのエンティティです。色付きのラベルが @type です。その下に name（または headline、title、URL）と、平文のプロパティが最大 4 つあります。
• 矢印は、プロパティを持つエンティティから、指す先のエンティティへ伸びます。ラベルはプロパティ名です。offers、brand、publisher、author、isPartOf。
• どこからも指されていないエンティティは、左の列にあります。右の列ほど、一段深くなります。
• 「参照されているが、未定義」と書かれた破線のカードは、何かが指しているが、ページ上の何も説明していない @id です。
• 同じ @id のオブジェクトは、別の script ブロックにあっても 1 枚のカードにまとまります。2 枚を期待して 1 枚なら、@id が同じです。
• 読むのは JSON-LD だけで、Microdata や RDFa は読みません。非常に大きなグラフは、最初の 150 エンティティを表示します。「PNG をダウンロード」は、白背景のグラフを保存し、チケットや顧客レポートに使えます。

スコアと問題の意味

スコアは 0 から 100 で、6 項目の重みです。JSON-LD が正しい形式か（20%）、リッチリザルトに Google が必須とするプロパティがあるか（30%）、値の形式が正しいか（20%）、推奨プロパティ（15%）、@id 参照が解決するか（10%）、細かな良いやり方（5%）です。JSON-LD がないページは 0 です。

問題はエラーが先に並びます。それぞれは Product.offers.price のようなパスで始まり、テンプレート内を検索できます。表示されるメッセージと、それぞれの対処です。

ブロックが有効な JSON ではありません

構文エラーのため、ブロック全体が無視されます。よくある原因は、末尾のカンマ、文字列内でエスケープされていない二重引用符、何も出力しなかったテンプレート変数です。ブロックを JSON パーサーに通し、示された行を直してください。

@context がありません

@context がないと、プロパティ名は意味を持ちません。各トップレベルのオブジェクトに "@context": "https://schema.org" を追加してください。http://schema.org でも動きます。https が望ましい形式なので、通知としてだけ表示されます。

ノードに @type がありません

プロパティがあっても型がないオブジェクトは、解釈できません。何であるかを示す @type を追加してください。例: Offer、Person、PostalAddress。

… には … が必要です。ないとリッチリザルトの対象になりません

Google はそのプロパティを、その型のリッチリザルトに必須としています。Event には name、startDate、location が必要です。BreadcrumbList には itemListElement が必要です。ページに表示されている実際の値で追加してください。

… には … を含めてください

推奨プロパティがありません。なくても対象には残りますが、結果の表示は減ることがあります。事実である場合だけ追加してください。通知を消すために、評価やレビュー数を作らないでください。

数値が必要 / 絶対 http(s) URL が必要 / ISO 8601 の日付が必要 / @type を持つ入れ子オブジェクトが必要

値の形が違います。価格 "$24.00" は 24.00 にし、通貨は priceCurrency に入れます。"Sept 3, 2026" のような日付は "2026-09-03" にします。/img/mug.jpg のような画像パスは、完全な URL にします。著者を平文で書く場合は、name を持つ Person または Organization のオブジェクトにします。availability のような決まった一覧の値は、https://schema.org/InStock のように、一覧のいずれかである必要があります。

… の中身は … です。必要なのは …

入れ子のオブジェクトの型が違います。住所が Person を持っている、などです。@type を、メッセージが示す型に変えてください。

position … は欠番なく 1..n である必要があります / 最後以外のすべてのパンくずには item が必要です

BreadcrumbList では、position は欠番なく 1、2、3 と数えます。最後（現在のページ）以外のすべてのパンくずには、そのパンくずの URL を持つ item が必要です。

@id "…" はこのページで参照されていますが、定義されていません

これはグラフの破線のカードです。何かが、このページの何も説明していない @id を指しています。多くは打ち間違い（#organization ではなく #org、https ではなく http、末尾のスラッシュ不足）か、エンティティが別ページにしか出ていない場合です。よくあるのは、ホームページの Organization です。参照はリンクではなく、取得しに行くものはありません。つづりを直すか、このページにもエンティティを出力してください。

互いに @id で参照し合わない、別々のエンティティが … 個あります

互いに指し合わない、トップレベルのエンティティが複数あります。有効ですが、無関係な事実として読まれます。それぞれに @id を付けてつないでください。WebPage の isPartOf を WebSite へ、Article の publisher を Organization へ。

… には、検査できるリッチリザルトがありません

その型のルールはありません。エラーではありません。エンティティはグラフに出ます。中に入れ子になったものも検査されます。

具体例

商品ページが、1 つの @graph に Organization、WebPage、Product を出しています。各部分は解析でき、一見問題ありません。

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Example Coffee Co.",
      "url": "https://example.com/",
      "logo": "https://example.com/logo.png"
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/products/blue-mug#webpage",
      "name": "Blue Mug",
      "url": "https://example.com/products/blue-mug"
    },
    {
      "@type": "Product",
      "@id": "https://example.com/products/blue-mug#product",
      "name": "Blue Mug",
      "image": "https://example.com/img/blue-mug.jpg",
      "mainEntityOfPage": { "@id": "https://example.com/products/blue-mug#webpage" },
      "brand": { "@id": "https://example.com/#org" },
      "offers": {
        "@type": "Offer",
        "price": "$24.00",
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock"
      }
    }
  ]
}

グラフは、コードが隠していることを示します。Organization は左の列に単独で、どこからも指されていません。Product の brand の矢印は、https://example.com/#org の破線カードで終わります。問題の一覧も、パス付きで同じことを言います。

error  Product.offers.price
       price on Offer: expected a number, got the bare text "$24.00"
error  Product.brand
       @id "https://example.com/#org" is referenced but never defined on this page

修正は 2 行です。brand を、Organization が実際に使う @id に向け、価格から通貨記号を除きます。

"brand": { "@id": "https://example.com/#organization" },
…
  "price": 24.00,

スコアは 79 から 94 になり、Organization は Product とつながりました。残る 4 件の通知は、sameAs、sku、aggregateRating、offer の url を求めています。店舗に当てはまるものだけ追加してください。レビューのない商品に、評価は付けないでください。

質問