Video schema markup: the implementation guide

TL;DR: VideoObject structured data needs three required properties (name, thumbnailUrl, uploadDate) to qualify for Google’s video rich results, and five more recommended ones (description, duration, contentUrl, embedUrl, interactionStatistic) to compete for video carousels, key moments, and the LIVE badge. Add Clip or SeekToAction for timestamp navigation, BroadcastEvent for livestreams, and validate every template with the Rich Results Test before you ship it site-wide.

---

Table of contents

1. What video schema markup actually does
2. The three required VideoObject properties
3. The five properties that win you more real estate
4. Full JSON-LD example for a blog post with an embedded video
5. Key moments: Clip and SeekToAction markup
6. The LIVE badge: BroadcastEvent for livestreams
7. Thumbnail requirements Google actually enforces
8. Video schema vs video sitemaps: do you need both
9. YouTube embeds vs self-hosted video: what changes in your markup
10. Validating your markup before you ship it
11. Seven mistakes that quietly break video rich results
12. Measuring whether it worked
13. Frequently asked questions
14. Key takeaways

---

What video schema markup actually does

VideoObject is a schema.org type that inherits from MediaObject and CreativeWork, and it is the single most widely deployed video vocabulary on the web: Google’s own documentation shows it in use on 1M to 10M domains, based on monthly aggregations of Google’s web index as of July 2026. That scale is not an accident. It is the only markup that qualifies a page for Google’s video-specific rich results: placement in the main results page video block, Video mode, Google Images, and Google Discover, according to Google’s video structured data documentation.

Here is what it does not do: it does not rank your page higher for a text query, and it does not guarantee a rich result even when the markup validates. Google states this directly in its structured data general guidelines: “Google does not guarantee that your structured data will show up in search results, even if your page is marked up correctly.” What VideoObject does is make your video eligible to compete for video-specific surfaces that text-only pages cannot reach at all: video carousels, key moments navigation, and the LIVE badge on livestreams.

The business case is straightforward once you see the demand side. In the 2026 State of Video Marketing report, Wyzowl found that 91% of businesses now use video as a marketing tool and 96% of consumers say they have watched an explainer video to learn about a product or service. That volume of video content competing for the same SERP real estate is exactly why the markup matters: without it, your video is just an embed Google has to infer metadata for. With it, you are handing Google the exact title, thumbnail, duration, and upload date it needs to decide whether your video earns a carousel slot.

This guide covers the required and recommended properties, full JSON-LD you can adapt directly, key moments and live badge markup, thumbnail specs, the sitemap-vs-schema question, and the validation workflow. Every code block below is built from Google’s published schema, not guessed. If you’re building out a full schema markup implementation across page types, treat this as the video-specific module of that broader project.

The three required VideoObject properties

Google will not consider a page for video rich results without these three properties present and valid. Miss one and the Rich Results Test flags an error, not a warning.

name is the video’s title. Google’s guidance is explicit that this needs to be unique per video: “Make sure to use unique text in the name property for each video on your site,” per the structured data documentation. Duplicate titles across a video library is one of the most common reasons a large video catalog underperforms in search, because Google cannot tell which page is the canonical destination for a given title.

thumbnailUrl is a URL pointing to the video’s unique preview image. This has to follow Google’s thumbnail guidelines, covered in detail below, and it needs to resolve to a stable, crawlable URL. A thumbnail that 404s after a CDN migration silently drops the video from eligibility.

uploadDate is the date and time the video was first published, in ISO 8601 format (for example 2026-08-02T09:00:00-07:00). This is not the date you last edited the page. Backdating or refreshing this value to make old content look fresh is a form of the misleading-markup violation Google’s spam policies prohibit.

Those three alone get you into consideration for the basic video result. They do not get you a carousel, key moments, or the LIVE badge. For those you need the recommended properties below.

The five properties that win you more real estate

Google’s own documentation lists these as recommended, meaning omitting them will not throw an error, but it does cap what surfaces your video can qualify for.

