VideoObject Schema: Get Video Thumbnails in Google Search
Add VideoObject schema so videos show thumbnails in Google: required properties, key moments, embeds versus hosted files, and how to check video indexing.
Kazi Khalid Hasan Tamim · BugViso Team
16 min read
VideoObject schema is JSON-LD that describes a video on a page: its name, description, thumbnail URL, upload date and duration.
Google can use it to show a video thumbnail in search results, provided the video is the main content of the page and the thumbnailUrl is crawlable. This guide covers the required fields and the common failures.
However, Google enforces criteria beyond basic schema syntax. Four conditions apply:
- The video must be the main content of the host webpage.
- The declared
thumbnailUrlmust meet aspect ratio and crawlability specifications. - Duration must use ISO 8601 duration notation (
PT1M33S). - Media playback links (
contentUrlorembedUrl) must be accessible to Googlebot without authentication walls.
Videoobject rich result architectural flow
| Step | What happens |
|---|---|
| 1. Host page validation | Google confirms the video is "Main Content" on the page |
| 2. Schema parse | Extracts VideoObject and checks required properties |
| 3. Thumbnail fetch | Googlebot-Image crawls thumbnailUrl (16:9 / 4:3) |
| 4. Media stream test | Validates an accessible mp4 contentUrl or embedUrl |
| 5. Visual SERP generation | A video thumbnail badge is rendered alongside the snippet |
This guide is a complete engineering blueprint for VideoObject schema. It covers required properties, video player integration (HTML5, YouTube, Vimeo, Wistia), Google's main-content policy rules, automated Python validation, and high-scale framework implementations.
1. Technical Mechanics: What Googlebot Requires for Video Thumbnails
Search algorithms evaluate VideoObject structured data through a specialized video processing pipeline:
Video extraction & validation pipeline
| Step | What the pipeline does |
|---|---|
| 1. Syntactic verification | Confirms name, description, uploadDate and thumbnails |
| 2. Media link discovery | Discovers contentUrl (direct) or embedUrl |
| 3. Thumbnail resolution | Verifies minimum dimensions (140x130 px, >60KB) |
| 4. Duration parsing | Converts ISO 8601 PT#M#S to a display timestamp |
| 5. Viewport prominence | Confirms the video is above the fold or the primary focus |
1. Mandatory vs Recommended Properties
Google's Rich Results documentation specifies strict property requirements for VideoObject:
| Property Name | Classification | Expected Format | Impact on Rich Results |
|---|---|---|---|
name | Mandatory | String (Title of the video) | Displayed as the primary video title in SERP |
description | Mandatory | String (Concise summary) | Summarizes video content for indexing and search |
thumbnailUrl | Mandatory | Array of valid image URLs | Provides the visual thumbnail rendered in search |
uploadDate | Mandatory | ISO 8601 Date (YYYY-MM-DDTHH:MM:SSZ) | Displays publication freshness in search cards |
contentUrl | Conditional* | URL pointing to direct media file (.mp4) | Enables Google to fetch raw video stream |
embedUrl | Conditional* | URL pointing to iframe player endpoint | Allows in-SERP playback preview |
duration | Recommended | ISO 8601 Duration (PT5M30S) | Renders time badge (e.g., 5:30) on thumbnail |
hasPart | Recommended | Array of Clip objects | Enables "Key Moments" timeline timestamps |
*Google mandates providing either contentUrl or embedUrl (or both). Providing both maximizes indexing reliability across web and video tabs.
2. The Main-Content Policy (The September 2023 Update)
In September 2023, Google updated its video indexing criteria: video thumbnails are only rendered if the video is the main content of the page.
- Eligible (Main Content): Dedicated video watch pages, dedicated webinar recordings, or standalone video tutorial guides where the video player is prominently positioned above the fold.
- Ineligible (Supplementary Content): A 2,500-word blog post where a small video is embedded at the bottom as a supplementary reference, or an e-commerce product page where the primary content is an item catalog.
Supplementary videos can still be indexed in Google's dedicated "Videos" tab, but they will no longer trigger video thumbnails on the primary Google Web Search result page.
For the other rich result types and their properties, see how to get rich snippets with schema markup.
2. VideoObject Schema: Production JSON-LD With Key Moments
The following production template demonstrates a complete VideoObject implementation featuring direct video streaming URLs, responsive thumbnail arrays, and timestamped Clip segments for Google's "Key Moments" feature:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "VideoObject",
"@id": "https://example.com/videos/core-web-vitals-deep-dive/#video",
"name": "How to Diagnose and Fix Interaction to Next Paint (INP)",
"description": "Comprehensive engineering walkthrough on debugging slow React hydration loops, long animation frames, and optimizing INP under 200ms.",
"thumbnailUrl": [
"https://example.com/thumbnails/inp-guide-16x9.jpg",
"https://example.com/thumbnails/inp-guide-4x3.jpg",
"https://example.com/thumbnails/inp-guide-1x1.jpg"
],
"uploadDate": "2026-09-15T09:00:00+00:00",
"duration": "PT14M45S",
"contentUrl": "https://cdn.example.com/videos/inp-diagnostics-1080p.mp4",
"embedUrl": "https://example.com/embed/inp-diagnostics",
"interactionStatistic": {
"@type": "InteractionCounter",
"interactionType": { "@type": "WatchAction" },
"userInteractionCount": 14200
},
"publisher": {
"@type": "Organization",
"name": "Apex Engineering Institute",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/assets/logo.png"
}
},
"hasPart": [
{
"@type": "Clip",
"name": "Understanding the INP Event Lifecycle",
"startOffset": 0,
"endOffset": 185,
"url": "https://example.com/videos/core-web-vitals-deep-dive?t=0"
},
{
"@type": "Clip",
"name": "Profiling Long Animation Frames in Chrome DevTools",
"startOffset": 186,
"endOffset": 490,
"url": "https://example.com/videos/core-web-vitals-deep-dive?t=186"
},
{
"@type": "Clip",
"name": "Refactoring Blocking Event Listeners with scheduler.yield()",
"startOffset": 491,
"endOffset": 885,
"url": "https://example.com/videos/core-web-vitals-deep-dive?t=491"
}
]
}
</script>3. Dynamic Next.js 15 Implementation with TypeScript
In modern React and Next.js 15 applications, video metadata is typically supplied via a headless CMS (Sanity, Contentful) or a video hosting API (Mux, Cloudflare Stream).
The component below demonstrates how to dynamically generate a Google-compliant VideoObject JSON-LD payload alongside an accessible HTML5 <video> player:
// components/media/VideoPlayerWithSchema.tsx
import React from 'react';
export interface VideoClip {
title: string;
startSeconds: number;
endSeconds: number;
}
export interface VideoData {
title: string;
description: string;
slug: string;
uploadedAt: string;
durationSeconds: number;
thumbnailUrls: string[];
mp4Url: string;
embedUrl: string;
clips?: VideoClip[];
}
// Convert raw seconds to ISO 8601 duration format (e.g. PT4M12S)
function formatIsoDuration(totalSeconds: number): string {
const hours = Math.floor(totalSeconds / 3600);
const minutes = Math.floor((totalSeconds % 3600) / 60);
const seconds = totalSeconds % 60;
let durationStr = 'PT';
if (hours > 0) durationStr += `${hours}H`;
if (minutes > 0 || hours > 0) durationStr += `${minutes}M`;
durationStr += `${seconds}S`;
return durationStr;
}
export function VideoPlayerWithSchema({ video, baseUrl }: { video: VideoData; baseUrl: string }) {
const pageUrl = `${baseUrl}/watch/${video.slug}`;
const jsonLd: Record<string, any> = {
'@context': 'https://schema.org',
'@type': 'VideoObject',
'@id': `${pageUrl}/#video`,
name: video.title,
description: video.description,
thumbnailUrl: video.thumbnailUrls,
uploadDate: video.uploadedAt,
duration: formatIsoDuration(video.durationSeconds),
contentUrl: video.mp4Url,
embedUrl: video.embedUrl
};
if (video.clips && video.clips.length > 0) {
jsonLd.hasPart = video.clips.map((clip) => ({
'@type': 'Clip',
name: clip.title,
startOffset: clip.startSeconds,
endOffset: clip.endSeconds,
url: `${pageUrl}?t=${clip.startSeconds}`
}));
}
return (
<div className="video-player-wrapper my-8 max-w-5xl mx-auto">
{/* Isolated JSON-LD Schema Injection */}
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>
<div className="relative aspect-video rounded-2xl overflow-hidden shadow-2xl bg-black">
<video
controls
preload="metadata"
poster={video.thumbnailUrls[0]}
className="w-full h-full object-cover"
>
<source src={video.mp4Url} type="video/mp4" />
Your browser does not support HTML5 video streaming.
</video>
</div>
<div className="mt-4">
<h1 className="text-2xl font-bold text-slate-900 tracking-tight">{video.title}</h1>
<p className="text-sm text-slate-600 mt-2 leading-relaxed">{video.description}</p>
</div>
</div>
);
}4. Advanced Video Features: Transcripts & Live Stream Broadcasting
Beyond standard on-demand tutorials, modern video engineering incorporates accessibility features and live streaming events to maximize indexability and real-time search discovery.
1. The transcript Property for Semantic Indexing
Adding a complete textual transcript to your VideoObject schema provides search engines and LLM answer engines with direct access to spoken dialogue without requiring external speech-to-text processing:
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "Distributed SQL vs NoSQL Benchmarks",
"description": "Engineering comparison of distributed ACID transactions versus eventual consistency models.",
"transcript": "Welcome everyone. In today's session, we are analyzing p99 latency benchmarks between distributed CockroachDB clusters and MongoDB sharded replica sets under high write contention..."
}This text enables search engines to rank your video page for long-tail spoken phrases that do not appear in the primary video title or description.
2. Live Stream Schema with BroadcastEvent
When hosting live technical webinars, product keynotes, or virtual conferences, implementing BroadcastEvent inside VideoObject enables the coveted red "LIVE" badge in Google search results:
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "Live Keynote: The Future of Generative Web Architecture",
"description": "Streaming live presentation on edge rendering, headless CMS pipelines, and AI search indexing.",
"uploadDate": "2026-10-01T08:00:00+00:00",
"thumbnailUrl": "https://example.com/thumbnails/live-keynote.jpg",
"publication": [
{
"@type": "BroadcastEvent",
"isLiveBroadcast": true,
"startDate": "2026-10-01T09:00:00-07:00",
"endDate": "2026-10-01T11:30:00-07:00"
}
]
}Googlebot continuously pings the live broadcast endpoint during the active window, removing the live badge automatically when endDate elapses.
5. Key Moments & Seeking Specification
Google Search allows users to jump directly to specific segments of a video from the search results page via the "Key Moments" interface. There are two primary architectural methods for enabling Key Moments:
2 methods to enable key moments in serps
- Method 1,
Clipschema nodes: hardcode specific time segments viahasPart. - Method 2,
SeekToAction: a dynamic URL template, for examplehttps://site.com/v?t={s}.
Method 1: Discrete Clip Elements (Best for Custom Chapters)
As demonstrated in our primary blueprint, you declare explicit start and end offsets for pre-defined editorial sections. This guarantees exact chapter naming in search results.
Method 2: Dynamic SeekToAction Schema (Best for Large Video Libraries)
If your video player natively supports deep-linking via a URL parameter (e.g., ?t=120 or #t=120), you can declare a dynamic SeekToAction property:
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "Cloud Architecture Deep Dive",
"potentialAction": {
"@type": "SeekToAction",
"target": "https://example.com/watch/cloud-architecture?t={seek_to_second_number}",
"startOffset-input": "required name=seek_to_second_number"
}
}Google will automatically identify significant visual and audio shifts in the video stream, generating automated chapters that deep-link directly into your player using the target parameter template.
5. Python Automation: Video Schema & Thumbnail Inspector
This automated Python script audits a URL hosting video content, verifies that required properties exist, tests thumbnail crawlability, and validates ISO 8601 duration syntax:
# scripts/audit_video_schema.py
import sys
import json
import re
import httpx
from bs4 import BeautifulSoup
def validate_iso_duration(duration_str: str) -> bool:
pattern = r"^PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?$"
return bool(re.match(pattern, duration_str))
def audit_video_page(url: str):
print(f"[*] Auditing VideoObject Schema on: {url}")
headers = {"User-Agent": "BugVisoVideoValidator/1.0 (+https://bugviso.com)"}
try:
res = httpx.get(url, headers=headers, timeout=12.0, follow_redirects=True)
except Exception as e:
print(f"[X] Request failed: {e}")
return False
soup = BeautifulSoup(res.text, "html.parser")
scripts = soup.find_all("script", type="application/ld+json")
if not scripts:
print("[X] No JSON-LD script blocks found on page.")
return False
video_found = False
for script in scripts:
if not script.string:
continue
try:
data = json.loads(script.string)
except json.JSONDecodeError as exc:
print(f"[X] Syntax Error: {exc}")
continue
nodes = data.get("@graph", [data]) if isinstance(data, dict) else data
for node in nodes:
if node.get("@type") == "VideoObject":
video_found = True
name = node.get("name")
desc = node.get("description")
thumbs = node.get("thumbnailUrl", [])
upload_date = node.get("uploadDate")
duration = node.get("duration")
content_url = node.get("contentUrl")
embed_url = node.get("embedUrl")
print(f"[✓] Detected VideoObject: '{name}'")
print("=" * 65)
# Check mandatory fields
if not name or not desc or not upload_date:
print("[X] Critical: Missing mandatory name, description, or uploadDate!")
else:
print(f" - Upload Date: {upload_date}")
# Validate Duration
if duration:
if validate_iso_duration(duration):
print(f" - Duration: {duration} [VALID ISO-8601]")
else:
print(f" [X] Invalid Duration Format: '{duration}'. Expected format 'PT#M#S'.")
else:
print(" [!] Warning: Missing 'duration'. SERP badge will not display time.")
# Validate Media URLs
if not content_url and not embed_url:
print(" [X] Critical Error: Must declare at least one of 'contentUrl' or 'embedUrl'.")
else:
if content_url:
print(f" - Direct Stream: {content_url}")
if embed_url:
print(f" - Embed Player: {embed_url}")
# Inspect Thumbnails
if not thumbs:
print(" [X] Critical Error: Missing required 'thumbnailUrl'.")
else:
thumb_list = [thumbs] if isinstance(thumbs, str) else thumbs
print(f" - Declared Thumbnails ({len(thumb_list)}):")
for t_url in thumb_list:
# Test thumbnail HTTP status
try:
t_res = httpx.head(t_url, timeout=5.0)
status_marker = "[OK]" if t_res.status_code == 200 else f"[HTTP {t_res.status_code}]"
except Exception:
status_marker = "[TIMEOUT/ERR]"
print(f" -> {t_url} {status_marker}")
# Inspect Key Moments
clips = node.get("hasPart", [])
if clips:
print(f" [✓] Key Moments Enabled: {len(clips)} chapter clips detected.")
for c in clips:
print(f" * {c.get('name')} ({c.get('startOffset')}s - {c.get('endOffset')}s)")
print("=" * 65)
if not video_found:
print("[X] No VideoObject entity detected.")
return False
return True
if __name__ == "__main__":
target = sys.argv[1] if len(sys.argv) > 1 else "https://example.com/watch/sample"
audit_video_page(target)6. How BugViso Audits Video Schema & Media Accessibility
Validating video structured data across thousands of pages cannot be done by hand. BugViso's structured data check reads the VideoObject markup on every page a signed-in scan crawls.
When you run a scan, it:
- Extracts VideoObject JSON-LD from each rendered page, including markup injected by JavaScript.
- Checks properties:
name,description,thumbnailUrlanduploadDateare required;contentUrl,embedUrlanddurationare recommended. Missing ones appear as findings. - Flags malformed JSON-LD that would stop Google reading the block.
- Lists the fix: each finding is in the ranked fix list, with AI-written JSON-LD fixes in the PDF.
BugViso does not test whether a thumbnail URL returns 200, whether duration is valid ISO 8601, or whether the video is the page's main content.
Use the Python inspector above for the first two and judge the third yourself. See the structured data and duplicate content checks feature page for the full list.
7. Common Implementation Traps & Edge Cases
Avoid these frequent engineering mistakes when deploying VideoObject structured data:
1. The Human-Readable Duration Mistake
A pervasive mistake is passing video duration in clock format rather than ISO 8601 duration syntax:
// ❌ Broken: Clock notation causes Google schema parsing failure
"duration": "08:45"
// ✅ Fixed: Compliant ISO 8601 duration notation (8 minutes, 45 seconds)
"duration": "PT8M45S"2. Blocking Thumbnails via robots.txt
If your thumbnail images are hosted on a dedicated CDN or media subdomain (e.g., media.example.com/thumbs/), ensure your robots.txt file does not disallow Googlebot-Image. If Google's image crawler cannot fetch the thumbnail asset, Google will discard the video rich snippet entirely.
For foundational guidance on structured data syntax, review schema markup for beginners.
8. Frequently Asked Questions
Why did video thumbnails disappear from my blog posts?
In September 2023, Google updated its search algorithm to show video thumbnails in main Google Web Search results only when the video is the "main content" of the page. If a video is embedded on a text-heavy blog post or product page as supplementary material, Google will not show a thumbnail in general search, though it may still appear in the dedicated "Videos" tab.
Can I markup YouTube or Vimeo embeds with VideoObject schema?
Yes. When embedding a YouTube or Vimeo video, provide the video's embed URL (e.g., https://www.youtube.com/embed/VIDEO_ID) in the embedUrl property and provide the YouTube thumbnail URL in thumbnailUrl.
What is the recommended aspect ratio for video thumbnails?
Google recommends providing thumbnail images in multiple aspect ratios (16:9, 4:3, and 1:1) to ensure optimal rendering across mobile, desktop, and Google Discover feeds.
Does VideoObject schema help with Google Discover inclusion?
Google has not said VideoObject schema affects Discover. Large, high-quality images are a general Discover recommendation, so provide a high-resolution thumbnail, but treat any Discover traffic as a bonus.
Do I still need an XML Video Sitemap if I use VideoObject schema?
While JSON-LD structured data is Google's preferred method for understanding video content, maintaining an XML Video Sitemap is recommended for large media sites with thousands of videos. It accelerates crawler discovery of newly published media assets.
9. Conclusion
Implementing compliant VideoObject schema for video thumbnails in search can make a video eligible for a thumbnail in search, but only when the video is the page's main content.
Follow Google's main-content guidance, provide a crawlable high-resolution thumbnail and format duration in ISO 8601. An automated BugViso scan checks the VideoObject markup across your domain.
Written by
Kazi Khalid Hasan Tamim · BugViso Team
Kazi writes BugViso’s guides on website audits, Core Web Vitals, technical SEO, accessibility and AI search. The data in them comes from audits BugViso runs in a real Chromium browser, including our 219-site study of website health.
Summarise with AI
Open this guide in your assistant.
Follow BugViso
New guides and audit data as we publish them.
AI visibility tracker
Is your brand in AI answers?
See how often AI assistants mention you, cite your site and rank you against your competitors.
- ChatGPT
- Gemini
- Perplexity
- Claude
- AI Overviews
See where your site stands
Run a free BugViso audit for SEO, speed, accessibility and AI search readiness — with fixes you can ship today.