Shopify ImageObject Schema for Visual Search — Product Image Structured Data & AI Vision Markup

Why Product Images Are Invisible to AI Visual Search Without Schema

Visual search AI systems index products in two steps: (1) crawl the image URL to analyze the visual content, and (2) read the structured data on the page to understand what the image represents. Without structured data, a crawler seeing "image": "https://cdn.shopify.com/s/files/1/0001/myproduct.jpg" gets only the image URL — no description, no context about whether it's the primary product shot or a packaging detail, no alt text, no dimensions. The AI must infer everything from the pixel content alone, which is error-prone for product imagery (multiple angles, lifestyle context, similar-looking SKUs).

Full ImageObject markup solves this by providing machine-readable metadata alongside the visual content. Google's systems use representativeOfPage to select which image to show in Shopping tiles. AI shopping agents use description to understand what is shown in each image before fetching it. Image search ranking algorithms use width/height aspect ratio and encodingFormat to match images to query contexts (portrait for apparel, square for products, widescreen for lifestyle).

ImageObject property reference

Primary Image Pattern: Single ImageObject on Product

For the simplest case — a product with one primary image — replace the bare string image URL with a full ImageObject. Set representativeOfPage: true to designate it as the page's primary visual. Map the Shopify image alt text to description.

{
  "@type": "Product",
  "name": "Navy Wool Coat",
  "image": "https://cdn.shopify.com/
    s/files/1/0001/coat.jpg"
  // No alt text
  // No dimensions
  // No primary signal
  // AI infers everything from pixels
}

{
  "@type": "Product",
  "name": "Navy Wool Coat",
  "image": {
    "@type": "ImageObject",
    "contentUrl": "https://cdn.../coat.jpg",
    "description": "Navy wool coat,
      front view on white bg",
    "representativeOfPage": true,
    "width": 1200,
    "height": 1600,
    "encodingFormat": "image/jpeg"
  }
}

Multi-Image Gallery: ImageObject Array

When a product has multiple images (multiple angles, lifestyle shots, detail views), output them as an array under the Product's image property. Set representativeOfPage: true only on the primary image — usually the main white-background hero shot.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Navy Double-Breasted Wool Coat",
  "description": "Tailored double-breasted coat in 100% virgin wool. Notched lapels, two front welt pockets, fully lined. Available in sizes XS–3XL.",
  "sku": "COAT-NAVY-DB-WOOL",
  "brand": { "@type": "Brand", "name": "Archibald & Co." },
  "image": [
    {
      "@type": "ImageObject",
      "contentUrl": "https://cdn.shopify.com/s/files/1/0001/coat-front.jpg",
      "url": "https://example.com/products/navy-wool-coat",
      "description": "Navy double-breasted wool coat, front view, white background — Archibald & Co.",
      "representativeOfPage": true,
      "width": 1200,
      "height": 1600,
      "encodingFormat": "image/jpeg",
      "thumbnail": {
        "@type": "ImageObject",
        "contentUrl": "https://cdn.shopify.com/s/files/1/0001/coat-front_400x.jpg",
        "width": 400,
        "height": 533,
        "encodingFormat": "image/jpeg"
      }
    },
    {
      "@type": "ImageObject",
      "contentUrl": "https://cdn.shopify.com/s/files/1/0001/coat-back.jpg",
      "url": "https://example.com/products/navy-wool-coat",
      "description": "Navy double-breasted wool coat, back view showing single center vent and half-belt detail",
      "representativeOfPage": false,
      "width": 1200,
      "height": 1600,
      "encodingFormat": "image/jpeg"
    },
    {
      "@type": "ImageObject",
      "contentUrl": "https://cdn.shopify.com/s/files/1/0001/coat-detail-lapel.jpg",
      "url": "https://example.com/products/navy-wool-coat",
      "description": "Close-up detail of notched lapel and top button on navy wool coat",
      "representativeOfPage": false,
      "width": 800,
      "height": 800,
      "encodingFormat": "image/jpeg"
    },
    {
      "@type": "ImageObject",
      "contentUrl": "https://cdn.shopify.com/s/files/1/0001/coat-lifestyle.jpg",
      "url": "https://example.com/products/navy-wool-coat",
      "description": "Model wearing navy wool coat over cream turtleneck and dark trousers, city street setting",
      "caption": "Styled with Archibald & Co. merino turtleneck",
      "representativeOfPage": false,
      "width": 1200,
      "height": 1500,
      "encodingFormat": "image/jpeg"
    }
  ]
}
</script>

The caption property on lifestyle images provides additional editorial context — AI agents use it to understand styling relationships between products. For the lifestyle shot above, the caption signals that the coat is styled with a turtleneck, which can influence "complete the look" AI shopping recommendations.

Alt Text in JSON-LD: The Shopify Gap

Shopify's Dawn theme and most popular themes render product JSON-LD from the product.json object, which includes only the image URL — not the alt text you've painstakingly entered in the Shopify admin (Products → Edit → Images → Add alt text). This is a significant gap: Google's image indexing systems and AI vision agents use the description field in ImageObject as the primary text signal for understanding image content in the absence of on-page context.

