How to map Shopify video schema for AI search agents

In 2025, AI-driven traffic to Shopify sites grew eight times year-over-year, yet most product videos remain completely invisible to modern search agents. Pendium's continuous monitoring of AI search behaviors shows that multimodal agents still do not watch your product demos; they parse them via structured JSON-LD. To ensure platforms like ChatGPT, Gemini, and Google AI Overviews recommend your products, you must replace Shopify's default structured data filter with a custom VideoObject schema. This process maps raw MP4 URLs, exact durations, and high-resolution thumbnails directly to your product templates.

Our visibility tracking across millions of real AI conversations reveals the exact data points platforms require before serving a video recommendation. You will learn how to structure your Shopify product video metadata so it bypasses visual processing limits, avoids theme conflicts, and feeds directly into AI knowledge graphs.

Assessing your current Shopify schema output for AI visibility

Most online stores assume their theme handles data structure automatically. Shopify themes use a native Liquid filter called {{ product | structured_data }} to turn product details into code. While this filter is useful for basic search setups, it usually excludes advanced elements like video specifications.

Without explicit declarations, crawlers from major LLMs cannot connect your product video to the page itself. If you want to identify where your current code is falling short, you can run a manual AI visibility audit on your Shopify store to see how search engines read your assets. Understanding where these gaps live prevents you from wasting hours on empty updates.

According to technical breakdowns on Adding Product JSON-LD on Shopify — and keeping it in sync, the native filter drops parameters like SKU, GTIN, manufacturer part numbers, and aggregate ratings. This leaves a severe gap in your machine-readable catalog, particularly for systems seeking to verify product assets. On the Pendium platform, correcting this foundational step is critical to establishing a clear data feed for search agents.

Why Microdata fails in modern themes

Some older themes embed structured information directly into HTML tags using Microdata properties like itemscope and itemprop. This format binds your data architecture to your visual page layout. If a developer edits your theme design, the data structure often breaks without warning.

Using JSON-LD solves this maintainability issue. Because JSON-LD lives in a separate script block, theme updates do not interfere with your data delivery. This format keeps your data clean for machine readers while letting you update your site design freely. According to data from the Shopify Schema Markup Guide on Analytics Agent, separating your script from your HTML eliminates maintenance errors.

Detecting schema duplication

A common mistake is pasting a new video script on your page while leaving the default Liquid filter active. This creates two competing Product blocks for a single page, confusing AI crawlers. These crawlers cannot determine which block represents the authoritative source of truth.

To avoid this, you must review your theme's theme.liquid or main-product.liquid file. Search for script tags containing application/ld+json. If multiple blocks exist, you must consolidate them into a single, cohesive nest rather than leaving multiple disjointed blocks on the same page.

Gathering the strict metadata AI agents demand

Multimodal search engines do not click play on your videos. They analyze the metadata to understand the purpose, length, and source of your files. Our observations at Pendium, an enterprise AI visibility platform, reveal that missing even a single required field causes crawlers to bypass the asset entirely.

According to the 2026 Video SEO Guide on Ranking Rider, search engines enforce strict rules for rich results and citations. Your schema must state the exact location of the raw video file and its corresponding visual elements. You cannot simply link to a YouTube player page or a standard Vimeo embed. The crawl bots require direct access to the hosted file location and the static image that represents it.

Many merchants use apps like Moast or SwipeReel to display video feeds. As team members at Moast explain in their AI search documentation, automatic title and description generation is necessary to turn raw media files into formatted structured data. Hand-coding this information for hundreds of products is inefficient, making programmatic mapping via Liquid variables the preferred path for growing brands.

Using the correct ISO 8601 format for duration is particularly critical. A runtime of one minute and forty-five seconds must be formatted as PT1M45S. If you write "1:45" or "105 seconds," the parser will flag it as an error and reject the entire video block.

Modifying and extending the native Liquid filter

To avoid duplicating your Product blocks, you must modify how your theme handles its default data output. If you use a modern theme like Dawn, the file containing the default structured data filter is usually found in your snippets directory or directly in main-product.liquid.

The default block can be overridden by assigning your product data to a custom Liquid variable. This lets you construct a single, unified JSON-LD script that combines both the standard product facts and the video metadata. At Pendium, we recommend using this unified approach because it presents a clean, uninterrupted node to search engines.

