Embedding a video on a page does not make that video exist for Google. What the browser shows is a player frame: the name of the file inside it, its duration, what it covers and when it was published are often written nowhere in the page's HTML. Google tries to fill this gap on its own, but when the only clue it has is an iframe address, it is likely to treat the page as an ordinary text result instead of identifying the video.
VideoObject is the structured data type that closes this gap. It declares the video's title, thumbnail, duration and publication time in a machine-readable form. However, writing the markup correctly is only half of getting a video result. The other half is a condition most guides skip: what kind of page the page itself is.
What exactly VideoObject schema tells Google
Google tries to understand video details on its own. VideoObject lets you steer that guesswork: you decide information such as the description, thumbnail URL, upload date and duration shown in video results. The markup also makes the video easier to find.
The surfaces where videos can appear are not limited to one place. The main search results page, the Videos mode, Google Images and Discover are different display channels. On top of these, additional features such as the live badge and key moments can kick in, depending on how the page is marked up.
One caveat here. Google does not guarantee that adding markup will result in a particular video feature, and some features may not be eligible to trigger for some queries. Schema produces eligibility, not results.
Fewer required fields, and more decisive recommended fields, than you think
Most Turkish-language resources list four required fields for VideoObject and include description in the list. In Google's own definition, there are three required fields.
- name: The title of the video. It must be unique for each video on the site.
- thumbnailUrl: The URL pointing to the video's unique thumbnail file. It is a repeatable field, and multiple sizes can be provided.
- uploadDate: The date and time the video was first published, in ISO 8601 format. If you don't specify a time zone, the time zone used by Googlebot is assumed.
The remaining fields fall into the recommended category, but "recommended" does not mean "optional decoration" here. The description, duration, contentUrl, embedUrl, expires and hasPart fields directly determine the information density of the result and which features you are eligible for. The duration field is written in ISO 8601 duration format: PT00H30M5S represents a video thirty minutes and five seconds long.
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "Setting up category page filters",
"description": "A walkthrough video showing step by step when filter parameters should produce indexable pages.",
"thumbnailUrl": [
"https://example.com/images/filter-setup-1280x720.webp",
"https://example.com/images/filter-setup-640x360.webp"
],
"uploadDate": "2026-05-14T09:30:00+03:00",
"duration": "PT14M22S",
"contentUrl": "https://example.com/video/filter-setup.mp4",
"embedUrl": "https://example.com/player/filter-setup",
"inLanguage": "en"
}A warning: the name, description and thumbnailUrl values must be unique for each video on the site. The most common mistake on corporate sites is stamping the same template description and the same brand image onto every video page. This leaves the markup technically valid but with zero distinguishing power.
The difference between contentUrl and embedUrl is the detail that costs the most in practice
Both are URL fields, and neither is the page's address. The distinction is this:
- contentUrl points to the actual content bytes of the video file. This is the most effective way for Google to fetch your video file, and this field should be provided whenever possible.
- embedUrl is the address of the player that plays the video. It is usually the
srcvalue of theiframeorembedtag on the page.
Writing the address of the page where the video is published into both fields is a common mistake and leaves the fields useless. If contentUrl cannot be provided, embedUrl is provided instead.
The practical consequence of this distinction ties directly to feature eligibility. For features such as video previews and key moments to work, Google must be able to successfully fetch the actual bytes of the video file. So blocking the streaming file's URL with robots.txt or noindex, keeping the video file at changing addresses or having a server that can't handle crawl requests switches off these features, even if the schema is flawless.
Schema that fails the thumbnail rule fails silently
The prerequisite for being eligible to appear in video features is that the video has a thumbnail. If Google can fetch your video files, it tries to generate the thumbnail itself; if you want to decide which image is used, you declare it through one of four sources: the poster attribute of the video tag, the video:thumbnail_loc tag in a video sitemap, the thumbnailUrl field in structured data or the og:video:image property in the Open Graph protocol. If you use more than one, you need to provide the same image URL in all of them.
The technical conditions the image must meet are also clear:
- Supported formats: BMP, GIF, JPEG, PNG, WebP, SVG and AVIF.
- Size: at least 60x30 pixels; larger is preferred.
- Access: Googlebot and Googlebot-Image must be able to reach the file, the file must not be blocked by robots.txt or a login requirement, and it must sit at a stable URL.
- Transparency: at least 80 percent of the pixels must have an alpha value above 250, meaning the image must be largely opaque.
The last item explains why PNG cover images with transparent backgrounds prepared on the design side are silently filtered out. No error shows up in the schema, yet the rich result still doesn't come.
If there is no video result despite correct schema, the problem is the page type
This section corrects the false assumption that wastes the most time in practice. Google reserves video features, including video results on the main search results page and the Videos mode, for pages where the video is the main reason the page exists. These pages are called watch pages, and the definition is simple: the main reason the user visits the page is to watch a single video.
Google's own distinction looks like this:
| Counts as a watch page | Does not count as a watch page |
|---|---|
| Video landing page | Blog post reviewing an embedded video |
| TV series episode player page | Product page hosting a 360-degree video of the product |
| News video watch page | Video category page listing multiple videos with equal prominence |
| Sports highlights page | Movie review page with an embedded trailer |
| Event clip page |
What the right-hand column has in common is that the video is an element that complements the other content on the page. Writing VideoObject on these pages is not wrong, and it is not wasted either: a page that is not a watch page may be eligible to appear as a text result and as a Google Images result with a video badge. But expectations should be set accordingly. When you add VideoObject for a promotional video on product pages, the goal is not to get a video thumbnail placed next to the product result but to accurately declare the video's existence and content.
If the video is an asset that should appear with video features, the solution is not to force the markup but to give that video its own watch page. It is not a problem for the same video to be on both a watch page and a news article or product page. Each watch page needs a page title and description specific to that video.
There is one more related rule: the main structured data type reflecting the page's primary focus must be present. If you put only Video markup on a page that is mostly a recipe, Google will not have enough information to show that page as a recipe rich result. Video schema does not replace the page's main type; it is added alongside it.
How to control key moments with Clip and SeekToAction
Key moments let users navigate a video like chapters in a book. Google tries to detect segments automatically; when you declare them, it gives priority to the ones you define. There are two ways to take control.
- With Clip, you write the start and end time and the label of each segment yourself. Its required fields are
name,startOffset(the start in seconds) andurl(a link pointing to the same URL path as the video and carrying a time parameter);endOffsetis recommended. It is supported in all languages where Google Search is available. - With SeekToAction, you don't write segments one by one; you declare where in your URL structure you put timestamps, and Google determines the key moments itself. Turkish is among the supported languages.
"hasPart": [
{ "@type": "Clip", "name": "Deciding on filter parameters",
"startOffset": 45, "endOffset": 180,
"url": "https://example.com/video/filter-setup?t=45" },
{ "@type": "Clip", "name": "Checking the canonical",
"startOffset": 181, "endOffset": 320,
"url": "https://example.com/video/filter-setup?t=181" }
]Defining segments manually makes sense when you want to decide which section appears with which title. If you want to switch the feature off completely, including automatic detection, the nosnippet rule is used. If the video is hosted on YouTube, key moments are managed not with Clip markup but with timestamps in the YouTube description.
Self-hosting or YouTube?
Schema does not make this decision; the business model does. A real comparison of the two options looks like this:
| Criterion | Hosting on your own site | Embedding via YouTube |
|---|---|---|
| Ability to provide contentUrl | Possible; Google can fetch the file directly | Not possible; only embedUrl remains |
| Control over key moments | From schema, via Clip or SeekToAction | From timestamps in the YouTube description |
| Infrastructure load | A server able to handle storage, streaming, the player and crawl traffic | No load on the hosting and transcoding side |
| Where the viewer goes | Traffic stays on your own domain | Part of it happens on YouTube |
| Additional visibility surface | Only your own page | YouTube is a search surface in its own right |
The honest conclusion is this: for most sites, YouTube is the practical choice. The infrastructure cost of hosting video, player maintenance and crawl load rarely pay off for a business where video is not the product. Moreover, when you embed a third-party player, Google may index the video both on your page and on the platform's equivalent page, and both versions may appear if the pages are eligible. Even in this case, it is recommended that you provide structured data for your own watch page and add those pages to your video sitemap.
Self-hosting plus a VideoObject setup wins in a narrow set of scenarios: education and course sites where the video itself is the product being sold, publishers that gather news and sports clips on their own domain, platforms that need to control viewing data and player behavior, and content that would be commercially problematic to move to YouTube. In these scenarios, the feature eligibility that comes with contentUrl and a watch page architecture make a real difference.
As video's share of brand visibility grows
Video is no longer just a page element; it is a source layer where the brand's name appears. In Ahrefs' study of 75,000 brands, a rank correlation of 0.737 was measured between the brand name appearing in video titles, descriptions or transcripts and the brand's visibility in AI answers, and this was the highest value among the signals examined in the study. This is a correlation, not proof that publishing video leads to AI visibility; large, well-known brands being mentioned in more videos and appearing in more answers can produce the same result.
The practical takeaway, without exaggeration, is this: video is not a standalone lever for visibility in generative search engines but a second mention surface that sits alongside text content. In this picture, VideoObject schema makes sure the video is described correctly in search; what produces mentions is the video itself and the quality of its content.
Checks to pass before going live
Once the schema is written, the following are verified in order:
- Is the video on the page in a common HTML element? Google can find videos provided with
video,embed,iframeandobjectelements. - Does loading the video require a user action such as scrolling or clicking? If so, the video cannot be found.
- If the video is added with JavaScript, does it appear in the rendered HTML? This is checked with the URL Inspection tool.
- Is a fragment identifier used to load the video? Google generally does not support fragment URLs.
- Is the thumbnail file at a stable URL and open to crawlers?
- Is the information in the schema consistent with the actual video content and other metadata?
- Is the markup syntactically valid? Critical errors are fixed in the Rich Results Test validation step; then a few pages go live and the URL Inspection tool is used to test how Google sees the page.
The order of this list matters. Syntax validation should be left until last, because most errors are not in the syntax but on the accessibility and page type side. A valid JSON-LD block will not rescue a thumbnail blocked by robots.txt or a page that is not a watch page.
Frequently Asked Questions
Does adding VideoObject mean the video will definitely appear as a video result?
No. Markup produces eligibility, not a guarantee. Google does not commit to triggering a particular video feature, and some features may not be eligible to appear for some queries.
What should you do if there are multiple videos on the same page?
A page listing multiple videos with equal prominence does not count as a watch page. If one of the videos really is the focus of the page, the structure is built accordingly; if they all carry equal weight, giving each video its own watch page is the way to become eligible for video features.
Does the video play directly in the search result?
Google does not show the video file directly in search results. A user who clicks a video result is sent to your site to watch the video. That is why the speed of the watch page and the player's behavior in the first second are as decisive as the result itself.
What should go in the schema if you know the video will be taken down?
The expires field is written only if the video really has an end of validity. Adding this field to a video that does not expire can cause the content to be treated as unavailable for no reason.
