shopify-json-ld

Shopify JSON-LD

Shopify ストアに補足的な構造化データを追加します。テーマ単独では生成できないスキーマタイプ（Recipe、FAQPage、より詳細な Article／Collection ノード）を、エンティティごとのメタフィールドに JSON-LD として保存し、単一の Liquid スニペットを通じてレンダリングします。基本原則は、不足しているものだけを追加し、テーマがすでに出力しているものは重複させないことです。 メタタグ、説明、Open Graph（別の役割です）については、関連スキルの shopify-seo-metadata を使用してください。

ストアへのアクセス

レーン A：カスタムアプリのトークン（スクリプトで実行可能）。 Shopify 管理画面で、Settings → Apps and sales channels → Develop apps の順に開き、このスキルに必要な最小限のスコープを許可してアプリを作成し、インストールして Admin API アクセストークンをコピーします。トークンをエクスポートしてください。コミット対象のファイルには絶対に書き込まないでください。

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # env only, not on disk

最小限のスコープは read_products、write_products、read_content、write_content です。メタフィールド専用のスコープはありません。メタフィールドへのアクセス権は、所有するリソースのスコープによって決まります（products → write_products、pages/articles → write_content）。スニペットのレンダリングにはテーマの編集アクセス権（テーマエディターまたはテーマの Git リポジトリ）が必要で、これは API とは別です。トークンが正常に動作するか確認します。

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}'

レーン B：Shopify CLI の OAuth（トークンを保存しない方法）。 shopify store auth --store $SHOPIFY_STORE --scopes read_products,write_products,read_content,write_content を実行してから、shopify store execute を実行します。ストアのオーナーがログインする、トークンを使わないストアに適しています。

ツールキットの事前確認。 レーン B は Shopify CLI を使用するため、まず shopify version を実行し、インストールされていない場合はインストールしてください。Admin GraphQL スキーマ全体を確認し、検証済みの実行を行うには、このスキルと Shopify 公式 AI ツールキットプラグインを組み合わせてください。Claude Code で claude plugin list を確認し、プラグインがない場合は次を実行します。

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

推奨ですが、必須ではありません。レーン A で必要なのは curl とトークンだけです。ツールキットはエージェントに API を提供し、このスキルは実行手順を提供します。

補足専用の原則：生成前に監査する

最新の Shopify テーマは、PDP で Product スキーマ（価格、バリエーション、在庫状況、Judge.me、Yotpo、Stamped などのレビューアプリを使用している場合は aggregateRating も）をすでに出力しています。また、サイト全体で Organization／WebSite を出力し、多くの場合 Article／BreadcrumbList も出力します。これらを重複させると、適格性が向上するどころか、競合するノードが作成されて適格性を損ないます。

そのため、最初に行うのは必ず読み取り専用の操作です。ホームページ、PDP、コレクション、ブログ記事を取得し、すべての <script type="application/ld+json"> ブロックを抽出します。

curl -s "https://$SHOPIFY_STORE/products/<some-handle>" \
  | grep -o '<script type="application/ld+json">[^<]*' | head

テーマがすでに対応しているものには、手を加えません。 補足スキーマは同じページ上の別のタイプ（テーマの Product ノードに加えて FAQPage または Recipe ノードを配置するなど）であり、2つ目の Product ノードを追加することではありません。テーマの Product スキーマが壊れている、または欠けている場合は、テーマを修正してください。重複データでその場しのぎをしてはいけません。

メタフィールドとスニペットのパターン

JSON-LD をメタフィールドに保存し、そのままレンダリングします。レンダリング時に値が変換されることはないため、保存する文字列はすでに有効な JSON-LD でなければなりません。

1. メタフィールドを定義する（Settings → Custom Data → エンティティタイプ → Add definition）：namespace は custom、key は json、type は multi_line_text_field に設定します。データを入力する各エンティティタイプ（Products、Collections、Pages、Articles）に定義を作成します。

2. theme.liquid の </head> の前に、レンダリングスニペットを1つ追加します。

{%- if request.page_type == 'product' and product.metafields.custom.json != blank -%}
  <script type="application/ld+json">{{ product.metafields.custom.json }}</script>
{%- elsif request.page_type == 'collection' and collection.metafields.custom.json != blank -%}
  <script type="application/ld+json">{{ collection.metafields.custom.json }}</script>
{%- elsif request.page_type == 'page' and page.metafields.custom.json != blank -%}
  <script type="application/ld+json">{{ page.metafields.custom.json }}</script>
{%- elsif request.page_type == 'article' and article.metafields.custom.json != blank -%}
  <script type="application/ld+json">{{ article.metafields.custom.json }}</script>
{%- endif -%}

3. GraphQL の metafieldsSet を使用して値を書き込みます。namespace／key を基準に upsert するため、既存のメタフィールドを重複させずに更新できます。これにより、すでに存在するメタフィールドに対して2つ目のメタフィールドを POST してしまう、REST でよくある問題を回避できます。JSON はコンパクトな形式（JSON.stringify(obj)、整形用の空白なし）で保存してください。一括書き込みの前に対象件数を確認します。想定を大幅に上回る場合は、処理を止めて対象範囲を見直してください。パイプライン全体とエンティティごとのプロンプトについては、references/pipeline-and-prompts.md を参照してください。

