No SpeakableSpecification schema for voice search

This issue reports a SpeakableSpecification block your page already declares (usually nested in a speakable property) that is missing cssSelector — not a page that has no speakable markup at all.

What this issue is not: it does not require Article or NewsArticle schema to be present first, and it does not check for xpath as an alternative — only cssSelector is verified. A page with no speakable property declared is never reported.

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.

If this issue was raised, your page already declares a speakable block missing cssSelector — open the finding and add it. The steps below are for adding speakable markup to a page that has none yet: worthwhile for voice-search-eligible content, and never reported as a defect while absent.

1. Identify pages worth marking as speakable: news and long-form content with a clear headline and summary benefit most; this schema is a limited beta for English-language news publishers today

2. Add a speakable property with cssSelector inside the Article/NewsArticle schema block — this is the property PixyScan's check requires:

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

   xpath is also valid schema.org markup, but PixyScan's check does not currently accept it as a substitute for cssSelector — declare both if xpath selectors are already in use elsewhere.

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

Example 1: No speakable Declared — Not This Issue

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

Nothing is reported. This check does not require Article/NewsArticle schema to carry a speakable property at all.

Example 2: SpeakableSpecification With cssSelector (passes)

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

Example 3: SpeakableSpecification With Only xpath (fails)

Problematic state:

{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "Breaking News: Algorithm Update",
  "speakable": {
    "@type": "SpeakableSpecification",
    "xpath": ["/html/body/article/header/h1"]
  }
}

Reported: cssSelector missing. xpath is a valid schema.org alternative, but PixyScan's check does not currently accept it in place of cssSelector — declaring both is the safest option if xpath selectors are already in use.

Corrected state:

{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "Breaking News: Algorithm Update",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".headline"],
    "xpath": ["/html/body/article/header/h1"]
  }
}

1. Read the declared structured data: every JSON-LD block is parsed, and @graph wrappers are flattened.

2. Select declared SpeakableSpecification entities: any nested object whose @type is SpeakableSpecification — typically the speakable property of a WebPage or Article-family schema. A page that declares none is not examined — this check does not require Article/NewsArticle schema to be present first.

3. Check the required property: a declared SpeakableSpecification must have cssSelector.

4. This is reported when: a declared SpeakableSpecification is missing cssSelector, reported as nested inside its parent schema. A page with no speakable property at all is never reported.

Note: only cssSelector is checked today. An xpath-only SpeakableSpecification (no cssSelector) is still reported missing cssSelector — xpath is not currently accepted as an alternative.

Storage Level

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

Database Table / Prisma Model

PageStructuredData

Stored Fields

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