# Unified schema (/docs/schema)



{/*
  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.
  */}

Unified schema [#unified-schema]

Most social-data APIs hand you raw upstream JSON, shaped differently on every platform. SocialCrawl normalizes each response into one canonical shape per archetype. A TikTok post and a YouTube video come back as the same `Post`; a Twitter profile and an Instagram profile come back as the same `Author`. Parse it once, read every platform.

Each page below documents a canonical shape: every field, its type, whether it can be null, which platforms populate it, and a machine-readable JSON Schema you can validate against.

Archetypes [#archetypes]

* [Post](/docs/schema/post.md): the unified post shape.
* [Author](/docs/schema/author.md): the unified author or creator profile shape.
* [Comment](/docs/schema/comment.md): the unified comment shape.
* [Product](/docs/schema/product.md): the unified product shape.
* [Review](/docs/schema/review.md): the unified review shape.
* [Seller](/docs/schema/seller.md): the unified seller offer shape.
* [Place](/docs/schema/place.md): the unified place or business shape.
* [App](/docs/schema/app.md): the unified app-store listing shape.
* [Quote](/docs/schema/quote.md): the unified financial quote shape.
* [Job](/docs/schema/job.md): the unified job posting shape.
* [News article](/docs/schema/news-article.md): the unified news article shape.
* [Web page](/docs/schema/web-page.md): the unified web page shape.
* [Transcript](/docs/schema/transcript.md): the unified video or audio transcript shape.
* [Media list](/docs/schema/media-list.md): the unified media-file list shape.

Cross-platform reference [#cross-platform-reference]

* [Field equivalence](/docs/schema/field-equivalence.md): how each platform's raw metric names map to the unified fields (e.g. TikTok `play_count` = YouTube `viewCount` = `engagement.views`).

Machine-readable schemas [#machine-readable-schemas]

Every archetype ships a JSON Schema (2020-12) at a stable URL, e.g. [`/schemas/post.json`](/schemas/post.json). Validate responses in code, or hand the URL to an agent so it can parse correctly on the first try.