How to Fix Missing VideoObject Schema on Video Pages

Your audit found pages that contain a video, such as a native <video> tag, a YouTube or Vimeo iframe, or a lazy-loaded video facade, but no VideoObject structured data. By the end of this guide every video page will carry valid VideoObject JSON-LD with name, description, thumbnailUrl and uploadDate, and you will have checked it in Google's tools.

By Updated ⏱ 20-40 minutes for a template fix; about 5 minutes per page for one-off pages🎯 Beginner● Medium impactContent
Illustration: VideoObject schema for videos fix guide
CONTENT · FIX GUIDE VideoObject schema for videos IMPACTEFFORT TIME20-40 minutes for a template fix; about 5 minutes per page for one-off pages LEVELBeginner

Why it matters

Without VideoObject markup, Google has to guess a video's title, thumbnail and date from the embed. That often means the video is not indexed, does not appear in the Videos tab, and gets no video thumbnail or key moments in results. Explicit markup also hands AI answer engines a clean, citable summary of what the video covers, which helps them describe and link your page.

Pages with lazy-loaded facades benefit most, because the real player isn't in the HTML until someone clicks it.

✕Beforehttps://example.com/how-to-install hasa YouTube iframe but only Organizationand BreadcrumbList JSON-LD, with no✓Afterhttps://example.com/how-to-installincludes a VideoObject block (name,description, thumbnailUrl, uploadDate,

What you need

A list of the URLs flagged by the audit as video pages
Access to edit page templates, theme code or per-page custom code in your CMS
Each video's title, description, thumbnail image URL and publish date
Google Rich Results Test (search.google.com/test/rich-results)

Step-by-step fix

1

List every page that contains a video

Start with the URLs from the audit. Then check your templates for anything else that renders a video. The audit counts three kinds of embed:

  • native <video> elements
  • <iframe> embeds from YouTube, Vimeo, Wistia and similar hosts
  • click-to-load facades such as lite-youtube or a thumbnail that swaps in a player

Muted background or hero videos count too. Group the pages by template (blog post, product, landing page) so you can fix many pages with one change.

Pro tip: In Screaming Frog, use Configuration > Custom > Custom Search with 'Contains' set to youtube.com/embed, player.vimeo.com or <video. That finds every embed in one crawl.
2

Collect the metadata for each video

Google requires name, thumbnailUrl and uploadDate for VideoObject. description is strongly recommended and is part of what the audit expects. g.

PT4M35S for 4 minutes 35 seconds. Write the description to match what the video actually shows, not a copy of the page's meta description.

Pro tip: For YouTube, a public thumbnail follows the pattern https://i.ytimg.com/vi/VIDEO_ID/maxresdefault.jpg. Use hqdefault.jpg if the max-resolution version doesn't exist. Copying the upload date from the YouTube watch page is the safest choice for uploadDate.
3

Write the VideoObject JSON-LD block

Create one script block per video using the template below. Use absolute HTTPS URLs. Give uploadDate as an ISO 8601 date, ideally with time and timezone (2026-03-12T09:00:00+00:00).

txt, and it should be at least 60x30 px; 1280x720 is ideal.

html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to install the Example Co wall bracket",
  "description": "Step-by-step walkthrough of mounting the Example Co wall bracket on drywall, including stud finding and torque settings.",
  "thumbnailUrl": "https://example.com/images/wall-bracket-video.jpg",
  "uploadDate": "2026-03-12T09:00:00+00:00",
  "duration": "PT4M35S",
  "embedUrl": "https://www.youtube.com/embed/VIDEO_ID",
  "publisher": {
    "@type": "Organization",
    "name": "Example Co",
    "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" }
  }
}
</script>
Pro tip: If you self-host the file, add "contentUrl": "https://example.com/videos/wall-bracket.mp4". Google can then fetch the actual video bytes, which makes indexing more reliable.
4

Handle pages with several videos or existing schema

For multiple videos, add one VideoObject per video, either as separate script blocks or inside a single @graph array. If the page already outputs Article, HowTo or Product schema, you can nest the VideoObject under that entity's video property instead. It is still recognised as VideoObject markup.

Don't add a VideoObject for a video that isn't on the page.

html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "VideoObject",
      "name": "Unboxing the Example Co kit",
      "description": "What comes in the box and how to check every part.",
      "thumbnailUrl": "https://example.com/images/unboxing.jpg",
      "uploadDate": "2026-02-01T10:00:00+00:00",
      "embedUrl": "https://player.vimeo.com/video/VIDEO_ID"
    },
    {
      "@type": "VideoObject",
      "name": "Assembling the Example Co kit",
      "description": "Full assembly in under ten minutes.",
      "thumbnailUrl": "https://example.com/images/assembly.jpg",
      "uploadDate": "2026-02-03T10:00:00+00:00",
      "embedUrl": "https://player.vimeo.com/video/VIDEO_ID_2"
    }
  ]
}
</script>
Pro tip: For long tutorials, add "hasPart" with Clip items (name, startOffset, endOffset, url). This makes the video eligible for key moments in search results.
5

