Skip to main content

SpeakableSpecification Schema Missing

Issue No: 150

Category: Structured Data & Rich Results

Issue type: Suggestion

Priority: STANDARD

Description​

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.

How do we capture it​

  • Check JSON-LD for "@type": "Article" or "@type": "NewsArticle" on the page
  • Within that block, look for "speakable" property containing a SpeakableSpecification node
  • If speakable property is absent → trigger suggestion

What to store​

StructuredDataAudit record with schemaType = SpeakableSpecification, issueNumber = 150, plus StructuredDataField rows:

FieldTypeComment
has_speakablebooleanspeakable property present in parent Article/NewsArticle schema
has_css_selectorbooleancssSelector property present in SpeakableSpecification node
has_xpathbooleanxpath property present in SpeakableSpecification node (alternative to cssSelector)
parent_schema_typestringType of the parent schema node (Article, NewsArticle, BroadcastEvent)

Core audit fields used: isPresent, rawJson

Condition for trigger​

  • Trigger Rule 1: SpeakableSpecification absent on editorial content page

    • Target Field: has_speakable
    • Evaluation Logic: has_speakable = false AND page has Article or NewsArticle schema
    • Severity: STANDARD
    • Diagnostic Message: "Article/NewsArticle schema found but no speakable property detected. Add SpeakableSpecification to improve voice-search compatibility."

  • Trigger Rule 2: SpeakableSpecification selector missing

    • Target Field: has_css_selector AND has_xpath
    • Evaluation Logic: has_css_selector = false AND has_xpath = false (speakable present but no selector)
    • Severity: STANDARD
    • Diagnostic Message: "SpeakableSpecification found but contains neither cssSelector nor xpath — Google cannot identify the speakable region."

Sources​

Long description​

SpeakableSpecification is a sub-type used inside Article, NewsArticle, or BroadcastEvent schema to indicate which portions of the page are most appropriate for text-to-speech rendering. When present, Google Assistant and other voice agents can read out the designated sections directly rather than attempting to interpret the full page body.

The spec uses either cssSelector (pointing to one or more CSS selectors on the page) or xpath (XPath expressions) to identify the readable sections.

Recommended implementation (cssSelector):

{
  "@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"
}

Alternative implementation (xpath):

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

Key points:

  • Only applicable inside Article, NewsArticle, and BroadcastEvent schema types
  • Selectors should point to the summary, introduction, or key section headings — not the entire body
  • Google uses this for Google Assistant Actions and voice-based news briefings
  • Currently primarily beneficial for news publishers targeting Google News

How to Fix​

  1. Identify all pages with Article or NewsArticle JSON-LD schema
  2. Inside the schema block, add a speakable property containing a SpeakableSpecification node
  3. Use cssSelector to list CSS selectors that target the headline, introductory paragraph, and key section headings (e.g., ".article-headline", ".article-intro")
  4. Validate with Google Rich Results Test
  5. Monitor Google Search Console for Speakable enhancements in the Rich Results report