# Implementing SpeakableSpecification for Voice AI: Structured Data for AEO
*By the OnlineCloud Engineering Team*
Search isn’t a list of links anymore. It’s a conversation — and increasingly, a spoken one. From Google Assistant reading the morning brief aloud to ChatGPT, Perplexity, and Gemini synthesizing answers in real time, visibility has shifted from ranking on page one to *being the source an engine chooses to read back*. That shift is called **Answer Engine Optimization (AEO)** — and at the layer where web content meets spoken output, no schema.org vocabulary does more heavy lifting than **`SpeakableSpecification`**.
This deep-dive is for technical leads and SEO strategists who own documentation sites, knowledge bases, or content platforms: what Speakable actually is, how to implement it on technical content, how to verify it end to end, and why it’s the clearest early signal of readiness for the conversational-agent era.
—
## 1. Introduction: AEO and the Rise of Voice Search
Let’s be precise about what AEO is. Classic SEO optimizes for the *search engine results page*: title tags, backlinks, meta descriptions, all aimed at earning a click. AEO optimizes for the **answer itself** — the entity, sentence, or passage an engine extracts, attributes, and serves *without* a click. The customer isn’t browsing blue links; they’re asking “how do I reset my MCP server auth token?” into a speaker, a phone, or a chat bar, and an engine is choosing which document to paraphrase back to them.
The numbers have trended this way for years. Late-2010s forecasts predicted roughly half of all searches would be voice-driven by 2020; reality landed closer to a third of mobile queries, but the direction never reversed. Smart speakers passed one-third of US households. Then came the generative inflection point: Google rolled out AI Overviews above the classic results, ChatGPT and Perplexity turned “search” into “answer,” and every assistant vendor began treating your content as material for spoken and written responses.
Here’s the uncomfortable implication: **an engine will not read aloud content that isn’t marked as readable.** If your documentation is the best answer on the internet but you haven’t told engines *which part of the page to speak*, the engine will happily attribute the next-best source instead. That’s the gap `SpeakableSpecification` was built to close.
## 2. What Is SpeakableSpecification? The schema.org Contract for Spoken Content
`SpeakableSpecification` is a schema.org type, championed by Google, that answers one question for text-to-speech (TTS) systems: **which section of this page is safe and appropriate to read aloud?**
When Google announced speakable in 2018, the goal was to give Google Assistant a reliable signal for reading news and answers back to users on smart speakers and phones. Rather than making an assistant guess whether a page’s content stays coherent once stripped of navigation, ads, and cookie banners, the markup tells it explicitly: *start here, stop here, read this.* An assistant doesn’t consume the whole page — it consumes the **speakable region**, a contiguous block of primary content.
### The Anatomy of the Markup
`SpeakableSpecification` is deliberately tiny. It has two meaningful properties, and you supply **one** (Google recommends `cssSelector`):
– **`cssSelector`** — a CSS selector or list of selectors identifying the elements to read aloud. Give sections stable `id` attributes and reference them directly.
– **`xpath`** — an XPath expression pointing at the same kind of content, for teams that prefer XPath.
The `speakable` property hangs off your content type — `NewsArticle`, `TechArticle`, `Article`, `WebPage` — and accepts a single specification or an array, letting you define multiple readable regions per page.
### What Speakable Is Not
– It is **not** a visual rich result. It renders as *audio output* on Assistant surfaces, which is why rich-result testers that only report on visual enhancements often ignore it.
– It is **not** a way to make hidden text readable. Content that isn’t visible, indexable, and substantial won’t be spoken.
– On the **Alexa side**, arbitrary web pages aren’t ingested through speakable markup today; Alexa’s pathways run through skills, Flash Briefings, and content APIs. But schema.org is the shared vocabulary, and teams building for both ecosystems treat speakable as the *content-layer* contract — structuring sections so a skill, an Assistant action, or a future Alexa web-reader can consume the same TTS-ready blocks. Think of Speakable as the **accessibility contract for the AI age**: the discipline that makes content readable to a screen reader also makes it readable to an AI’s voice.
## 3. Technical Implementation: Adding Speakable to Technical Documentation
Documentation is arguably the *best* use case for speakable — even better than news. Tutorials, API guides, and troubleshooting flows are exactly what users ask assistants: “how do I connect this data source?”, “what’s the retry policy?”, “walk me through setup.”
### Step 1: Structure the page for speech
Before a line of JSON-LD, make the page TTS-friendly:
– Wrap the overview in `
– Keep each speakable unit small — a few sentences to a short paragraph. Assistants truncate long reads, and a five-minute monologue won’t be served anyway.
– Keep code samples inside the speakable region only if an assistant can meaningfully read them; otherwise exclude the code block and let the surrounding explanation carry the answer.
### Step 2: Inject the JSON-LD
Add a `