Video Schema (VideoObject JSON-LD): The Complete How-To Guide
Understand with AI
Discuss with your preferred AI assistant
Listings with a video thumbnail and duration badge attract more clicks than plain text results.
name, description, thumbnailUrl, and uploadDate are the must-have VideoObject properties.
This generator builds valid VideoObject JSON-LD instantly — no signup, no API calls.
Video is one of the few content types Google rewards with a dedicated visual treatment in search. A thumbnail, a duration badge, and even clip-level "Key moments" can lift your click-through rate dramatically — but only if Google can confidently understand what your video is about. That understanding comes from VideoObject schema, a small block of structured data you add to the page.
This guide explains what VideoObject schema is, which properties Google actually requires, how to format the tricky fields (especially duration and dates), and how to validate and ship your markup so it qualifies for video rich results.
What Is VideoObject Schema?
VideoObject is a schema.org type that describes a video in machine-readable JSON-LD. You embed it inside a <script type="application/ld+json"> tag on the page where the video lives. Search engines read it to populate the video box in results, the Videos tab, Google Images, and Discover.
Crucially, schema does not replace the video itself — it describes a video that is already embedded or hosted on the page. The markup and the visible video must match, or Google may ignore the structured data entirely.
Required and Recommended Properties
Google has a short list of properties it treats as required for video rich results, plus several it strongly recommends. Get the required ones right first.
| Property | Status | What it is |
|---|---|---|
| name | Required | The title of the video. |
| description | Required | A plain-text summary of the video. |
| thumbnailUrl | Required | One or more high-resolution thumbnail image URLs. |
| uploadDate | Required | The date the video was first published, in ISO 8601. |
| duration | Recommended | Runtime as an ISO 8601 duration, e.g. PT12M45S. |
| contentUrl | Recommended | A direct link to the raw video file (.mp4, etc.). |
| embedUrl | Recommended | The URL of the player (e.g. a YouTube embed). |
Provide at least one of contentUrl or embedUrl — Google needs a way to actually fetch or play the video. Including both is best.
How to Format the Tricky Fields
Duration must be ISO 8601
The single most common mistake is writing the duration the way it appears on a player ("12:45") instead of the ISO 8601 format Google requires: PT12M45S. The prefix is PT (period of time), then hours (H), minutes (M), and seconds (S). So a 1-hour-2-minute-30-second video is PT1H2M30S. This tool accepts either format and converts mm:ss to ISO 8601 for you automatically.
Dates must be ISO 8601 too
uploadDate, expires, and any broadcast start or end times should be ISO 8601 dates (2026-05-12) or full timestamps (2026-05-12T09:30:00+00:00). A date-only value is fine for uploadDate; a precise timestamp is better for live broadcasts.
Thumbnails should be large and 16:9
Google recommends thumbnails at least 1200px wide, in a 16:9 aspect ratio, and publicly crawlable. You can supply several sizes — list each URL on its own line and the tool emits them as an array, so Google can pick the best one for each surface.
Going Further: Key Moments, Live, and Engagement
Once the basics are solid, three optional enhancements can win extra real estate:
- Key moments — a SeekToAction tells Google your page exposes chapter timestamps, enabling the clickable "Key moments" links beneath your result. You still need real timestamps in the description or via the Clip markup.
- Live video — a BroadcastEvent with isLiveBroadcast marks a stream as live or previously live, and a future startDate can earn the red "LIVE" badge.
- Engagement — an interactionStatistic with a WatchAction view count signals popularity. It is optional but cheap to include.
How to Add and Validate the Markup
- Generate your JSON-LD with the tool above and copy the <script> tag.
- Paste it into the <head> or <body> of the page that hosts the video — one VideoObject per video on the page.
- Run the page through Google's Rich Results Test to confirm it is eligible and error-free.
- Submit or re-crawl the URL in Search Console, then watch the Videos report for impressions.
Keep the markup in sync with the page: if the title, thumbnail, or duration changes, update the schema. Mismatches are the fastest way to lose your rich result.
Common Mistakes to Avoid
- Writing duration as "12:45" instead of PT12M45S.
- Marking up a video that is not actually visible and playable on the page.
- Using a tiny or non-crawlable thumbnail image.
- Omitting both contentUrl and embedUrl, leaving Google no way to access the video.
- Forgetting to update the schema when you re-edit or replace the video.
Expert Tips
Always use ISO 8601 duration
Convert your runtime to the PT#M#S format Google requires — 12:45 becomes PT12M45S. A wrong duration silently drops the runtime badge from your result.
Validate before you ship
Paste the snippet into Google’s Rich Results Test before publishing. Confirm zero errors and that the video is actually visible and playable on the same page.
Frequently Asked Questions
Is VideoObject schema required to rank videos?
It is not strictly required to appear in search, but it is required to be eligible for video rich results — the thumbnail, duration badge, and Key moments. Without it, Google has to infer everything, which usually means a plainer, lower-CTR listing.
What format does the duration need to be?
ISO 8601 duration format, which looks like PT#H#M#S. For example, PT45S is 45 seconds, PT12M45S is 12 minutes 45 seconds, and PT1H2M30S is one hour, two minutes, thirty seconds. This generator converts mm:ss or hh:mm:ss input to that format for you.
Do I need both contentUrl and embedUrl?
You need at least one. contentUrl points to the raw video file and embedUrl points to the player page. Providing both gives Google the most flexibility, so include both whenever you can.
Where do I put the JSON-LD on the page?
Inside a <script type="application/ld+json"> block, on the same page that hosts the visible, playable video. It can go in the <head> or <body>; both are valid. Use one VideoObject block per video.