The fix is straightforward in Liquid: the product.images[i].alt property exposes the admin-entered alt text. Map it to the description field in your ImageObject JSON-LD block. If no alt text has been entered, fall back to the product title concatenated with a positional description ("Product image 2 of 4").

Alt text quality signals for AI visual search

Dawn Liquid Snippet: Full ImageObject Output

Save as snippets/product-image-schema.liquid and render from your product template via {% raw %}{% render 'product-image-schema' %}{% endraw %}. The snippet iterates all product images, outputs a full ImageObject for each, sets representativeOfPage: true on the first, and falls back to a clean description string if no alt text is present.

{% comment %} product-image-schema.liquid — full ImageObject JSON-LD for all product images {% endcomment %}
{% assign primary_image = product.featured_image %}
{% assign all_images = product.images %}

{% if all_images.size > 0 %}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": {{ product.title | json }},
  "url": "{{ shop.url }}{{ product.url }}",
  "image": [
    {% for image in all_images %}
    {% assign is_primary = false %}
    {% if image.id == primary_image.id %}{% assign is_primary = true %}{% endif %}

    {% assign img_alt = image.alt %}
    {% if img_alt == blank %}
      {% assign img_alt = product.title | append: ' — product image ' | append: forloop.index | append: ' of ' | append: all_images.size %}
    {% endif %}

    {% assign img_url = image | img_url: '1200x' %}
    {% assign thumb_url = image | img_url: '400x' %}
    {% assign img_format = 'image/jpeg' %}
    {% if image.src contains '.webp' %}{% assign img_format = 'image/webp' %}{% endif %}
    {% if image.src contains '.png' %}{% assign img_format = 'image/png' %}{% endif %}

    {
      "@type": "ImageObject",
      "contentUrl": "https:{{ img_url }}",
      "url": "{{ shop.url }}{{ product.url }}",
      "description": {{ img_alt | json }},
      "representativeOfPage": {{ is_primary }},
      "encodingFormat": {{ img_format | json }},
      "thumbnail": {
        "@type": "ImageObject",
        "contentUrl": "https:{{ thumb_url }}",
        "encodingFormat": {{ img_format | json }}
      }
    }{% unless forloop.last %},{% endunless %}
    {% endfor %}
  ]
}
</script>
{% endif %}

This snippet outputs the image array as a standalone Product JSON-LD block. To merge it with your existing product JSON-LD, extract just the "image": [...] array and splice it into your main product schema block. The standalone approach is safer for most themes as it avoids JSON-LD conflicts.

ImageGallery for Editorial Collections

For editorial lookbook pages or collection pages that feature multiple products in context, use ImageGallery — an ItemList of ImageObject values. This schema type signals to AI that the page is a curated image collection rather than a single product page, enabling AI shopping agents to identify and surface individual products from within the gallery.

{
  "@context": "https://schema.org",
  "@type": "ImageGallery",
  "name": "Spring 2026 Collection — Lookbook",
  "description": "Styled product photography for the Archibald & Co. Spring 2026 outerwear collection.",
  "url": "https://example.com/collections/spring-2026",
  "image": [
    {
      "@type": "ImageObject",
      "contentUrl": "https://cdn.shopify.com/…/lookbook-01.jpg",
      "description": "Model in navy wool coat and camel trousers, rooftop setting",
      "about": {
        "@type": "Product",
        "name": "Navy Wool Coat",
        "url": "https://example.com/products/navy-wool-coat"
      }
    },
    {
      "@type": "ImageObject",
      "contentUrl": "https://cdn.shopify.com/…/lookbook-02.jpg",
      "description": "Model in camel cashmere overcoat, park setting",
      "about": {
        "@type": "Product",
        "name": "Camel Cashmere Overcoat",
        "url": "https://example.com/products/camel-cashmere-overcoat"
      }
    }
  ]
}

The about property on each ImageObject in the gallery links the image to the specific product it depicts. AI shopping agents use this to serve "shop the look" recommendations — when a user uploads a photo of a coat they saw in a lookbook, the AI can trace the image back to the product via this structured link.

Shopify Metafield Architecture for Image SEO

Note: Shopify Liquid's img_url filter applies size transformations (e.g., image | img_url: '1200x'), which changes the rendered image dimensions from the original. If your product images are uploaded at 2000×2000 and you serve them at 1200×, output "width": 1200 in the ImageObject, not 2000. The dimensions should match the contentUrl you're pointing to, not the original upload dimensions.

5 Common ImageObject Mistakes in Shopify

Related Resources

• Shopify Product Images & AI Shopping Agents
• Shopify Product Image Alt Text & AI Agent Optimization
• Shopify Product Photography & AI Alt Text Guide
• Shopify AR & 3D Model Structured Data
• Shopify ProductGroup & Variant Schema
• CatalogScan Blog — AI Shopping Agent Optimization