Site SEO AI Auditpor Internet Solutions

VideoObject Schema: Markup for Pages With Video

8 de novembro de 20268 min de leituraSEO técnico
VideoObject Schema: Markup for Pages With Video

Short answer: VideoObject is a schema.org type that describes a video on a page: its title, description, thumbnail, upload date, duration and where the file or player lives. Added as JSON-LD, it helps search engines and other systems understand the video and may make the page eligible for video features. The markup must match the visible page, the thumbnail and video address must be reachable, and the video should be a real part of the content. Test with a validator and check Search Console reports after launch.

Video is hard for machines to understand without help. A page may contain an embedded player, but the page alone does not tell a crawler what the video is about, how long it lasts, when it was published or what image represents it. Structured data fills that gap. When it is correct, it can support video results and give assistants clear facts about your content. When it is wrong, it can lead to errors, ignored markup or a loss of trust. This guide explains the properties that matter, shows how to write them, lists common mistakes and describes a simple testing routine. The wider context is in the guide to video SEO and embedded videos.

What VideoObject is for

The schema.org vocabulary includes a type called VideoObject for a video file or a video shown on a page. In search, the markup helps the engine confirm that a page contains a video and learn its basic facts. It is one input among others, because search engines also analyse the page and the video itself. The markup does not guarantee a video result, and it should not be used for content that is not on the page. Think of it as a precise label, not a ranking trick.

The general idea of structured data and its role for AI systems is explained in the guide to structured data for AI search. For the format, JSON-LD is usually the easiest to maintain, as discussed in the guide to JSON-LD and microdata.

The core properties

A basic VideoObject needs a name, a description, a thumbnail URL and an upload date. The name should be the title of the video as shown on the page. The description should summarise the content in a sentence or two, without keyword stuffing. The thumbnail URL points to an image that represents the video, and it must be accessible to crawlers, not blocked by robots.txt or hidden behind a login. The upload date should use a full date format and include a time zone where possible. Requirements and recommendations change from time to time, so check the current documentation of the search engine whose features you want.

The thumbnail should be a real, clear image, large enough to be useful, and its address should be stable. Avoid thumbnails that change at every request, and avoid placeholder images. If your platform generates several sizes, offer the largest sensible one.

Properties that add value

Beyond the basics, several properties help. The duration, written in the ISO 8601 format such as PT4M30S for four and a half minutes, tells systems the length. The contentUrl gives the address of the actual video file, and the embedUrl gives the address of the player. Provide the one that you can, and make sure it is reachable. If the video expires, the expires property tells engines when it will no longer be available. The interactionStatistic can show view counts, but only include figures that match the page.

For videos in several languages or with subtitles, describe the language and offer transcripts on the page, as described in the guide to multilingual video subtitles. A transcript is not a property, but it gives readers and machines the content in text.

A simple JSON-LD example

A basic block looks like this in words: the script is of type application/ld+json, with a context of schema.org, a type of VideoObject, a name, a description, a thumbnailUrl pointing to the image, an uploadDate such as 2026-09-14T08:00:00+02:00, a duration such as PT3M20S and an embedUrl pointing to the player. Place the script in the head or the body of the page that shows the video. One video per object, and if a page has several videos, include several objects, each matching a visible video.

If your structured data uses identifiers to connect entities, keep them consistent, as covered in the guide to linked structured data with IDs. Link the video to the page it belongs to and, where relevant, to the organisation that published it.

Key moments, clips and chapters

Long videos are easier to navigate when they have chapters. You can describe parts of a video with Clip markup, giving each part a name, a start offset and an end offset, so that search engines can show key moments. Another option is to explain how a player supports seeking, so that engines can build their own moments from a time parameter in the URL. Some platforms detect moments automatically. If you add chapters, make them the same as the chapters visible on the page, with descriptive titles rather than numbers.

Good chapters also help readers. A list of timestamps with short titles under the video works for both humans and machines, and it matches the guidance for answer-friendly structure in the guide to passage chunking.

