# Review schema (/docs/schema/review)

The unified SocialCrawl review schema. Every field, its type, per-platform availability, and a machine-readable JSON Schema, generated from the canonical Zod source.

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 | 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 | Owner/brand/management replies to the review, each `{id, author, text, published_at}` with `published_at` as an ISO 8601 UTC string (REL-07.6). |
| `published_at` | `string` or `integer` | Yes | Review creation timestamp as an ISO 8601 UTC string (REL-07.6). Upstreams that send only a calendar date land on midnight UTC. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `review.ext.published_at_epoch`. |

## 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

18 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.

<div className="overflow-x-auto">

| Platform | `author.avatar_url` | `author.location` | `helpful_votes` | `rating.max` | `url` | `language` | `author.reviews_count` | `author.url` | `title` | `verified` | `images` | `entity_id` |
| -------- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| AliExpress |  | yes | yes |  |  |  |  |  |  |  |  |  |
| Amazon | yes |  |  |  | yes |  |  | yes | yes | yes |  | yes |
| Apple App Store | yes |  | yes | yes |  |  |  |  | yes |  |  | yes |
| G2 |  |  |  |  | yes |  |  |  | yes |  |  |  |
| Google | yes |  |  | yes | yes |  | yes | yes |  |  |  | yes |
| Google Play | yes |  | yes | yes |  |  |  |  | yes |  |  | yes |
| Google Shopping |  |  |  | yes | yes |  |  |  | yes |  |  | yes |
| Home Depot |  | yes | yes |  |  |  |  |  | yes |  |  | yes |
| Klarna |  |  | yes | yes | yes | yes |  |  | yes |  |  | yes |
| Kohl's |  | yes | yes | yes |  |  |  |  | yes |  |  | yes |
| Sephora |  | yes | yes |  |  |  |  |  | yes |  |  | yes |
| Target |  |  | yes | yes |  |  |  |  | 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 | yes |  | yes |
| Walmart |  |  | yes |  |  |  |  |  | yes |  |  | yes |
| Wayfair |  | yes |  |  |  | yes |  |  |  |  | yes | yes |
| Yelp | yes | yes |  |  |  | yes | yes |  |  |  |  | yes |

</div>

## 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

Endpoints with the `Review` / `ReviewList` archetype return this shape:

[AliExpress](/platforms/aliexpress) · [Amazon](/platforms/amazon) · [Apple App Store](/platforms/app_store) · [G2](/platforms/g2) · [Google](/platforms/google) · [Google Play](/platforms/google_play) · [Google Shopping](/platforms/google_shopping) · [Home Depot](/platforms/home_depot) · [Klarna](/platforms/klarna) · [Kohl's](/platforms/kohls) · [Sephora](/platforms/sephora) · [Target](/platforms/target) · [TikTok Shop](/platforms/tiktokshop) · [Tripadvisor](/platforms/tripadvisor) · [Trustpilot](/platforms/trustpilot) · [Walmart](/platforms/walmart) · [Wayfair](/platforms/wayfair) · [Yelp](/platforms/yelp)

See how the same fields map to each platform's raw upstream names in the [cross-platform field equivalence table](/docs/schema/field-equivalence.md).