No SpeakableSpecification schema for voice search

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 Is This Important

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 XeoPix Detects This

XeoPix follows these logical steps to detect missing SpeakableSpecification schema:

Find Article/NewsArticle schema: The crawler identifies pages with:
- Article schema
- NewsArticle schema
- BroadcastEvent schema
Check for speakable property: The crawler examines whether the schema block has a speakable property
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?
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

How To Fix

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

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"
  ]
}

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)
Only applicable for:
- Article schema
- NewsArticle schema
- BroadcastEvent schema
Validate with Google’s Rich Results Test

What We Store

Storage Level

Page Level — This issue is evaluated for each individual URL that contains structured data.

Database Table / Prisma Model

PageStructuredData

Stored Fields

Field	Type	Description
schemaType	SchemaType	The type of schema (e.g., Organization, Person)
schemaFormat	SchemaFormat	The format of the schema (JSON-LD, Microdata, RDFa)
schemaIdentifier	String?	Unique identifier for the schema
rawJson	Json?	The raw JSON-LD or structured data content
schemaErrors	Json?	Array of validation errors found in the schema
isValidSchema	Boolean?	Whether the schema is valid according to validation
missingFields	Json?	Array of required fields that are missing

Detection Dependencies

The following data sources are required to evaluate this issue:
HTML Document — The crawler parses the HTML to find structured data (JSON-LD, Microdata, RDFa)
Structured Data Validation — The extracted schema is validated against Schema.org definitions
Schema Parser — JSON-LD scripts, Microdata attributes, and RDFa markup are parsed

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

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/structuredDataRichResults/issue-150-speakable-schema.test.js

Purpose

Validates that the crawler correctly validates SpeakableSpecification JSON-LD schemas and does not report false positives when the schema is properly formed.

Tested Function

runStructuredDataRichResults()

Issue Information

Issue Number: 150
Issue Code: speakablespecification_schema_voice
Toggle Group: structuredDataRichResults

Test Scenarios

Positive Test Cases

Valid SpeakableSpecification schema: Page has a SpeakableSpecification schema with cssSelector — no issue reported.

Negative Test Cases

None — the test only validates that valid schemas pass.

Boundary Cases

None.

Edge Cases

Empty HTML: <html></html> — no crash.

Expected Outcome

Pass

Issue should not be reported when a valid SpeakableSpecification schema with required properties is present.

Fail

No negative test cases are defined.

Validation

Correct pass-through of valid SpeakableSpecification schemas
Graceful handling of empty HTML

xeopix-crawling-v2/toggleGroups/structuredDataRichResults.js
xeopix-crawling-v2/issueCodes.js
xeopix-crawling-v2/utils/context.js
xeopix-crawling-v2/utils/issues.js
xeopix-crawling-v2/utils/schema.js

Coverage Summary

Covers valid SpeakableSpecification schema detection
Covers empty HTML resilience

References

Schema.org — SpeakableSpecification — Schema.org
Google — Speakable (Article) Structured Data — Google Search Central