Review Schema & Structured Data: The Complete Guide

Structured data is machine-readable annotation (usually JSON-LD using the schema.org vocabulary) that tells crawlers what a page means rather than only what it says. A human reads “4.7 from 89 reviews”; a crawler reads an AggregateRating with ratingValue and reviewCount properties, unambiguous and comparable across the entire web.

Reviews are the vocabulary’s most commercially consequential corner because Google renders them directly in results as review snippets (the orange stars), and stars measurably raise click-through. The same data feeds product knowledge panels, shopping surfaces, and increasingly the AI assistants that summarize “what’s the best X” for their users. One block of correct markup, several distribution channels.

This guide covers the whole layer: the types, the format war, Google’s eligibility rules (including the one that invalidates most DIY attempts), testing, and what to automate.

Two schema.org types do the heavy lifting. Review represents a single review: author, rating, body, date. AggregateRating summarizes many: average value plus rating/review counts. Critically, neither stands alone: both must be nested inside the item they describe. For a SaaS product that parent is SoftwareApplication (or WebApplication); for physical goods, Product; other supported parents include Course, Book, Recipe, and LocalBusiness.

Orphaned rating markup (an AggregateRating floating on a page with no parent item) is the most common structural error validators catch, and it is disqualifying. The second most common: marking up ratings that do not visibly appear on the page, which violates Google’s content-parity requirement and risks manual action.

The property-level walkthrough (required fields, ratingCount vs reviewCount, scale bounds, the zero-count trap) is in how to add AggregateRating schema.

Schema.org data can be expressed three ways: JSON-LD (a self-contained script block), microdata (attributes woven into your HTML), and RDFa (similar weaving, W3C lineage). All three parse; the choice is still settled. Google explicitly recommends JSON-LD, it survives redesigns because it is decoupled from presentation, it serializes naturally from application state, and it can be read and validated as a single block.

Microdata’s installed base in older e-commerce themes still works and is not worth ripping out; RDFa persists in government and library contexts. The one hard rule: never emit two formats for the same entity; conflicting statements are a classic source of rich-result flakiness. The full comparison with code samples is in JSON-LD vs Microdata vs RDFa.

Valid markup buys a lottery ticket, not a guarantee. Google applies quality filters before rendering stars, and the decisive one is the self-serving restriction: review markup about an entity, published by that entity on its own site, is ignored. Your homepage cannot star-rate your own product, no matter how genuine the underlying reviews. This has been policy since 2019 and it is the reason most SaaS schema projects quietly produce nothing.

The escape hatch is independence: reviews published on a third-party platform’s page about your product, with schema on that page, are exactly what the system is designed to reward. This is the structural reason TheWebRatings exists as a platform rather than a plugin: every public app page carries SoftwareApplication + AggregateRating + Review markup generated from live verified-review data. You can inspect it on any page in the apps directory.

Other filters worth knowing: supported parent types only, visible-content parity, no incentivized or gated review pools, and freshness (profiles with recent reviews are more likely to keep their stars). The complete rundown: how to get star ratings in Google results.

Three tools cover the lifecycle. The Rich Results Test validates a URL against Google’s subset and tells you whether review snippets are detected. The schema.org validator checks structural correctness beyond Google’s scope. Search Console’s review-snippets report monitors valid and invalid items across your site over time, the place drift shows up first.

We also publish free utilities for generating and checking review markup at /tools, useful if you maintain schema by hand for a directory or comparison site.

Operational advice from maintaining this at scale: generate JSON-LD from the same data source that renders the visible rating (never hardcode), re-validate after every markup-adjacent deploy, and treat a disappeared star as an incident with a checklist: validity error, content drift, eligibility change, or sitewide quality issue, in that order of likelihood.

After validity, most star failures trace to a short list. Orphaned ratings: an AggregateRating not nested inside a parent item; validators flag it, and it never renders. Zero counts: reviewCount: 0 invalidates the item entirely; omit rating markup until reviews exist rather than shipping zeros. Out-of-range values: a ratingValue outside the declared best/worst bounds, usually left over from a scale migration. Duplicate markup: a theme plugin emitting microdata while your code emits JSON-LD for the same entity, with subtly different numbers; parsers see two conflicting statements and often trust neither. Invisible data: ratings present in markup but nowhere on the rendered page, which violates content parity and risks manual action.

And the silent one: drift. A hardcoded snippet that said 4.7 from 89 reviews at deploy time says the same thing a year later, while the visible page has moved on. Nothing errors; the stars just eventually vanish in a quality re-evaluation. The fix is architectural (generate markup from the same live data that renders the page), and it is the single practice that separates schema setups that keep working from ones that decay.

When stars disappear, debug in likelihood order: validity error (test the URL), content drift (compare markup numbers to visible numbers), eligibility change (re-read the current review-snippet guidelines), then sitewide quality issues. Nine times out of ten it is one of the first two.

Three setups cover nearly every SaaS situation. Pattern one (you have a product and want stars for it): use an independent review platform whose public page carries the schema. Your engineering cost is zero; your job is collection volume and freshness. This is the TheWebRatings model, and it is the only pattern that survives the self-serving rule for your own product.

Pattern two (you publish content about other products): a directory, comparison site, or review blog can legitimately mark up Review and AggregateRating for the third-party items it covers. Generate the JSON-LD server-side from your data layer, one block per item page, and keep visible ratings and markup sourced from the same field.

Pattern three (both): common for SaaS companies with content marketing. Keep the two concerns separate: your product’s stars come from the independent platform page; your content’s markup covers only the items the content reviews. The failure mode to avoid is sprinkling your own product’s aggregate rating into every blog post footer; it does nothing for rich results and reads as manipulation to quality systems.

Whichever pattern applies, budget for the boring parts: validation in CI or at least after every markup-adjacent deploy, and a quarterly check of Search Console’s review-snippets report. Schema is infrastructure; it needs monitoring, not faith.

A growing share of software discovery now happens inside AI assistants, and structured data is disproportionately legible to them. When an LLM-backed answer engine evaluates products, crawlable pages with unambiguous rating markup from independent sources are among the cleanest signals it can retrieve. The same JSON-LD that earns review snippets makes your rating citable in AI answers, a channel with rising volume while classic search click-through declines.

The implication: publishing verified reviews with maintained schema on an independent page is now more than an SEO tactic. It is how your product’s reputation becomes machine-readable, which is increasingly how it becomes visible at all. For the collection side of that equation, see the companion guide on customer reviews for SaaS; for the platform decision, the alternatives guide.

If you skimmed everything above, here is the whole guide as a sequence you can execute this week:

• Decide which pattern applies: stars for your own product (independent platform), markup for items you cover (your own JSON-LD), or both, kept separate.
• For your own product: claim a public profile on a platform that maintains SoftwareApplication + AggregateRating + Review markup from live data, and focus your energy on verified collection volume.
• For markup you own: JSON-LD only, generated server-side from the same source as the visible content, nested in a supported parent type, with counts and bounds correct.
• Validate with the Rich Results Test before and after every deploy that touches markup; wire the schema.org validator into review if you ship markup often.
• Check Search Console’s review-snippets report monthly, and treat missing stars as a debuggable incident, not weather.
• Re-read the eligibility rules once a year; Google tightens them more often than it loosens them.

None of this is difficult; all of it is easy to half-do. The teams that get and keep stars are simply the ones that treat structured data as maintained infrastructure rather than a launch-week task.