Video schema markup: earn video rich results with VideoObject

Video schema markup is a small block of VideoObject JSON-LD you add to a page so Google understands there's a video on it — what it's called, when it went live, and where the file sits. Add it correctly and your result can carry a video thumbnail, clickable key moments, and a LIVE badge; skip it and you're a plain blue link competing against pages that aren't. This guide covers the required properties, a copy-paste example, chapters via Clip and SeekToAction, livestreams, and how to validate.

What video schema markup is and why it matters

Search engines don't watch your videos. They read the HTML around them. Structured data is how you hand Google a machine-readable summary of the video instead of hoping it infers one from your markup. The specific type is VideoObject, part of the schema.org vocabulary, and the recommended format is JSON-LD — a <script> block you drop into the page rather than attributes sprinkled through your HTML.

The payoff is a video rich result: a thumbnail in the main results, in the Videos tab, in Google Images, and in Discover. On mobile especially, a thumbnail is a wildly bigger click target than a text snippet. It's the same logic as a good YouTube thumbnail — the image does the persuading — which is why it pairs with everything in YouTube thumbnails and CTR.

One honest caveat up front: markup makes you eligible, not guaranteed. Google still decides whether the query deserves a video result. Your job is to remove every technical reason it might say no.

Required and recommended VideoObject properties

Google splits VideoObject properties into required and recommended. Miss a required one and the page is not eligible for video rich results — full stop. The recommended ones unlock extra features like key moments and live badges.

Two mistakes cause most failures. First, a thumbnailUrl Google can't crawl — blocked by robots.txt, behind a login, or a data URI. Provide a real, public image URL. Second, a description that just repeats the title; write two useful sentences about what the viewer will see.

JSON-LD example you can copy and adapt

Here's a complete, valid VideoObject. Replace the values, keep the structure.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to run a technical SEO audit in 30 minutes",
  "description": "A walkthrough of crawling a site, spotting index bloat, and fixing Core Web Vitals — with a downloadable checklist you can reuse on any project.",
  "thumbnailUrl": [
    "https://example.com/thumbs/audit-1x1.jpg",
    "https://example.com/thumbs/audit-4x3.jpg",
    "https://example.com/thumbs/audit-16x9.jpg"
  ],
  "uploadDate": "2026-06-26T08:00:00+05:30",
  "duration": "PT12M30S",
  "contentUrl": "https://example.com/videos/technical-seo-audit.mp4",
  "embedUrl": "https://example.com/embed/technical-seo-audit",
  "publisher": {
    "@type": "Organization",
    "name": "DeployFlare",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  }
}
</script>

Notes that trip people up:

• Provide three thumbnail aspect ratios (16:9, 4:3, 1:1) so Google can pick per surface. An array is fine.
• uploadDate must be ISO 8601. June 26, 2026 will fail validation.
• Include either contentUrl or embedUrl (both is better). Without one, key moments and previews are weaker.

If you'd rather not hand-write JSON, a video schema generator — Google's own Structured Data Markup Helper, or the templating in most modern CMS platforms — produces the same block. Whatever you use, still validate the output; generators happily emit fields Google ignores.

Key moments with Clip and SeekToAction

Key moments are the clickable timestamps that appear under a video result, letting a searcher jump straight to the relevant part. They're one of the highest-value video features because they turn one result into several entry points. There are two ways to get them.

Method 1 — Clip (explicit)

You define each segment by hand. Best when you want exact labels and full control.

"hasPart": [
  {
    "@type": "Clip",
    "name": "Crawling the site",
    "startOffset": 30,
    "endOffset": 210,
    "url": "https://example.com/watch?v=audit&t=30"
  },
  {
    "@type": "Clip",
    "name": "Fixing Core Web Vitals",
    "startOffset": 210,
    "endOffset": 480,
    "url": "https://example.com/watch?v=audit&t=210"
  }
]

Each Clip needs a name, startOffset (seconds), and a url with a deep link to that timestamp. Your player must actually honor that t= parameter, or the moments send viewers to the wrong spot.

Method 2 — SeekToAction (automatic)

Instead of listing clips, you tell Google the URL pattern your player uses for timestamps, and Google auto-detects chapters from your video's own structure.

"potentialAction": {
  "@type": "SeekToAction",
  "target": "https://example.com/watch?v=audit&t={seek_to_second_number}",
  "startOffset-input": "required name=seek_to_second_number"
}

Use SeekToAction when your video already has clear chapters and you'd rather Google generate the moments than maintain a Clip list. Use Clip when you want precise, human-written labels. Don't use both for the same video. Well-structured chapters here reinforce the same transcript work described in video transcripts for SEO.

Livestreams with BroadcastEvent

For a live video, you use the same VideoObject and add a publication node of type BroadcastEvent. This is what earns the red LIVE badge in search — a strong CTR lift while you're on air.

"publication": {
  "@type": "BroadcastEvent",
  "isLiveBroadcast": true,
  "startDate": "2026-06-26T18:30:00+05:30",
  "endDate": "2026-06-26T19:30:00+05:30"
}

Three things make live markup work:

• Set isLiveBroadcast: true and provide a startDate. Add endDate when known.
• Update the markup as the state changes — before, during, and after the stream. Google offers the Indexing API for live videos so the badge appears and disappears at the right time.
• Keep the surrounding VideoObject valid; the BroadcastEvent is an addition, not a replacement.

After the stream ends, the recording keeps its VideoObject and can still earn a normal video result — so a single livestream page can rank twice over its life.

Validating and pairing with a video sitemap

Markup you haven't tested is a guess. Two steps close the loop.

1. Run the Rich Results Test. Paste the live URL (or the code) into the Rich Results Test. It tells you whether the page is eligible for video rich results and lists errors (missing required field) and warnings (recommended field absent). Fix every error; treat warnings as an upgrade backlog. Then watch the Videos report in Search Console for how many of your videos Google actually indexed.

2. Submit a video sitemap. Schema describes a video; a video sitemap helps Google discover it and understand which page it belongs to. The two work together — this is important enough that it has its own guide in video sitemaps. At minimum, list each video's page URL, thumbnail, title, and description in your sitemap so crawling and structured data agree.

Here's the launch checklist I run before calling a video page done:

Schema is the technical layer of a bigger picture. It decides how your video appears, but ranking still rests on the fundamentals in video SEO and how to rank YouTube videos. Once your video pages are earning impressions, watch which queries actually surface them — DeployFlare's rank tracker lets you monitor video and SERP-feature positions the same way you'd track any keyword, so you can see whether that thumbnail is winning clicks or just sitting there.

Get the four required properties right, add key moments where they help, validate, and back it with a sitemap. That's the whole job — and it's the difference between a result people scroll past and one they click.