How to Add Video Structured Data: VideoObject Markup, Testing and Search Console Monitoring

What Is Video Structured Data?

Video structured data is machine-readable markup, usually schema.org VideoObject in JSON-LD, that describes a video on a page: its title, description, thumbnail, upload date, duration and where the file or player lives.

Google says that although it tries to understand video details automatically, you can “influence the information that's shown in video results, such as the description, thumbnail URL, upload date, and duration” by marking up the video, and that markup “can also make it easier for Google to find your video” (Google). The full vocabulary is on schema.org/VideoObject. For the same syntax applied to articles, see how to add Article structured data.

How to Add Video Structured Data at a Glance

Time: about an hour per video template (our estimate). Tools: a text editor or CMS, the Rich Results Test, Search Console. Cost: none. Skill level: intermediate.

What You Need Before Starting

• A public page with the video embedded, not behind a login (or paywall markup if gated).
• A thumbnail image at a stable URL, minimum 60x30 pixels, larger preferred.
• The upload date and time, ideally with time zone, and the duration.
• Verified Search Console access; see how to verify your site.
• Unique title and description text for each video.

Step 1: Confirm the Page Is a Watch Page and Can Be Indexed

Check that the page's main purpose is to show this video and that it is indexable. Google lists a video landing page, a TV episode page and a news video page as watch pages, and a blog post that reviews an embedded video as not one (Google).

Process: open the page, confirm the video sits on the page without a click, and test indexing as described in how to check if a page is indexed. Google notes that the watch page must be indexed and “performing well in Search” before its video can be considered for indexing, and that an indexed page does not mean an indexed video. Expected result: an indexable page with a visible player. Common mistake: marking up a page that lists many videos of equal prominence.

Step 2: Make the Video and Thumbnail Fetchable

Allow Googlebot to fetch the thumbnail and, for features such as previews and key moments, the video file. Google says it needs the actual bytes of the file for those.

Process: serve the thumbnail at a single stable URL (Google warns that quickly expiring CDN URLs can prevent indexing), do not block the thumbnail or video URL with robots.txt or noindex, and use a supported format such as MP4 or WebM (Google). Do not load the video only after a swipe, click or typing. Expected result: both URLs return 200 to a crawler. Common mistake: signed URLs that change on each page load.

Step 3: Collect the Property Values

List each value from the page itself, because Google says the markup must be consistent with the actual video and other metadata.

Source: Google Search Central, VideoObject properties. Common mistake: putting the watch page URL in contentUrl; Google says not to.

Step 4: Write the VideoObject JSON-LD

Write one VideoObject per video, using the values from Step 3. This example uses placeholder URLs and follows the property names in Google's documentation.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How we calibrate the sensor",
  "description": "A four-minute walkthrough of the calibration steps for the Model 4 sensor.",
  "thumbnailUrl": ["https://www.example.com/thumbs/sensor-16x9.jpg"],
  "uploadDate": "2026-09-14T08:00:00+00:00",
  "duration": "PT4M12S",
  "contentUrl": "https://www.example.com/video/sensor.mp4",
  "embedUrl": "https://www.example.com/embed/sensor"
}
</script>

Expected result: valid JSON with straight quotes and no trailing commas. Common mistake: copying the same name and description to every video; Google asks for unique text for each.

Step 5: Add the Markup to the Watch Page

Place the script block in the page's HTML head or body, or generate it with your CMS or JavaScript. Google's documentation gives examples in JSON-LD and Microdata (Google).

Process: add the block to the template so each watch page outputs its own values. If JavaScript injects the video or the markup, confirm it appears in the rendered HTML in the URL Inspection tool (Google). Expected result: markup present once per video. Common mistake: markup for a video that is not visible on the page.

Step 6: Test With the Rich Results Test and URL Inspection

Run the page through the Rich Results Test and fix critical errors. Google also suggests fixing non-critical issues, although that is not needed for eligibility.

Then use the URL Inspection tool to see how Google sees the page; Google says the page must be accessible, not blocked by robots.txt, noindex or a login (Google). Expected result: the VideoObject is detected and the page is crawlable. Common mistake: testing a staging URL that Google cannot reach.

Step 7: Request Recrawl, Monitor and Extend

Ask Google to recrawl, then monitor the video reports in Search Console. Google says it “may take several days” to find and crawl a page after publication.

Search Console offers a video indexing report (how many indexed watch pages contain an indexed video, and why others did not), a video rich result report (structured data issues) and a Videos filter in the Performance report (Google). Keep sitemaps current; see how to submit a sitemap. For many videos, Google supports a video sitemap with required video:thumbnail_loc, video:title, video:description and either video:content_loc or video:player_loc (Google video sitemaps). Optional extension: Clip markup for segments needs a video of at least 30 seconds and a deep-linkable URL. Common mistake: changing markup and not requesting a recrawl.

How to Verify It Worked

• Rich Results Test: detects a VideoObject with no critical errors.
• URL Inspection: the live test shows the page is available and the rendered HTML contains the markup.
• Video indexing report: the page appears with an indexed video, or a stated reason when not.
• Search Console performance: the Videos search appearance filter shows impressions over time. This does not prove the markup caused them.

How to Choose a Markup Method

Common Problems and Fixes

What Not to Do

• Do not mark up content that is not on the page. Consequence: markup outside Google's guidelines may lead to a manual action. Correction: describe only the visible video.
• Do not reuse one description across videos. Consequence: you ignore Google's request for unique name and description text for each video. Correction: write unique text.
• Do not block the thumbnail or file. Consequence: no indexing. Correction: allow both.
• Do not set an expiry date unless it expires. Consequence: a past date removes the video from results. Correction: omit expires.
• Do not promise clients a video rich result. Consequence: unmet expectations. Correction: say eligibility is not a guarantee.

Frequently Asked Questions

Sources and Methodology

This guide is built from Google Search Central and schema.org pages read on October 9, 2026; the structured-data page was last updated September 24, 2026 and the video best-practices page December 18, 2025. We did not deploy or test the example markup in Search Console, and we did not measure indexing time. Bing's handling of video markup is not covered. Interface labels can change; where documentation did not confirm a label we describe the control.

1. official Google Search Central, Video (VideoObject, Clip, BroadcastEvent) structured data. Read October 9, 2026.
2. official Google Search Central, Video SEO best practices. Read October 9, 2026.
3. official Google Search Central, Video sitemaps and alternatives. Read October 9, 2026.
4. official schema.org, VideoObject. Read October 9, 2026.