Property	Format	What it enables	Required for
description	Plain text, unique per video	Snippet text under the thumbnail	Carousel eligibility
duration	ISO 8601 (PT00H30M5S = 30 min 5 sec)	Duration badge on the thumbnail	Carousel eligibility
contentUrl	Direct URL to the video file	Preferred playback path Google indexes first	Video mode indexing
embedUrl	URL of the video player	Fallback playback path	Video mode indexing
interactionStatistic	InteractionCounter with view count	View count display	Trust signal, not gating

contentUrl is preferred over embedUrl when both are available, because a direct file URL lets Google verify the content matches your markup without loading a player. If you only have an embed (YouTube, Vimeo, Wistia), embedUrl is the correct field, and you should not fabricate a contentUrl you don’t control.

The duration format trips people up more than any other field. ISO 8601 duration is PT followed by hours, minutes, seconds: PT1H2M10S is one hour, two minutes, ten seconds. PT45S is 45 seconds, not PT0H0M45S written out. Get this wrong and the field silently fails validation instead of throwing a hard error in some parsers, so it is worth checking with the Rich Results Test every time.

Full JSON-LD example for a blog post with an embedded video

Here is a complete, valid VideoObject block for a typical case: a blog post with a self-hosted or CDN-hosted video plus a fallback embed player.

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to set up server-side tracking in GA4",
  "description": "A walkthrough of server-side GA4 tagging using Google Tag Manager, covering the three most common misconfigurations.",
  "thumbnailUrl": [
    "https://example.com/videos/ga4-server-tagging-thumb.jpg"
  ],
  "uploadDate": "2026-08-02T09:00:00-07:00",
  "duration": "PT00H14M32S",
  "contentUrl": "https://cdn.example.com/videos/ga4-server-tagging.mp4",
  "embedUrl": "https://www.example.com/embed/ga4-server-tagging",
  "interactionStatistic": {
    "@type": "InteractionCounter",
    "interactionType": { "@type": "WatchAction" },
    "userInteractionCount": 15420
  }
}

A few notes on fields that are not obvious from the property list alone:

• thumbnailUrl accepts an array, and Google recommends supplying multiple aspect ratios where you have them (16:9, 4:3, 1:1) so the right crop is available for different result placements.
• interactionStatistic.interactionType should be WatchAction for a view count, not LikeAction or another type. Using the wrong action type is a common copy-paste error when adapting examples from other schema types.
• If your video sits behind a login or paywall, do not simply omit the markup. Google’s guidance covers paywalled content explicitly through separate structured data (isAccessibleForFree plus a hasPart paywalled-content declaration) rather than silent omission, which without the correct markup risks a cloaking violation under the same structured data guidelines that ban misleading markup.

Place this JSON-LD in a <script type="application/ld+json"> tag in the page <head> or body. Position does not affect parsing, but keeping it near the video element in your CMS template makes it easier to keep the two in sync when someone swaps the embed later.

Key moments: Clip and SeekToAction markup

Key moments are the timestamped segments Google shows under a video thumbnail, letting a searcher jump straight to the 4:12 mark instead of watching from the start. Google detects some of these automatically from things like YouTube description timestamps, but you have two structured-data options to declare them explicitly, per Google’s key moments documentation.

Option 1: Clip markup, when you know the exact segments and want to control the labels:

{
  "@context": "https://schema.org/",
  "@type": "VideoObject",
  "name": "How to set up server-side tracking in GA4",
  "hasPart": [
    {
      "@type": "Clip",
      "name": "Creating the server container",
      "startOffset": 30,
      "endOffset": 145,
      "url": "https://www.example.com/videos/ga4-server-tagging?t=30"
    },
    {
      "@type": "Clip",
      "name": "Configuring the client tag",
      "startOffset": 145,
      "endOffset": 320,
      "url": "https://www.example.com/videos/ga4-server-tagging?t=145"
    }
  ]
}

name, startOffset, and url are required for each Clip; endOffset is optional but recommended so Google knows where one segment ends and the next begins. startOffset and endOffset are expressed in seconds, not ISO 8601, which is a deliberate inconsistency with the duration field above and a frequent source of implementation bugs.

Option 2: SeekToAction, when your player already supports URL-based timestamp seeking and you want Google to detect segments automatically instead of hand-labeling every one:

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "potentialAction": {
    "@type": "SeekToAction",
    "target": "https://www.example.com/videos/ga4-server-tagging?t={seek_to_second_number}",
    "startOffset-input": "required name=seek_to_second_number"
  }
}

