VideoObject schema markup: example, required fields and WordPress setup

JSON-LD example

Copy this into a <script type="application/ld+json"> tag and replace the values with your own.

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to True a Bicycle Wheel at Home",
  "description": "Step-by-step wheel truing with a spoke wrench and zip-tie gauge, no truing stand needed.",
  "thumbnailUrl": [
    "https://example.com/video/wheel-truing-16x9.jpg",
    "https://example.com/video/wheel-truing-1x1.jpg"
  ],
  "uploadDate": "2026-05-12T09:00:00-07:00",
  "duration": "PT8M42S",
  "contentUrl": "https://example.com/video/wheel-truing.mp4",
  "embedUrl": "https://example.com/embed/wheel-truing",
  "hasPart": [
    {
      "@type": "Clip",
      "name": "Find the wobble",
      "startOffset": 35,
      "endOffset": 140,
      "url": "https://example.com/wheel-truing?t=35"
    },
    {
      "@type": "Clip",
      "name": "Adjust the spokes",
      "startOffset": 140,
      "endOffset": 395,
      "url": "https://example.com/wheel-truing?t=140"
    },
    {
      "@type": "Clip",
      "name": "Check spoke tension",
      "startOffset": 395,
      "endOffset": 522,
      "url": "https://example.com/wheel-truing?t=395"
    }
  ]
}

Properties

Key moments: Clip vs SeekToAction

Key moments let searchers jump to a section of a video. There are two ways to provide them:

• Clip (inside hasPart): you list each segment yourself with a name, start and end offsets in seconds, and a URL that starts playback at that point. Use this when you want control over the labels.
• SeekToAction (in potentialAction): you tell Google the URL pattern for a timestamp, such as https://example.com/wheel-truing?t={seek_to_second_number}, and Google identifies the moments itself.

Both need URLs that actually start the video at the given time. For videos hosted on YouTube, Google can detect key moments from YouTube's own chapters, so your page markup matters most for self-hosted video.

Add it in WordPress

By hand. Print JSON-LD from wp_head with values from the video provider. Take care that the thumbnail and duration match the actual video.

With Hydrogen SEO. VideoObject schema can be added to a post in the Hydrogen SEO metabox. Hydrogen SEO's video sitemap also detects embedded videos (YouTube, Vimeo, self-hosted files and others) and looks up their details; VideoObject values you enter override the detected ones, so schema is how you correct a title, description or thumbnail for one video. If a video is missing from the video sitemap because it has no thumbnail, adding VideoObject schema with a thumbnail, or setting a featured image, fixes it.

Common mistakes

• Blocked or missing thumbnails. thumbnailUrl must be an image Googlebot can fetch.
• uploadDate without a time zone. Add an offset so the date is unambiguous.
• Duration in plain text. Use PT8M42S, not "8:42".
• Markup for a video that is not on the page. The video must be embedded and playable on that URL.
• Clip URLs that ignore the timestamp. If ?t=140 does not start playback at 2:20, key moments will not work.
• Marking up every page that mentions a video. Focus on pages where the video is the main content.

See invalid structured data.

Test it

Two passes work best for VideoObject: syntax and required fields in our validator, then the live URL in the Rich Results Test and validator.schema.org. Search Console's Video indexing report shows which pages Google treats as video pages and why others are excluded, such as the video not being the main content. The Videos enhancement report covers markup errors.