# Review schema (/docs/schema/review) {/* AUTO-GENERATED. Do not hand-edit. Source: packages/social-api/src/docs/generate-schema-pages.ts Regenerate with: pnpm -F @repo/social-api generate:docs Field tables derive from the canonical Zod schemas (packages/social-api/src/schemas/canonical.ts); availability + equivalence derive from the registry fieldMaps. */} Review schema [#review-schema] Every SocialCrawl endpoint that returns a review gives you this exact shape, whatever the source platform. Write your parser once and the same code reads review data from every platform below. That is the unified schema: one contract instead of a dozen raw upstream formats. Field reference [#field-reference] | Field | Type | Nullable | Description | | ---------------------- | ------------------- | -------- | ----------------------------------------------------------- | | `id` | `string` | No | Review ID (parsed from the review URL when not first-class) | | `entity_id` | `string` | Yes | ID of the reviewed entity (e.g. the Amazon ASIN) | | `url` | `string` | Yes | | | `title` | `string` | Yes | | | `text` | `string` | Yes | Full review body | | `rating.value` | `integer` | Yes | | | `rating.max` | `integer` | Yes | | | `author.name` | `string` | Yes | | | `author.avatar_url` | `string` | Yes | | | `author.url` | `string` | Yes | | | `author.location` | `string` | Yes | | | `author.reviews_count` | `integer` | Yes | | | `helpful_votes` | `integer` | Yes | Helpful-vote count (Amazon; null elsewhere) | | `verified` | `boolean` | Yes | Verified-purchase flag (Amazon; null elsewhere) | | `source` | `string` | Yes | | | `language` | `string` | Yes | | | `original_language` | `string` | Yes | | | `translated` | `boolean` | Yes | | | `images` | `string[]` | Yes | | | `responses` | `object[]` | Yes | | | `published_at` | `string or integer` | Yes | Union: string \| integer \| null | Extension fields (`ext`) [#extension-fields-ext] Platform-specific passthrough. Each field is present only on the platforms that expose it and is absent everywhere else, so treat every `ext.*` field as optional. These carry the richer, per-platform signals the unified leaves cannot hold, and the join keys that chain endpoints together. | Field | Type | Nullable | Description | | ---------------- | -------- | -------- | ----------- | | `ext.appdata` | `string` | Yes | | | `ext.tiktokshop` | `string` | Yes | | Platform availability [#platform-availability] 11 platforms return the `Review` shape. `id` are never null on any platform. The fields below vary: **yes** means the platform populates it (the value may still be null); a blank means the platform never provides it, so it is always null.
| Platform | `helpful_votes` | `url` | `verified` | `author.avatar_url` | `author.location` | `author.url` | `language` | `rating.max` | `author.reviews_count` | `original_language` | `images` | `source` | | --------------- | --------------- | ----- | ---------- | ------------------- | ----------------- | ------------ | ---------- | ------------ | ---------------------- | ------------------- | -------- | -------- | | Amazon | | yes | yes | yes | | yes | | | | | | | | Apple App Store | yes | | | yes | | | | yes | | | | | | Google | | yes | | yes | | yes | | yes | yes | yes | | | | Google Play | yes | | | yes | | | | yes | | | | | | Google Shopping | | yes | | | | | | yes | | | | yes | | Home Depot | yes | | yes | | yes | | yes | | | | | | | Target | yes | | yes | | | | | yes | | | yes | | | TikTok Shop | | | yes | yes | yes | | yes | | | yes | yes | | | Tripadvisor | | yes | | yes | yes | yes | yes | yes | yes | yes | | | | Trustpilot | | yes | yes | yes | yes | yes | yes | yes | yes | | | | | Walmart | yes | | | | | | | | | | | |
Machine-readable schema [#machine-readable-schema] Validate responses programmatically against the JSON Schema (2020-12): [`/schemas/review.json`](/schemas/review.json) Point a validator (Ajv, `jsonschema`, or your framework's) at that URL, or hand it to an agent so it can check the shape without a live call. Returned by [#returned-by] Endpoints with the `Review` / `ReviewList` archetype return this shape: [Amazon](/platforms/amazon) · [Apple App Store](/platforms/app_store) · [Google](/platforms/google) · [Google Play](/platforms/google_play) · [Google Shopping](/platforms/google_shopping) · [Home Depot](/platforms/home_depot) · [Target](/platforms/target) · [TikTok Shop](/platforms/tiktokshop) · [Tripadvisor](/platforms/tripadvisor) · [Trustpilot](/platforms/trustpilot) · [Walmart](/platforms/walmart) See how the same fields map to each platform's raw upstream names in the [cross-platform field equivalence table](/docs/schema/field-equivalence).