The startOffset-input value has to be exactly "required name=seek_to_second_number". This is a fixed string Google’s parser matches against, not a placeholder you customize. Use Clip when you have a small number of hand-picked, well-labeled segments (a tutorial’s numbered steps). Use SeekToAction when your player already supports arbitrary second-level seeking and you would rather let Google infer segments than maintain a hand-built list. The two are not mutually exclusive, but most sites pick one to avoid maintaining duplicate segment data.

The LIVE badge: BroadcastEvent for livestreams

The red LIVE badge that appears on a livestreamed video in search results comes from a BroadcastEvent nested inside your VideoObject, via the publication property:

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "Q3 product roadmap livestream",
  "description": "Live walkthrough of the Q3 roadmap with a Q&A segment.",
  "thumbnailUrl": ["https://example.com/videos/q3-livestream-thumb.jpg"],
  "uploadDate": "2026-08-02T09:00:00-07:00",
  "publication": {
    "@type": "BroadcastEvent",
    "isLiveBroadcast": true,
    "startDate": "2026-08-02T17:00:00-07:00",
    "endDate": "2026-08-02T18:00:00-07:00"
  }
}

isLiveBroadcast is the flag that triggers the badge while the stream is active. Once endDate passes, Google treats the video as an on-demand recording and drops the badge automatically. If you re-air a recording, set isLiveBroadcast back to false and update uploadDate only if it is genuinely a new upload, not a re-publish of the same file, per the same anti-cloaking language covered in the required-properties section.

Thumbnail requirements Google actually enforces

Thumbnails fail validation more often than any other field because the specs are specific and rarely checked before launch. Per Google’s video best practices documentation:

• Accepted formats: BMP, GIF, JPEG, PNG, WebP, SVG, AVIF.
• Minimum size 60x30 pixels, though Google recommends larger for actual display quality.
• At least 80% of the thumbnail’s pixels must have an alpha (transparency) value greater than 250. In practice this means avoid heavily transparent or watermark-washed thumbnails, since Google’s crawler treats a mostly-transparent image as low quality.
• The thumbnail must stay at a stable URL Googlebot can access without authentication.

You can supply the thumbnail four separate ways, and doing more than one is not redundant, it is redundancy Google explicitly recommends: the video element’s poster attribute, a video sitemap’s <video:thumbnail_loc> tag, the thumbnailUrl structured data property, and Open Graph’s og:image. When these four disagree (a stale CDN path in one, a fresh one in another), Google has to guess which is authoritative, and inconsistent guesses are a common cause of a video losing its thumbnail in results after a redesign.

Video schema vs video sitemaps: do you need both

Short answer: yes, if you have more than a handful of videos, and structured data alone is not a substitute for a video sitemap when you need Google to discover and re-crawl video pages at scale.

Signal	VideoObject structured data	Video sitemap
Purpose	Describes one video for rich result eligibility	Discovery and crawl-priority hint for many videos
Format	JSON-LD in page HTML	XML file, separate from or embedded in your main sitemap
Required fields	name, thumbnailUrl, uploadDate	<loc>, <video:thumbnail_loc>, <video:title>, <video:description>
Scales to a video library	✗ Per-page only, no bulk signal	✓ Purpose-built for hundreds or thousands of videos
Enables rich results	✓ This is what gates carousels and key moments	✗ Discovery only, does not gate rich results by itself
Update frequency signal	✗ No native “recrawl this” mechanism	✓ lastmod on each entry

If you run a handful of embedded videos across blog posts, structured data alone covers it: Google discovers the page normally through your regular sitemap and crawl, then reads the VideoObject markup for eligibility. If you run a video-heavy site (a course platform, a media archive, hundreds of product demo clips), add a dedicated video sitemap so Google can prioritize crawling those pages instead of relying on the same crawl budget as the rest of the site. The two systems are complementary, not competing.

YouTube embeds vs self-hosted video: what changes in your markup

