Speakable Schema Generator — Highlight Audio-Friendly Snippets

Mark concise, newsworthy passages so voice assistants can read them aloud accurately. Keep selectors clean, policy-compliant, and easy to maintain.

Try the Speakable Generator

Why Speakable efforts stall

Pain points we solve

• Publishers nominate entire articles as speakable, so Google rejects the markup for being too long or duplicative.
• Selectors reference pre-rendered HTML instead of the DOM after paywall scripts, leading to broken references that never resolve.
• Editorial teams refresh headlines, but the schema stays stale and points to old CSS classes, so coverage silently disappears.
• Stakeholders expect dramatic traffic lifts even though Speakable is limited; poor expectation-setting triggers unnecessary churn.

How SwiftSchema keeps selectors trustworthy

Solution

The generator focuses on the exact elements voice assistants can read: the canonical headline plus a short summary paragraph, list item, or pull quote that stays under a few sentences.

We prompt you to record whether selectors use CSS or XPath and to document how the DOM renders behind paywalls or frameworks, so developers know where to adjust if components change.

Every schema block includes governance language reminding teams about Speakable’s limited availability, which helps stakeholders treat it as a bonus enhancement rather than a guaranteed feature.

How it works

How it works

1. Select Speakable in the generator below.
2. Confirm the parent page type (Article or NewsArticle) and ensure the visible copy includes a clear headline and short summary.
3. Add `cssSelector` or `xpath` entries referencing the headline element and a concise paragraph (100–200 characters).
4. Specify language, publish date, and canonical URL so the schema mirrors the on-page metadata.
5. Copy the JSON‑LD, deploy it on the article template, and validate using the Rich Results Test or URL Inspection.

Generate Speakable JSON‑LD

Mark concise summaries. Validate. Ship.

What is Speakable structured data?

Speakable structured data attaches a

to an Article or NewsArticle so voice assistants know which fragments of text are safe to read aloud. Instead of guessing which sentences summarize the story, the structured data explicitly lists CSS selectors or XPath expressions pointing to the headline, dek, or bulleted recap. This schema was originally introduced for publishers targeting Google Assistant and similar voice experiences, and while its footprint is smaller today, it remains useful for newsrooms that want to preserve audio accessibility for breaking updates.

Eligibility & status

Speakable is a limited, experimental enhancement. Google paused broad expansion, but many publishers still keep it active for Assistant-style experiences. To stay eligible, the targeted page must be an Article or NewsArticle with clear authorship, dates, and structured data that already meets core guidelines. Do not add Speakable to evergreen marketing landing pages or unvetted UGC. The selected text should be short (ideally 20–30 seconds of speech), free of ads, and accessible without logging in. If you operate a paywall, ensure the selectors resolve in the fully rendered DOM for logged-out users, otherwise the markup will fail validation.

Why speakable markup matters

• Accessible summaries: Voice assistants can recite the same headline and short summary you highlight on-page, preserving editorial intent across surfaces.
• Faster corrections: During breaking news, you can swap the summary paragraph and instantly update the spoken response via schema rather than waiting for crawlers to reinterpret the full article.
• Structured governance: Documented selectors make template refactors safer because engineers know exactly which elements must remain for voice compatibility.
• Localization clarity: By pairing
  inLanguage
  with short selectors, you help assistants read the correct language variant when you syndicate content globally.

Essential properties to include

• @type
  : Use
  NewsArticle
  or
  Article
  for the parent entry, and ensure the speakable block references actual DOM nodes inside that article.
• speakable
  with
  @type
  SpeakableSpecification
  .
• cssSelector
  list targeting headlines (
  article h1
  ,
  .headline
  ) and short summary paragraphs or bullet lists.
• xpath
  only when CSS selectors are unreliable (AMP or server-rendered markup without class hooks).
• headline
  ,
  description
  ,
  datePublished
  ,
  dateModified
  ,
  author
  ,
  publisher
  ,
  mainEntityOfPage
  : keep them aligned with your Article markup.
• Optional supporting fields:
  inLanguage
  ,
  image
  ,
  isAccessibleForFree
  ,
  articleSection
  ,
  about
  ,
  mentions
  ,
  speakable.alternateName
  .

Preparing content before generating schema

1. Audit templates: Ensure the page’s markup exposes stable selectors for the headline and summary elements. Avoid ephemeral hashed class names from CSS-in-JS.
2. Define the summary voice snippet: Work with editorial teams to craft a two-sentence summary or bullet list that stands on its own without visuals.
3. Coordinate paywall logic: Confirm the targeted DOM nodes remain visible to crawlers and anonymous users; move the summary above the paywall break if necessary.
4. Document localization: Record which language variants receive speakable markup and link to translated summaries where possible.
5. Set reviewer ownership: Assign both editorial and engineering sign-off for each template update so selectors stay accurate.
6. Plan validation cadence: Schedule weekly or per-release Rich Results tests to catch regressions before new articles publish.

Implementation workflow inside SwiftSchema

1. Choose Speakable in the generator and confirm the Article slug you are marking up.
2. Paste the canonical URL, headline, publisher name, and publish dates (mirroring on-page metadata).
3. Add
   cssSelector
   entries for the headline and short summary. Note any XPath fallbacks if the DOM requires them.
4. Provide
   inLanguage
   (BCP 47 codes) and whether the article is accessible for free to set appropriate expectations.
5. Include contact fields (
   publisher.logo
   ,
   author
   ) so the voice surface can attribute the snippet correctly.
6. Export and deploy the JSON‑LD globally via your article template or headless CMS injection. Keep a shared doc describing each selector so developers know what not to break.

Troubleshooting & QA

• Selectors that fail post-render: Use browser devtools to inspect the final DOM, not just the server-rendered HTML. Update selectors if hydration adds wrappers.
• Overly long snippets: If assistants reject your markup, trim the summary to 2–3 sentences (~250 characters).
• Language mismatches: When the article is bilingual, include separate Article entries or limit the speakable block to one language.
• Paywall interference: If speakable elements hide behind a modal, configure paywall scripts to exclude them or place duplicates outside the paywall for crawlers.
• Missing Article schema: Speakable relies on proper Article markup. Validate that first, then layer Speakable on top.

Maintenance and governance

• Treat Speakable as part of your publishing checklist: whenever the headline or dek changes, update the summary and revalidate.
• Keep a shared inventory of selectors per template (standard article, live blog, AMP) so engineering knows dependencies during redesigns.
• Monitor Search Console or structured data logs for Speakable warnings and triage them alongside article QA tasks.
• Reassess ROI quarterly; if voice surfaces stop honoring Speakable, document the findings but leave the markup in place for future support unless it adds maintenance overhead.

Common errors & quick fixes

• Targeting entire articles: Limit selectors to short snippets — typically the
  <h1>
  and one
  <p class=\"lead\">
  block — to avoid rejection.
• Using relative selectors in components: Always include enough context (e.g.,
  article h1
  ) so the selector remains stable if the DOM adds wrappers.
• Ignoring
  inLanguage
  : Supply
  inLanguage
  so assistants pronounce names correctly.
• Outdated metadata: When the publish date or headline changes, update the schema immediately to prevent mismatched spoken summaries.
• XPath typos: Validate XPath expressions using browser tools; one missing slash can invalidate the entire block.

{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "New structured data workshop announced",
  "datePublished": "2025-09-30",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [
      "article h1",
      "article p.lead"
    ]
  }
}