Speakable Schema — Text-to-Speech Sections for Google Assistant
Speakable markup points Google Assistant to the parts of a news page worth reading aloud, usually the headline and a two- or three-sentence summary.
Generate Speakable JSON-LDWhy speakable markup goes wrong
- The markup uses both cssSelector and xPath. Google says to use one or the other.
- The selectors point to the whole article instead of a short summary.
- A selector targets a dateline, photo caption, or source credit, which sounds confusing when read aloud.
- The class names in the selectors were renamed in a redesign, so they no longer match anything.
How SwiftSchema helps
The generator below makes you pick CSS selectors or XPath, so the output never mixes the two, and lets you choose Article, NewsArticle, or WebPage as the parent type.
The examples on this page follow Google’s speakable documentation, including its XPath example that reads the page title and meta description.
What is speakable schema?
speakable is a schema.org property whose value is a SpeakableSpecification. It lists the parts of a page that are best suited to text-to-speech, using CSS selectors or XPaths.
Google Assistant uses it to answer topical news questions on smart speakers, such as "What's the latest news about $topic?". Google says the Assistant returns up to three articles from around the web, reads the speakable sections aloud, attributes the source, and sends the full article URL to the user's phone through the Google Assistant app.
Who Google supports
Speakable is in beta and subject to change. Google says it works for:
- users in the U.S. with Google Home devices set to English, and
- publishers that publish content in English.
Google says it hopes to launch in other countries and languages once enough publishers have implemented speakable. In practice, it's for news content. A product page or a service page won't be read out as a news answer.
Properties
From Google's speakable documentation:
| Property | Required? | Notes |
|---|---|---|
speakable | Yes | On an Article (including NewsArticle) or WebPage. Its value is a SpeakableSpecification. |
cssSelector | One of the two | A list of CSS selectors for the content, such as .headline and .summary. |
xpath | One of the two | A list of XPaths, assuming an XML view of the page. |
Google says to use either cssSelector or xPath, not both.
xpath or xPath?
Schema.org names the property xpath, all lowercase. Google's speakable page writes it xPath. JSON-LD property names are case-sensitive, so the two aren't the same. The July 2018 version of Google's page used lowercase xpath in both its example and its property table; the camelCase spelling appeared in later edits, with no announcement in Google's changelog. This generator uses the schema.org spelling, which the Schema Markup Validator accepts. If you want to avoid the question entirely, use cssSelector, which both spell the same way.
Content guidelines
Google's guidelines for speakable content:
- Keep it short. Google recommends around 20–30 seconds of content per speakable section, or roughly two to three sentences.
- Mark key points, not the article. Google says to focus on key points rather than highlighting an entire article, so listeners get the idea of the story.
- Write for the ear. Speakable sections need concise headlines and summaries that make sense out of context. For top-of-story content, Google suggests rewriting it into individual sentences so it reads more clearly in TTS.
- Skip what sounds confusing. Don't mark datelines (where the story was reported), photo captions, or source attributions.
Choosing selectors
- Give the headline and summary stable class names, such as
.headlineand.summary, instead of generated class names that change on every build. - Check that each selector matches only the text you mean. In the browser console,
document.querySelectorAll(".summary")should return the summary and nothing else. - Make sure the text is in the page for logged-out visitors, not behind a paywall or a script that runs later.
- For pages without good class names, Google's XPath example reads the
<title>and the meta description. That works when both are written as a short spoken summary.
How to build one here
- 01
Choose the page type: NewsArticle, Article, or WebPage.
- 02
Enter the headline or page name and the page URL.
- 03
Pick CSS selectors or XPath, then add one entry for the headline and one for the summary.
- 04
Check each selector in your browser so it matches two or three sentences, not the whole article.
- 05
Copy the JSON-LD into the page and check the syntax in the Schema Markup Validator.
Ready to build the markup?
CSS selectors or XPath, never both.
Adding speakable to existing Article markup
If the page already has Article or NewsArticle markup, add the speakable property to that object instead of publishing a second one. Keep the headline, dates, author, and publisher in the same object; the NewsArticle guide covers those properties.
Common mistakes
- Both cssSelector and xpath. Use one.
- The whole article. Aim for two or three sentences per section.
- Datelines, captions, and credits. They sound confusing out of context.
- Selectors that match nothing. After a redesign, check that the class names still exist.
- Expecting a visual result. Speakable is for Google Assistant audio, not a rich result in Search.
- Expecting it worldwide. Google supports it only for English, in the U.S., on Google Home devices.
Required properties
cssSelector or xpath (one, not both)
{
"@context": "https://schema.org",
"@type": "NewsArticle",
"headline": "City council approves new bike lanes downtown",
"datePublished": "2026-10-06T09:00:00-05:00",
"url": "https://www.example.com/news/bike-lanes-approved",
"speakable": {
"@type": "SpeakableSpecification",
"cssSelector": [
".headline",
".summary"
]
}
}{
"@context": "https://schema.org",
"@type": "WebPage",
"name": "Quick Brown Fox",
"url": "https://www.example.com/quick-brown-fox",
"speakable": {
"@type": "SpeakableSpecification",
"xpath": [
"/html/head/title",
"/html/head/meta[@name='description']/@content"
]
}
}FAQs
What is speakable schema?ShowHide
A speakable property with a SpeakableSpecification that points to the parts of a page best suited to text-to-speech, usually the headline and a short summary. Google Assistant uses it to read news aloud on smart speakers.
Who can use speakable?ShowHide
Google's speakable feature is in beta. It works for users in the U.S. with Google Home devices set to English, and for publishers of English news content. Google says it hopes to launch in other countries and languages.
Should I use CSS selectors or XPath?ShowHide
Either one, but not both. Google says to use either cssSelector or xPath. CSS selectors such as .headline and .summary are easier to maintain, and they avoid a spelling difference: schema.org names the property xpath, while Google's documentation writes xPath.
How much text should a speakable section have?ShowHide
Google recommends around 20 to 30 seconds of content per section, or roughly two to three sentences. Mark key points, not the whole article.
Which types can have speakable?ShowHide
Google says speakable is used by the Article or WebPage object. NewsArticle is a subtype of Article, so it works too.
Will speakable change how my page looks in Google Search?ShowHide
No. Speakable is used for audio playback on Google Assistant, not for a visual search result. Google also doesn't guarantee that any structured data feature will be used.