When you search for a tutorial or review on Google, you’ve probably noticed video results with clickable timestamps that let you jump directly to specific sections. Those timestamps called “Key Moments” are powered by video schema markup, and they’re transforming how video content performs in search.
Video schema markup is structured data that tells search engines exactly what’s in your video: its title, duration, thumbnail, upload date, and most importantly, the specific moments within the video that address different topics. This video structured data enables Google to display rich video results with enhanced features. Video schema markup is structured data that tells search engines this video structured data helps improve AI understanding.
What Are Key Moments?
Key Moments are clickable timestamp links that appear in Google search results, allowing users to jump directly to specific sections of a video. Instead of watching an entire 20-minute tutorial, users can click to the exact 3-minute mark that answers their question.
Key Moments can be generated two ways: automatically by Google’s AI analyzing your video, or manually through key moments schema using Clip markup that you control.
Why Video Schema Matters for Search
Video schema markup improves discoverability and engagement:
- Visual prominence: Video rich results stand out with thumbnails and timestamps
- Direct navigation: Key Moments let users jump to exactly what they need
- AI integration: Structured video data feeds into AI-powered search summaries
- Voice search: Video metadata helps assistants answer “show me how to” queries
Understanding Video Structured Data
Video structured data is a form of schema markup that helps search engines clearly understand the content and context of your videos. By using formats like VideoObject, you can provide key details such as title, duration, thumbnail, and timestamps, making your videos eligible for rich results like Key Moments. This not only improves visibility in search but also enhances how AI systems interpret and present your video content.
Schema.org VideoObject
Schema.org defines VideoObject as “A video file.” It’s the core type for video schema markup, containing properties for everything from basic metadata (name, description, duration) to engagement metrics and chapter information.
Required vs. Recommended Properties
| Property | Status | Description |
| name | Required | Video title |
| thumbnailUrl | Required | URL to video thumbnail image |
| uploadDate | Required | When the video was published (ISO 8601) |
| description | Recommended | Video summary |
| duration | Recommended | Video length (ISO 8601 duration) |
| contentUrl | Recommended | Direct URL to video file |
| embedUrl | Recommended | URL for embedding the video |
VideoObject vs. Clip vs. SeekToAction
Understanding the difference between these schema types for implementing key moments:
- VideoObject: The core video markup describing the entire video
- Clip: Defines a specific segment with name, startOffset, and endOffset used for manual key moments schema
- SeekToAction: Enables Google to automatically link to any timestamp using your player’s URL structure
What Are Key Moments in Google?
Manual Timestamps with Clip Markup
Clip markup gives you precise control over which moments appear in search results. Each Clip represents a named segment with specific start and end times. This is ideal when you want to highlight specific chapters or sections.
Automatic Key Moments
When you use SeekToAction instead of Clip, Google’s algorithms automatically identify key moments based on the video content, audio, and visual analysis. This works well for YouTube videos and when you don’t need manual control.
How Key Moments Appear in Search
In search results, Key Moments display as a scrollable list of timestamps below the video thumbnail. Each moment shows a timestamp and title, allowing users to click directly to that section. This significantly improves user experience by eliminating the need to scrub through videos.
Benefits for Engagement
- Users find relevant content faster, improving satisfaction
- Lower bounce rates as viewers land on exactly what they need
- Increased watch time for viewers who explore multiple segments
- Better accessibility for users seeking specific information
Step-by-Step Implementation Guide
Complete VideoObject JSON-LD Example
Here’s a comprehensive video schema markup example:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "How to Build a React Dashboard from Scratch",
"description": "Complete tutorial on building a responsive dashboard using React, covering components, state management, and styling.",
"thumbnailUrl": "https://example.com/thumbnails/react-dashboard.jpg",
"uploadDate": "2025-01-15T08:00:00Z",
"duration": "PT25M30S",
"contentUrl": "https://example.com/videos/react-dashboard.mp4",
"embedUrl": "https://example.com/embed/react-dashboard",
"publisher": {
"@type": "Organization",
"name": "CodeTutorials",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/logo.png"
}
},
"interactionStatistic": {
"@type": "InteractionCounter",
"interactionType": "https://schema.org/WatchAction",
"userInteractionCount": 45000
}
}
</script>Key Properties Explained
duration: Uses ISO 8601 format: PT25M30S = 25 minutes, 30 seconds. PT1H15M = 1 hour, 15 minutes.
contentUrl vs. embedUrl: contentUrl is the direct video file URL; embedUrl is the embeddable player URL. Include both when possible.
interactionStatistic: Optional but valuable for showing engagement. Use WatchAction for views, LikeAction for likes.
Key Moments Schema Using Clip
Add Clip markup to define specific video segments:
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "How to Build a React Dashboard",
"thumbnailUrl": "https://example.com/thumb.jpg",
"uploadDate": "2025-01-15",
"duration": "PT25M30S",
"hasPart": [
{
"@type": "Clip",
"name": "Project Setup",
"startOffset": 0,
"endOffset": 180,
"url": "https://example.com/video?t=0"
},
{
"@type": "Clip",
"name": "Component Architecture",
"startOffset": 180,
"endOffset": 540,
"url": "https://example.com/video?t=180"
},
{
"@type": "Clip",
"name": "State Management",
"startOffset": 540,
"endOffset": 900,
"url": "https://example.com/video?t=540"
}
]
}Alternative: SeekToAction for Automatic Detection
SeekToAction tells Google how to construct timestamp URLs for your video player:
{
"@type": "VideoObject",
"name": "React Dashboard Tutorial",
"potentialAction": {
"@type": "SeekToAction",
"target": "https://example.com/video?t={seek_to_second_number}",
"startOffset-input": "required name=seek_to_second_number"
}
}When to Use Clip vs. SeekToAction
Use Clip when: You want precise control over which segments appear, have well-defined chapters, or need specific segment titles.
Use SeekToAction when: You prefer Google’s automatic detection, have many videos to manage, or don’t have clearly defined chapters.
Eligibility and Google Guidelines
Video Accessibility Requirements
For video schema to work, your video must be accessible to Google:
- Video must be publicly accessible (not behind login)
- Google must be able to fetch the video file or access the embed
- The page containing the video must be indexable
- Video content must match the schema description
Hosting Considerations
- Self-hosted videos: Provide contentUrl pointing to the actual video file
- YouTube videos: Use embedUrl with the YouTube embed URL; Google can often detect Key Moments automatically
- Third-party players: Ensure the embedUrl is valid and the player supports timestamp URLs
Content Alignment
Your video schema must accurately reflect visible content. The video title, description, and thumbnail referenced in schema should match what users see on the page.
Validation and Testing
Testing Video Schema Markup
Google Rich Results Test: Verify video eligibility at Google Rich Results Test. Look for VideoObject detection and any Clip markup.
Schema Markup Validator: Full Schema.org validation at validator.schema.org for comprehensive property checking.
Common Errors
- Missing thumbnailUrl: Required property—always include a valid image URL
- Invalid duration format: Use ISO 8601: PT10M30S not “10:30”
- Timestamp mismatch: Clip startOffset/endOffset must match actual video times
- Inaccessible video: Google must be able to access contentUrl or embedUrl
Monitoring Performance
Use Google Search Console’s Video enhancement report to track indexing status, errors, and valid items across your video content.
Common Mistakes to Avoid
Avoid using incomplete or incorrect schema markup, such as missing required fields or invalid formats. Ensure your video is publicly accessible and matches the structured data provided. Don’t use inaccurate timestamps or misleading titles, as this can harm user experience and search visibility. Regular validation and updates are essential to prevent errors and maintain eligibility for rich results.
Missing Required Properties
Every VideoObject needs name, thumbnailUrl, and uploadDate at minimum. Missing any of these prevents rich results.
Incorrect Duration Format
// WRONG
"duration": "10:30"
"duration": "10 minutes"
// CORRECT
"duration": "PT10M30S" // 10 min 30 sec
"duration": "PT1H5M" // 1 hour 5 minTimestamp Mismatches
If your Clip markup says “Component Architecture” starts at 180 seconds, but the actual video content starts at 200 seconds, users will land on the wrong section. Always verify timestamps against the actual video.
Hidden or Inaccessible Videos
Schema pointing to login-protected videos, geo-blocked content, or expired URLs won’t generate rich results. Ensure videos are publicly accessible.
AI Search and Voice Optimization
AI search and voice optimization focus on making your content easily understandable for AI systems and voice assistants. By using structured data, clear context, and natural language, you help search engines identify relevant information and deliver precise answers. This improves your chances of appearing in AI-generated results and voice queries like “show me how to”, increasing visibility and user engagement.
Video Schema in AI Summaries
As Google integrates more AI features, video structured data helps AI systems:
- Surface relevant video segments when answering questions
- Generate accurate summaries of video content
- Recommend specific timestamps for user queries
Multimodal Search
Google increasingly combines video, text, and image results. Well-structured video schema helps your content appear in these mixed-media search experiences.
Voice Search Compatibility
For “show me how to…” voice queries, video schema helps assistants identify and recommend relevant video content. Clear Clip names improve voice result relevance.
Entity Clarity
Help AI understand your video by using specific titles (“React Dashboard Tutorial” not “My Video”), including publisher information, and connecting videos to related content through structured data.
Best Practices for Video Search Dominance
High-Quality Thumbnails
Use compelling, high-resolution thumbnails (1280×720 minimum). Thumbnails significantly impact click-through rates and are required for video schema.
Descriptive Titles and Transcripts
- Use clear, keyword-rich video titles
- Include full transcripts on the page for SEO and accessibility
- Add closed captions to improve Google’s content understanding
Structured Chapter Segmentation
Break videos into logical chapters with clear, descriptive names. This improves both Clip markup accuracy and automatic Key Moments detection.
Mobile-First and Performance
- Ensure videos play smoothly on mobile devices
- Use CDN hosting for faster video delivery
- Implement lazy loading for video embeds
- Optimize page speed around video content
Frequently Asked Questions
What’s the difference between Clip and SeekToAction?
Clip lets you manually define specific video segments with names and timestamps. SeekToAction tells Google how to construct timestamp URLs, enabling automatic Key Moments detection based on Google’s analysis.
Do YouTube videos need video schema markup?
YouTube videos often get Key Moments automatically through YouTube’s chapter feature and Google’s detection. However, adding video schema to pages embedding YouTube videos can enhance discoverability on your own site.
How do I format video duration in schema?
Use ISO 8601 duration format: PT followed by time values. PT10M30S = 10 minutes 30 seconds. PT1H15M = 1 hour 15 minutes.
Can I use video schema for podcast episodes?
For audio-only content, use AudioObject instead of VideoObject. VideoObject is specifically for video content with visual elements.
Is thumbnailUrl required for video schema?
Yes. thumbnailUrl is a required property for VideoObject. Without it, your video schema won’t qualify for video rich results.
How many Clips should I include?
There’s no strict limit, but focus on meaningful segments. For most videos, 3-10 well-defined clips work better than dozens of granular timestamps.
Do Key Moments work for live streams?
Key Moments are designed for pre-recorded content. For live streams, use BroadcastEvent schema. You can add VideoObject with Clips to the recorded version after the stream ends.
Why aren’t my Key Moments showing in search results?
Key Moments display depends on query type, search context, and Google’s algorithms. Valid markup makes you eligible but doesn’t guarantee display. Verify your schema validates without errors and that timestamps match actual video content.
Should I use contentUrl or embedUrl?
Include both when possible. contentUrl is the direct video file URL. embedUrl is the player URL for embedding. Google uses both for different purposes.
Video Schema Implementation Checklist
Use this checklist for every video page.
Required Properties:
- name – Video title matching visible content
- thumbnailUrl – Valid image URL (1280×720+)
- uploadDate – ISO 8601 format
Recommended Properties:
- description – Video summary
- duration – ISO 8601 duration (PT10M30S)
- contentUrl and/or embedUrl
- publisher – Organization info with logo
For Key Moments:
- Use Clip markup for manual control
- Or SeekToAction for automatic detection
- Verify timestamps match actual video content
- Include descriptive clip names
Validation:
- Test with Google Rich Results Test
- Verify video is publicly accessible
- Check duration format is valid ISO 8601
Monitor Search Console Video report
