Video Schema in WordPress: Getting Video Results From a Page That Can Earn Them

A site with forty videos adds VideoObject markup to every item on its gallery page, submits the sitemap, and waits. Three weeks later the Video indexing report shows pages discovered and no video indexed. The markup is valid. The thumbnails are the right shape. Nothing is wrong with the JSON-LD, and nothing is going to happen, because the page it sits on is not the kind of page Google indexes videos from.

The rule is short enough to fit in one sentence, and almost every video schema guide on the internet skips it: a gallery is not a watch page, and Google indexes one video per page.

The Rule the Markup Cannot Override

Google’s video SEO documentation defines the page type before it defines anything else:

A watch page’s main purpose is to show users a single video.

It then lists pages that qualify — a video landing page, an episode player, a news clip, a sports highlight, an events clip — and pages that do not:

A video category page that lists multiple videos of equal prominence

That is a gallery. A grid of forty thumbnails, each linking to a lightbox, each link equally prominent, is the exact page shape the documentation names as not a watch page. The markup does not change the classification. You can validate a perfect VideoObject block on a category page and Google will still treat the page as a category page, because the classification comes from what the page is for, not from what the JSON says.

The indexing requirements say the same thing from the other direction:

The video must be embedded on a watch page. The video can’t be hidden behind other elements.

And the Video indexing report documentation states the consequence plainly:

Google indexes only one video per page.

Read those statements together and the gallery case resolves. Forty videos on one URL cannot produce forty video results, and they usually produce none, because the page’s purpose is browsing rather than watching.

What a Gallery Page Can Still Do

None of this makes the gallery page useless. It has three jobs, and it does all three better than a watch page does.

It is the navigation layer. A gallery earns links, ranks for category queries, and passes visitors and crawlers to individual videos. That is the job the video gallery guide covers: layout, thumbnails, and how the pieces fit together.

It can still carry a video badge. Google’s documentation is explicit that a non-watch page is not excluded from every video surface:

a non-watch page can still be eligible to appear as a text result and Google Image result with a video badge

So a blog post that reviews a video, or a product page with a 360 view, can appear as an ordinary result with a small video marker. That is a different, smaller outcome than a video result, and it is worth having.

It is the place where the decision gets made. A gallery tells you which videos people actually open. That data is the input for the only question that matters here: which of the forty deserve their own URL.

One Video, One URL

The fix is not a markup change. It is a page per video, for the videos that justify one.

Google’s requirement is narrow: each watch page needs a title and description unique to its video. That rules out the shortcut of auto-generating forty pages from a template with the video title dropped into the <title> tag and a two-line excerpt underneath. Those pages exist, they are indexed, and they compete with each other for the same thin content.

A pattern that holds up:

  • A video custom post type with a single template, so the markup is generated in one place rather than pasted into forty pages.
  • A unique title and description written for each video, in the same way you would write them for an article.
  • A transcript below the player. It is the page’s text content, it makes the page accessible, and it gives Google something to match against a query that the video title alone would miss.
  • A link back to the gallery, so the category page keeps its role as the hub.

The guide to turning pages into video content is a useful planning input here, because it starts from pages that already answer a question and asks which ones deserve a video, which is the same prioritisation problem as deciding which videos deserve a page.

Two details from the documentation that people get wrong:

The same video can live on two pages. Google says it is fine to include a video on both a watch page and a news article or product page, and both can be eligible in different ways. You do not have to strip embeds out of blog posts to protect the watch page.

A third-party embed does not block you. If you embed a YouTube or Vimeo player, Google may index the video on your page and on the platform’s equivalent page. Both can appear, as long as both meet the indexing criteria. The video SEO guide covers the surrounding strategy; the markup requirement is the same either way, because your page still has to describe the video itself.

The Three Required Properties, and the Four That Do the Work

The VideoObject documentation separates required from recommended, and the split is smaller than most plugins suggest.

