VideoObject Schema

Element Code: RI-014

What VideoObject schema actually does

When Googlebot hits a page with an embedded video, it sees a player iframe or a video tag and not much else. It has to work out the title, the thumbnail, how long the video runs, and whether the video is the point of the page or just a garnish. VideoObject schema removes the guesswork. It is a schema.org type, usually delivered as a JSON-LD block in the head or body, that hands Google that metadata directly.

I treat it as non-negotiable on any page where video carries real weight: product demos, tutorials, webinars, video-first blog posts. Google states in its video structured data documentation that VideoObject markup makes videos eligible for the video badge in mobile results, key moments, and inclusion in dedicated video surfaces like the Videos tab. No markup means Google may still index the video, but you are betting on its extraction instead of stating the facts yourself.

Why this matters for rankings and visibility

Three concrete reasons, in the order I care about them.

1. Eligibility for video results. Video thumbnails and video-tab visibility drive clicks that plain blue links do not. Since a 2023 change Google documented, video thumbnails in main search results only show when the video is the primary content of the page, which makes accurate markup on your genuinely video-led pages even more valuable: those are now the only pages that get the treatment.

2. Cleaner video indexing. Search Console has a dedicated video indexing report. Pages that embed video without machine-readable metadata are where I most often see "Google could not determine the prominent video" style problems. Markup with a proper contentUrl or embedUrl gives Google a direct line to the file.

3. Key moments. With Clip markup or SeekToAction inside your VideoObject, Google can deep-link into timestamps. For long tutorials this is a genuine CTR lever, and almost nobody in mid-sized niches bothers, which is exactly why you should.

Required and recommended properties

Google splits properties into required and recommended. Miss a required one and the whole block is ineligible.

How the pieces fit together

How to implement it

Use JSON-LD. Google accepts microdata, but JSON-LD stays out of your template markup and survives redesigns. A minimal working block looks like this:

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to Fix Redirect Chains in 15 Minutes",
  "description": "A walkthrough of finding and flattening redirect chains.",
  "thumbnailUrl": "https://example.com/thumbs/redirect-chains.jpg",
  "uploadDate": "2026-05-14T08:00:00+00:00",
  "duration": "PT7M32S",
  "embedUrl": "https://www.youtube.com/embed/VIDEO_ID"
}

Placement rules that save you pain: one VideoObject per video, on the page where the video actually appears, and the marked-up video must be visible to users on that page. Marking up a video that is not on the page violates Google's structured data guidelines and can earn a manual action for spammy structured markup. If you run WordPress, most SEO plugins (Yoast Video, Rank Math) generate this for recognized embeds, but verify their output instead of trusting it. I have seen plugins emit uploadDate as the post date years after the video went live.

How to detect missing or broken VideoObject markup

1. Rich Results Test on your key video pages. It flags missing required properties and warns on recommended ones.
2. Screaming Frog with structured data extraction enabled (Config, Spider, Extraction, tick JSON-LD plus Schema.org validation). Crawl the site, filter the Structured Data tab for pages containing video embeds but no VideoObject. A custom search for "youtube.com/embed" cross-referenced against the schema report finds the gap pages fast.
3. Search Console: the Video indexing report shows which video pages Google found and where it failed, and the Videos enhancement report lists invalid VideoObject items with the exact property errors.
4. Schema Markup Validator at validator.schema.org for pure syntax checking when Google's tool is being flaky.

DO vs DON'T

FAQ