What Is Video Schema?
Video schema is structured data, using schema.org's VideoObject type, that tells search engines the key details of a video on a page: its title, description, thumbnail, upload date, and duration. Marking up videos this way lets Google display them as video rich results, list them in the Videos tab, and unlock features like key moments and live badges. Instead of guessing from surrounding text, search engines read the facts directly, which improves how videos are discovered and shown.
- Schema type
- VideoObject (schema.org)
- Required properties
- name, description, thumbnailUrl, uploadDate (Google Search Central)
- Recommended format
- JSON-LD, though microdata and RDFa are supported (Google Search Central)
- Features unlocked
- video thumbnails, key moments, live badge, video carousels (Google Search Central)
What is video schema, exactly? #
Video schema is a block of structured data that describes a video to search engines in a machine-readable way. It uses the schema.org VideoObject type and is usually added to a page as JSON-LD in the head or body. Instead of forcing Google to guess what a video is about from surrounding text, the markup states the facts directly: the title, a description, a thumbnail image, when it was published, and how long it runs. Search engines use those signals to show the video as a rich result, list it in the Videos tab, and surface it inside features like video carousels. For a local business, that video might be a walkthrough of your shop, a customer testimonial, or a short explainer of how your service works. If you are new to structured data in general, our /wiki/schema-markup-guide explains the fundamentals before you add video-specific markup to your pages.
Which properties does VideoObject need? #
Google requires four properties for a video to be eligible for rich results: name (the title), description, thumbnailUrl (a valid, crawlable image), and uploadDate in ISO 8601 format. Beyond those, recommended properties sharpen how the result appears and how much Google trusts your data. contentUrl points to the raw video file, while embedUrl points to a player. duration uses ISO 8601 duration format, such as PT2M30S for two minutes thirty seconds. For live streams you add a publication object with isLiveBroadcast set to true. The example below shows a complete, valid VideoObject in JSON-LD. Paste your own values, then confirm it parses cleanly with our /tools/schema-validator before publishing. Small formatting errors, like a malformed date or a thumbnail Google cannot fetch, quietly disqualify the video from features, so validation is worth the extra minute every time.
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "How We Replace a Water Heater in Under 2 Hours",
"description": "A step-by-step look at our licensed team installing a 50-gallon water heater for an Austin homeowner.",
"thumbnailUrl": "https://www.example.com/img/water-heater-thumb.jpg",
"uploadDate": "2026-05-14T08:00:00-05:00",
"duration": "PT4M12S",
"contentUrl": "https://www.example.com/video/water-heater.mp4",
"embedUrl": "https://www.example.com/embed/water-heater"
}What video rich results can it unlock? #
Correct markup makes a video eligible, though never guaranteed, for several search features. The most common is a video thumbnail beside your listing, which draws the eye and lifts click-through. Videos can also appear in the dedicated Videos tab, in a video carousel on mobile, and inside Google Discover. Live videos with the right publication data can earn a LIVE badge while broadcasting. Perhaps the most useful for tutorials is key moments, which splits a video into labeled, clickable segments that jump viewers to the right timestamp. Google decides which features to show based on the query, the quality of your data, and where the video is hosted. Structured data is the entry ticket, but the video still competes on relevance and quality. Pair strong markup with genuinely helpful content and you improve your odds across all of these placements rather than relying on the code alone to do the work. It also helps to keep the surrounding page relevant to the video, since Google weighs the whole context, not just the isolated markup, when deciding which enhancement to award and to which query it applies.
How do you host and reference the video file? #
Search engines need to actually access your video to index it, so hosting choices matter. You can self-host an MP4 on your own server and point contentUrl at it, or embed a player from YouTube or Vimeo and use embedUrl. Self-hosting gives you full control and keeps viewers on your site, which helps engagement, but it adds bandwidth load and can slow the page if the file is large. Embedding offloads delivery but sends some attention to the host platform. Whichever route you choose, the thumbnailUrl must be a real, crawlable image at a supported size, and the video must not be blocked by robots.txt. If self-hosting strains your server, our /services/managed-hosting and /services/speed-optimization teams can offload heavy media and keep load times fast, which directly protects the page's Core Web Vitals. A slow-loading video page undermines both user experience and the search performance the markup is meant to support.
What are key moments and how do you mark them? #
Key moments, Google's term for video chapters in search, break a long video into labeled segments that appear directly under the result. A viewer searching how to relight a pilot light can jump straight to that chapter instead of scrubbing. There are two ways to enable them. The simplest is to add clear chapter timestamps in your YouTube description, and Google may generate key moments automatically. For full control on self-hosted video, you add Clip markup with a name, a startOffset in seconds, and a url containing a timestamp fragment. Key moments reward genuinely structured, tutorial-style content, the kind local service businesses often film without realizing its SEO value. A dentist explaining pre-op steps, or an HVAC company walking through seasonal maintenance, both fit naturally. If your video answers a common customer question, chapter markup helps that answer surface at exactly the right second for the person who needs it.
Does video schema help local businesses? #
Yes, in two ways. First, a thumbnail makes your result more visually prominent than plain text links, which lifts clicks even when your ranking position is unchanged. Second, video content increasingly feeds AI-driven answers, and well-structured video is easier for systems to parse and cite, which matters as more searches surface /wiki/what-are-ai-overviews. Practical local uses are everywhere: a roofer's drone footage of a finished job, a gym's facility tour, or a law firm's what to expect at your consultation explainer. Each builds trust before the prospect ever calls, and video tends to increase time on page, a positive engagement signal. The markup itself does not rank you higher directly, but it unlocks the visual features and machine-readability that improve real-world outcomes. Combine it with a solid /services/local-seo foundation so the pages hosting your videos are already competing for the right local queries in your service area.
What are common video schema mistakes? #
The most frequent error is a thumbnail Google cannot fetch, whether from a wrong path, a robots.txt block, or an image that is too small. Next is a malformed uploadDate; it must be valid ISO 8601, ideally with a timezone. Marking up a video that is not actually visible on the page also breaks Google's guidelines, because structured data must match on-page content. Some sites mark up a video that loads only after user interaction, or one that exists purely in a lightbox Google never sees. Others forget duration, or provide a duration that does not match the file. Finally, do not spam markup onto pages with no real video hoping for a thumbnail, since that risks a manual action. Run every template through /tools/schema-validator and Google's Rich Results Test, then spot-check with Search Console's Video enhancement report after deploying. Honest markup that mirrors what users actually see is the whole game.
How do you test and maintain video markup? #
Treat video markup as living code, not a one-time task. Before publishing, validate the JSON-LD for syntax and required properties, then run the page through Google's Rich Results Test to confirm eligibility. After it goes live, Search Console's Videos report shows which pages Google recognized and flags errors at scale. Re-check whenever you migrate hosting, change URLs, or redesign templates, because a /services/website-migrations or /services/website-redesign project can silently strip embedded markup. If you manage many videos, generate the JSON-LD from a template using our /tools/schema-generator so every entry stays consistent. Keep thumbnails, durations, and dates accurate as content changes, since stale data erodes trust over time. For businesses without in-house developers, an ongoing /services/care-plans arrangement keeps structured data healthy through updates. The goal is simple: every video Google can see should be described accurately, every time, so the features you earned do not quietly disappear.
FAQ
Do I need video schema if I use YouTube?
YouTube applies its own structured data on youtube.com, so your channel benefits there. But when you embed that video on your own site, adding VideoObject markup to your page helps your domain earn the thumbnail and video features in search, value YouTube's markup does not pass along to you. For self-hosted pages, schema is essential rather than optional.
Will video schema improve my rankings?
Not directly. Structured data is not a ranking boost. What it does is make your page eligible for video rich results such as thumbnails, carousels, and key moments that raise click-through rate. More clicks and longer engagement can indirectly support performance, but the video and page must still earn relevance for the query on their own merits.
What thumbnail size does Google require for video?
Google recommends high-resolution thumbnails, generally at least 60 by 30 pixels but ideally much larger, in a widely supported format like JPG, PNG, or WebP. The image must be crawlable and not blocked by robots.txt, and it should genuinely represent the video. Providing multiple thumbnailUrl entries at different sizes gives Google useful flexibility.
Can I add video schema to any page?
Only pages where a video is actually visible to users. Google's guidelines require structured data to match on-page content, so marking up a video that is hidden, removed, or loads only in an inaccessible player violates the rules and can trigger a manual action. Marking up one clear primary video per page is the cleanest approach.
How is video schema different from other rich result markup?
It shares the same JSON-LD format and schema.org foundation as the other types covered in our /wiki/schema-markup-guide, but it describes moving media rather than text, reviews, or events. VideoObject unlocks visual features unique to video, such as thumbnails, live badges, and key moments, that text-based types like Article or FAQ simply cannot produce.
How long until video rich results appear?
After Google recrawls and indexes the page, eligibility can register within days, though display is never guaranteed and depends on the query. Speed recrawling by submitting the URL in Search Console and keeping the page in your sitemap. If features do not appear after a few weeks, recheck your markup and confirm the video is fully accessible to Google.
Was this helpful?