Skip to content
Browse all guides

Issue #147 · important

Issue 147

What is this issue?

Pages with embedded video content are missing VideoObject schema, preventing the video from appearing in Google Video Search, video carousels, and video rich results.

Without VideoObject schema:

  • Your videos won't appear in Google Video Search
  • Videos won't be eligible for video carousels in search results
  • Video rich results (thumbnail, duration, upload date) won't display
  • Google must detect and understand the video from page context alone
  • Key moments/chapters won't appear in search results

A proper VideoObject schema should include: @type (VideoObject), name, description, thumbnailUrl, uploadDate, and optionally duration, contentUrl, embedUrl, hasPart (for key moments).

Why does it matter?

VideoObject schema is important for video SEO and discoverability:

  • Google Video Search: Enables videos to appear in Google's dedicated Video Search
  • Video carousels: Videos with proper schema can appear in video carousels in search results
  • Rich results: Enables video thumbnail, duration, and upload date to appear in search results
  • Key moments: Adding Clip items enables chapter markers in Google Video results
  • AI search readiness: AI engines use VideoObject schema to understand and cite video content
  • User engagement: Video rich results have higher click-through rates

Resolving this issue improves your SEO health score by ensuring videos are properly structured for maximum visibility in search.

How to fix it

  1. Identify pages with video content: Look for pages with:

    • <video> tags
    • YouTube/Vimeo embeds (<iframe>)
    • Video player elements

  2. Add VideoObject JSON-LD structured data to the page's <head> or before </body>:

    {
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to Optimise Your Title Tags",
  "description": "A walkthrough of best practices for writing effective title tags for SEO.",
  "thumbnailUrl": "https://www.example.com/thumbnail.jpg",
  "uploadDate": "2024-03-01T08:00:00Z",
  "duration": "PT9M45S",
  "embedUrl": "https://www.youtube.com/embed/dQw4w9WgXcQ",
  "contentUrl": "https://www.example.com/videos/title-tags.mp4"
}

  3. Include required properties:

    • name: Video title
    • description: Video description
    • thumbnailUrl: Video thumbnail image URL (required by Google)
    • uploadDate: ISO 8601 format (required by Google)

  4. Add recommended properties:

    • duration: In ISO 8601 format (PT9M45S = 9 min 45 sec)
    • contentUrl: For self-hosted videos
    • embedUrl: For YouTube/Vimeo embeds
    • hasPart: For key moments/chapters (Clip items)

  5. For long videos with chapters, add hasPart with Clip items:

    "hasPart": [
  { "@type": "Clip", "name": "Introduction", "startOffset": 0, "endOffset": 60, "url": "https://example.com/video?t=0" },
  { "@type": "Clip", "name": "Main Tutorial", "startOffset": 60, "endOffset": 540, "url": "https://example.com/video?t=60" }
]

  6. Validate with Google's Rich Results Test

Examples

Example 1: Missing VideoObject Schema

Problematic state:

<!-- Page with video embed but no schema -->
<html>
  <head>
    <title>SEO Tutorial Video</title>
  </head>
  <body>
    <h1>How to Optimise Title Tags</h1>
    <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe>
    <p>Watch our tutorial on title tag optimization.</p>
  </body>
</html>

Corrected state:

<!-- Page with proper VideoObject schema -->
<html>
  <head>
    <title>SEO Tutorial Video</title>
    <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "VideoObject",
        "name": "How to Optimise Your Title Tags",
        "description": "A walkthrough of best practices for writing effective title tags for SEO.",
        "thumbnailUrl": "https://www.example.com/thumbnail.jpg",
        "uploadDate": "2024-03-01T08:00:00Z",
        "duration": "PT9M45S",
        "embedUrl": "https://www.youtube.com/embed/dQw4w9WgXcQ"
      }
    </script>
  </head>
  <body>
    <h1>How to Optimise Title Tags</h1>
    <iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ"></iframe>
    <p>Watch our tutorial on title tag optimization.</p>
  </body>
</html>

Example 2: Incomplete VideoObject Schema

Problematic state:

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "SEO Tutorial"
}

Missing required properties: description, thumbnailUrl, uploadDate

Corrected state:

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to Optimise Your Title Tags",
  "description": "A walkthrough of best practices for writing effective title tags for SEO.",
  "thumbnailUrl": "https://www.example.com/thumbnail.jpg",
  "uploadDate": "2024-03-01T08:00:00Z",
  "duration": "PT9M45S"
}

Example 3: Video with Chapters/Key Moments

Corrected state with hasPart:

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "Complete SEO Audit Guide",
  "description": "Learn how to perform a complete SEO audit for your website.",
  "thumbnailUrl": "https://www.example.com/audit-guide-thumb.jpg",
  "uploadDate": "2024-03-15T10:00:00Z",
  "duration": "PT15M30S",
  "hasPart": [
    {
      "@type": "Clip",
      "name": "Introduction",
      "startOffset": 0,
      "endOffset": 60,
      "url": "https://example.com/video?t=0"
    },
    {
      "@type": "Clip",
      "name": "Technical SEO Check",
      "startOffset": 60,
      "endOffset": 300,
      "url": "https://example.com/video?t=60"
    },
    {
      "@type": "Clip",
      "name": "Content Analysis",
      "startOffset": 300,
      "endOffset": 600,
      "url": "https://example.com/video?t=300"
    }
  ]
}

How PixyScan detects this

PixyScan follows these logical steps to detect missing VideoObject schema:

  1. Detect video content: The crawler identifies pages with:

    • <video> HTML tags
    • YouTube/Vimeo embeds (<iframe> with video URLs)
    • Video player elements or video-related metadata

  2. Extract structured data: The crawler looks for JSON-LD, Microdata, or RDFa blocks on the page

  3. Check for VideoObject schema: The crawler verifies if any schema block has:

    • @type set to VideoObject
    • Required properties: name, description, thumbnailUrl, uploadDate

  4. Validate schema completeness: If VideoObject schema is found, the crawler checks for:

    • thumbnailUrl property (required by Google)
    • uploadDate property (required by Google)
    • duration in ISO 8601 format
    • contentUrl or embedUrl for the video

  5. Trigger conditions: The issue is flagged when:

    • Page has video embed but no VideoObject schema
    • VideoObject schema exists but thumbnailUrl is missing
    • VideoObject schema exists but uploadDate is missing

References