What Is Video Schema Markup?

Video schema markup is JSON-LD structured data — based on schema.org's VideoObject type — that describes a video in a format search engines and AI crawlers can read directly, instead of guessing from the surrounding page text. At minimum it covers the title, description, thumbnail, upload date, and duration, and it can optionally flag live broadcasts, key moments, and jump-to-timestamp actions.

Create Video Schema Markup in 4 Simple Steps

You don't need to memorize schema.org's property list to get this right. Here's the process:

  1. Gather your video's core details — title, description, thumbnail URL, upload date, and duration. If it's hosted on YouTube, grab the embed URL too.
  2. Decide which optional properties apply. Live stream? Add BroadcastEvent. Distinct chapters or moments? Add Clip. Want Google to generate jump-to-timestamp links automatically? Add SeekToAction.
  3. Generate the JSON-LD. Hand-writing this is where most mistakes happen — a missing comma or the wrong property name silently breaks the whole block. A generator such as the Video Schema Generator builds it correctly every time, free.
  4. Add it to your page and validate. Paste the script into your page's <head>, or just before </body>, then run it through Google's Rich Results Test to confirm it's eligible.

A minimal, valid example looks like this:

JSON-LD · Video Schema Example
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to Create Video Schema Markup",
  "description": "A quick walkthrough of adding VideoObject schema to a webpage.",
  "thumbnailUrl": [
    "https://example.com/thumbnail-1x1.jpg",
    "https://example.com/thumbnail-4x3.jpg",
    "https://example.com/thumbnail-16x9.jpg"
  ],
  "uploadDate": "2026-07-18T09:00:00Z",
  "duration": "PT2M30S",
  "contentUrl": "https://example.com/videos/video.mp4",
  "embedUrl": "https://example.com/videos/embed/123"
}

Note: use contentUrl for a self-hosted file or embedUrl for an embed — you don't need both. More on that next.

Marking Up a YouTube Video? Here's What Changes

The steps above are identical whether your video is self-hosted or embedded from YouTube — only one field changes. For a self-hosted file, use contentUrl pointing to the actual video file. For a YouTube embed, use embedUrl pointing to the YouTube player URL instead — you don't need direct access to the video file itself.

One limitation worth knowing: YouTube doesn't publicly expose a video's exact duration or upload date on the embed itself, so grab both from the video's own YouTube page and enter them manually. Everything else — title, description, thumbnail — you already have.

VideoObject or Nested in Your Article — Which Should You Use?

This is the decision most guides skip, and it's the one that actually determines whether your markup gets used.

Use a standalone VideoObject when the video is the main reason someone visits the page — a dedicated tutorial, a product demo, a landing page built around one embedded video.

Nest the video inside your page's Article or BlogPosting schema instead when the video is supporting content inside a longer piece, such as an explainer embedded partway through a blog post. In that case, add it as the video property on the Article/BlogPosting object rather than marking it up separately.

info
Why this trips people up

Standing up a full VideoObject for a decorative video — or burying your only video inside an Article when it's actually the main content — is a common reason schema goes unused by Google even when it's technically valid.

5 Best Practices That Actually Affect Rich Results

  • One primary video per page. Multiple competing VideoObjects on one page dilute which one Google treats as canonical.
  • Thumbnails in three aspect ratios — 1:1, 4:3, and 16:9 — give Google flexibility across placements.
  • Duration and upload date must be accurate. Mismatches with the actual video are a common cause of Search Console errors.
  • Markup must match what's visible. Don't describe a video that isn't actually embedded on the page.
  • Don't skip it because "YouTube already has schema." YouTube's own markup describes the YouTube page — your page still needs its own.

Will Video Schema Help You Show Up in AI Search?

Google's own Search Central documentation is direct about this: there's no special schema you need for AI Overviews or AI Mode — no separate markup, no separate index. The same structured data and content quality that earns organic rich results is what AI Overviews draw from.

That doesn't make video schema pointless for AI visibility, though — the actual mechanism is just more modest than "more citations" claims tend to promise. Complete, standards-compliant markup removes ambiguity about what your video contains, and that matters for any system reading the page — Google's crawler, an AI Overview, or a browsing agent — not because of a special ranking bonus, but because there's nothing left for it to guess. A video with a fabricated or incomplete schema property simply gives an AI system less to work with.

check_circle
The bottom line

There's no special "AI schema" to add. Use a generator that outputs complete, accurate, schema.org-standard properties, and you've done what's actually within your control — for Google, and for everything reading your page after it.

For the deeper mechanics of AI citation — E-E-A-T signals, why most pages get skipped, how to structure content AI tools actually quote — see our guide to FAQ schema for AI search.

Frequently Asked Questions

Does video schema guarantee a rich result?

No. Video schema makes your video eligible for a rich result, but Google decides what to actually display based on content quality, page experience, and relevance — schema markup alone does not guarantee placement.

Do I need a specific tool to generate video schema automatically?

No. Any generator that outputs the correct schema.org VideoObject properties works — free tools like the Flawless Schema Video Schema Generator cover the full required and optional property set at no cost.

Is a video sitemap the same as video schema?

No. A video sitemap helps search engines discover and crawl pages that contain video, while video schema describes what the video actually contains once it's found. Most video-heavy sites benefit from having both.

What's the fastest way to create video schema without coding?

Use a video schema generator: enter your video's title, description, thumbnail, duration, and upload date (or its YouTube URL), and copy the finished JSON-LD directly into your page.

Video schema is one of the fastest structured-data wins available — a single JSON-LD block, generated once, that makes your video eligible for rich results without touching your page's design. Build yours now, free, at flawlessschema.com/video-schema-generator.