Video Schema Markup: Rich Results and Key Moments

Video is one of the most visually rewarding types of structured data you can add, and one where a little markup goes a long way. Done right, VideoObject schema can put your videos into Google's video carousel, unlock Key Moments (those clickable timestamp links that let people jump straight to the useful part), and add a LIVE badge to your streams. It also makes your video content discoverable to AI systems, which increasingly recommend and cite video when answering people's questions.

Here's the thing worth knowing up front, and it shapes the whole approach: AI systems and search engines can't actually watch your video. They understand it through the structured data and text you provide around it. That means the markup isn't a nice-to-have, it's how machines know what your video is, what's in it, and when to surface it. This guide covers all of it: the features, the required and recommended properties, Key Moments, the LIVE badge, and the text strategy that makes AI genuinely able to "watch" your videos.

What video schema gets you

VideoObject structured data makes your video eligible for several distinct features, and they're worth knowing so you can aim for the ones that fit your content:

The video rich result and carousel. Your video can appear as a standalone rich result with a thumbnail, or in Google's scrollable video carousel, which is prime, eye-catching placement for video-intent searches.

Key Moments. This is the standout feature. Key Moments show clickable chapter markers directly in the search result, letting users jump straight to a specific segment: "how to whisk the eggs" at 2:14, or "the final result" at 8:30. They take up more space, they're genuinely useful, and they can meaningfully improve click-through because people can see the video answers their exact question.

The LIVE badge. For livestreams, a LIVE badge signals the stream is happening now, drawing attention to real-time content.

AI and assistant discovery. Beyond traditional rich results, VideoObject is the prerequisite for your video showing up in AI-mediated discovery: AI Overview video citations, assistant video recommendations, and Discover feed video cards. As people increasingly ask AI systems to find them a video that explains something, structured video data is what makes yours findable.

Not every video qualifies for every feature, but complete VideoObject markup is the foundation for all of them. It sits alongside the other schema types worth using in 2026, and you can see how it fits the wider vocabulary in our schema types library.

The first decision: standalone or embedded?

Before any markup, answer one question, because getting it wrong is the single most common and most damaging video schema mistake: is the video the main content of the page, or supporting content?

If the video is the main content (a dedicated watch page, a video landing page, or a page where the video is the primary reason someone visits), use standalone VideoObject schema. This tells Google to index the video as its own entity and makes it eligible for the video-specific features above.

If the video is supporting content (an embedded YouTube clip inside a longer blog article, a product demo within a features page, a tutorial alongside written instructions), do not add standalone VideoObject as a separate block. Instead, add the video as a property within the page's existing Article or BlogPosting schema, using the video property.

Here's why this matters so much. If you put a standalone VideoObject and a BlogPosting on the same page, Google sees two top-level entities and doesn't know which one represents the page. That confusion can hurt both the article's rankings and the video's eligibility for rich results, so you end up worse off than with cleaner markup. Decide what the page is fundamentally about, and let that decide your structure: video-first pages get VideoObject, article-first pages get Article with the video nested inside. This one decision prevents a lot of grief.

Required and recommended properties

Google's own video documentation is stricter than most guides suggest about which properties are genuinely required. There are three:

• name: the video title, which should be unique for each video on your site and should match or closely mirror your YouTube title if it's also there
• thumbnailUrl: an absolute URL to the thumbnail image, crawlable and not blocked in robots.txt
• uploadDate: when the video was published, in ISO 8601 format

You'll see plenty of articles list description as a fourth required property. Google actually files it under recommended, but treat it as required anyway: a video with no description gives machines almost nothing to work with, and it's the single field AI systems lean on hardest when deciding what your video is about. Write a clear summary of roughly 150 to 300 characters, unique to that video.

Those basics make you eligible. But eligibility isn't competitiveness, and the strong recommended signals are what give machines a real understanding of your video:

• description: the summary described above
• duration: the length, in ISO 8601 duration format (PT8M30S for 8 minutes 30 seconds)
• contentUrl: the URL of the actual video file, which Google prefers
• embedUrl: the URL of the video player, useful when a direct file URL isn't available, and worth including alongside contentUrl where you have both

And for richer context that helps both Google and AI:

• inLanguage: the video's language
• publisher and author: who published and created it, connected to your entities
• about and mentions: the entities the video is about, which we'll come back to
• keywords: relevant topics
• expires: for content that should stop appearing after a date
• interactionStatistic: view counts, if you have real ones to report

Fill in the required three plus a solid description and the strong signals, and you've got a competitive VideoObject.

A complete VideoObject example