flowchart TD
    A[Video is going on the page] --> B{Where is it hosted?}
    B -->|YouTube or Vimeo embed| C[Use embedUrl, no contentUrl]
    B -->|Self-hosted or CDN file| D[Use contentUrl as primary, embedUrl as fallback player]
    C --> E{Need key moments?}
    D --> E
    E -->|Yes, hand-picked segments| F[Add Clip array via hasPart]
    E -->|Yes, player supports URL seeking| G[Add SeekToAction]
    E -->|No| H[Ship with required + recommended properties]
    F --> I{Is it a livestream?}
    G --> I
    H --> I
    I -->|Yes| J[Add BroadcastEvent via publication]
    I -->|No| K[Validate with Rich Results Test]
    J --> K

The decision that matters most upstream of your markup is hosting, because it decides which URL field carries the weight. A YouTube or Vimeo embed does not give you a direct file URL you control, so embedUrl is correct and contentUrl should be left out rather than pointed at a URL you do not actually serve. A self-hosted or CDN-hosted file gives you both: point contentUrl at the actual media file and embedUrl at your player page as the fallback. Getting this reversed, for example putting a YouTube watch URL in contentUrl, is a validation-passing but semantically wrong implementation that Google’s parser will not always catch, because the field accepts any URL syntactically, it just will not resolve to a media file Google can directly verify.

Validating your markup before you ship it

Google’s Rich Results Test is the tool of record. Feed it a live URL or raw HTML and it reports which rich result types the page is eligible for, flags missing required fields as errors, and flags missing recommended fields as warnings. Test both the URL-based flow and the paste-code flow, since a URL test also confirms the markup is actually reachable in your rendered HTML, not just present in a template that never ships.

A few checks worth running beyond the pass/fail result:

• Confirm the tool is reading your production-rendered HTML, not a cached or staging version, especially if your VideoObject markup is injected client-side by JavaScript. Server-rendered or statically generated markup avoids an entire class of “it validates locally but not in production” bugs.
• Check that duration and offset values parse as the numbers you intended. A duration of PT5M when you meant PT50M validates fine syntactically and is simply wrong.
• Re-test after any CMS or theme migration. Thumbnail paths and embed URLs are exactly the fields most likely to silently break during a platform move, since they often live in a different template partial than the rest of the page content.

Run the test against one representative template, not every individual video page, then spot-check a sample after deployment. If your CMS generates VideoObject markup from a shared template, a single field-mapping bug will replicate across your entire video library, so catching it before full rollout matters more than catching it on any single page.

Seven mistakes that quietly break video rich results

1. Duplicate name values across a video library. Google’s own documentation calls out unique titles per video specifically because duplicate titles across a catalog make it hard for Google to attribute the right result to the right page.
2. Wrong duration format. Writing 30:05 or 1800s instead of ISO 8601 PT30M5S. This is the single most common syntax error in VideoObject implementations.
3. startOffset in the wrong unit. Clip offsets are plain seconds, not ISO 8601 like duration. Copy-pasting duration-style formatting into a Clip block is a frequent bug.
4. Thumbnail URL rot. A CDN migration or image optimization pipeline change breaks the thumbnailUrl path without touching the rest of the page, and the video quietly loses rich result eligibility with no visible error on the page itself.
5. Backdated uploadDate on a refreshed video. Changing uploadDate to make an old video look freshly published, when the video file itself has not changed, risks the same misleading-content violation Google applies to fake freshness signals elsewhere.
6. contentUrl pointed at a page, not a file. contentUrl should resolve to the actual media bytes. Pointing it at the watch page URL instead of the file (or a proper embedUrl) is a common copy-paste error from adapting another site’s markup.
7. Markup that does not match visible content. If your JSON-LD claims a duration or title that does not match what a visitor actually sees on the page, that is a direct violation of the “markup must describe content visible to readers” rule in Google’s structured data policies, and it is grounds for a manual action that strips rich result eligibility site-wide, not just on the offending page.

Measuring whether it worked

Google Search Console has no dedicated “Video” search appearance filter as consistently as it does for FAQ or product rich results, so measurement here is closer to standard performance tracking than a single dashboard. Cross-reference the Performance report filtered by pages that carry VideoObject markup against the same pages before implementation, watching impressions and click-through rate rather than raw position, since video rich results change the physical layout of the result rather than just its rank. If you separately maintain a Google Search Console analysis workflow, add your video-marked pages as a saved segment so you are not re-building the comparison by hand every reporting cycle.

