Website Testimonials & Review Schema
Turn real quotes into (1) a UI section and (2) valid Review structured data,
both from one typed data file so the visible card and the JSON-LD can never
drift. This skill owns the testimonial pattern; it hands generic schema work
(Product, FAQ, Breadcrumb, Article…) to schema-markup.
Read this first — what schema can and can't buy you
- Google does NOT show ⭐ rich-results for self-hosted reviews about your own
Organization / LocalBusiness. It treats them as self-serving and may
ignore — or, for a fabricated AggregateRating, penalise — them. So the value
here is truthful semantic markup + GEO (LLMs / AI answer engines citing
your social proof), not blue-link stars. Set expectations honestly (Rule 12).
itemReviewed is the specific thing the person reviewed — the Event
(talk/workshop), Product, Service, Course — not a blanket org rating.
This keeps the markup accurate and is what review-snippet-eligible types want.
- Individual
Review nodes only by default. No AggregateRating unless the
reviewed item is a genuinely rich-results-eligible type (e.g. Product) AND
the rating reflects all real ratings. Few hand-picked 5-stars + an aggregate
reads as spam.
Accuracy rules (non-negotiable)
- Quotes are verbatim. Never invent, embellish, or "tidy" a quote or a name.
- Keep the original language. A quote written in another language stays in
that language (e.g. a German quote on an English page) — translating a
testimonial misrepresents it. Set
lang on the element AND inLanguage on the
Review so screen readers + parsers get it right.
- Real ratings only.
ratingValue is what the person actually gave.
Sourcing quotes (where they come from)
Testimonials come from wherever real feedback lives: post-purchase emails,
post-event surveys, support tickets, sales calls, or review sites (G2,
Trustpilot, app stores). Most sources are private to you, with no public feed
or API to pull from, so the workflow is manual curation — which is also
better editorially, since you pick the strongest, on-message quotes:
- Open the source and copy the best verbatim quote + the rating + the
person's name/affiliation.
- Add one entry to
src/data/testimonials.ts (set lang; map itemName/itemUrl
to the specific item reviewed — the product, service, or event). No sync script
is possible for most sources — don't build one.
- Get consent for named quotes before they go live — see Consent &
shipping below.
Example (event sites): Luma keeps ratings organizer-private in Manage
Event → Insights, exportable only as CSV; its per-response "share card" is a
one-off image, not a live source — so you transcribe by hand. Expect the same
of most platforms.
Consent & shipping named quotes
A person left feedback for one purpose, not blanket permission to be quoted by
name on your marketing site. Treat consent as a publish gate, applied per person:
- Ask before production. "OK to feature this quote, with your name and
affiliation, on our site?" Anonymous/handle-only quotes are lower-risk — but
still ask if the wording itself is identifying. Keeps you clean on GDPR/consent.
- Ship to PREVIEW first, not prod. Put the section on a preview deploy (a
branch build, off the production branch) so the team can review wording and
layout while consent is pending. Keep testimonials off production until approved.
- Promote per person — ship only the approved subset. If two of three
consent, the live
TESTIMONIALS array carries those two; the third stays out.
- Withhold, don't delete. Keep an unconsented quote out of the array but
leave a
// NOTE: comment (the verbatim text also survives in git history), so
re-adding on approval is a one-line edit.
Caveat: a static preview is usually not auto-noindexed, and a Worker's Preview
link or a *.pages.dev URL can be opened by anyone who has it — so a named, unconsented quote sitting on a
preview is still exposure. Keep previews unlinked and short-lived (or add a
branch-only noindex);
the real guarantee is keeping it off production until consent lands.
The data model — one source of truth
src/data/testimonials.ts exports the typed list and the schema builder, so
a page imports both and nothing is duplicated:
import { SITE } from '../config';
export interface Testimonial {
author: string; // name or handle, verbatim
org?: string; // affiliation, shown after the name
rating: number; // 1–5, as actually given
quote: string; // verbatim
lang: string; // BCP-47 tag, e.g. 'en' / 'de' → `lang` attr + inLanguage
itemName: string; // the thing reviewed → itemReviewed.name
itemUrl: string; // canonical URL of that item (absolute)
itemType?: string; // schema.org type of the reviewed thing; default 'Event'
}
// Only consent-approved entries ship here; withhold the rest with a // NOTE.
export const TESTIMONIALS: Testimonial[] = [ /* … */ ];
// Individual Review nodes — no self-serving AggregateRating.
export function reviewSchemas(): Record<string, unknown>[] {
return TESTIMONIALS.map((t) => ({
'@context': 'https://schema.org',
'@type': 'Review',
author: { '@type': 'Person', name: t.author },
reviewRating: { '@type': 'Rating', ratingValue: t.rating, bestRating: 5, worstRating: 1 },
reviewBody: t.quote,
inLanguage: t.lang,
itemReviewed: { '@type': t.itemType ?? 'Event', name: t.itemName, url: t.itemUrl },
}));
}
Wiring it in (Astro / new-website kit)
- Schema — pass the builder to
Base's schemas prop; the Base layout
already serialises each entry to <script type="application/ld+json">:---
import { TESTIMONIALS, reviewSchemas } from '../data/testimonials';
---
<Base titleExact="…" description="…" schemas={reviewSchemas()}>
(Do NOT hand-write JSON-LD in the page — go through schemas so it stays in
sync with the data file and Base's other schema nodes.)
- UI — render cards from the same
TESTIMONIALS array. Stars are decorative
(aria-label="Rated 5 out of 5", the glyphs themselves hidden from the name);
foreign-language quotes get lang={t.lang} so AT pronounces them correctly.
- Theme — reuse the site's tokens (
--dark-card, --text, --text-muted,
--primary-light); a gold star (#F5A623) clears AA on the dark card.
Done means
npm test green — a11y.spec.ts (star contrast + lang attrs), tone, seo.
- JSON-LD parses and passes the schema.org validator / Google Rich Results Test
with no errors; each
Review has author, reviewRating (with
bestRating/worstRating), reviewBody, inLanguage, and an itemReviewed
with a real name + absolute url.
- The rendered card text equals the
reviewBody (same source — verify one).
- No
AggregateRating unless justified per the rules above.
- Every NAMED quote on production has consent; un-approved ones are withheld
(with a
// NOTE:), and anything pending consent shipped to preview only.
1---2name: website-testimonials3description: >4 Encode customer / attendee testimonials as proper schema.org `Review` JSON-LD5 AND render the "What people say" UI from ONE typed source of truth6 (`src/data/testimonials.ts`). Individual Review nodes only — author + 5/57 reviewRating + reviewBody + inLanguage + itemReviewed pointing at the SPECIFIC8 thing reviewed (Event / Product / Service), never a fabricated org-wide9 AggregateRating. Use when adding quotes, testimonials, social proof, ratings,10 or star reviews to a site built with the new-website kit (pipeline step 5,11 alongside `website-seo-geo`). Delegates other schema types to `schema-markup`.12 Trigger phrases: "add testimonials", "customer quotes", "attendee feedback",13 "review schema", "star ratings", "social proof section", "encode the quotes",14 "schema.org Review", "what people say section".15metadata:16 source: https://skillmd.com/skills/karero/website-testimonials17---1819# Website Testimonials & Review Schema2021Turn real quotes into (1) a UI section and (2) valid `Review` structured data,22both from **one typed data file** so the visible card and the JSON-LD can never23drift. This skill owns the testimonial pattern; it hands generic schema work24(Product, FAQ, Breadcrumb, Article…) to `schema-markup`.2526## Read this first — what schema can and can't buy you2728- **Google does NOT show ⭐ rich-results for self-hosted reviews about your own29 `Organization` / `LocalBusiness`.** It treats them as *self-serving* and may30 ignore — or, for a fabricated `AggregateRating`, penalise — them. So the value31 here is **truthful semantic markup + GEO** (LLMs / AI answer engines citing32 your social proof), not blue-link stars. Set expectations honestly (Rule 12).33- **`itemReviewed` is the specific thing the person reviewed** — the `Event`34 (talk/workshop), `Product`, `Service`, `Course` — not a blanket org rating.35 This keeps the markup accurate and is what review-snippet-eligible types want.36- **Individual `Review` nodes only by default. No `AggregateRating`** unless the37 reviewed item is a genuinely rich-results-eligible type (e.g. `Product`) AND38 the rating reflects *all* real ratings. Few hand-picked 5-stars + an aggregate39 reads as spam.4041## Accuracy rules (non-negotiable)4243- **Quotes are verbatim.** Never invent, embellish, or "tidy" a quote or a name.44- **Keep the original language.** A quote written in another language stays in45 that language (e.g. a German quote on an English page) — translating a46 testimonial misrepresents it. Set `lang` on the element AND `inLanguage` on the47 Review so screen readers + parsers get it right.48- **Real ratings only.** `ratingValue` is what the person actually gave.4950## Sourcing quotes (where they come from)5152Testimonials come from wherever real feedback lives: post-purchase emails,53post-event surveys, support tickets, sales calls, or review sites (G2,54Trustpilot, app stores). Most sources are **private to you, with no public feed55or API** to pull from, so the workflow is **manual curation** — which is also56better editorially, since you pick the strongest, on-message quotes:57581. Open the source and copy the best **verbatim** quote + the rating + the59 person's name/affiliation.602. Add one entry to `src/data/testimonials.ts` (set `lang`; map `itemName`/`itemUrl`61 to the specific item reviewed — the product, service, or event). No sync script62 is possible for most sources — don't build one.633. **Get consent for named quotes before they go live** — see *Consent &64 shipping* below.6566> Example (event sites): **Luma** keeps ratings organizer-private in *Manage67> Event → Insights*, exportable only as CSV; its per-response "share card" is a68> one-off image, not a live source — so you transcribe by hand. Expect the same69> of most platforms.7071## Consent & shipping named quotes7273A person left feedback for one purpose, not blanket permission to be quoted **by74name on your marketing site**. Treat consent as a publish gate, applied per person:75761. **Ask before production.** "OK to feature this quote, with your name and77 affiliation, on our site?" Anonymous/handle-only quotes are lower-risk — but78 still ask if the wording itself is identifying. Keeps you clean on GDPR/consent.792. **Ship to PREVIEW first, not prod.** Put the section on a preview deploy (a80 branch build, off the production branch) so the team can review wording and81 layout while consent is pending. Keep testimonials **off production** until approved.823. **Promote per person — ship only the approved subset.** If two of three83 consent, the live `TESTIMONIALS` array carries those two; the third stays out.844. **Withhold, don't delete.** Keep an unconsented quote out of the array but85 leave a `// NOTE:` comment (the verbatim text also survives in git history), so86 re-adding on approval is a one-line edit.8788Caveat: a static preview is usually **not auto-noindexed**, and a Worker's Preview89link or a `*.pages.dev` URL can be opened by anyone who has it — so a named, unconsented quote sitting on a90preview is still exposure. Keep previews unlinked and short-lived (or add a91branch-only `noindex`);92the real guarantee is keeping it **off production** until consent lands.9394## The data model — one source of truth9596`src/data/testimonials.ts` exports the typed list **and** the schema builder, so97a page imports both and nothing is duplicated:9899```ts100import { SITE } from '../config';101102export interface Testimonial {103 author: string; // name or handle, verbatim104 org?: string; // affiliation, shown after the name105 rating: number; // 1–5, as actually given106 quote: string; // verbatim107 lang: string; // BCP-47 tag, e.g. 'en' / 'de' → `lang` attr + inLanguage108 itemName: string; // the thing reviewed → itemReviewed.name109 itemUrl: string; // canonical URL of that item (absolute)110 itemType?: string; // schema.org type of the reviewed thing; default 'Event'111}112113// Only consent-approved entries ship here; withhold the rest with a // NOTE.114export const TESTIMONIALS: Testimonial[] = [ /* … */ ];115116// Individual Review nodes — no self-serving AggregateRating.117export function reviewSchemas(): Record<string, unknown>[] {118 return TESTIMONIALS.map((t) => ({119 '@context': 'https://schema.org',120 '@type': 'Review',121 author: { '@type': 'Person', name: t.author },122 reviewRating: { '@type': 'Rating', ratingValue: t.rating, bestRating: 5, worstRating: 1 },123 reviewBody: t.quote,124 inLanguage: t.lang,125 itemReviewed: { '@type': t.itemType ?? 'Event', name: t.itemName, url: t.itemUrl },126 }));127}128```129130## Wiring it in (Astro / new-website kit)1311321. **Schema** — pass the builder to `Base`'s `schemas` prop; the Base layout133 already serialises each entry to `<script type="application/ld+json">`:134 ```astro135 ---136 import { TESTIMONIALS, reviewSchemas } from '../data/testimonials';137 ---138 <Base titleExact="…" description="…" schemas={reviewSchemas()}>139 ```140 (Do NOT hand-write JSON-LD in the page — go through `schemas` so it stays in141 sync with the data file and Base's other schema nodes.)1422. **UI** — render cards from the same `TESTIMONIALS` array. Stars are decorative143 (`aria-label="Rated 5 out of 5"`, the glyphs themselves hidden from the name);144 foreign-language quotes get `lang={t.lang}` so AT pronounces them correctly.1453. **Theme** — reuse the site's tokens (`--dark-card`, `--text`, `--text-muted`,146 `--primary-light`); a gold star (`#F5A623`) clears AA on the dark card.147148## Done means149150- `npm test` green — `a11y.spec.ts` (star contrast + lang attrs), `tone`, `seo`.151- JSON-LD parses and passes the schema.org validator / Google Rich Results Test152 with **no errors**; each `Review` has `author`, `reviewRating` (with153 `bestRating`/`worstRating`), `reviewBody`, `inLanguage`, and an `itemReviewed`154 with a real `name` + absolute `url`.155- The rendered card text equals the `reviewBody` (same source — verify one).156- No `AggregateRating` unless justified per the rules above.157- Every NAMED quote on **production** has consent; un-approved ones are withheld158 (with a `// NOTE:`), and anything pending consent shipped to **preview only**.