Data Schema and Field Dictionary

Every delivery is one JSONL file (one VideoObject per line) plus, for Growth and Scale, four joinable Parquet tables (videos, people, brands, products). Scale adds two more tables (industry_claims and statements), for six Parquet tables in total. The JSONL record is denormalized; Parquet is normalized for warehouse ergonomics. Current schema version is 3.2.0.

No VidScore quality score is included in the feed. That is an internal operational metric and is not published to any tier.

Data provenance

Source data is publicly available YouTube content, including video metadata and public captions. All entity extraction, classification, and scoring are performed by VidScore's proprietary AI pipeline on VidScore-controlled infrastructure. No third-party data enrichment services are used. Every record is traceable to a specific YouTube video via video_url.

Field nullability

Fields marked *Required: Yes* are guaranteed present and non-null on every record. Optional fields may be null. Fields gated to higher tiers return null on lower-tier deliveries, see [Tier Comparison and Field Gating](/help/enterprise-portal/tier-comparison-and-field-gating).

Freshness

Deliveries are produced weekly (Growth and Scale, Monday mornings UTC) or biweekly (Starter). Each delivery contains videos published during the prior delivery period. See [Delivery Cadence, File Formats, and What Arrives When](/help/enterprise-portal/delivery-cadence-and-format) for the full schedule.

Example record

Abbreviated for readability. Shows the full nesting: channel, iab, entities.people, entities.brands, entities.products, topics. Field types and every enum value are documented in the Field Index below.

{
  "schema_version": "3.2.0",
  "entity_type": "VideoObject",
  "extracted_at": "2026-04-21T09:15:00Z",
  "video_id": "dQw4w9WgXcQ",
  "video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "iPhone 17 Pro, honest review after 30 days",
  "title_translated": null,
  "language": "en",
  "published_at": "2026-04-17T14:22:08Z",
  "duration_seconds": 847,
  "view_count": 2840000,
  "channel": {
    "id": "UCBJycsmduvYEL83R_U4JriQ",
    "name": "MKBHD",
    "handle": "@mkbhd",
    "subscriber_count": 19400000,
    "is_verified": true
  },
  "iab": {
    "content": [{
      "unique_id": "611",
      "name": "Smartphones",
      "tier1": "Technology & Computing",
      "tier2": "Consumer Electronics",
      "tier3": "Smartphones",
      "tier4": null,
      "confidence": 0.96,
      "is_scd": false
    }],
    "content_form_factor": "Video",
    "is_sensitive_content": false,
    "openrtb_cat": ["611"],
    "openrtb_cattax": "2"
  },
  "content_type": "review",
  "industries": ["consumer_electronics"],
  "entities": {
    "people": [{
      "entity_type": "Person", "name": "Marques Brownlee",
      "role": "host", "confidence": 0.95,
      "sameAs": ["https://www.wikidata.org/wiki/Q18810450"]
    }],
    "brands": [{
      "entity_type": "Brand", "name": "Apple", "is_sponsor": false,
      "sentiment": 0.62, "sentiment_label": "positive",
      "context_role": "review", "prominence_level": "primary"
    }],
    "products": [{
      "entity_type": "Product", "name": "iPhone 17 Pro",
      "parent_brand": "Apple", "sentiment": 0.55,
      "price_mentioned": true, "estimated_price_cents": 119900, "currency": "USD"
    }]
  },
  "topics": [{
    "slug": "smartphones",
    "label": "Smartphones",
    "unique_id": "611",
    "name": "Smartphones",
    "tier1": "Technology & Computing",
    "tier2": "Consumer Electronics",
    "tier3": "Smartphones",
    "tier4": null,
    "confidence": 0.94
  }],
  "summary": "Long-term review of the iPhone 17 Pro covering battery, camera, and build quality."
}

Field Index

Delivery specification

• Transport. Signed URL (AWS S3-backed Supabase Storage), valid for 7 days from generation. Regenerate from the portal if a URL expires before you download.
• Path pattern. {customer_id}/{YYYY-W##}/vidscore-data-{YYYY-W##}.jsonl Example: org-abc123/2026-W17/vidscore-data-2026-W17.jsonl
• Manifest. Each delivery ships with a companion vidscore-data-{YYYY-W##}-manifest.json containing delivery_id, period_start, period_end, schema_version, record counts, industries included, and a quality scorecard.
• Parquet (Growth, Scale). Normalized tables videos.parquet, people.parquet, brands.parquet, products.parquet all joinable on video_id. Scale adds industry_claims.parquet and statements.parquet, for six Parquet tables in total.
• Retention of delivered files. 90 days (Starter), 180 days (Growth), 365 days (Scale), measured from each delivery's original date. See [Data Governance, Quality Checks, and Retention](/help/enterprise-portal/data-governance-and-retention) for retention mechanics.

Schema versioning

Current: 3.2.0. Minor versions (3.x → 3.y) only add fields; they never remove or rename existing fields. A parser that ignores unknown keys stays forward-compatible. A major version bump (3.x → 4.x) requires 90 days of written notice. Every JSONL record is validated against the published JSON Schema before it leaves our infrastructure. For quality rules, validation checks, and retention policies, see [Data Governance, Quality Checks, and Retention](/help/enterprise-portal/data-governance-and-retention).