Video Schema Markup: A Working VideoObject Example and the Rules That Decide Rich Results

Most video markup on the web is wasted. Not wrong, exactly, just pointless: a VideoObject block wrapped around a YouTube embed on a page where the video is an afterthought, describing a file Google cannot fetch, pointing at a thumbnail behind a redirect. The markup validates, the site owner checks the box, and the rich result never arrives. This page walks through the version that works: the complete field set, a copy-ready example, what disqualifies pages in practice, and the honest arithmetic of self-hosting versus YouTube.

What video schema markup actually does

VideoObject markup describes a video to crawlers in machine-readable terms: what it is called, what it covers, how long it runs, when it was published, where the file lives, and what frame represents it. Google's video structured data documentation lists the payoff: eligibility for the video rich result (thumbnail plus duration badge in blue-link results), placement in the dedicated Video search tab, and key-moment links that jump viewers to a timestamp.

Eligibility is the operative word. Markup does not rank the video; it makes an already-indexed, already-relevant video legible enough for enhanced display. Google can find videos without it, but leaves the metadata to guesswork: it might pick a bad thumbnail, misread the duration, or skip the video tab entirely. The markup replaces guesswork with declaration. In the 12 Vectors framework we run every engagement on, this sits squarely in Vector 6, Structure: schema that machines read with high confidence.

The four properties Google checks first

Google's requirements are shorter than most guides make them sound. Four things decide basic eligibility:

• name: the title of the video, not the page.
• thumbnailUrl: one or more still images, at least 1200 px wide for full eligibility, fetchable by Googlebot without login or redirect.
• uploadDate: ISO 8601, ideally with a timezone.
• contentUrl or embedUrl: a direct path to the video file, or the address of the embeddable player. Providing both is stronger than either alone.

description and duration are officially "recommended", and treating them as optional is a mistake. The description feeds snippet text and helps AI surfaces summarize the video; the duration feeds the badge that makes the listing look like a video at a glance. Every VideoObject we ship carries all seven fields.

A complete, valid VideoObject example

The block below passes the Rich Results Test as written. Swap the values, keep the shape:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to Winterize a Backyard Ice Rink",
  "description": "Step-by-step walkthrough of draining, lining, and boarding a backyard rink before the first hard frost, filmed in Brantford, Ontario.",
  "thumbnailUrl": [
    "https://example.ca/videos/rink-winterize/thumb-16x9.jpg",
    "https://example.ca/videos/rink-winterize/thumb-4x3.jpg"
  ],
  "uploadDate": "2026-07-19T09:00:00-04:00",
  "duration": "PT6M42S",
  "contentUrl": "https://example.ca/videos/rink-winterize/rink-winterize-1080p.mp4",
  "embedUrl": "https://example.ca/videos/rink-winterize/player.html"
}
</script>

Three details in that example carry more weight than they look like they do. The duration uses ISO 8601 form, PT6M42S for six minutes forty-two seconds; writing "6:42" invalidates the field. The thumbnailUrl is an array, letting Google pick an aspect ratio per surface. And the uploadDate carries a timezone offset, which Google specifically recommends so the date does not shift a day when interpreted in UTC. If the placement mechanics are new to you, our walkthrough on how to add schema markup covers where the script tag goes and how to test it.

Standalone block or a property of Article schema?

One decision trips up more implementations than any syntax error: does the video get its own VideoObject block, or does it ride inside the page's existing schema? The rule of thumb the documentation supports is about primacy. When the video is the main reason the page exists, a watch page or a video landing page, VideoObject stands alone as its own entity. When the video supports written content, an explainer embedded halfway down a long article, attach the VideoObject as the video property of the Article or BlogPosting schema instead of floating a second competing entity.

The distinction matters because Google reads a page's structured data as one connected graph, and two unconnected top-level entities describing the same content dilute each other. We covered the same graph logic from the article side in our article schema example; the video case is the same principle with a different node type.

Key moments: Clip versus SeekToAction

The key-moments feature, those chapter links under a video result, comes in two flavours, and they answer different questions. Clip markup is manual: you declare each segment with a startOffset, endOffset, name, and a URL that jumps to the timestamp. Use it when the segment boundaries are editorial decisions, like steps in a how-to. SeekToAction is delegated: you tell Google how your URLs express a timestamp (a t={seek_to_second_number} pattern) and Google's systems pick the moments themselves. Search Engine Land's launch coverage from June 2021 is still the clearest account of the split.