PropertyStatusWhat happens without it
nameRequiredNo title in the result; must be unique per video
thumbnailUrlRequiredNothing to show, and the video may not be indexed at all
uploadDateRequiredNo date, so the result cannot be dated or trusted as fresh
contentUrlRecommendedThe most reliable way for Google to fetch the file
embedUrlRecommendedThe alternative when you cannot expose the file
descriptionRecommendedFalls back to whatever Google can infer from the page
durationRecommendedNo duration shown; ISO 8601 format
creatorRecommendedNo attribution to the person or organisation that made it

The required three are the ones a validator will flag, and they are also the ones a lazy implementation gets wrong, because a title and a date are easy to fake from the post and a thumbnail is not.

uploadDate takes ISO 8601, ideally with a timezone. WordPress produces that format directly through DATE_W3C, which matters because 2026-11-18 alone is valid ISO 8601 but gives Google no time to work with.

duration also takes ISO 8601, and the documentation’s example is the clearest explanation of the format:

PT00H30M5S represents a duration of “thirty minutes and five seconds”

That is not 30:05, and it is not 1805. A string in the wrong format is worse than no duration at all, because it is a value that claims to be something it is not.

contentUrl deserves one warning, because it is the property most often pointed at the wrong URL:

Don’t link to the page where the video lives; this must be the URL of the video file’s actual content bytes itself.

A contentUrl of https://yourdomain.com/videos/steak-grilling/ is not a video file. It is the page you are already marking up. For a self-hosted MP4 the value is the file in wp-content/uploads, and for a YouTube embed you use embedUrl with the player URL instead.

Markup That Comes From the Post, Not From a Form

Most WordPress video schema comes from a plugin field: paste a URL, paste a thumbnail, pick a date. That works until the date is wrong, the thumbnail is deleted, or the field is filled in on a page that is not a watch page.

Generating the block from the post itself removes the second failure mode and makes the first one visible. This goes in a small plugin or the theme’s functions.php:

add_action( 'wp_head', function () {
    if ( ! is_singular( 'video' ) ) {
        return;
    }

    $post_id = get_queried_object_id();
    $meta    = get_post_meta( $post_id, '_video_object', true );

    if ( empty( $meta['content_url'] ) || empty( $meta['thumbnail_url'] ) ) {
        return;
    }

    $schema = array(
        '@context'     => 'https://schema.org',
        '@type'        => 'VideoObject',
        'name'         => get_the_title( $post_id ),
        'description'  => wp_strip_all_tags( get_the_excerpt( $post_id ) ),
        'thumbnailUrl' => esc_url_raw( $meta['thumbnail_url'] ),
        'uploadDate'   => get_the_date( DATE_W3C, $post_id ),
        'contentUrl'   => esc_url_raw( $meta['content_url'] ),
        'creator'      => array(
            '@type' => 'Organization',
            'name'  => get_bloginfo( 'name' ),
            'url'   => home_url( '/' ),
        ),
    );

    if ( ! empty( $meta['duration'] ) ) {
        $schema['duration'] = $meta['duration'];
    }

    echo '<script type="application/ld+json">'
        . wp_json_encode( $schema, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE )
        . '</script>' . "\n";
} );

Four decisions in that block carry the argument:

  • The is_singular( 'video' ) guard. The markup can only appear on a single video page. A gallery, an archive, or a blog post cannot emit it by accident, which is the most common cause of markup on the wrong page.
  • The empty check. No contentUrl or no thumbnail means no block. Half a VideoObject is a failed validator run with a confusing message.
  • wp_json_encode with the slash flags. WordPress’s wrapper handles encoding failures and keeps URLs readable. The flags stop https:\/\/ escaping, which is valid JSON and ugly in the source.
  • The conditional duration. A missing duration is left out rather than emitted as "". An empty string looks like a value in a format Google has to parse, and it fails the check it appears to satisfy.

creator is not a required property, and the block names the site rather than inventing an author. It became documented in September 2026, and the publishing organisation is the accurate value for most setups. If a freelancer or contributor made the video and you have their profile URL, that person is the better value.

Thumbnails, Files, and the Click That Kills the Index

The markup describes the video. The page has to serve it, and the serving rules are where self-hosted WordPress sites lose videos they have already published.

The thumbnail needs a stable URL. The documentation says the video must have “a valid thumbnail that’s available at a stable URL”, and it warns that a URL which changes too often can prevent indexing. A thumbnail served from a CDN with expiring signed URLs, or regenerated with a cache-busting string on every deploy, is a new URL every time. Serve one fixed image per video from wp-content/uploads.