Pair that with the Rich Results Test’s own eligibility report, re-run monthly on a sample of pages, since eligibility can silently regress after any template or CDN change without a corresponding drop showing up immediately in click data. Fold that check into a broader AI visibility audit rather than treating video markup as a one-time launch task, and track it alongside the SEO KPIs that still matter once clicks alone stop telling the full story.

Frequently asked questions

Is VideoObject schema required to rank a video page in Google?

No. Ranking depends on the standard set of signals (content quality, relevance, links, page experience) that apply to any page. VideoObject markup does not change your ranking for text search. It changes whether your page is eligible for video-specific rich results: carousels, key moments, and the LIVE badge, which are separate surfaces from the standard ranked list.

What happens if I only add the three required properties and skip the rest?

Your video becomes eligible for the basic video result but not for a carousel placement, key moments, or duration display, since those depend on description, duration, and the URL fields. Google’s documentation lists them as recommended rather than required precisely because the page still validates without them, it just competes for less real estate.

Can I use VideoObject markup for a YouTube embed I don’t host myself?

Yes. Use embedUrl pointing at the YouTube (or other platform) player URL, and skip contentUrl since you do not control a direct file URL for embedded third-party video. Do not fabricate a contentUrl pointing at the YouTube watch page; that is not a media file and will not validate correctly against Google’s content-matching checks.

Does the video need to be visible without scrolling to qualify for rich results?

Google’s guidance requires the markup to describe content that is actually present and accessible on the page, not specifically above the fold. A video further down the page with correct markup is not disqualified for placement alone, but a video hidden behind extra clicks or gated content needs the appropriate paywall structured data rather than being omitted from markup entirely.

How is the duration field formatted, exactly?

ISO 8601 duration format: PT followed by hours, minutes, and seconds in that order, each with its own letter. PT1H30M15S is one hour, thirty minutes, fifteen seconds. A video under an hour omits the hour segment: PT14M32S is fourteen minutes, thirty-two seconds. Seconds-only videos still need the PT prefix: PT45S.

What is the difference between Clip and SeekToAction for key moments?

Clip is a manually authored list of named segments with explicit start and end offsets in seconds, giving you full control over labels. SeekToAction instead tells Google how to construct a timestamp URL so it can detect segments automatically from your player’s own behavior. Use Clip for a small set of hand-picked, precisely labeled moments; use SeekToAction when you would rather let Google infer segments at scale.

Do I need a video sitemap if I already have VideoObject structured data?

Not always. Structured data alone is enough for a small number of embedded videos discovered through normal crawling. A dedicated video sitemap matters once you have a large video library, because it gives Google an explicit discovery and re-crawl priority signal that per-page structured data does not provide on its own.

Why did my video lose its thumbnail in search results after a site redesign?

The most common cause is a broken thumbnailUrl path after a CDN or image-pipeline migration, or a mismatch between the poster attribute, thumbnailUrl, video sitemap <video:thumbnail_loc>, and og:image values. Check all four sources agree on the same accessible URL and re-validate with the Rich Results Test after any platform migration.

Can I mark up a paywalled or subscriber-only video?

Yes, but you cannot simply omit the markup or mark it up as freely accessible when it is not; that risks a cloaking violation. Google covers paywalled content through a dedicated combination of isAccessibleForFree and hasPart structured data rather than silent omission. If your platform gates video content, implement the paywall-specific markup rather than treating video schema and paywall schema as separate concerns.

Does adding VideoObject markup guarantee a video carousel appears for my page?

No. Google states plainly that correct structured data does not guarantee any rich result will display, even when validation passes. Markup makes you eligible; the actual decision to show a carousel, key moments, or the LIVE badge depends on Google’s broader ranking and result-selection systems that are not fully documented.

What’s the minimum video length for key moments to appear?

Google’s video best practices note a practical floor around 30 seconds for Clip and SeekToAction features to be useful, since shorter videos rarely need internal segment navigation. There is no hard technical block below that length, but expect key moments to be functionally irrelevant for very short clips.

Should uploadDate change when I re-encode or re-host the same video file?

