Millions of business videos sit on well-optimised pages and still never appear in Google rich results or AI search citations. The reason is rarely the video quality. It is that search engines and AI systems cannot watch a video; they read data. Video schema markup is the structured code that tells them exactly what your video contains, who made it, and when it was published. By the end of this guide, you will be able to build valid VideoObject JSON-LD for your own setup, test it correctly, and understand precisely what it takes to become eligible for rich results. This is also a technical layer that specialist video production companies now apply as standard, so you can either implement it yourself using what follows, or hand it off to a production partner.
The stakes are real. Without structured data, a professionally filmed video and a page full of well-written copy still leaves Google guessing. With it, your content becomes machine-readable and citable, eligible for video rich results in Google Search and increasingly visible in AI-generated answers. That is a significant difference in organic reach, and it starts with understanding the VideoObject schema.
What video schema markup is and why search engines need it
Search engines and AI systems primarily process text and structured data rather than audiovisual content. When a video sits on a page without markup, Google can only infer its subject from surrounding text, page titles, and whatever metadata the hosting platform provides. Video schema markup bridges that gap by providing a machine-readable data layer attached directly to the page. It uses the schema.org video markup vocabulary, a shared standard maintained by Google, Bing, and other major search engines that allows machines to parse content without ambiguity.
Within the schema.org vocabulary, VideoObject is a specific type designed for video content. It differs significantly from general schema types like Article, WebPage, or LocalBusiness. Those types describe static page content and organisational details. VideoObject carries properties for playback URLs, thumbnail images, upload dates, and durations, properties that no general-purpose schema type can accommodate. This distinction matters both for Google’s rich results system and for AI systems that need to identify and cite video sources accurately. A LocalBusiness schema tells Google where you are. A VideoObject schema tells Google what the video contains, how long it runs, and where to find a frame from it.
The VideoObject properties that control rich result eligibility
Google mandates four properties for a page to be eligible for video rich results: name, thumbnailUrl, uploadDate, and at least one of contentUrl or embedUrl. Each one is non-negotiable. A missing uploadDate alone can disqualify an otherwise complete VideoObject. The name is the video title as it should appear in search results. The thumbnailUrl must be a publicly crawlable image URL with a minimum size of 112×112 pixels, though 1280×720 is the practical standard and will serve you far better in search carousels. The uploadDate must be in ISO 8601 format: for example, 2026-05-19, not “19 May 2026”. The URL properties tell Google where the video can be played back. According to Google’s VideoObject guidance, including both contentUrl and embedUrl together is recommended even when only one is technically required.
Beyond the required four, several properties meaningfully improve indexing quality and AI citability. description should be a specific, unique summary of what the video covers, not a generic marketing line. duration uses ISO 8601 format (covered in the next section) and functions as an eligibility signal as well as a descriptive property. publisher identifies the organisation that produced the video, which builds authority associations over time. interactionStatistic carries view count data via WatchAction. For time-sensitive content, expires signals when a video will become unavailable. For UK-localised content, including inLanguage set to en-GB adds useful context for regional search. These recommended fields form the basis of a strong video SEO schema implementation.
Video schema markup examples for the three most common setups
Place your VideoObject JSON-LD where it will be present in the server-rendered HTML, the is a reliable location. Avoid client-side injection that only appears after rendering, as this can lead to Search Console reporting discrepancies, particularly on CMS-built sites where JSON-LD is sometimes injected by plugins after the initial page load.
Note that the JSON-LD examples below use the @context value that points to the schema standard; you can review the canonical definition of the VideoObject type on schema.org’s VideoObject page for the full property list and expected formats.
Video schema example: self-hosted video
For a self-hosted MP4, contentUrl points directly to the video file URL. One common failure point at this stage is CDN URL instability, if the file path changes after deployment, your markup will reference a broken URL and fail validation silently. If you also have an embed player on the same domain, include embedUrl alongside contentUrl; both together improve your chances of a rich result appearing.
This video schema example demonstrates all four required properties plus duration and embedUrl, the recommended combination for self-hosted video.
Video schema example: YouTube and Vimeo embeds
For YouTube embeds, embedUrl takes the format https://www.youtube.com/embed/{videoId}, while contentUrl uses the standard watch URL. For Vimeo, embedUrl uses the Vimeo player URL. A common misconception is worth clearing up: YouTube and Vimeo generate their own schema internally for their own platforms. Adding VideoObject markup to your page signals to Google that the video belongs to your content and your domain. It is the markup on your page that increases your chances of earning the rich result, not the video platform. Without markup on your page, the rich result, if it appears at all, is more likely to point to YouTube than to you, though Google’s final attribution will depend on ranking signals and context.
This video schema example shows the correct embedUrl and contentUrl pattern for a YouTube-hosted video embedded on your own page.
For additional, practical implementation notes on video schema pieces, see the guidance from developers who build SEO-focused CMS features such as Yoast’s video schema documentation.
Thumbnail, duration, and transcript: getting the technical details right
Google requires the thumbnail URL to be crawlable and publicly indexable. The practical standard is 1280×720, in JPG or PNG format, with no robots.txt blocks on the image URL. A visually strong thumbnail also improves click-through rate if the rich result does appear, so this is not purely a technical consideration. One common failure point: thumbnail URLs behind CDNs with authentication layers or aggressive caching rules sometimes fail validation silently, appearing correct in the Rich Results Test but returning errors in Search Console once the page is live.
For practical design and optimisation advice, publishers can follow industry best practices such as these 5 tips for better video thumbnails, which cover sizing, composition, and text treatment for higher click-through rates.
The duration property uses ISO 8601 duration syntax, which trips up developers regularly. The format is PT followed by H for hours, M for minutes, and S for seconds. Three minutes and twenty seconds is PT3M20S. One hour and five minutes is PT1H5M. Five minutes and thirty seconds is PT5M30S. Google requires the video to be at least 30 seconds long to qualify for rich results, which means the duration value functions as an eligibility signal as well as a descriptive property. Videos with no duration property are less likely to be displayed even if they meet the minimum length.
The transcript property is optional, but it serves two purposes that matter directly for AI search visibility. It gives search engines a full text record of what the video contains, and it helps meet WCAG accessibility standards for users who cannot hear the audio. There is also growing evidence that AI systems draw on transcripts when assessing whether a video is a relevant, citable source for a given query, a complete, accurate transcript gives an AI system far more to verify than a brief description field alone. If you are already producing transcripts for accessibility compliance, and for UK businesses subject to the Equality Act, there is a strong case to do so, submitting them via schema costs nothing additional.
How to test your video structured data and fix common errors
Testing video schema markup follows a two-stage workflow. Before or immediately after publishing, use Google’s Rich Results Test at search.google.com/test/rich-results. Paste the page URL or the raw JSON-LD code to check for errors and warnings. Errors block eligibility entirely; warnings reduce your chances but do not disqualify the markup. Once the page is live and has been crawled, monitor the Enhancements section of Google Search Console under the Video report. This second stage catches production errors that the tester may have missed, particularly where JSON-LD is injected by JavaScript after the initial page load and is not present in the server-rendered HTML that Googlebot first reads.
For the latest official requirements and examples, consult Google’s Video structured data documentation. For further practical guides and case studies, see our Video SEO Archives.
The five errors that appear most often in validation are straightforward to fix once you know what to look for:
- Missing required properties: usually uploadDate or thumbnailUrl. Fix by adding the missing field with a valid value in the correct format.
- Invalid date format: using a date like “19 May 2026” instead of ISO 8601 “2026-05-19”. Always use the YYYY-MM-DD structure.
- Invalid thumbnail URL: image blocked by robots.txt or behind authentication. Move the image to a publicly accessible path and verify using a browser in incognito mode.
- JSON syntax errors: missing commas, unclosed brackets, or duplicate keys. Run the raw JSON through a linter before deploying, jsonlint.com or the Code tab in the Rich Results Test both work well.
- Markup not associated with a watchable video: schema placed on a page where the video does not appear. Google treats this as misleading structured data, which carries a manual actions risk beyond simply losing rich result eligibility.
What it looks like when video schema is handled as standard
Most video production companies deliver a finished video file and leave the technical indexing entirely to the client. The result is that professionally produced, high-quality videos sit on well-designed pages and never appear in rich results or AI citations because no one added the structured data layer. Many UK businesses have yet to implement video schema markup, and adoption across several sectors appears to lag behind more technically mature markets. That gap is an opportunity: businesses that implement VideoObject markup now are competing against a majority that still have not.
This Video Works includes video schema markup as part of its standard client delivery. VideoObject JSON-LD is built directly into the page alongside the video transcript and thumbnail optimisation, so clients do not need to understand JSON-LD or test their markup manually. For businesses that want their video content indexed, cited by AI systems, and eligible for rich results from the moment it goes live, having schema markup handled at the production stage removes the most common point of failure entirely. Read more about our approach in AI-optimised video content: what it really means in 2026.
Putting it all together
Video schema markup is not a bonus SEO technique. It is the technical requirement that makes video content readable and citable by both Google and AI systems. The VideoObject properties covered here, name, thumbnailUrl, uploadDate, contentUrl(or embedUrl), description, and duration, form the foundation of any valid implementation. Testing through the Rich Results Test and monitoring via Search Console closes the loop and keeps your markup valid as pages change over time.
For businesses working with a production partner, it is worth asking one direct question: is video schema markup included in the delivery as standard, or is it something you will need to add yourself after the fact? If you’re reviewing partners, our Video Marketing overview explains how technical delivery fits into broader campaign planning. The difference between a video that earns search and AI visibility and one that sits invisible in a media library often comes down to this single technical layer. If you want to talk through how schema markup fits into a video production project, get in touch with This Video Works, this is exactly the kind of detail built in from the start.
