Video is one of the most engaging formats in search, and Google gives video results their own thumbnails, durations and even clickable “key moments”. To be eligible for those features, your video pages need video schema, structured data that describes the video to search engines. Without it, Google may not realise your page hosts a video at all. This guide explains what video schema is, the properties Google requires, and how to add it correctly.
What video schema is
Video schema is structured data (usually JSON-LD) using Schema.org’s VideoObject type. It describes a video embedded on a page: its title, description, thumbnail, upload date, duration, and where the actual video file or stream lives. When Google reads valid video markup, your page becomes eligible for video rich results, the thumbnail-led listings and the Video tab, and potentially enhanced features like key moments.
The properties that matter
Several properties are required for eligibility:
| Property | Role |
|---|---|
| name | The video’s title (required) |
| description | What the video is about (required) |
| thumbnailUrl | Thumbnail image (required) |
| uploadDate | When it was published (required) |
| duration | Length, in ISO 8601 format |
| contentUrl / embedUrl | The video file or player URL |
The four required properties, name, description, thumbnail and upload date, are the minimum; adding duration and a content or embed URL strengthens eligibility.
Key moments and chapters
One of the more useful video features is “key moments”, the clickable timestamps that let searchers jump to a specific part of your video right from the results. You can enable these by marking up chapters with the hasPart property (using Clip objects with start times), or in some cases Google detects them automatically from a clearly timestamped description. Key moments make your listing more useful and can lift clicks, because a searcher sees your video answers their exact sub-question. If your video is long or covers several topics, adding clip markup is a worthwhile step, just make sure the timestamps and labels genuinely match the video’s content.
Host the video so Google can verify it
A subtle but important point: for video rich results, Google needs to be able to access and verify the actual video, not just your markup. That means the video file or stream referenced in contentUrl/embedUrl must be reachable (not blocked from crawling), the thumbnail must be a valid, accessible image, and the markup must describe a video that is genuinely present and prominent on the page. Marking up a video that is hidden, tiny, or not actually the page’s main content goes against Google’s guidelines. If you host on a platform like YouTube and embed, make sure the embed and its details line up with your schema. The rule, as ever, is that the markup must reflect a real, accessible, visible video.
Why it is worth doing
Video rich results are visually dominant, a thumbnail draws the eye far more than a text link, and eligibility for the Video tab and key moments opens extra surfaces where your content can appear. For anyone investing in video, schema is what makes that investment visible in search rather than hidden inside a page Google reads as plain text. It also helps search engines and AI systems understand that your page offers video, which matters as results diversify across formats.
Generate and validate your video schema
Building VideoObject JSON-LD with correctly formatted dates and durations is fiddly by hand. Our free video schema generator creates valid markup from your video details, ready to paste into the page. Always confirm it parses with our schema validator. For the fundamentals of structured data, see our guide to what schema markup is.
The takeaway
Video schema tells Google your page hosts a video and makes it eligible for thumbnail-led rich results, the Video tab, and clickable key moments. Include the required name, description, thumbnailUrl and uploadDate, add duration and a content or embed URL, and make sure the video is real, accessible and prominent on the page. Generate valid markup with our video schema generator, validate it with the schema validator, and explore the rest of our free SEO tools.
