Shopify SpeakableSpecification Schema — Voice Commerce & AI Read-Aloud Product Optimization

How SpeakableSpecification Works

The schema.org SpeakableSpecification type lives on a WebPage JSON-LD block (not on the Product block). It uses two targeting methods:

• cssSelector (recommended for Shopify) — CSS selector string(s) pointing to the HTML elements containing the speakable content. Multiple selectors are supported as an array.
• xpath — XPath expression(s) for more precise targeting. More powerful but harder to maintain when your Shopify theme changes.

When a voice assistant or AI agent processes your product page, it finds the SpeakableSpecification, extracts the text content of the targeted CSS elements, and uses that text for spoken synthesis or AI summary generation — instead of attempting to extract key text from the full page via NLP.

What SpeakableSpecification improves

Implementation: Shopify Theme + JSON-LD

Implementation has two parts: (1) add a speakable summary element to your Shopify product template, and (2) add a WebPage JSON-LD block with SpeakableSpecification that targets it.

Step 1: Add a speakable summary element to your theme

Add a dedicated <p> element to your product template with a consistent CSS class (e.g., .product-speakable-summary). This element should contain a 1-2 sentence summary of the product's core benefit — written for spoken output, not visual scanning. Keep it under 50 words.

<!-- In product.liquid or main-product.liquid, near the product title -->
<h1 class="product-title">{{ product.title }}</h1>

<!-- Speakable summary: 1-2 sentences, core benefit, voice-optimized -->
<p class="product-speakable-summary">
  {{ product.metafields.seo.speakable_summary | default: product.description | strip_html | truncatewords: 40 }}
</p>

<!-- Price -->
<span class="product-price">{{ product.selected_or_first_available_variant.price | money }}</span>

The product.metafields.seo.speakable_summary metafield lets you write a custom voice-optimized summary per product. Fall back to a truncated description if not set.

Step 2: Add WebPage JSON-LD with SpeakableSpecification

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "@id": "{{ shop.url }}{{ page.url }}",
  "name": {{ product.title | json }},
  "url": "{{ shop.url }}{{ product.url }}",
  "breadcrumb": {
    "@type": "BreadcrumbList",
    "itemListElement": [
      { "@type": "ListItem", "position": 1, "name": "Home", "item": "{{ shop.url }}/" },
      { "@type": "ListItem", "position": 2, "name": {{ product.type | json }}, "item": "{{ shop.url }}/collections/{{ product.type | handleize }}" },
      { "@type": "ListItem", "position": 3, "name": {{ product.title | json }}, "item": "{{ shop.url }}{{ product.url }}" }
    ]
  },
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [
      ".product-title",
      ".product-speakable-summary",
      ".product-price"
    ]
  }
}
</script>

Step 3: Verify the speakable content

After deploying, view your product page source and manually copy the text content of the targeted CSS elements. Read it aloud. The result should answer "what is this product and how much does it cost?" in a natural, complete sentence within 30 seconds of spoken audio. If it sounds awkward, rewrite the speakable_summary metafield.

What to Target: CSS Selector Guide

Writing a Good Speakable Summary

The speakable summary is the most impactful thing you control. It must work as a standalone spoken sentence without visual context. Write it as if answering the question "What is this product?" over the phone.

Speakable summary formula

Use this structure for consistent, voice-optimized speakable summaries across your catalog:

[Article] [Adjective chain] [Product type] [key feature 1] [key feature 2] — [primary benefit claim in plain language], [relevant qualifier if space permits].

Example: "A lightweight, water-based hyaluronic acid serum with 2% concentration — deeply hydrates dry and dehydrated skin and layers under any moisturizer or SPF."

SpeakableSpecification with Shopify Dawn Theme

Dawn uses main-product.liquid for the primary product template. Add the speakable summary element after the product title and before the price:

{% comment %} In sections/main-product.liquid, after the title block: {% endcomment %}

<h1 class="product__title">
  {{ product.title | escape }}
</h1>

{% comment %} Speakable summary — add after h1 {% endcomment %}
{% assign speakable = product.metafields.seo.speakable_summary %}
{% if speakable != blank %}
<p class="product-speakable-summary visually-hidden-on-mobile">
  {{ speakable | escape }}
</p>
{% endif %}

{% comment %} Add to theme.liquid head — WebPage JSON-LD with SpeakableSpecification {% endcomment %}
{% if template.name == 'product' %}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "@id": "{{ shop.url }}{{ product.url }}",
  "name": {{ product.title | json }},
  "url": "{{ shop.url }}{{ product.url }}",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [
      ".product__title",
      {% if product.metafields.seo.speakable_summary != blank %}
      ".product-speakable-summary",
      {% endif %}
      ".price__regular .price-item--regular"
    ]
  }
}
</script>
{% endif %}

The Dawn .price__regular .price-item--regular selector targets the primary sale price. Adjust selector names if you are using a customized Dawn variant — inspect element on your theme to verify the exact class names.

SpeakableSpecification for Collection and Blog Pages

SpeakableSpecification is not limited to product pages. Apply it to collection pages to help AI agents summarize your category, and to blog posts to improve AI article read-aloud quality.

Collection page

{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "name": {{ collection.title | json }},
  "url": "{{ shop.url }}{{ collection.url }}",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [
      ".collection__title",
      ".collection__description"
    ]
  }
}

Blog post page

{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "name": {{ article.title | json }},
  "url": "{{ shop.url }}{{ blog.url }}/{{ article.handle }}",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [
      "h1.article__title",
      ".article__excerpt",
      ".article__content > p:first-child"
    ]
  }
}

Common SpeakableSpecification Mistakes

Related Resources

• Shopify Product Descriptions for AI Agents — Writing for Machine Readability
• Shopify Schema Markup Guide — Complete JSON-LD Reference
• Shopify Breadcrumb Schema Navigation — BreadcrumbList JSON-LD
• E-commerce AI Readiness Checklist
• CatalogScan Blog — AI Shopping Agent Optimization