Make the page and the video crawlable

Markup cannot fix a page that crawlers cannot read. Make sure the page with the video is indexable, that the video is visible on the page without a click that loads it only afterwards, and that the player does not require special permissions. If you load videos lazily, check that the structured data and the embed address are present in the HTML, a topic described in the guide to lazy loading and SEO. A heavy auto-playing video can slow the page, so balance speed and experience, following the guide to page speed for AI crawlers.

List videos in a video sitemap if you have many, and keep the information the same in the sitemap and the markup, as explained in the guide to image and video sitemaps.

Common errors to avoid

The most frequent problems are simple. Missing or invalid dates, a thumbnail that returns an error, a duration in the wrong format, a description that is empty or copied from another page, and markup for a video that is not on the page. Others include marking up many videos on a category page where none is the main content, using the same video markup on dozens of pages that only link to the video, and leaving old markup after the video has been removed.

Also avoid claims in the markup that do not match the page, such as a different title or a wrong upload date. If a platform plugin adds markup automatically, review what it outputs, since duplicates and conflicts are common when several plugins act at once. The most common fixes are described in the guide to fixing structured data errors.

Choose the right page for the markup

Search engines look for a page where the video is the main content or a central part of it. A page that is mostly text with a small video at the bottom is less likely to be treated as a video page, though the markup may still be useful for understanding. A category page that lists thirty videos should link to the individual video pages and carry the markup only on those pages, not on the list. If you publish the same video in several places, choose one main page, point the others to it with canonical tags and avoid repeating the same markup on each, as discussed in the guide to canonical tags.

Make the page worth visiting for a reason beyond the video. Add a summary, key points, a transcript, related links and a clear title. These elements turn a thin page into a useful resource, and they help people who cannot or prefer not to watch, such as those in a quiet place or on a slow connection. They also give assistants text that supports what the markup says. Keep the visible title, the markup title and the player title the same, so that systems see one consistent description.

When a video is removed, decide what happens to the page: keep it with a note, redirect it to a replacement or return an error status, using the guidance for removed content in the guide to 410 and 404 status codes. Remove the markup in the same release, so that you do not describe a video that no longer exists.

Test and monitor

After adding markup, test a few pages with a structured data testing tool and the rich result test of the search engine, then view the rendered HTML to confirm that the script is present. The tools differ in what they check, as compared in the guide to structured data testing tools. After launch, open the video indexing report and the enhancement reports in Search Console and watch for errors and warnings. Fix problems by template, not page by page, and record each change.

Give the system time. Reports update with a delay, and eligibility for a feature is never guaranteed. Measure the effect on visibility and clicks over weeks, not days.

Site SEO AI Audit crawls your website and checks structured data, titles, descriptions, headings, status codes, broken links, page speed and AI visibility settings, which helps you find pages where video markup is missing or broken in the HTML. It does not analyse the video files themselves. The first audit of up to 200 pages is free, and larger sites can see the pricing page.

Related reading

The bottom line

Mark up only videos that are really on the page, keep every address reachable and test before and after launch.

FAQ

Is VideoObject markup required to rank a video?

No. It helps search engines understand the video and may support video features, but it is not a ranking requirement.

Do I need markup for YouTube embeds?

It can still help, because it describes the video on your page. Make sure the details match the page and the embed.

What format should the duration use?

Use the ISO 8601 duration format, for example PT3M20S for three minutes and twenty seconds.

Can I mark up several videos on one page?

Yes, with one object for each video that is visible on the page. Do not mark up videos that are not there.

Why does my markup show errors in Search Console?

Common causes are missing dates, unreachable thumbnails, wrong formats or conflicting markup from plugins. Check the details in the report.

#Indexing#Structured data#Technical SEO#Video SEO
Audite seu próprio site.O Google enxerga o seu site?
Comece grátis
Internet Solutions

Mais da nossa equipe

Feitas pela Internet Solutions. Experimente nossos outros produtos — cada um economiza seu tempo de um jeito diferente.

internet-solutions.net ↗