譲れない2つのスキーマルール

Googleは、深くネストされたものも含め、検出したすべての型付きノードを検証します。ノードが1つでも不正な形式だと、ブロック全体が失敗します。次の2つのルールで、その大半を防げます。

• Productノードを単独で記述しないでください。 Googleはすべての@type: "Product"にoffers、review、aggregateRatingのいずれかを必須としています。補足スキーマでは、（テーマが管理するため）これらがほとんどないので、商品を名前で参照する場合は@type: "Thing"を使い、Productは使いません。
• 不完全なVideoObjectノードを使わないでください。 VideoObjectにはname、description、thumbnailUrl、uploadDate、およびcontentUrlまたはembedUrlが必要です。実際の動画メタデータがない場合は、VideoObjectを出力せず、代わりにThingか、ListItemエントリーのItemListを使ってください。

この2つの間違いが、Search Consoleで「Invalid object type for field」や「missing field」エラーが発生する主な原因です。

FAQPageはもはやリッチリザルトの利点ではありません

Googleは**2026年に、権威性のない（コマース）サイト向けのFAQリッチリザルトを廃止しました。**商品ページやストアページのFAQPageマークアップは、検索結果に展開可能なQ&Aスニペットを表示しなくなります。有効な構造化データであり、ページの機械的な理解にも引き続き役立ちますが、リッチリザルトやSERPでの可視性向上につながるものとして売り込んだり、宣伝したりしないでください。その説明は古くなっています。Recipeと、本当に該当する場合のArticleは引き続き対象となります。目に見える結果を約束する前に、Googleのドキュメント（出典を参照）でタイプごとの最新の対象条件を確認してください。

ハルシネーションを防ぐ生成

エージェントが商品やページのコンテンツからFAQや説明的なスキーマを生成する場合、**ソーステキストに記載されている事実のみを断定できます。**寸法、重量制限、素材、機能を作り出してはいけません。ソースの説明が簡素な場合は、エントリーを減らして生成してください。根拠のあるQ&Aが3件あるほうが、回答を2件捏造した5件より優れています。また、スキーマ内で仕様を捏造すると、Google（および顧客）に見抜かれる事実の主張になります。プロンプトでは捏造を明示的に禁じ、「推測」より「省略」を優先してください。エンティティごとのプロンプト構成はリファレンスにあります。

ストアフロントではなくAdmin APIで確認する

書き込み後、ShopifyのCDNがレンダリング済みページをキャッシュするため、ストアフロントでは数分から数時間、古いJSON-LDが提供されることがあります。商品ページにcurlを実行するのではなく、Admin API経由でメタフィールドを読み戻して書き込みを確認してください。

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ product(id:\"gid://shopify/Product/<ID>\") { metafield(namespace:\"custom\",key:\"json\"){ value } } }"}'

メタフィールドの値が正となるデータです。値が正しければ、ストアフロントはキャッシュの更新サイクルで追いつきます。この遅延は、追跡して修正すべきバグではありません。

非破壊のデフォルト設定

• 読み取ってから書き込んでください。一括更新時にメタフィールドのセルを空白にすると、値をスキップするのではなく削除します。上書きを意図していない限り、未入力の項目だけを埋めてください。
• 一括書き込みの前にバックアップを取ってください（既存のcustom.json値を先にエクスポートします）。
• Admin APIアクセストークンを表示したり、コミットしたりしないでください。環境変数から読み取ってください。

参考資料

• references/pipeline-and-prompts.md：生成パイプライン（fetch → filter → generate → validate → write）と、エンティティごとのプロンプトレシピ（Product FAQ、Recipe、Collection、Page、Article）。必要に応じて読み込みます。

出典とメンテナンス

最終確認日：2026-07-05。GraphQLはAdmin API 2025-07に固定されています。Shopifyは四半期ごとにバージョンを非推奨にするため、バージョン固有の説明を信頼する前にバージョンを確認してください。Googleのリッチリザルトの対象条件は変更されます。FAQリッチリザルトはコマースサイト向けに廃止され、ほかのタイプも変わるため、目に見えるSERP結果を約束する前に、 Googleの構造化データに関するドキュメント でスキーマタイプごとに再確認してください。正規の型定義は schema.org にあります。第三者でも実行できる読み取り専用の再確認方法：

# 1. Confirm the token reaches the store.
curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}'

# 2. Confirm a product page actually renders a JSON-LD block.
curl -s "https://$SHOPIFY_STORE/products/<some-handle>" \
  | grep -c 'application/ld+json'

次に、Googleのリッチリザルトテスト（https://search.google.com/test/rich-results）でライブURLを検証してください。これらのスキルには、ドキュメントにはない運用上の教訓が含まれていますが、schema.orgやGoogleの参考資料に取って代わるものではありません。