Video Schema Markup: How to Add VideoObject and Key Moments

By PDS Team

Video schema markup is structured data, usually written in JSON-LD, that tells Google exactly what a video on your page is: its title, thumbnail, upload date, length and the moments inside it. Google can find many videos without it, but the markup removes guesswork and makes your video eligible for features such as key moments in Search.

This guide shows which VideoObject properties Google requires, how to add key moments with Clip or SeekToAction, and how to test your markup before and after it goes live.

What is video schema markup and when should you use it?

Use video schema markup on any page where a video is the main thing a visitor comes to watch.

Google’s documentation calls this kind of page a watch page. A product demo page, a recorded webinar page or a “how to install” tutorial page are good examples. A long blog post with a short clip near the end is not, because the video is not the main content there.

The markup sits in the page code and does not change what visitors see. It gives Google a clear, machine-readable summary of the video, which is especially helpful when the video is self-hosted or loaded through a custom player. If your videos are scattered across pages with no clear plan, working with video SEO experts can help you decide which ones deserve their own watch pages first.

New to the topic? Our guide on what video SEO is and how videos rank on YouTube and Google covers the basics before you get into code.

Which VideoObject properties does Google require?

Google requires three properties: name, thumbnailUrl and uploadDate.

Everything else is recommended. In practice, you should add as many recommended properties as you can fill accurately, because they give Google more to work with.

Two details people often get wrong

• Time zone in uploadDate. Google says that if you leave out the time zone, it uses the time zone Googlebot uses. For an Indian business, add +05:30 to the date and time.
• contentUrl versus embedUrl. contentUrl points to the actual video file (for example an MP4), while embedUrl points to the player. Google describes contentUrl as the most effective way for it to fetch your video files. Neither should be the URL of the page itself.

How do you add VideoObject markup to a page?

Add a JSON-LD script block to the watch page’s HTML, filled with values that match the video exactly.

Here is a simple example for a self-hosted video:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to set up a WhatsApp catalogue for your shop",
  "description": "A step-by-step walkthrough of adding products to a WhatsApp Business catalogue.",
  "thumbnailUrl": "https://www.example.com/video/catalogue-thumb.jpg",
  "uploadDate": "2025-07-01T10:00:00+05:30",
  "duration": "PT6M10S",
  "contentUrl": "https://www.example.com/video/catalogue.mp4",
  "embedUrl": "https://www.example.com/player/catalogue"
}
</script>

On WordPress, many SEO plugins can generate this for you, but check the output. Plugins sometimes fill uploadDate with the post date instead of the video’s first publish date, or use the page URL where the file URL should go.

Whatever tool you use, keep the markup consistent with what is on the page. Google’s structured data guidelines say markup that does not follow its rules can lead to a manual action, and then the structured data on that page is ignored.

How do you get key moments for your videos?

Key moments let people jump to a specific part of your video from Search, and you can enable them in three ways depending on where the video is hosted.

• YouTube-hosted videos: add timestamps and labels to the YouTube description. Google may detect key moments automatically, but it prefers explicit timestamps.
• Clip markup: you define each moment yourself with a name, start time and URL.
• SeekToAction markup: you tell Google how your URLs link to a point in time, and Google picks the moments automatically.

Option 1: Clip markup

Each Clip needs a name, a startOffset in seconds and a url that opens the video at that point (for example ?t=120 for two minutes in). An endOffset is recommended. Clips are nested inside the VideoObject using hasPart:

"hasPart": [
  {
    "@type": "Clip",
    "name": "Adding your first product",
    "startOffset": 45,
    "endOffset": 150,
    "url": "https://www.example.com/video/catalogue?t=45"
  },
  {
    "@type": "Clip",
    "name": "Sharing the catalogue with customers",
    "startOffset": 150,
    "endOffset": 260,
    "url": "https://www.example.com/video/catalogue?t=150"
  }
]

Google’s rules for Clip include: the video must be at least 30 seconds long, the URL must deep link to a point other than the start, and no two clips on the same video can share a start time.

Option 2: SeekToAction markup

SeekToAction is added as a potentialAction inside the VideoObject. Its target is your watch URL with a placeholder, {seek_to_second_number}, where the time would go, and startOffset-input is set to required name=seek_to_second_number. Google must be able to fetch your video file for this to work.

Google lists a limited set of supported languages for automatic key moments, including English and several European and Asian languages. Check that list before you rely on SeekToAction. If your video is in Hindi or another regional language that is not listed, Clip markup or YouTube timestamps are the safer choice.

Clip or SeekToAction: which should you choose?

Choose Clip when you want to control the exact moments and labels, and SeekToAction when you have many videos and are happy for Google to pick the moments.

Google advises using Clip rather than SeekToAction if you want to define key moments yourself. If you do not want key moments to appear at all, Google says you can use the nosnippet meta tag.

How do you test and monitor video structured data?

Test the markup with the Rich Results Test before launch, then watch Search Console reports after it goes live.

1. Validate: run the page or code through the Rich Results Test and fix any critical errors.
2. Check access: use the URL Inspection tool in Search Console to confirm the page is not blocked by robots.txt, a noindex rule or a login.
3. Request a recrawl for a few pages and allow several days for Google to process them.
4. Submit a sitemap that includes your watch pages.
5. Monitor: check the rich result status report for valid and invalid items, and the Performance report for how video results are doing.

Repeat the checks whenever you change your page template or video player, because a single code change can break markup on every page at once. Structured data errors often sit alongside wider crawling problems, which our technical SEO services look at together.

Video Schema Markup FAQs