Video VideoObject: Thumbnails, Key Moments, and Video Rich Results

Video structured data determines whether your videos can appear as thumbnail cards in Google Search, video tabs, and Google Discover, and even highlight "key moments" in results that let users jump to segments they care about. The core is simple: for each video actually embedded on your page, provide a clear name, thumbnail, and upload date, then supplement as needed with playable address, duration, and key moments.

What is VideoObject#

VideoObject describes a video on your page. Google uses it to generate video rich results: thumbnails, title, duration, upload date, and optional key moments and live badges. The prerequisite is that the page actually contains the video, and Google can fetch its thumbnail and playable address.

Official documentation: Google Search Central: Video (VideoObject) structured data.

Required and Recommended Fields#

Basic JSON-LD Example#

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "Understanding Structured Data in 5 Minutes",
  "description": "Explaining with one example how JSON-LD helps search engines understand pages.",
  "thumbnailUrl": [
    "https://example.com/thumbs/sd-1x1.jpg",
    "https://example.com/thumbs/sd-4x3.jpg",
    "https://example.com/thumbs/sd-16x9.jpg"
  ],
  "uploadDate": "2026-06-24T08:00:00+08:00",
  "duration": "PT5M12S",
  "contentUrl": "https://example.com/videos/structured-data.mp4",
  "embedUrl": "https://example.com/embed/structured-data"
}

contentUrl vs embedUrl#

Provide at least one, preferably both. Both must ensure they are not blocked by robots.txt, otherwise Google cannot confirm the video actually exists.

Key Moments#

Key moments let search results directly list segments within your video, where users can click to jump to the corresponding time point. Two implementation methods, choose one only:

Method 1: Clip — you define each segment yourself.

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "Structured Data Complete Workflow",
  "thumbnailUrl": "https://example.com/thumbs/full-16x9.jpg",
  "uploadDate": "2026-06-24T08:00:00+08:00",
  "duration": "PT12M",
  "contentUrl": "https://example.com/videos/full.mp4",
  "hasPart": [
    {
      "@type": "Clip",
      "name": "What is JSON-LD",
      "startOffset": 30,
      "endOffset": 180,
      "url": "https://example.com/watch?v=full&t=30"
    },
    {
      "@type": "Clip",
      "name": "How to Validate",
      "startOffset": 181,
      "url": "https://example.com/watch?v=full&t=181"
    }
  ]
}

Method 2: SeekToAction — tell Google your timestamp URL structure, and let it automatically identify key moments (often used in conjunction with chapter timestamps in video descriptions). Do not use both methods on the same video.

Live Broadcast Badge BroadcastEvent#

Live videos can obtain a "LIVE" badge by nesting publication (BroadcastEvent) within VideoObject,关键是 isLiveBroadcast set to true and providing startDate and endDate. Update these fields accordingly before, during, and after the live stream. Additionally, call the Indexing API to notify Google of live status changes.

Time and Date Formats#

• duration uses ISO 8601 duration: PT1M30S, PT2H5M;
• uploadDate, startDate, endDate use ISO 8601 date/date-time, timezone recommended, such as 2026-06-24T08:00:00+08:00;
• Do not write localized dates or omit timezone causing ambiguity.

Why This Site Doesn't Implement VideoObject#

This page is a text and image tutorial without embedded real videos. Marking VideoObject on a page without videos will be judged as marking non-existent content.

Validation and Monitoring#

1. Use Rich Results Test to check required fields.
2. Confirm thumbnailUrl, contentUrl/embedUrl are not blocked by robots.txt.
3. Verify name, description, and upload date are consistent with visible page content.
4. When using key moments, confirm Clip urls can jump to corresponding time points.
5. After launch, monitor invalid items in Search Console's video enhancement report; video sites should provide video sitemaps.

Common Mistakes#

VideoObject Launch Checklist#

• name, thumbnailUrl, uploadDate all present
• Provide one of contentUrl or embedUrl
• thumbnailUrl and video files not blocked by robots.txt
• duration uses ISO 8601 duration
• uploadDate uses ISO 8601 date-time with timezone
• Key moments use only one of Clip or SeekToAction
• Live uses BroadcastEvent with isLiveBroadcast=true
• Page actually embeds this video
• Rich Results Test shows no critical errors
• Consider video sitemap for large video libraries

Frequently Asked Questions#

Which fields are required for VideoObject?

Google's required fields for VideoObject are name, thumbnailUrl, and uploadDate. To make videos playable and better understood, it's strongly recommended to supplement with one of contentUrl or embedUrl, duration, and description. Without thumbnails or upload date, video rich results typically cannot be generated.

What is the difference between contentUrl and embedUrl?

contentUrl points to the original video file (such as .mp4), while embedUrl points to an embeddable player address (such as an iframe player page). Google recommends providing at least one of them, preferably both. Ensure Googlebot can access these addresses without being blocked by robots.txt or login walls.

How do I mark key moments?

There are two approaches: first, use Clip to explicitly label each segment's name, startOffset, and url; second, use SeekToAction to tell Google your URL timestamp structure so it can automatically identify key moments. Choose one approach only, do not duplicate. The url must include parameters that enable jumping to the corresponding time point.

How do I format duration?

duration uses ISO 8601 duration format, for example PT1M30S means 1 minute 30 seconds, PT2H5M means 2 hours 5 minutes. uploadDate, startDate and other dates use ISO 8601 date or date-time with timezone format, do not write in localized strings.