Video schema: required vs recommended properties
Google requires three properties for a video — a name, a thumbnail and an upload date — and recommends a description, content and embed URLs, duration, expiry, view counts and clips for key moments.
| Property | Status | Format | Notes |
|---|---|---|---|
| Video title | Required | Text | |
| Thumbnail URLs | Required | List | One URL per line. The thumbnail must be crawlable and indexable. |
| Upload date | Required | Date and time, ISO 8601 | |
| Description | Recommended | Text | Unique for each video. |
| Video file URL | Recommended | URL | The actual video file. |
| Embed player URL | Recommended | URL | A player for the video, not the page it is on. |
| Duration | Recommended | Duration, ISO 8601 | |
| Expiry date | Optional | Date and time, ISO 8601 | If the video will stop being available. |
| View count | Optional | Number | Total views, as an integer. |
| This is a livestream | Optional | Yes / no | |
| Livestream start | Optional | Date and time, ISO 8601 | For a livestream. |
| Livestream end | Optional | Date and time, ISO 8601 | |
| Key moments (clips) | Optional | Repeated group | Optional. Lets Google show key moments. |
| Key moments (clips) › Label | Optional | Text | |
| Key moments (clips) › Starts at (seconds) | Optional | Number | |
| Key moments (clips) › Ends at (seconds) | Optional | Number | |
| Key moments (clips) › Link to this moment | Optional | URL |
Is VideoObject markup eligible for a Google rich result?
VideoObject markup can make a video eligible for video rich results, key moments and a LIVE badge for livestreams. Google requires a name, a thumbnail and an upload date.
Status verified on 24 September 2026. Google’s documentation: https://developers.google.com/search/docs/appearance/structured-data/video
About Video structured data
A video can appear in Google’s results with a thumbnail and duration, in the dedicated Videos results, and, with clips or a table of contents, with key moments that jump to a point in the video. VideoObject markup is how you describe the video to Google when it cannot work it out from the page alone.
For a livestream, adding a BroadcastEvent with isLiveBroadcast and the start and end time makes the video eligible for a LIVE badge. The generator adds this when you tick the livestream box.
Common Video schema mistakes
- Pointing embedUrl at the page the video lives on. It must be the URL of a player for the video, such as the embed address.
- A thumbnail that Google cannot crawl or index, for instance one blocked by robots.txt or behind a login.
- Reusing the same title and description for every video on the site. Each video needs its own unique text.
- A duration in plain text. Use an ISO 8601 duration such as PT4M30S for four and a half minutes.
- An upload date that is a date only, with no time zone. Give the date and time with an offset.
- Key-moment clips whose start and end times are in minutes instead of seconds, or that overlap the wrong part of the video.
Video schema example
A four-and-a-half-minute video with a file and embed URL, a view count and two key moments, as generated on this page, is shown below.
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "How to repot a houseplant",
"description": "A four-minute walkthrough of repotting a root-bound houseplant.",
"thumbnailUrl": "https://example.com/img/repot-thumb.jpg",
"uploadDate": "2026-05-02T08:00:00+05:00",
"contentUrl": "https://example.com/media/repotting.mp4",
"embedUrl": "https://example.com/embed/repotting",
"duration": "PT4M30S",
"interactionStatistic": {
"@type": "InteractionCounter",
"userInteractionCount": 12450
},
"hasPart": [
{
"@type": "Clip",
"name": "Loosening the roots",
"startOffset": 65,
"endOffset": 120,
"url": "https://example.com/video/repotting?t=65"
},
{
"@type": "Clip",
"name": "Potting it up",
"startOffset": 120,
"endOffset": 210,
"url": "https://example.com/video/repotting?t=120"
}
]
}How to use it
- Fill in the video details — the form marks each field Required, Recommended or Optional.
- Watch the JSON-LD and the validation list update as you type.
- Copy the JSON-LD, the HTML script tag or the Next.js snippet, or download the .json file.
- Paste it into your page, then check it with Google’s Rich Results Test.
Frequently asked questions
Which properties are required for VideoObject?
A name, a thumbnail URL and an upload date. Description, content URL, embed URL, duration, expiry, interaction statistics and clips are recommended.
What is the difference between contentUrl and embedUrl?
contentUrl points at the actual video file. embedUrl points at a player for the video. Provide whichever you have; both are recommended.
How do I write the duration?
As an ISO 8601 duration: PT30S for thirty seconds, PT4M30S for four and a half minutes, PT1H2M for an hour and two minutes.
How do I get key moments?
Add Clip entries with a label, a start and end offset in seconds and a URL that jumps to that moment. Google may also detect key moments on its own.
How do I mark up a livestream?
Tick the livestream option and give the start and end times. The generator adds a BroadcastEvent so that Google can show a LIVE badge.
Valid markup makes a page eligible for a rich result; it does not guarantee one. Google decides what to show. Test your page with Google’s Rich Results Test before relying on it.