No, if the content itself has not changed. uploadDate represents when the video was first published, not when the file was last touched technically. Changing it to signal freshness for the same underlying video content is the kind of misleading-markup practice Google’s policies specifically prohibit.

Can I put multiple videos on one page with separate VideoObject blocks?

Yes. Each video on the page should get its own VideoObject block with its own unique name, thumbnailUrl, and uploadDate. Reusing one block’s values across multiple embeds, or nesting multiple videos under one object, produces markup Google cannot reliably attribute to the correct on-page video.

Does BroadcastEvent markup work for a livestream hosted on a third-party platform?

Yes, as long as you can update isLiveBroadcast, startDate, and endDate in near real time. Third-party platforms that expose a status API (live, ended, scheduled) let you sync your own page’s publication block to match; without that sync, your LIVE badge can persist after the stream actually ends, which risks the same misleading-content issue as any other stale markup.

How often should I re-validate video schema after launch?

Re-run the Rich Results Test on a representative sample whenever you touch the CMS template, CDN configuration, or embed provider, and as a baseline check monthly if you have a video-heavy site. Eligibility regressions are silent; nothing on the page itself signals that a thumbnail path broke or a duration field stopped parsing.

Is JSON-LD the only accepted format for VideoObject markup?

No. Google accepts JSON-LD, Microdata, and RDFa for VideoObject, as it does for schema.org types generally. Google’s own documentation recommends JSON-LD as the preferred format because it is easier to generate programmatically and does not require inline attributes scattered through your HTML, but the other two formats are valid and parsed the same way.

What’s the interactionStatistic field actually used for?

It reports a view count via an InteractionCounter with interactionType set to WatchAction. Google can display this count alongside the video result as a trust signal. It is not a gating requirement for any rich result feature, unlike name, thumbnailUrl, and uploadDate.

Does video schema help with citation in AI search tools, not just Google?

VideoObject is a standard schema.org vocabulary, and other search and AI systems that crawl structured data can parse it the same way Google does, since it is not a Google-proprietary format. Whether a given AI engine actually uses VideoObject fields to select or cite video content is not documented by those engines the way Google documents its own usage, so treat any cross-engine benefit as unverified rather than assumed.

Can I mark up a video that’s embedded from a third-party player I don’t control at all, like an ad network’s video?

Technically yes if you can supply accurate name, thumbnailUrl, and uploadDate values, but this is a narrow case. If you cannot verify the metadata is accurate and stable (a third-party ad player rotating creative, for example), marking it up risks the visible-content-mismatch violation, since the markup could describe content that changes independently of your control.

Do I need separate VideoObject markup for the same video embedded on two different pages?

Yes. Each page needs its own VideoObject block describing the video as it appears on that page, even if the underlying file is identical. uploadDate can stay the same across both since the video itself was published once, but name and description should reflect the context of each individual page rather than being copied verbatim, which helps Google attribute the right result to the right URL.

Key takeaways

• Three properties gate basic eligibility: name, thumbnailUrl, uploadDate. Five more (description, duration, contentUrl, embedUrl, interactionStatistic) enable carousels and richer display.
• duration uses ISO 8601 (PT14M32S); Clip offsets use plain seconds. Mixing the two formats is the most common implementation bug.
• Clip is for hand-picked, labeled segments; SeekToAction is for letting Google auto-detect key moments from a URL-seekable player.
• BroadcastEvent with isLiveBroadcast: true triggers the LIVE badge, and needs to stay synced to your stream’s actual status to avoid stale-markup violations.
• Thumbnails fail validation more than any other field. Check format, size, transparency, and URL stability across all four places a thumbnail can live: poster, sitemap, structured data, and Open Graph.
• Structured data and video sitemaps are complementary, not redundant. Add a sitemap once your video library scales past a handful of pages.
• Validate with the Rich Results Test on your production-rendered HTML, and re-check after every CMS, CDN, or embed-provider change, since eligibility regressions do not show visible errors on the page itself.

If your video content lives inside a larger technical SEO program, check the companion YouTube SEO guide for how video ranking on YouTube itself interacts with what you mark up on your own site, and the complete schema markup guide for how VideoObject fits alongside your other structured data types.