Two constraints worth knowing before you invest the effort. Key-moment markup applies to videos you host and control; for YouTube-hosted videos, chapters come from timestamps in the YouTube description, not from your schema. And the feature only pays off on longer videos where mid-roll navigation is genuinely useful. A 45-second clip with five declared moments reads as markup for markup's sake.

Self-hosted versus YouTube: the trade nobody prices out

This is the part most guides soften because the honest version is inconvenient. If a video lives on YouTube and is embedded on your service page, the probable winner of the video rich result is YouTube. That is not automatically bad: a business whose strategy is channel-first may want exactly that. But a business that paid for a testimonial video to strengthen its own service page should know the embed hands the search asset to a domain it does not own. The middle path we use with clients: host the conversion-critical videos (testimonials, service explainers) on the client's own domain with full VideoObject markup, and keep YouTube for reach content where the platform's audience is the point.

The disqualifiers: how valid markup still earns nothing

Passing the Rich Results Test is necessary, not sufficient. These are the failure modes that show up in Search Console's video indexing report after the markup itself validates:

The pattern across all six: the markup made a promise the site did not keep. Structured data is a claim about the page, and Google verifies claims. That is also why we treat schema work as an engineering discipline rather than a plugin checkbox; the same verification logic applies to product schema on e-commerce sites, where an out-of-sync price does the same silent damage a dead contentUrl does here.

Who actually benefits from video schema markup

The honest answer: fewer businesses than the tutorials imply, and those that do, benefit a lot. The markup earns its keep when three things line up: you host or control the video, the video is prominent on a page you want ranking, and the query space shows video results. That combination describes:

• Trades and how-to publishers. "How to" queries trigger video results constantly, and a self-hosted walkthrough with Clip markup can own moments a YouTube competitor cannot claim on your page.
• Service businesses with testimonial and process footage. A prominent, marked-up video on a service page differentiates the listing in results where every competitor shows the same blue link.
• Course sellers and gated-content publishers. VideoObject supports properties for subscription content, so previews can appear in search while the full video stays paid.
• Local businesses in visual trades. Renovation reveals, detailing results, landscaping transformations: queries where a thumbnail in the results does the selling.

And who should skip it: sites whose only video presence is a channel-hosted embed repeated site-wide, and pages where the video is decoration. Marking those up costs maintenance and earns nothing, which is worse than neutral because stale schema erodes trust in the rest of your graph.

What video markup means for AI search surfaces

A qualifier before the claim: Google's own AI-features documentation states that structured data is not required for generative surfaces, so nobody should sell VideoObject as an AI-visibility switch. What the markup does provide is clean, attributed metadata at the moment AI systems assemble multimodal answers, and multimodal is where these surfaces are heading. An AI Overview that includes a video needs a title, a duration, and a source to attribute; a declared VideoObject supplies all three without inference. The Princeton GEO research (Aggarwal et al., 2023) found that clear statistics and citable structure raise citation probability across generative engines, and the same legibility principle applies to media: content that machines can describe accurately gets used more confidently than content they have to guess at.

Our position, stated plainly: markup is one input among several, the video's actual visibility on a fast, crawlable page matters more, and anyone promising AI placement from a JSON block alone is selling something the documentation contradicts.

Implementation order that avoids rework

The sequence we run, condensed:

1. Decide hosting per video: own domain for conversion assets, YouTube for reach assets. This decision precedes any markup.
2. Generate real thumbnails, 1200 px or wider, on stable URLs Googlebot can fetch directly.
3. Write the VideoObject with all seven core fields; nest it under Article schema when the video supports written content.
4. Confirm robots.txt allows the media paths, then validate in the Rich Results Test.
5. Request recrawl via URL inspection and monitor the video indexing report over the following month.

Practitioner reporting through 2026 puts the typical wait at two to four weeks between recrawl and visible rich results, so judge the work on a monthly cycle, not a daily one. What we tell clients up front: the markup itself is an afternoon of careful work, the hosting decision behind it can reshape a content plan, and the payoff arrives on Google's schedule rather than yours. What video markup earns varies with your niche, your competition, and how much video you actually publish.