Learn · Video SEO

What is VideoObject schema and why every hosted video needs it.

A complete guide to the Schema.org type that turns a plain URL into a rich search result with thumbnail, duration badge, and Google Key Moments chapter markers.

Direct answer

Q: What is VideoObject schema?

A: VideoObject is a Schema.org type describing a video with structured properties — name, description, thumbnailUrl, uploadDate, duration, embedUrl — that search engines read as JSON-LD in a <script type='application/ld+json'> block on the hosting page. It's what makes a video eligible for Google's video thumbnail, duration badge, and Key Moments features in the search results. Every HostMyVideo watch page emits it automatically with the video's transcript and AI-generated chapters.

VideoObject + Clip → Google Key Moments in the SERP

Required properties

Google's Rich Results test refuses to validate a VideoObject without these four. Missing any and the page won't be eligible for the video-thumbnail treatment.

name

Human-readable title of the video.

description

Short summary (aim for 60-200 characters, plain text).

thumbnailUrl

One or more URLs to representative thumbnail images. Google recommends 16:9 and at least 1280 pixels wide.

uploadDate

ISO 8601 date the video was published.

Recommended properties

Not strictly required, but each one meaningfully increases how much real estate Google will give your video in the SERP.

duration

ISO 8601 duration (e.g. PT4M12S for 4 min 12 sec). Enables Google to display video length in search results.

contentUrl

Direct URL to the MP4 file. Optional if embedUrl is present.

embedUrl

URL to the embedded player (iframe src). Preferred over contentUrl for third-party hosts.

hasPart

Array of Clip objects for chapters — enables Google Key Moments. Each Clip needs startOffset, endOffset, name, url.

transcript

Full plain-text transcript. Boosts topical relevance and lets Google surface the video for spoken-content queries.

publisher

Nested Organization with name + logo. Anchors E-E-A-T signals for YMYL queries.

A complete working example

This is roughly what HostMyVideo emits on every watch page. Copy it, swap the values, and drop it into your page's <head>.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to embed a HostMyVideo video on Squarespace",
  "description": "5-step guide with a Code Block, ~5 minutes total.",
  "thumbnailUrl": [
    "https://cdn.example.com/thumb-16x9.jpg",
    "https://cdn.example.com/thumb-4x3.jpg"
  ],
  "uploadDate": "2026-07-24T09:15:00-04:00",
  "duration": "PT4M12S",
  "embedUrl": "https://hostmyvideo.io/embed/abc123",
  "contentUrl": "https://cdn.example.com/video.mp4",
  "publisher": {
    "@type": "Organization",
    "name": "HostMyVideo",
    "logo": {
      "@type": "ImageObject",
      "url": "https://hostmyvideo.io/logo.png"
    }
  },
  "hasPart": [
    {
      "@type": "Clip",
      "name": "Intro",
      "startOffset": 0,
      "endOffset": 72,
      "url": "https://hostmyvideo.io/v/abc123?t=0"
    },
    {
      "@type": "Clip",
      "name": "Setup",
      "startOffset": 72,
      "endOffset": 160,
      "url": "https://hostmyvideo.io/v/abc123?t=72"
    },
    {
      "@type": "Clip",
      "name": "Demo",
      "startOffset": 160,
      "endOffset": 230,
      "url": "https://hostmyvideo.io/v/abc123?t=160"
    }
  ],
  "transcript": "Full transcript text goes here..."
}
</script>

Why the extra markup is worth it

CTR uplift

Video results with thumbnails routinely see 2-4× the click-through rate of plain text listings for the same query. That's the largest and most reliable win.

Key Moments carousels

With hasPart Clip elements, Google renders a horizontally-scrolling row of chapter thumbnails under your result. Users click straight to the moment they want — you get the traffic anyway.

AI Overview eligibility

Google's AI Overviews (and Perplexity, ChatGPT Search) prefer structured sources they can cite with a thumbnail. Explicit VideoObject + transcript makes your video citable, not just discoverable.

VideoObject schema FAQ

What is VideoObject schema?

VideoObject is a Schema.org type that describes a video with structured properties like name, description, thumbnailUrl, uploadDate, duration, and embedUrl. Search engines read it as JSON-LD in a <script type="application/ld+json"> block on the page hosting the video. Adding it lets Google display video thumbnails, duration badges, and Key Moments chapters in the search results — features that dramatically increase click-through rate versus a plain text result.

Do I have to add VideoObject schema by hand?

You can, but it's tedious. HostMyVideo emits a complete VideoObject JSON-LD block on every /v/{videoId} watch page automatically — with name, description, thumbnailUrl, uploadDate, duration, embedUrl, hasPart (chapters), and transcript when available. If you embed a HostMyVideo video on your own site, the schema lives on your watch page and Google indexes it there. If you want the schema on YOUR canonical URL instead of ours, use the free JSON-LD generator tool to build one.

What's the difference between VideoObject and Clip schema?

VideoObject describes the WHOLE video (title, duration, thumbnail, transcript). Clip is a sub-type describing a single named segment within a video (chapter title + start/end offsets + link). Google's Key Moments feature — the row of chapter thumbnails under a search result — requires both: a VideoObject with a hasPart array of Clip objects. HostMyVideo auto-generates chapters via GPT-4o-mini from the transcript, then emits them as Clip elements.

Does adding VideoObject schema actually help rankings?

It doesn't rank the page higher by itself, but it dramatically improves click-through rate on the results it already gets. A search result with a video thumbnail + duration + chapter markers takes 3-4× more screen real estate than a plain blue link and gets substantially higher CTR. Higher CTR is a well-established ranking signal, so indirectly, yes.

Where should the JSON-LD script go on the page?

Google accepts it anywhere in the HTML — <head> or <body>. The convention is <head> so it loads with the initial HTML flush and doesn't wait for hydration. In Next.js App Router, use a <script type="application/ld+json" dangerouslySetInnerHTML={{__html: JSON.stringify(schema)}} /> inside your page component and Next auto-hoists it to head during SSR.

How do I validate my VideoObject markup?

Paste the URL into Google's Rich Results Test at https://search.google.com/test/rich-results. It parses the JSON-LD, flags missing required properties, and shows a preview of how Google may display the video snippet. Schema.org's Structured Data Linter is a secondary check.

Can I use VideoObject for YouTube-hosted videos on my site?

Yes. When you embed a YouTube video, the video is hosted on YouTube but the schema lives on YOUR page. Set embedUrl to the YouTube embed URL, contentUrl to the direct video URL if you have it (usually you don't for YouTube), and fill in the rest. Google treats your page as the canonical page for that video for search purposes.

Get VideoObject schema for every video, for free.

HostMyVideo emits complete schema on every watch page — with transcript, chapters, and thumbnails — automatically.

Start free 14-day trial See live demo