The file needs a supported type. The documented list includes MP4, MOV, WebM, MKV, AVI, and others, in a sentence that ends with a flat exclusion: “Data URLs aren’t supported.” A player fed from a base64 string, or a blob URL created at runtime, is invisible to Google no matter what the markup says.

The player must exist in the HTML. This is the one that catches WordPress sites using a lightweight facade: a poster image and a play button, with the <iframe> or <video> injected only after a click. Google’s requirement is that the video “must be embedded on a watch page” and “can’t be hidden behind other elements”, and the discovery guidance adds:

Don’t rely on user actions (such as swiping, clicking, or typing) to load the video.

A click-to-load facade is good for Core Web Vitals and bad for video indexing, and those two goals genuinely conflict. The resolution is not to abandon the facade everywhere. It is to keep it off the watch pages you want indexed, which are the handful of pages where the video is the reason for the visit. The speed-optimised gallery guide covers the performance side, including when a facade is the right call for the pages that are not watch pages.

A gated video needs paywall markup. If the video sits behind a login or a subscription, Google can still index it when paywall structured data is present. Hiding it without that markup removes it from consideration.

The Video Sitemap Is a Second Channel

Structured data and the video sitemap are not substitutes. The sitemap is a discovery signal, and it carries a few fields that the JSON-LD does not.

The video sitemap documentation lists the required tags: <video:video>, <video:thumbnail_loc>, <video:title>, <video:description>, and either <video:content_loc> or <video:player_loc>. The description caps at 2,048 characters, and the duration is optional:

The duration of the video, in seconds. Value must be from 1 to 28800 (8 hours).

Three constraints that cause rejections in practice:

  • The <loc> is the watch page, not the file. Each <video:video> entry describes one video on the page named by <loc>, which is the same page-oriented logic as the structured data.
  • Everything in the sitemap must be crawlable. No robots.txt disallow, no login, no firewall block, and only HTTP or FTP. Streaming protocols are not supported.
  • The title and description should match the page. They do not have to be word-for-word copies, but a sitemap that describes a different video than the page does is a data quality problem.

If a plugin generates the sitemap from the same post meta as the JSON-LD, the two stay aligned. If they come from different sources, they drift, and nothing in the admin flags it.

Two Reports, Two Different Questions

The Video indexing report answers “does Google have this video”. It counts indexed pages that contain an indexed video, indexed pages that contain a video Google did not index, and a reason for each failure. It covers indexed pages only, so a page that is not indexed does not appear at all.

The report also explains its own totals in a way that stops a common misreading:

Your site has multiple videos per page

and

Your site embeds the same video on multiple pages

Both are listed as reasons the chart totals will not match a count of unique videos. Neither is an error. They are the shape of a normal site.

For one URL, the URL Inspection tool is faster: if a video was found, the results include a Video indexing section, and if no video was detected, that section is absent. An absent section means Google found no video on the page, which is the clearest signal that the player is not in the rendered HTML.

The Rich Results Test answers a different question. It checks that the markup is valid and follows the guidelines. It does not tell you whether the video is indexed, and a green result on a category page is fully consistent with zero video results.

The September 2026 Change Worth Knowing

Google’s documentation updates record a September 24, 2026 entry titled “Added creator property and updated interactionStatistic in VideoObject structured data”. The entry says the change added creator, with support for author, and updated interactionStatistic “to document supported interaction types”.

Two practical readings:

  • Add creator when attribution is real. A named author or the publishing organisation, with a URL that identifies them. It is the same entity signal that matters elsewhere in structured data.
  • Do not invent view counts. interactionStatistic now documents which interaction types are supported, which is an invitation to be precise, not to estimate. A fabricated watch count is a data quality problem with no upside, because no documented feature depends on it.

The VideoObject type page is the reference for the full property set if you need something beyond the documented subset. Properties that Google does not document are not harmful, but they do not earn anything either.

Which of the Forty Videos Deserve a Page

