Skip to content
Browse all guides

Issue #150 · important

Issue 150

What is this issue?

Pages with long-form editorial or news content are missing SpeakableSpecification inside their Article or NewsArticle schema. Without it, Google Assistant and other TTS agents have no structured hint about which sections of the page are best suited for audio playback.

Without SpeakableSpecification schema:

  • Google Assistant and voice agents can't identify which parts of the page to read aloud
  • Voice search results won't be able to provide audio playback of your content
  • Text-to-speech rendering will attempt to interpret the full page body
  • News content won't be eligible for Google Assistant Actions
  • Voice-based news briefings won't include your content

A proper SpeakableSpecification schema should be nested inside Article, NewsArticle, or BroadcastEvent schema and include: cssSelector or xpath properties pointing to the speakable sections of the page.

Why does it matter?

SpeakableSpecification schema is important for voice search and audio content:

  • Voice search optimization: Helps Google Assistant and voice agents identify content for audio playback
  • Google Assistant Actions: Enables content to be included in voice-based news briefings
  • Text-to-speech: Provides structured hints for TTS rendering
  • News publishers: Particularly beneficial for news sites targeting Google News
  • AI search readiness: Voice assistants use this to provide audio versions of content
  • Accessibility: Improves accessibility for users who prefer audio content

Resolving this issue improves your SEO health score by ensuring content is optimized for voice search and audio playback.

How to fix it

  1. Identify pages with Article/NewsArticle schema: Find all pages with Article or NewsArticle JSON-LD schema

  2. Add SpeakableSpecification inside the Article/NewsArticle schema block:

    Using cssSelector (recommended):

    {
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "How to Improve Your Website's SEO",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".headline", ".summary", "article h2"]
  },
  "url": "https://www.example.com/seo-guide"
}

    Using xpath (alternative):

    "speakable": {
  "@type": "SpeakableSpecification",
  "xpath": [
    "/html/head/title",
    "/html/head/meta[@name='description']/@content"
  ]
}

  3. Choose the right selectors:

    • Point to summary, introduction, or key section headings
    • Don't select the entire body content
    • Use CSS selectors that target specific elements (e.g., .headline, .summary, article h2)

  4. Only applicable for:

    • Article schema
    • NewsArticle schema
    • BroadcastEvent schema

  5. Validate with Google's Rich Results Test

Examples

Example 1: Missing SpeakableSpecification in NewsArticle

Problematic state:

{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "New SEO Guidelines Released",
  "description": "Google announces updated SEO guidelines for 2024."
}

Missing speakable property

Corrected state:

{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "New SEO Guidelines Released",
  "description": "Google announces updated SEO guidelines for 2024.",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".headline", ".article-summary", "article h2"]
  }
}

Example 2: SpeakableSpecification with CSS Selectors

Corrected state:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Complete Guide to Technical SEO",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [
      ".article-headline",
      ".article-intro",
      ".key-points",
      "article h2"
    ]
  }
}

Targets specific elements for voice playback

Example 3: SpeakableSpecification with XPath

Corrected state (alternative approach):

{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "Breaking News: Algorithm Update",
  "speakable": {
    "@type": "SpeakableSpecification",
    "xpath": [
      "/html/body/article/header/h1",
      "/html/body/article/section[@class='summary']",
      "/html/body/article/section[@class='key-points']"
    ]
  }
}

Uses XPath selectors instead of CSS

How PixyScan detects this

PixyScan follows these logical steps to detect missing SpeakableSpecification schema:

  1. Find Article/NewsArticle schema: The crawler identifies pages with:

    • Article schema
    • NewsArticle schema
    • BroadcastEvent schema

  2. Check for speakable property: The crawler examines whether the schema block has a speakable property

  3. Validate SpeakableSpecification structure: If speakable property is found, the crawler checks:

    • Does it have @type set to SpeakableSpecification?
    • Does it have cssSelector or xpath property?
    • Are the selectors valid and pointing to existing page elements?

  4. Trigger conditions: The issue is flagged when:

    • Page has Article/NewsArticle schema but no speakable property
    • speakable property exists but contains neither cssSelector nor xpath

References