Here's a well-formed standalone VideoObject for a video watch page:

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to Add Schema Markup in WordPress (Step by Step)",
  "description": "A complete walkthrough of adding structured data to a WordPress site, from choosing types to validating your markup.",
  "thumbnailUrl": "https://example.com/videos/schema-tutorial-thumb.jpg",
  "uploadDate": "2026-08-01T09:00:00+01:00",
  "duration": "PT12M40S",
  "contentUrl": "https://example.com/videos/schema-tutorial.mp4",
  "embedUrl": "https://example.com/embed/schema-tutorial",
  "inLanguage": "en",
  "publisher": {
    "@type": "Organization",
    "name": "Bright SEO",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  }
}

Note that every URL is absolute (https://…), the date is ISO 8601, and the duration uses the PT12M40S format. Those three details are where a lot of otherwise-valid video markup quietly breaks.

If your site runs on a JavaScript framework, where and how you output this block matters as much as what's in it. The same rules covered in our guide to schema markup in Next.js apply here: the markup has to be in the HTML the crawler actually receives, not added later in the browser.

Key Moments: the click-through win

Key Moments are the most impactful video feature to pursue, because those clickable chapter links genuinely stand out in search results and draw clicks. There are two ways to enable them, and they suit different situations.

Method one: Clip structured data (manual control). You define each segment precisely, giving you exact control over which moments appear and what they're called. For long-form videos you add these as segments via hasPart, each Clip carrying a name, a startOffset, and a url that deep-links to that point. An endOffset is optional but worth adding, since it makes each segment's boundaries explicit rather than leaving them inferred:

"hasPart": [
  {
    "@type": "Clip",
    "name": "Choosing your schema types",
    "startOffset": 62,
    "endOffset": 180,
    "url": "https://example.com/videos/schema-tutorial?t=62"
  },
  {
    "@type": "Clip",
    "name": "Validating your markup",
    "startOffset": 181,
    "endOffset": 300,
    "url": "https://example.com/videos/schema-tutorial?t=181"
  }
]

One rule to remember: no two clips defined for the same video on the same page can share a start time. Use Clip when you want precise, labelled control over your key moments.

Method two: SeekToAction (let Google detect them). Instead of defining each segment, you tell Google how your URL timestamp structure works (that ?t=62 jumps to 62 seconds), and Google automatically identifies key moments from your video's existing chapters and links to them. This is less manual: you describe the URL pattern once, and Google does the detection. It suits videos that already have clear chapters, like labelled YouTube chapters.

The requirements for either method:

• The video must be deep-linkable: its URL must support jumping to a specific point, like ?t=30
• The VideoObject must be on a page where users can actually watch the video (pointing people to a page where they can't watch is a bad experience Google guards against)
• The total video must be at least 30 seconds long
• For SeekToAction specifically, Google must be able to fetch your video content files

A practical tip that helps both methods: give your video chapters clear, answer-driven labels. "Validating your markup" is a better key-moment label than "Part 3," because it tells the searcher, and the machine, exactly what that segment answers.

The LIVE badge for streams

If you broadcast livestreams, BroadcastEvent markup enables the LIVE badge, a small but attention-grabbing signal that your stream is happening now. It isn't a separate top-level block: you nest it inside your VideoObject's publication property, marking isLiveBroadcast as true and giving it a startDate. Add the endDate once the stream has finished and is no longer live, which is required rather than optional, otherwise you're telling Google something is still live when it isn't.

Live content also has a timing problem ordinary video doesn't: the badge is only useful while it's accurate, so Google asks you to notify it when the stream goes live and when the markup changes, rather than waiting for a routine crawl. For anyone doing live content (launches, events, real-time Q&As), it's a straightforward way to make live content stand out as live.

How AI actually "watches" your video

Here's the insight that changes how you think about video and AI, and it's genuinely important: AI systems don't watch your videos. They read the text around them.

An AI answering "how do I add schema to WordPress" can't view your twelve-minute tutorial and extract the answer from the footage. What it can do is read your VideoObject markup, your on-page description, and, crucially, any transcript, show notes, or written summary you publish alongside the video. That text is how the video's content becomes available to AI retrieval and citation.

This makes the transcript approach one of the highest-value things you can do for video discoverability in the AI era. Publishing a page-level transcript, detailed show notes, or a structured written summary converts your spoken video content into text that AI systems can directly index, understand, and cite. A video with a full transcript on its page isn't just more accessible to humans: it's the difference between a video AI can't parse and one it can quote from confidently.

So the complete video strategy is two layers working together. VideoObject markup makes the video eligible for rich results and identifiable as video content, and rich accompanying text (description, transcript, show notes) makes the actual content of the video legible to AI. The markup gets you the carousel and Key Moments, the text gets you into the AI answers. Do both, and your video works across every surface. This is the same principle behind being cited by ChatGPT and other assistants: the clearer and more structured your information, the more accurately machines can understand and surface it.

Connect your video to entities

A refinement that strengthens both discovery and your broader entity picture: use about and mentions to connect your video to the specific entities it covers.

If your video is about schema markup, connecting it to the recognized entity for structured data, rather than just leaving "schema" as a loose word in the description, tells machines precisely what topic the video addresses. about names the primary subject, mentions names entities referenced along the way. Connecting these to real, disambiguated entity references is the same entity thinking that strengthens all your markup: it removes ambiguity and ties your video into the web of things machines already understand. For a channel building authority on a topic, videos that explicitly declare their subject as a recognized entity reinforce that authority.

Keep it consistent with YouTube

If your videos also live on YouTube, as most do, keep your schema metadata consistent with your YouTube metadata. Your name should match or closely mirror the YouTube title, and your description should align with what's on YouTube. Consistency helps machines confidently connect your hosted video, your page, and your YouTube presence as the same piece of content rather than three loosely related things. A video sitemap, if you maintain one, further helps Google discover and understand your video content.

Common mistakes to avoid

The errors that most often cost people video rich results:

Standalone VideoObject on an article page. The big one. If the video supports an article, nest it in the Article schema, don't add a competing standalone VideoObject. Two top-level entities confuse Google about what the page is.

Relative URLs. thumbnailUrl, contentUrl, and embedUrl must be absolute (https://…), not relative paths. Relative URLs quietly break the markup.

Wrong date or duration format. uploadDate must be ISO 8601, and duration uses the PT#M#S format. Locale-formatted dates or plain-language durations fail.

Reused names and descriptions across videos. Google explicitly asks for unique text in both fields for every video on your site. Copy-pasting the same description across a series makes your videos indistinguishable to machines.

Description that doesn't match the video. If your schema description doesn't reflect the actual video content, Google may ignore the markup. Describe what's genuinely in the video.

Keyword-stuffed descriptions. Google's parser evaluates quality, so write natural, accurate descriptions, not keyword lists.

No markup on individual video pages. If each video has its own page, each page needs its own VideoObject. Marking up only a hub page leaves the individual videos unlabelled.

A thumbnail Google can't fetch. If your thumbnailUrl is blocked in robots.txt or unreachable, the feature can't work. Make sure it's crawlable.

Implementing it on WordPress

Your route depends on where your videos live and how they're presented.

If you use a video or SEO plugin, check what it already outputs. View source on a video page and see whether it produces VideoObject markup, whether it includes the recommended signals, and whether it handles the standalone-versus-embedded distinction correctly. Many plugins produce only the bare minimum, or produce standalone VideoObject on pages where the video is actually supporting content.

Hand-maintained markup works for a few videos but becomes a burden across a growing library: every new video is a manual block, and the standalone-versus-embedded decision has to be made correctly each time.

Generating from your content scales best. AI Schema Gen reads your pages and produces appropriate video markup (VideoObject where the video is the main content, or nested video within your Article schema where it's supporting) with the recommended signals filled in and connected to your entities. Because it generates from your live content, it stays accurate as you publish, and it makes the standalone-versus-embedded call based on what the page actually is. That correct structural decision, made automatically, is worth a lot given how commonly it's the thing people get wrong.

Whatever route you choose, the tests are the same: is the standalone-versus-embedded decision right for each page, are the required and recommended properties present, and are your URLs absolute and your dates properly formatted.

Video schema and AI search

To bring it together: video is increasingly part of how people discover answers, and AI systems are increasingly part of how people find video. VideoObject markup makes your video identifiable and eligible for the rich features that drive clicks, while the accompanying text (description, transcript, show notes) makes the actual content legible to the AI systems that recommend and cite video.

The brands that win video visibility in 2026 do both: they mark up their videos properly and they publish the text that lets machines understand what's in them. Neither alone is enough. Markup without text gives you a carousel listing but nothing for AI to quote, and text without markup gives you content AI can read but no rich-result eligibility. Together, they make your video work everywhere people and machines look for it.

Validating your video schema

Google's Rich Results Test confirms eligibility for video rich results and Key Moments, and flags errors. Test your individual video pages.

Search Console has a Videos report showing how Google indexed your videos across the site, which surfaces issues at scale, and it's worth watching if you publish regularly.

The Schema Markup Validator at validator.schema.org checks general syntax.

And verify the practical details: that your thumbnail loads, your URLs are absolute, your dates and durations are correctly formatted, and, if you're using Key Moments, that your deep-links actually jump to the right points.

Publishing video on WordPress? AI Schema Gen generates the right video markup for each page, standalone VideoObject or nested in your article, with the recommended signals and entity connections, so your videos are eligible for rich results and legible to AI. Start free at aischemagen.com.