Add the markup at the template level

Insert the JSON-LD in the <head> or anywhere in the <body> of each video page. Where possible, generate it from your CMS fields (title, excerpt, featured image, publish date) inside the template. That way new video pages get markup automatically instead of relying on someone remembering to paste it.

js, render it as a script element in the page component, as shown below.

javascript
export default function VideoSchema({ video }) {
  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'VideoObject',
    name: video.title,
    description: video.description,
    thumbnailUrl: video.thumbnail,
    uploadDate: video.publishedAt,
    duration: video.duration,
    embedUrl: `https://www.youtube.com/embed/${video.youtubeId}`
  };
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, '\\u003c') }}
    />
  );
}
Pro tip: Make sure the markup is in the server-rendered HTML. Schema injected only after a user clicks a facade or loads the player won't be seen by crawlers.
6

Validate, deploy and re-run the audit

Paste a fixed URL into the Rich Results Test and confirm a Videos item appears with no errors. Clear page or CDN caches, then re-run the audit to confirm the flagged pages now pass. In Google Search Console, open Indexing > Videos over the following weeks to see which video pages Google has indexed.

Pro tip: Use URL Inspection > Request indexing in Search Console on your most important video pages to speed up recrawling.

Platform-specific notes

WordPress

Rank Math can output Video schema through the Schema tab in the post editor (Schema Generator > Video Schema). Its autodetect option is under Rank Math > Titles & Meta > Posts. Yoast needs the paid Video SEO add-on. Without a plugin, paste the script block into a Custom HTML block in the post, or use WPCode to add it per page.

Shopify

In Online Store > Themes > Edit code, open the main product section (e.g. sections/main-product.liquid). Loop over product.media and, for media.media_type 'video' or 'external_video', output VideoObject using product.title | json, media.preview_image | image_url: width: 1280 | prepend: 'https:', and product.published_at | date: '%Y-%m-%dT%H:%M:%S%z'. For YouTube media, set embedUrl to https://www.youtube.com/embed/{{ media.external_id }}. Check that your theme or an app isn't already outputting VideoObject before adding your own.

Wix

Open the page in the Editor, go to Pages & Menu > page settings (…) > SEO basics > Advanced SEO > Structured data markup, and paste the JSON object without the script tags. For dynamic pages, add the markup in the dynamic page's SEO settings using collection field variables.

Webflow

For static pages, use Page settings > Custom code > Inside <head> tag. For CMS template pages, put the script in the template's custom code and insert collection fields (Name, Video Thumbnail, Published On) through the '+ Add Field' picker.

Next.js

Render the JSON-LD as a <script type="application/ld+json"> element inside the page or layout component, not via next/script with lazy strategies. Escape '<' characters in JSON.stringify output to avoid XSS when values come from a CMS.

Check that it worked

✅ How to verify

  • Run the page through Google's Rich Results Test and confirm a valid 'Videos' item with name, thumbnailUrl and uploadDate detected.
  • View the page source (Ctrl+U / Cmd+Option+U) and search for "VideoObject" to confirm it is in the server-rendered HTML.
  • Re-run the site audit and check that the 'VideoObject schema for videos' check passes for all video pages.
  • Monitor Search Console > Indexing > Videos for the pages moving into 'Video indexed'.

⚠️ Common mistakes

  • Adding the markup only to the homepage or a single sample page, while the template-driven blog or product pages with embeds stay unmarked.
  • Using a relative or blocked thumbnailUrl, or an uploadDate in a non-ISO format like '12/03/2026'. This makes the markup invalid for Google.
  • Injecting the JSON-LD only after the video facade is clicked, so crawlers never see it.
  • Copying one generic VideoObject (same name and thumbnail) across many pages instead of describing each page's actual video.

Is this still an issue on your site? Run a free audit — ZORO checks this and 294 other SEO, AI-visibility, accessibility and security signals, with fixes for your platform.

Check my site free

FAQ

Do I need VideoObject schema for embedded YouTube videos?

Yes, it helps. Google can sometimes read YouTube embeds without it, but explicit VideoObject markup on your page tells Google your page hosts the video. It also supplies the title, thumbnail and date, which makes video indexing and thumbnails for your URL far more reliable.

What are the required properties for VideoObject?

For Google video rich results, name, thumbnailUrl and uploadDate are required. description, contentUrl or embedUrl, duration, and hasPart (for key moments) are recommended and improve eligibility.

Should a decorative background video have VideoObject markup?

Google mainly indexes videos that are the main content of a page, so a muted hero loop is unlikely to earn a video result. Many audits still detect it as a video, though. Either add accurate, brief markup describing it, or replace it with an image or CSS animation if it adds no value.

Can I put VideoObject inside my Article or Product schema?

Yes. Add it as the value of the parent entity's 'video' property. It is still read as a VideoObject and keeps the relationship between the article or product and its video clear.