Video Schema

Video schema is structured data, using the schema.org VideoObject type, that describes a video on a web page to search engines. It tells Google the video’s title, description, thumbnail, upload date and other details, helping it index the video and show it in video results and features such as key moments.

Written by Paul Hoda, SEO consultant since 2005. Last updated 8 November 2026.

How video schema works

Video schema is a form of schema markup. You add it to the page that hosts the video, usually as JSON-LD in the page code. Google can sometimes detect videos without it, but structured data removes guesswork and gives Google details it might not otherwise find, such as the exact upload date or the file location.

Structured data must describe what is actually on the page. If the markup says a page has a video but users cannot find or play it, Google may ignore the markup or treat it as misleading. Each video should also be reachable at a stable URL that Google can crawl.

Required and recommended properties

Google’s documentation lists three required properties for VideoObject:

  • name: the title of the video.
  • thumbnailUrl: a URL for a thumbnail image that Google can crawl.
  • uploadDate: when the video was first published.

Recommended properties include description, duration, contentUrl (the video file itself), embedUrl (the player URL), expires for videos that will be removed, and interactionStatistic for view counts.

Key moments and live videos

Video schema can also unlock extra features:

  • Clip: mark up named segments with start and end times so Google can show them as key moments.
  • SeekToAction: tell Google how your URLs link to a timestamp, so it can identify key moments automatically.
  • BroadcastEvent: mark a livestream so it can show a LIVE badge.

On YouTube, chapters in the description do a similar job for key moments.

Key moments do not appear for every video or search. Google decides when to show them, and it can also identify segments automatically. Markup gives you more control over the labels and timings Google uses.

How to add and test video schema

  1. Choose one main video per page and make sure it is the page’s main content.
  2. Add VideoObject JSON-LD with at least the required properties, matching what users see.
  3. Include contentUrl or embedUrl so Google can fetch the video.
  4. Test the page with the Rich Results Test to catch errors.
  5. Monitor the Video pages report in Search Console after publishing.
  6. Consider a video sitemap as well, especially for large video libraries.

Common mistakes

  • Using a thumbnail URL blocked by robots.txt or behind a login.
  • Adding markup for a video that is not actually visible on the page.
  • Marking up the same video on many unrelated pages.
  • Leaving out the time zone in uploadDate, which Google recommends including.
  • Expecting schema alone to guarantee rich results: Google decides whether to show them.

Further reading: Google’s video structured data documentation.

Key Takeaways

  • Video schema uses the schema.org VideoObject type, usually written in JSON-LD.
  • Google requires name, thumbnailUrl and uploadDate.
  • Clip and SeekToAction markup can enable key moments.
  • Markup must describe a video that users can actually see on the page.
  • Test with the Rich Results Test and monitor the Video pages report.

Related Terms

Wondering what to fix first on your site? Get a free check of your site’s SEO, or keep learning in the SEO Encyclopedia.