Schema Markup·4 min read

VideoObject Schema Explained: Thumbnails and Key Moments

A video embedded on your page tells Google very little by itself. The player is an iframe, the file is a URL, and the crawler has no reliable way to know the title, length, or even that the video is the point of the page. VideoObject markup fixes that: it turns an anonymous embed into a described video, eligible for video results with thumbnails, durations and key moments. Below are the required fields, the date and duration formats, key moments, a worked example and the failures worth avoiding.

Open the free Video Schema Generator All insights

What VideoObject markup changes

The gap between embedding and describing.

The typical trigger is a content team publishing a product demo or tutorial and expecting it to show up the way video results do, with a thumbnail and a runtime. Weeks later the page appears as plain text. The difference between those two presentations is VideoObject markup: a JSON-LD block declaring the video's name, description, thumbnail, upload date and where the media lives.

With the block in place, Google can index the video itself rather than just the page around it. That opens video results with thumbnails and, when you add clip data, key moments that link to specific timestamps. One condition applies: the page must be a watch page, where the video is the main content. A video used as decoration on a page about something else won't be shown.

Thumbnails: the thumbnailUrl rules

The image is the feature.

The thumbnail is what most people want from this markup, and thumbnailUrl controls it. The image must be crawlable, at least 60x30 pixels though much larger works better, in a standard format like JPG, PNG or WebP, and it should represent the video rather than a generic brand card.

Blocked thumbnails fail silently. If robots.txt disallows your image path, the video is ineligible no matter how good the rest of the markup is, and nothing warns you except the Video indexing report in Search Console. Check the image URL loads publicly before shipping the block.

Required VideoObject fields, and the ISO 8601 trap

Three properties plus a format that bites.

Google requires name, thumbnailUrl and uploadDate, and recommends description, contentUrl, embedUrl, duration, a view count and key moments. uploadDate is where hand-written markup goes wrong, because Google wants ISO 8601 with time zone information, and 14/05/2026 or May 14, 2026 both fail quietly.

Duration has the same problem: it uses ISO 8601 duration syntax, PT8M13S for eight minutes thirteen seconds, and writing 8:13 gets ignored. The Video Schema Generator avoids both traps with separate date, time and time zone inputs plus hours, minutes and seconds fields, each showing a preview of the exact string it writes.

Auto-fill and key moments

Less typing, more detail.

Paste a YouTube or Vimeo link and press Auto-fill from video. For YouTube it reads the public page for the title, description, thumbnail, upload date, duration and view count, and builds the embed URL. Then set Watch page URL to the page on your own site that plays the video, because that is the page the markup describes.

Key moments come in two forms. Press Add clip for each chapter, with a name and start and end seconds; each clip URL is the watch page plus ?t= and the start second, so your page must honor that parameter. Or tick Use SeekToAction instead and Google picks the moments itself from your URL pattern. Use one approach, not both.

A worked VideoObject with thumbnailUrl and duration

One plumbing tutorial, fully described.

Take an eight-minute repair tutorial uploaded on the morning of May 14, 2026 from Pakistan. The essential fragment: {"@type": "VideoObject", "name": "Fixing a Leaky Trap", "thumbnailUrl": "https://example.com/trap.jpg", "uploadDate": "2026-05-14T09:30:00+05:00", "duration": "PT8M13S"}.

Notice what the two tricky values look like when correct: the upload date carries a full time and a +05:00 offset, and the duration reads PT8M13S rather than 8:13. Add a description, your page URL, and a contentUrl or embedUrl, and the block is complete. A view count, written as an interactionStatistic, and a publisher with a logo round it out.

VideoObject mistakes that block video results

Learned from indexing reports.

These are the errors behind most video indexing failures:

Neither contentUrl nor embedUrl provided, leaving Google with details about a video it can't fetch.
A thumbnail on a path that robots.txt blocks, which disqualifies the video silently.
uploadDate in a local format instead of ISO 8601, or with no time zone offset.
Marking up a page where the video is a decorative background rather than the main content.
Clip URLs that don't actually start the player at the given second.

Tips for VideoObject markup that keeps working

Beyond the first validation pass.

Keep the markup and the page in sync when videos get replaced; a swapped embed with a stale upload date and wrong duration makes everything else the page declares less credible. The view count doesn't refresh itself, so update it now and then. Use the Expiration fields only for content that disappears on a known date, like a webinar replay with a licensing window, because an expiry date removes the video from results on schedule.

If a video appears on several pages, mark it up on the main watch page and let the others link there. Each video should have a unique name and description on your site.

Video Schema Generator and the related tools

Matching markup to media.

Tutorial articles with an embedded video can carry two blocks: this one for the video and one from the Article Schema Generator for the text. Audio shows belong to the Podcast Schema Generator, which uses a MediaObject for the audio file.

For link previews on social platforms, the Open Graph Generator builds the og:image and og:video tags, which are a separate system from search structured data. To see what markup a watch page already outputs, run it through the Schema Markup Extractor.

Try it now

Open Video Schema Generator

The tool is one click away. No sign up, no upload, no payment.

Open Video Schema Generator

Write a review