Schema Markup for YouTube Videos

What Schema Markup Does for YouTube Videos

Schema markup is structured data — code added to a web page that describes its content in a machine-readable format. For YouTube videos, the relevant schema type is VideoObject, a format defined by Schema.org and supported by Google for generating rich results.

When you embed a YouTube video on your own website or blog and add VideoObject schema to that page, you give Google explicit structured information about the video. This increases the page's eligibility for enhanced search result formats that display the video thumbnail, title, and duration directly in the search results page — improving click-through rate compared to a standard text result.

Schema markup does not guarantee rich results. It makes your page eligible for them. Google evaluates the page's overall quality and relevance before deciding whether to show the enhanced format.

The VideoObject Schema Format

VideoObject schema is implemented in JSON-LD format — a script block placed in the head or body of the HTML page. JSON-LD is Google's preferred format because it does not require modifying the visible HTML structure of the page.

A complete VideoObject implementation looks like this:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "Your Video Title Here",
  "description": "A clear description of what this video covers.",
  "thumbnailUrl": "https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg",
  "uploadDate": "2025-01-15",
  "duration": "PT8M30S",
  "embedUrl": "https://www.youtube.com/embed/VIDEO_ID",
  "contentUrl": "https://www.youtube.com/watch?v=VIDEO_ID"
}
</script>

Required vs. Recommended Properties

Google requires specific properties for a VideoObject implementation to be eligible for rich results. Additional recommended properties improve the quality of the structured data and expand eligibility for more advanced rich result types.

Required Properties

• name — The title of the video. Match this to your YouTube video title for consistency.
• description — A description of the video content. Can be a condensed version of your YouTube description.
• thumbnailUrl — URL of the video thumbnail image. For YouTube videos, use the YouTube thumbnail URL format: https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg
• uploadDate — The date the video was originally published, in ISO 8601 format (YYYY-MM-DD).

Recommended Properties

• duration — Video length in ISO 8601 duration format. PT8M30S means 8 minutes and 30 seconds. PT1H means 1 hour.
• embedUrl — The YouTube embed URL format: https://www.youtube.com/embed/VIDEO_ID
• contentUrl — The full YouTube watch page URL.
• hasPart — Used to define Clip markup for key moments (covered in detail below).
• interactionStatistic — View count data, which adds social proof context to the structured data.

Key Moments and Clip Markup

Key moments is a Google rich result feature that displays chapter timestamps directly in search results, allowing users to jump to specific sections of a video from the search results page. This feature significantly increases click-through rate because users can see that the video contains exactly the information they need.

To enable key moments through schema, you use the hasPart property with Clip schema objects, each representing one chapter. Here is the structure:

"hasPart": [
  {
    "@type": "Clip",
    "name": "Introduction",
    "startOffset": 0,
    "endOffset": 45,
    "url": "https://www.youtube.com/watch?v=VIDEO_ID&t=0"
  },
  {
    "@type": "Clip",
    "name": "How to Set Up",
    "startOffset": 45,
    "endOffset": 180,
    "url": "https://www.youtube.com/watch?v=VIDEO_ID&t=45"
  }
]

Alternatively, if you add chapter timestamps directly in your YouTube video description (in the format "0:00 Introduction", "0:45 How to Set Up"), YouTube automatically generates key moments in Google search without requiring schema on an embedding page. Both methods can work simultaneously.

Validating Your VideoObject Implementation

Google provides the Rich Results Test tool at search.google.com/test/rich-results to validate any structured data implementation. Paste your page URL or the raw HTML to check whether Google can read your VideoObject schema and whether it passes validation. Common errors include:

• Missing required properties (name, description, thumbnailUrl, or uploadDate)
• Incorrect date format — must be ISO 8601 (YYYY-MM-DD)
• Incorrect duration format — must be ISO 8601 duration (PTxMxS)
• Thumbnail URL returning a 404 or redirect error
• Schema placed on a page that does not actually embed or feature the video

For a deeper grounding in schema markup principles and validation processes for SEO broadly, the Schema Markup for SEO lesson covers the full range of structured data types and how Google uses them.

Where to Implement VideoObject Schema

VideoObject schema should be implemented on any web page you control that embeds or prominently features your YouTube video. This includes:

• Your own website blog posts that embed the video
• Landing pages built around a video resource
• Course or tutorial pages that use the video as the primary teaching content

You cannot add schema to third-party pages where others have embedded your video. But you can include schema on your own pages and encourage publishers who embed your content to add their own VideoObject schema as part of their SEO practice.