The hard part is editorial, not technical. A site with forty videos does not need forty watch pages, and creating them all at once produces the thin template pages that the unique-title requirement is designed to prevent.

A workable filter, in order:

  1. Does the video answer a query someone types? A product demo titled “Demo” does not. “How to replace a brake pad on a 2019 model” does.
  2. Is the video the reason for the visit? If a reader would rather have a paragraph than a five-minute video, the video belongs inside an article, not on its own URL.
  3. Is there text to go with it? A transcript and a short summary give the page content that a player alone does not.
  4. Can you maintain it? A watch page with a dead video in eighteen months is worse than no page. The documentation covers removing or updating videos for a reason.

Start with the five that pass all four. The guide to making videos that convert is about production choices, and the same choices decide which videos are worth a page: a specific promise, a clear opening, and a reason to keep watching are also what make a page worth indexing.

The video content strategy guide puts the count in context. A smaller library with watch pages and transcripts usually beats a larger library that only exists as a grid.

Verify It Yourself

Three commands, run against a watch page and its gallery:

# 1. A watch page should emit exactly one VideoObject block.
curl -s https://yourdomain.com/videos/brake-pad-replacement/ \
  | grep -c '"@type":"VideoObject"'

# 2. A gallery page should emit zero.
curl -s https://yourdomain.com/videos/ | grep -c '"@type":"VideoObject"'

# 3. The thumbnail must resolve, and must be an image.
curl -sI https://yourdomain.com/wp-content/uploads/2026/11/brake-pad.jpg \
  | grep -i '^HTTP'
curl -sI https://yourdomain.com/wp-content/uploads/2026/11/brake-pad.jpg \
  | grep -i '^content-type'

The first count should be 1. More than one on a single page is a sign that a plugin is emitting a block per attachment or per gallery item, which is the failure this article is about. The second should be 0; if the gallery emits markup, either a plugin is adding it sitewide or the template is looping over videos and printing a block for each.

The third check is the one that catches silent breakage. A 404 on the thumbnail is enough to stop a video from being indexed, and it is invisible in the browser because the player loads its own poster.

For the authoritative answer, use the Video indexing report and URL Inspection. The commands tell you what your server sends. Only Search Console tells you what Google did with it.

FAQ

Why does my gallery page show no video results?

A gallery is a category page, and Google’s documentation explicitly names “a video category page that lists multiple videos of equal prominence” as not a watch page. Video indexing also requires the video to be embedded on a watch page. Without that, the markup has no feature to attach to.

Can I mark up several videos on one page?

You can emit several VideoObject blocks, and validators will accept them. Google indexes one video per page, and the Video indexing report shows information about only one video even when it finds more. If several videos matter equally, they need separate URLs.

Do I need a video sitemap if I already have VideoObject markup?

No, but the two do different jobs. Structured data describes the video on the page; the sitemap helps discovery and carries fields like duration in seconds. Running both is normal, and the risk is drift between them rather than duplication.

How long does a video need to be?

There is no minimum in the structured data. In the sitemap, <video:duration> is optional and must be between 1 and 28,800 seconds if present. Duration affects what Google can display, not whether the page qualifies.

Does VideoObject markup improve rankings?

It makes a video eligible for video features, and eligibility is not a ranking boost. Google’s general guidance is that structured data enables a feature to be present and does not guarantee that it will be. The page’s performance in Search is also a stated precondition for a video to be considered.

Does an embedded YouTube video count as my video?

Google may index the video both on your page and on YouTube, and both versions can appear. Your page still needs its own title, description, thumbnail, and markup. The platform’s markup does not transfer to your URL.

What is a watch page, exactly?

A page whose main purpose is showing one video. Google’s examples include a video landing page, an episode player, a news clip, and a sports highlight. A blog post that reviews a video, or a product page with a 360 view, is explicitly not one.

Why does Search Console say a video is not indexed?

The report lists a reason per page, and the common ones are an invalid or oversized thumbnail, an unsupported file type, a page that is not indexed, or a video that is not embedded in the rendered HTML. Start with the URL Inspection tool, which shows whether a video was detected at all.

A WP Life
A WP Life

Hi! We are A WP Life, we develop best WordPress themes and plugins for blog and websites.