Video Schema Markup Generator (VideoObject JSON-LD)

VideoObject schema is what gets your videos into Google's video carousel — the horizontal strip of video results that appears for queries with video intent. If you embed YouTube videos on your blog or host video content, you should be using VideoObject schema. Our free generator builds the JSON-LD with every field Google supports for video search.

Why VideoObject Schema Matters Even for Embedded YouTube

You might think: I'm just embedding a YouTube video, isn't that enough? It's not. YouTube has its own structured data on the YouTube watch page, but that data lives on YouTube's domain, not yours. When Google decides which videos to show in the video carousel for a query, it looks for VideoObject schema on the page where the video is being watched in context.

If your blog post has the perfect tutorial video embedded but no VideoObject schema, Google may show a competitor's blog post instead — even if their video is worse — because their schema gives Google more confidence in the match.

Adding VideoObject is also how your video can show with a thumbnail, duration, and "Key Moments" timestamps in the search snippet. Plain blue links can't compete with that visual real estate.

Required and Recommended Video Fields

Required:

• name — video title
• description — what the video is about (160-300 characters works best)
• thumbnailUrl — direct URL to a high-quality thumbnail (1280x720 or larger)
• uploadDate — ISO 8601 date

Strongly recommended:

• contentUrl or embedUrl — the actual video file URL or embed URL
• duration — ISO 8601 duration (PT5M30S for 5 minutes 30 seconds)
• publisher — Organization with name and logo
• hasPart — for "Key Moments" / chapter markers (Clip objects with startOffset and name)
• interactionStatistic — view count if you have one
• uploadDate — when the video was first published

For embedded YouTube videos, use embedUrl with the YouTube embed URL (not the watch URL). For self-hosted videos, use contentUrl pointing to the .mp4 file.

Adding Key Moments (Chapter Markers)

Key Moments are chapter markers Google can show as a list under your video result, letting users jump to specific parts. They're a major click-through booster for tutorial and how-to videos.

Two ways to add them. The first: include Chapter timestamps in your YouTube video description (YouTube parses them automatically when you embed the video and Google can pick them up). The second, more reliable approach: add them explicitly via the hasPart property in your VideoObject schema.

Each Clip has a name (the chapter title), startOffset (time in seconds from video start), and url (the deep link to that chapter, usually the embedUrl with a t=Xs parameter). The generator builds the structure for you — you fill in the chapter list.

Videos with explicit Key Moments schema get better visual treatment in search results than videos without. For long-form tutorials this is especially valuable.

Sell Custom Apparel — We Handle Printing & Free Shipping

Adding VideoObject to a Blog Post With Embedded YouTube

The easiest pattern: build the JSON-LD with the generator, paste it into a Custom HTML block at the top of the post (above the embed itself), and publish. The schema can live anywhere on the page — head, body, or footer — but having it appear before the visible video helps Google connect them.

Make sure the thumbnail URL in the schema matches the actual video. For YouTube videos, the thumbnail URL pattern is: img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg. That gets you the highest-quality thumbnail available.

If you embed multiple videos in one post, add a VideoObject for each. They can share publisher info but each needs its own name, description, thumbnail, and uploadDate. Google can show multiple videos from one page in different searches.

Self-Hosted Videos vs YouTube Embeds

For self-hosted videos (hosted on your own server, Vimeo, or a CDN), you have more control but also more responsibility. The schema works the same way, but contentUrl should point to the actual video file, embedUrl should point to your custom player page, and you should also generate a proper Open Graph video card so social shares work.

Self-hosted videos benefit from VideoObject schema even more than YouTube embeds because they have no other structured data signal. Google has nothing else to go on — your VideoObject is the only data source.

For YouTube embeds, the choice is whether to use embedUrl alone or also include contentUrl. Google's docs prefer both when possible. For most blogs, embedUrl alone is enough — embedding the YouTube iframe and providing the embedUrl gives Google everything it needs.

Validating Video Schema

Run Google's Rich Results Test on your page after publishing. It'll confirm the VideoObject is valid and tell you if anything's missing. Common errors:

• Missing or low-resolution thumbnail (must be at least 60px on the shortest side, but 1280x720+ is recommended)
• Missing uploadDate
• contentUrl pointing to a page instead of a video file
• Duration in the wrong format (use PT5M30S, not 5:30)
• Description too short (under 50 characters)

Once published, monitor the Videos report in Search Console. Google tracks every video it discovers via VideoObject and reports impressions and clicks. If a video has schema but no impressions, the issue is usually thumbnail quality or topical relevance, not schema validity.

Frequently Asked Questions

Do I need VideoObject schema if I'm just embedding a YouTube video?

Yes. YouTube has its own schema on the YouTube watch page, but that data lives on YouTube's domain. Adding VideoObject schema to your blog post tells Google your page is a relevant context for that video — which can get your post into video search results.

What thumbnail URL should I use for a YouTube video?

Use img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg for the highest quality thumbnail. Replace VIDEO_ID with the actual YouTube video ID. If maxresdefault returns a 404 (some older videos), fall back to hqdefault.jpg.

Can I add VideoObject for multiple videos on one page?

Yes. Use multiple separate script blocks or one script block with an array of VideoObject entries. Both work. Google parses all VideoObject entries on a page and can show different videos in different searches.

What's the difference between contentUrl and embedUrl?

contentUrl is the direct URL to the actual video file (.mp4, .webm). embedUrl is the URL of an embeddable video player. For YouTube embeds, use embedUrl pointing to youtube.com/embed/VIDEO_ID. For self-hosted videos, use contentUrl pointing to the file.

Does VideoObject schema improve YouTube SEO?

It improves the SEO of the page where the video is embedded — your blog post or landing page. It doesn't affect the YouTube video's ranking on YouTube itself. Think of it as helping your blog post compete in Google video search, not helping your YouTube channel.

How do I add chapter markers / Key Moments?

Use the hasPart property with an array of Clip objects. Each Clip has a name (chapter title), startOffset (time in seconds from start), and url (deep link). Or include timestamps in your YouTube description and Google may pick them up automatically — but explicit schema is more reliable.