Schema Markup·3 min read

VideoObject Schema Explained: Thumbnails and Duration

A video embedded on your page tells Google almost nothing 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 a video is the point of the page. This is VideoObject schema explained from that problem outward: the markup that turns an anonymous embed into a described video, eligible for thumbnails in search, duration badges, and key moments. Below are the required fields, a worked example, and the failure modes worth avoiding.

Open the tool All insights

VideoObject schema explained: what the markup actually 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 YouTube results do, with a thumbnail and a runtime. Weeks later the page ranks 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 location of the actual media.

With the block in place, Google can index the video itself rather than just the page around it. That opens the video tab, thumbnail treatments in main results, and, when you go further with clip data, the key moments feature that deep-links into specific timestamps.

Video thumbnails in search: the thumbnailUrl rules

The image is the feature.

Video thumbnails in search are what people actually want from this markup, and the thumbnailUrl property controls them. The requirements are concrete: the image must be crawlable, at least 60x30 pixels though substantially larger performs better, in a standard format like JPG, PNG, or WebP, and it must represent the video rather than a generic brand card.

Blocked thumbnails are a silent killer. If robots.txt disallows your image CDN path, the video is ineligible no matter how perfect the rest of the markup is, and nothing warns you except the video indexing report in Search Console. Check the image URL resolves publicly before shipping the block.

The required VideoObject fields, and the ISO 8601 trap

Four properties plus a format that bites.

The required VideoObject fields are name, description, thumbnailUrl, and uploadDate. The first three are straightforward. uploadDate is where hand-written markup goes wrong, because Google wants ISO 8601 with timezone information, and 14/05/2026 or May 14, 2026 both fail quietly.

Duration has the same flavor of problem: it uses ISO 8601 duration syntax, PT8M13S for eight minutes thirteen seconds, and writing 8:13 gets ignored. The VideoObject Schema Generator sidesteps both traps with separate date, time, and timezone inputs plus an H/M/S duration builder, each showing a live preview of the exact string being emitted.

VideoObject mistakes that break video rich results

Learned from indexing reports.

These are the errors that dominate video indexing failures:

Neither contentUrl nor embedUrl provided, leaving Google with metadata about a video it can't fetch.
A thumbnail hosted on a path that robots.txt blocks, which disqualifies the video silently.
uploadDate in a local format instead of ISO 8601, or with no timezone offset at all.
Marking up a page where the video is a decorative background rather than the main content, which Google explicitly ignores.
Duration written as minutes and seconds with a colon instead of the PT format.

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. An optional publisher node with a logo rounds it out for brands that want attribution.

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 uploadDate and wrong duration erodes trust in everything else the domain declares. Use the expires property only for content that genuinely disappears, like webinar replays with a licensing window, because an accidental expiration removes the video from results on schedule.

If a video appears on several pages, mark it up on the canonical watch page and let the others link there, since duplicate VideoObject blocks with diverging metadata confuse extraction.

VideoObject Schema Generator and the related tools

Matching markup to media.

Tutorial articles with an embedded video usually deserve two blocks: this one for the video and one from the Article Schema Generator for the text. Audio-first shows belong to the Podcast Schema Generator, which uses MediaObject for the audio file rather than VideoObject.

For the social side of video sharing, the Open Graph Generator builds the og:image and og:video tags that control link previews, a separate system from search structured data. And the Schema Markup Generator remains the general fallback when a page needs types beyond video.

Try it now

Open VideoObject Schema Generator

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

Open VideoObject Schema Generator

Write a review