【ITニュース解説】Your JSON-LD is probably inside a @graph, and most parsers don't look there

Webサイトが持つ情報は、人間が読むだけでなく、検索エンジンやAIなどの機械が理解しやすいように整理されていると、その価値が大きく高まる。この目的のために使われるのが「構造化データ」であり、その中でも「JSON-LD」という形式が広く利用されている。JSON-LDは、ウェブページの内容（例えば、記事のタイトル、商品の価格、イベントの日時など）を機械が正確に解釈できるよう、特定のルールに基づいて記述されたデータだ。これにより、検索結果に魅力的な情報（リッチスニペット）が表示されたり、AIがより精度の高い情報収集を行ったりすることが可能になる。

しかし、このJSON-LDの記述方法には、主に二つの異なる「形」が存在し、多くの解析ツールがその違いを十分に認識できていない、という重要な問題が起きている。この問題は、システムエンジニアがウェブサイトを評価したり、機能を開発したりする際に、誤った情報に基づいて判断を下してしまう原因となるため、その詳細を理解しておく必要がある。

一つ目の形は「シンプルなフラット形式」と呼ばれ、多くのJSON-LDの入門書やチュートリアルで紹介されている基本的な構造だ。この形式では、JSONデータの一番上の階層に、そのデータが何を表すかを示す「@type」（例えば「Article」なら記事の情報）が直接記述されている。記事であれば、そのタイトルや著者がこの「@type」の下にまとめられており、単一の情報をシンプルに表現するのに適している。

もう一つの形は「グラフ形式」と呼ばれ、実は今日のWebサイトの多く、特にWordPressのようなコンテンツ管理システム（CMS）で、検索エンジン最適化（SEO）のためのプラグイン（Yoast SEOやRankMathなど）を利用している場合にデフォルトで生成される形だ。このグラフ形式では、JSONデータの一番上の階層には「@context」という共通の語彙定義と、「@graph」という特別なキーが配置される。そして、この「@graph」の中には、組織情報、ウェブサイト情報、具体的なウェブページ情報、記事情報といった、複数の独立した情報が配列として格納されている。

このグラフ形式の大きな強みは、格納されている個々の情報が「@id」という識別子を通じて互いに参照し合える点にある。例えば、「記事」の情報がその記事が掲載されている「ウェブページ」を参照し、その「ウェブページ」が属する「ウェブサイト」を参照し、さらにその「ウェブサイト」を運営する「組織」を参照するといった具合に、関連性のある複数の情報を一つのまとまりとして表現できる。このように、情報同士のつながりを明確にし、データの重複を避けることで、検索エンジンはコンテンツ全体の複雑な構造や相互関係をより深く、正確に理解できるようになる。多くのSEOプラグインがこの形式を採用しているのは、まさにその優れた特性を最大限に活かすためだ。

ところが、ここに大きな問題が生じる。世の中に存在する多くのJSON-LD解析ツールは、この「グラフ形式」の構造を正しく処理できない場合が多いのだ。これらのツールは、トップレベルに直接「@type」があることを前提に設計されているため、グラフ形式のように情報が「@graph」の内部に格納されている場合、「@type」が見つからないと判断し、「このページには構造化データが存在しない」という誤った結果を報告してしまう。これは、Webサイトのデータが間違っているわけではなく、解析ツールが想定している形式と実際の形式が異なるという、解析ツール側の認識不足に起因する。

筆者自身の経験でも、開発したツールがこの問題に直面し、正しくマークアップされているはずのページが「構造化データがない」と診断されてしまう事態があったという。このような誤った診断は、システムエンジニアがWebサイトの問題解決に取り組む際に、大きな混乱を招く可能性がある。例えば、ツールが「データがない」と報告したからといって、実際には問題がないにもかかわらず、JSON-LDの記述を見直したり、手動で修正しようと試みたりするような、無駄な作業に時間を費やしてしまうことになりかねない。

この問題を解決するためには、JSON-LDを解析するツール側で特別な処理を組み込む必要がある。具体的には、解析を行う前に、JSON-LDデータがどのような形式であっても、そこに含まれるすべての構造化データの要素を「平坦化」する処理を挟むのだ。平坦化とは、グラフ形式のように複雑にネストされたデータ構造の中から、すべての個別の情報要素を抽出し、それらを平坦なリストとして取り出す作業を指す。

この平坦化処理を実装する際には、いくつか注意すべき点がある。まず、WebページにはJSON-LDが複数のブロックとして記述されていたり、あるいは一つのブロックの中にデータの配列として格納されていたりする場合がある。そのため、データを受け取る側は、こうした多様な形式に対応できる柔軟な処理が必要だ。次に、「@graph」の中にさらに「@graph」がネストしているような、より複雑な構造も考慮し、再帰的にデータを深く探索する仕組みが求められる。また、@typeの値が単一の文字列だけでなく、複数のタイプを示す配列（例: "@type": ["Person", "Organization"]）である可能性も考慮し、適切に処理する必要がある。

このような平坦化処理を解析の初期段階で一度実行しておけば、その後のデータチェックや分析を行うツールは、データの形式がシンプルなフラット形式であろうとグラフ形式であろうと意識することなく、統一された形式のデータとして扱うことができる。これにより、解析ツールはより正確な情報を提供できるようになり、システムエンジニアは構造化データに関する誤った報告に惑わされることなく、本当に解決すべき問題に集中できるようになる。

最終的に、Webサイトの構造化データについて監査ツールや検証ツールが「データがない」と報告した場合でも、まずは自分の目でウェブページのソースコードを確認し、実際にJSON-LDが存在するか、そしてそれが「グラフ形式」で記述されていないかを確認することが重要だ。ツールが示す結果を鵜呑みにせず、その裏にある技術的な仕組みを理解する姿勢こそが、より正確な問題解決への第一歩となる。今回のJSON-LDの形式問題は、まさに「ツールの報告が常に正しいとは限らない」という、システム開発において常に心に留めておくべき教訓の一つであると言えるだろう。