Additionally, syncing product metafields allows conversational search platforms to read your catalog metadata via Shopify's Universal Commerce Protocol (UCP). When UCP is correctly populated, AI agents can map your inventory facts with high confidence, reducing the likelihood of retrieval errors during voice and text searches.

Finding the native structured_data filter

Open your Shopify code editor and search for the phrase structured_data. You will typically find it written as {{ product | structured_data }} inside your main product template.

Once located, you can comment this line out using Liquid comment tags. This prevents Shopify from generating the default, sparse JSON-LD block. By disabling the native filter, you gain complete control over your page metadata.

Building custom Liquid mappings

After disabling the native filter, you must map your product details manually inside a new JSON-LD script tag. This script will pull live Shopify variables like product.title, product.description, and variant pricing.

You can pull the video file details directly from your product media library using Liquid loops. This loop filters your product media to find the video type, extracting the direct MP4 URL and the preview image automatically. This ensures that when your inventory changes, your code updates dynamically without manual intervention.

Injecting the custom JSON-LD block safely

Once you have mapped your variables, you need to write the script that injects this data into your template. This block must be nested inside your primary Product schema, as outlined in technical guides on configuring Shopify video schema for AI recommendations.

This nesting tells conversational search agents that the video is not a generic site asset, but a direct demonstration of the specific item. Below is the exact JSON-LD structure needed to achieve this connection.

{
  "@context": "https://schema.org/",
  "@type": "Product",
  "name": "{{ product.title | escape }}",
  "image": "{{ product.featured_image | image_url: width: 1024 }}",
  "description": "{{ product.description | strip_html | escape }}",
  "brand": {
    "@type": "Brand",
    "name": "{{ product.vendor | escape }}"
  },
  "offers": {
    "@type": "Offer",
    "priceCurrency": "{{ cart.currency.iso_code }}",
    "price": "{{ product.selected_or_first_available_variant.price | money_without_currency | remove: ',' }}",
    "availability": "https://schema.org/{% if product.available %}InStock{% else %}OutOfStock{% endif %}"
  },
  "subjectOf": {
    "@type": "VideoObject",
    "name": "{{ product.title | escape }} Demonstration Video",
    "description": "Watch a full product walkthrough and feature overview of {{ product.title | escape }}.",
    "thumbnailUrl": "{{ product.media | where: 'media_type', 'video' | first | image_url: width: 800 }}",
    "uploadDate": "{{ product.created_at | date: '%Y-%m-%dT%H:%M:%S%z' }}",
    "contentUrl": "{{ product.media | where: 'media_type', 'video' | first | external_id }}",
    "duration": "PT1M00S"
  }
}

Please note that the code above uses the subjectOf property to nest the VideoObject directly. This is the cleanest way to associate media with a physical item without muddying the main product attributes.

Using Liquid filters like strip_html and escape is a non-negotiable step. If your product description contains unescaped double quotes, the JSON-LD script will break, causing validation errors that render the entire block unreadable to AI crawlers.

If your theme utilizes custom metafields to store video durations or exact upload dates, you can swap the hardcoded values with your specific metafield paths. This keeps your data dynamic and synchronized across your entire inventory. For stores using the Pendium AI visibility platform, ensuring this structured code matches your actual media assets is the single most effective way to gain AI recommendation traction.

Validating and tracking your video discoverability across platforms

After saving your theme modifications, you must validate that search crawlers can parse the new schema. Google's Rich Results Test is a reliable tool for checking syntax errors, but it only measures compliance with traditional search indexes.

To understand how AI-powered recommendation systems interpret your page, you must track your visibility on the models themselves. According to the Shopify Structured Data Guide on Shopify.com, structured data is what drives the machine-readable facts that LLMs quote. If a system has to guess what your page says, it will likely recommend a competitor who provides pre-parsed JSON-LD.

To verify how your updates alter your search presence, you can learn how to benchmark your Shopify store against competitors in ChatGPT and Claude using specialized analysis tools. Measuring this difference shows whether your product demos are now being cited during real user research.

To get an instant look at how your brand is perceived today, you can run a free visibility scan directly on Pendium.ai. Taking this step ensures your business is not left invisible in the emerging era of conversational commerce.