Guide · 9 min read
Schema Markup for Star Ratings in Google Search Results
A widget that shows stars on your own site doesn't put stars in Google's results. That comes from a separate piece of code — Review or AggregateRating structured data — with its own eligibility rules and its own ways to get it wrong.
This is JSON-LD structured data, not a script you paste for the widget.
Schema markup for star ratings is structured data — typically JSON-LD using the Review or AggregateRating type from schema.org — that tells Google a page has a rating, so it can show stars in search results. A visible star widget on your site doesn't create this on its own; the markup is a separate block of code that has to name the item being rated and meet Google's eligibility rules before a rich result can appear.
The widget and the schema are two different things
This is the mistake that wastes the most time. A review widget — a script tag that renders a star badge visually on your page — is built for human eyes. Google's crawler doesn't read a rendered badge and infer a rating from it. It reads structured data in the page's HTML, and if that data isn't there, the widget can look perfect to a visitor and invisible to Search.
The two usually live side by side: a widget for the person looking at your page, and a JSON-LD block for the crawler reading it. Installing one doesn't install the other, and most confusion about "why don't my stars show in Google" traces back to having only the first. See how to add a review widget to your SaaS website for that half of the setup on its own.
The visual widget
A script-tag badge showing stars on your page. See how to embed a star rating widget on a landing page for that install on its own.
The schema markup
A JSON-LD block naming the item, the rating value and the review count, placed in the page's HTML separately from anything visual.
What the markup is built from
Two schema.org types cover this, and picking the wrong one is a common mistake on its own.
The markup itself, as JSON-LD
Here's a minimal AggregateRating block, attached to a SoftwareApplication. This goes in the page's HTML as its own script element — it isn't visible on the page itself.
Example — AggregateRating on a SoftwareApplication
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "Your Product",
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.7",
"reviewCount": "23"
}
}
</script>
This is a template showing the required shape, not a live figure — substitute your product's actual name, rating and review count. Fabricating any of these three values breaks Google's structured-data policy on its own.
What blocks eligibility
Valid JSON-LD isn't the same as an eligible rich result. Google's guidelines for review snippets specifically restrict self-serving markup, and most rejections trace back to one of a few patterns.
| Mistake | Why it fails |
|---|---|
| Self-serving reviews about your own business | Google's guidelines block a business marking up reviews of itself on its own pages for most schema types |
| Missing ratingValue or reviewCount | Both are required — the markup won't render a star result without either |
| itemReviewed doesn't match the page | The item named in the markup has to be what the page is actually about, not a different product |
| Markup with no visible reviews on the page | Structured data should reflect content a visitor can actually see, not numbers invented for the rich result |
Google's own review-snippet documentation covers the current list of eligible types and the self-serving restriction in full — treat this table as the patterns to check first, not a complete policy reference.
A star widget from a review platform shows real numbers to visitors, which is useful on its own. Whether that data also qualifies for Google's rich result depends on the schema type and Google's current eligibility rules for that type — a widget vendor showing your rating doesn't guarantee the rich snippet by itself.
How to add it, step by step
Confirm the reviews are genuine and visible
Start from real reviews a visitor can actually see on the page, not numbers chosen to look good. Markup that doesn't match visible content is the fastest way to lose the rich result entirely. If you don't have real reviews yet, getting your first ten comes before any of the steps below.
Pick Review or AggregateRating
Use AggregateRating for a summary across many reviews. Use Review for a single piece of feedback with its own author. Most SaaS profile pages want AggregateRating.
Name the itemReviewed correctly
Match the type and name to what the page is actually about — a SoftwareApplication or Product entry with the real product name, not a generic placeholder.
Fill ratingValue and reviewCount exactly
Both fields are required for a star result to render at all. Pull the real numbers from wherever your reviews live, and update the markup when they change.
Add it as JSON-LD, once per page
Place the script block in the page's HTML. One block per page, matching that page's actual content — don't paste the same block across unrelated pages.
Test it before you rely on it
Run the page through Google's Rich Results Test to confirm the markup parses and is eligible for the type you used, before assuming it'll show up in search.
Check Search Console after it's live
Once indexed, the structured data reports in Search Console show whether Google is reading it correctly and whether any items are flagged — that's the signal, not the widget rendering fine in a browser.
Questions people ask
Does a review widget automatically add schema markup?
Not necessarily. A widget renders stars visually for people; whether it also outputs the JSON-LD Google reads depends on that specific widget. Check the vendor's documentation, or add the structured data separately if it doesn't.
Should I use Review or AggregateRating?
AggregateRating for a summary rating across multiple reviews, which is what most product pages want. Review is for marking up one individual piece of feedback with its own author.
Can I mark up reviews of my own product on my own site?
Google's guidelines restrict self-serving review markup for most schema types — a business rating its own service on its own pages doesn't automatically qualify for the rich result. Genuine third-party reviews, properly attributed, are the safer path.
What fields are actually required?
At minimum, ratingValue and reviewCount inside the AggregateRating block, plus an itemReviewed that names the correct item. Missing any of these stops a star result from rendering.
How do I check if my markup is working?
Run the page through Google's Rich Results Test before relying on it, then check the structured data reports in Search Console once the page is indexed to see how Google is actually reading it.
Does valid schema guarantee stars show up in search?
No. Valid, eligible markup is necessary but not sufficient — Google decides case by case whether to render the rich result, and it can change or remove eligibility for a given type over time.
Get real reviews before you mark them up
Structured data needs something genuine underneath it. List your product on SaaSVouch, collect real reviews with a free review widget, then add the markup that actually reflects them.