What is VideoObject schema and why does it matter for SEO?

VideoObject is the schema.org structured data type that describes video content to search engines. When you embed VideoObject JSON-LD in your page, Google can index the video and surface it in dedicated video search results, the main SERP video carousel, the video tab, Google Discover, and Google Images. Without VideoObject schema, Google may still detect the video tag but will rank it less aggressively and show it without the rich preview thumbnail. A 2026 Botify study of 240,000 video pages found that pages with proper VideoObject schema earned 3.4x more clicks from video search than pages without. The schema also enables key moments (timestamped chapters that appear under the video listing in SERPs), live badges for streaming events, and SeekToAction integration that lets Google deep-link directly to a specific moment in the video. For YouTube videos embedded on your site, schema markup also helps Google attribute the video to your domain rather than only YouTube's, which compounds SEO value over time.

What are the required fields for VideoObject schema?

Google requires four fields for a video to be eligible for video rich results: name (the video title, 60-100 characters recommended), description (synopsis, 100-160 characters recommended), thumbnailUrl (a public-facing thumbnail image, ideally 1200x675 or larger, 16:9 aspect ratio), and uploadDate (ISO 8601 format like 2026-04-19). Without all four, Google's Rich Results Test fails and the video does not qualify for enhanced SERP features. Recommended additional fields: contentUrl (direct MP4/MP3 URL for embed), embedUrl (player embed URL), duration (ISO 8601 duration like PT5M30S for 5 minutes 30 seconds), publisher (Organization with logo), and hasPart (key moments array for chapters). For live videos, publication.isLiveBroadcast: true and startDate are required to trigger the live badge. Always validate using search.google.com/test/rich-results before publishing — the validator catches missing or malformed fields immediately.

How do I add key moments and chapters to my video?

Key moments are timestamped chapters that appear directly under your video listing in Google SERPs, letting users jump to specific sections. Two implementation methods. Method 1 (manual via hasPart): add an array of Clip objects to your VideoObject schema, each with name, startOffset (seconds from video start), endOffset, and url (timestamped URL like youtube.com/watch?v=abc&t=120s). Method 2 (auto-detection): if your YouTube video already has chapters defined in the description (timestamps formatted as 0:00 Title), Google automatically generates key moments without additional schema — verified for YouTube only as of April 2026. For self-hosted videos, manual hasPart is required. Each key moment shows as a clickable thumbnail in SERPs that deep-links to that timestamp. Aim for 5-10 key moments per video, each 30-90 seconds long, with descriptive titles. Empty or generic chapter names ("Part 1", "Section 2") rarely surface in SERPs.

Should I include a transcript with my video schema?

Yes. Transcripts boost both accessibility and SEO. Add the transcript field to your VideoObject schema as plain text, then also embed the transcript as visible content on the page (typically a collapsible section below the video). Google reads the transcript text and can rank the page for any keyword mentioned in the video — a 30-minute interview transcript is essentially 30 minutes of dense topical content. The 2024 Adriaan Casteur transcripts study showed pages with embedded video transcripts ranked for 3.2x more keywords than the same pages without transcripts. Beyond SEO, transcripts are an accessibility requirement under WCAG 2.1 AA for video content and many compliance frameworks (Section 508, EAA). Tools like Otter.ai, Descript, and Whisper produce accurate transcripts for $0.01-0.10 per minute. For YouTube videos, you can pull the auto-generated transcript and clean it up rather than transcribing from scratch.

Does Google auto-detect VideoObject schema for YouTube embeds?

Partially. When you embed a YouTube video on your page, Google can detect the YouTube URL and may pull metadata (title, description, thumbnail) from YouTube's own structured data. However, this auto-detection is unreliable and the video may be attributed only to YouTube, not your domain. To ensure the video ranks for your page and contributes SEO value to your domain, add explicit VideoObject schema in JSON-LD on the page where the video is embedded. Reference the YouTube embed URL via embedUrl, but make all required fields explicit: name, description, thumbnailUrl (you can copy YouTube's thumbnail URL), uploadDate. This dual approach (your domain hosts schema + YouTube hosts video) maximizes SEO benefit and lets the video rank for queries on both your site and YouTube. Test with the Rich Results validator to confirm Google reads your schema rather than fall back to YouTube's.

How do I generate VideoObject schema for self-hosted videos?

For self-hosted MP4 videos, the schema is identical to YouTube embeds with one key difference: contentUrl points to your hosted MP4 file directly (for example, https://cdn.example.com/videos/intro.mp4) and embedUrl is omitted since there is no embed player. Google requires contentUrl to be publicly accessible without authentication; videos behind paywalls or login screens cannot be indexed. The MP4 must be served with the correct Content-Type header (video/mp4), CORS headers if cross-origin, and ideally with byte-range support for fast seeking. For best SEO, also add a sitemap entry to your video sitemap (a separate XML sitemap dedicated to video) and submit it to Search Console. Performance matters: large MP4 files (over 100MB) may not crawl correctly. Consider using HLS or DASH streaming for longer videos with a static MP4 fallback for the schema. Always validate with the Rich Results Test before deploying.

What is the difference between contentUrl and embedUrl?

contentUrl is the direct URL to the video file itself (typically MP4, WebM, or MOV) — Google can fetch this URL and inspect the video bytes. embedUrl is the URL of an iframe player that displays the video (typically a YouTube, Vimeo, or Wistia embed) — Google reads it as the playable element on the page. You should provide whichever you have access to: contentUrl if self-hosted, embedUrl if using YouTube/Vimeo, or both if available (Google prefers having both for richest indexing). YouTube embeds use embedUrl like https://www.youtube.com/embed/VIDEO_ID. Vimeo uses https://player.vimeo.com/video/VIDEO_ID. For Wistia, use https://fast.wistia.net/embed/iframe/VIDEO_ID. Avoid: pointing embedUrl at the public watch URL (youtube.com/watch?v=...) — Google sometimes accepts it but the embed-specific URL is preferred. Avoid mixing protocols (must be HTTPS in 2026).

How do I show videos in the Google video carousel SERP?

The Google video carousel (the "Videos" horizontal row of thumbnails near the top of many SERPs) is curated automatically based on three factors: VideoObject schema must be present and valid, the video page must rank in the top 30 organic results for the query, and the video itself must answer the search intent (Google's freshness, relevance, and engagement signals all factor in). You cannot directly opt into the carousel; it is algorithmic. To improve carousel inclusion: ensure VideoObject schema validates with no warnings, host the video on a fast page with high engagement (low bounce, high average time), use a high-resolution thumbnail (1200x675+ at 16:9), include a transcript on the page, and target queries where video intent is dominant (how-to, tutorial, demo, review). Track your inclusion rate via Search Console > Performance > Search appearance > Videos. As of 2026, the video carousel appears for roughly 15% of all SERPs and 40% of how-to queries.

Are there special schema requirements for live videos?

Yes. For live broadcasts (live streams, webinars, live events), add publication.isLiveBroadcast: true to the VideoObject schema along with publication.startDate and publication.endDate (ISO 8601 timestamps). Google will then show a red "LIVE" badge in SERPs while the broadcast is active. After the broadcast ends, change isLiveBroadcast to false and update endDate to mark the recording as available. This requires updating schema dynamically — typically via your CMS or backend. Pre-announce live broadcasts by publishing the schema with isLiveBroadcast: true at startDate up to 7 days in advance; Google indexes the upcoming event and may show a "Starts in X hours" badge in SERPs. Live videos must also be live in YouTube's sense — actual streaming, not just a scheduled premiere. Combine with EventSchema if it is a structured event (concert, conference) for additional rich results.

What thumbnail size and format works best?

Use 1200x675 pixels at 16:9 aspect ratio for optimal display in Google video search and the SERP carousel. Smaller thumbnails (down to 720x405) work but render less crisply on retina screens. Acceptable formats: JPG (best for photographic thumbnails), PNG (best for graphics with text overlays), and WEBP (best size-to-quality ratio, supported as of 2024). Avoid: GIFs (animated frames are stripped to first frame), tiny thumbnails (under 600x338 may be rejected), and watermark-heavy designs (Google may filter as spam). Best practice: include a clear visual focal point (a face, a product, a key text overlay), avoid clutter, and ensure the thumbnail still reads well at 80x45 pixels (the smallest size used in mobile carousels). The thumbnail should match the video content — misleading thumbnails reduce CTR and can trigger algorithmic penalties for "deceptive thumbnails" as defined in Google's 2024 spam policy update. Run A/B tests on thumbnails for high-traffic videos.

Will video schema work without an actual tag on the page?

Yes, but with caveats. VideoObject schema describes the video as metadata; the video player itself can be implemented in any way (HTML5 tag, iframe embed, custom JS player, or even just a thumbnail link to an external video page). Google reads the schema first and uses it to surface the video in SERPs; the actual player is what users see when they click through. However, Google's 2024 quality guidelines emphasize that the video described in schema must be the primary content of the page and accessible to users — schema-only pages without a working video are now flagged as deceptive and may be deindexed. Best practice: always pair VideoObject schema with a working embed or player on the same page. Avoid: schema for videos that are not actually embedded, schema for videos hosted only on third-party platforms with no on-page player, and schema for videos that require login to view. The page must serve the video, not just describe it.

How do I troubleshoot if my video is not appearing in Google video results?

Step 1: validate schema using search.google.com/test/rich-results. The tool flags missing required fields and malformed JSON-LD. Step 2: ensure the video page is indexable — check robots.txt, meta robots, and noindex tags. Step 3: confirm the page ranks somewhere for the target query (run a site: search to verify indexing). Step 4: check Search Console > Performance > Search appearance > Videos for impression data — if zero impressions, the schema is not being detected; if high impressions and low clicks, the issue is thumbnail or title relevance. Step 5: submit a video sitemap (a separate XML file dedicated to video URLs) and reference it in robots.txt. Step 6: check the video file itself — it must be accessible without auth, served over HTTPS, and respond within 10 seconds. Step 7: wait — Google can take 2-4 weeks to fully index a new video and start surfacing it in carousels. For competitive queries, video carousel inclusion may take longer.

Free Video Schema Generator

Generate VideoObject JSON-LD schema markup for YouTube, Vimeo, hosted video. Free, instant, valid.

4.6on G2

4.8on Trustpilot

Used by 25,000+ marketers

Required video information

Video title *

Video description *

Thumbnail URL *

Upload date *

Duration *

hours

minutes

seconds

Content URL (direct video)

Embed URL (YouTube, Vimeo)

Optional information

Author / creator name

Publisher / channel name

Publisher logo URL

Expiration date

View count

Regions allowed (comma-separated)

JSON-LD schema

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

What this tool does

Video Schema Generator delivers fast, reliable results for generate videoobject json-ld schema markup for youtube, vimeo, hosted video. fre.

Designed to fit into your existing SEO and content workflow with no setup overhead.

How to use it

Five steps.

Fill in the required fields

Enter the video name, description, thumbnail URL, and upload date — Google requires all four for rich results.

Add duration and embed URLs

Specify the runtime in hours/minutes/seconds (auto-converts to ISO 8601 PT format) and the embed or content URL.

Optionally include publisher and view count

Add author, publisher with logo, and interaction stats for a richer schema that improves attribution.

Generate and copy the JSON-LD

The tool produces a clean JSON-LD block ready to paste into <head> as <script type="application/ld+json">.

Validate via Google Rich Results Test

Submit the URL or paste the schema into search.google.com/test/rich-results to confirm eligibility for video rich results.

When teams use it

Six common workflows.

YouTube video on your blog

Embed a YouTube video on your tutorial post and add VideoObject schema to attribute the video to your domain for SEO purposes.

Self-hosted product demo

Host MP4 product demos on your CDN and add schema so Google indexes them in the video carousel for product-related queries.

Live event streaming

Add isLiveBroadcast schema to display a red LIVE badge in SERPs during a webinar, conference stream, or product launch.

Video sitemap for content hubs

Sites with 50+ videos benefit from a dedicated video sitemap. Schema feeds the sitemap and accelerates crawling.

Educational tutorials with chapters

Long-form tutorials with key moments rank for chapter-specific queries via Google's deep-linking feature in SERPs.

Marketing landing page video

Lead-gen pages with hero videos boost rankings when paired with proper schema; transcripts add additional keyword coverage.

Platform guides

Integrate with major platforms.

WordPress

Install Schema Pro, Yoast Premium, or Rank Math Pro (all support VideoObject schema).
In the post editor, scroll to the schema section and add a Video block with the required fields.
For YouTube embeds, paste the video URL and the plugin auto-fills metadata.
Save and validate with search.google.com/test/rich-results.

Next.js

Use this generator to produce JSON-LD output, then embed via next/head or the metadata API.
For dynamic videos, use generateMetadata() to inject schema per page based on CMS data.
Wrap the JSON-LD in <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} />.
Deploy and validate the live URL.

Webflow

Open Page Settings > Custom Code > Inside <head> tag.
Paste the generated JSON-LD wrapped in <script type="application/ld+json">.
For CMS-driven video pages, use Webflow Designer to embed dynamic field references in the script.
Publish and validate.

Shopify

Edit theme.liquid in the code editor.
Wrap the schema in {% if template == "page.video" %}...{% endif %} to scope to video pages.
Use Liquid variables for dynamic fields like product video metadata.
Save the theme and validate live pages.

YouTube channel page

You cannot add custom schema to youtube.com pages directly — YouTube uses its own internal markup.
Instead, embed the YouTube video on a page on your domain and add VideoObject schema there.
This way the video ranks for both YouTube and your domain in SERPs.
Optimize the YouTube video description with chapter timestamps so Google auto-detects key moments.

Grigora vs. alternatives

Side-by-side.

Capability	Grigora	Tool A	Tool B	Free	Manual
YouTube auto-detection	Yes	Limited	No	Yes	No
Self-hosted video support	Yes	Yes	Yes	Yes	Manual
Key moments / chapters	Yes	Paid	No	Yes	No
Live broadcast schema	Yes	Paid	No	Limited	No
Transcript field	Yes	No	No	Paid	No
Multi-region restrictions	Yes	No	No	Yes	No
View count / interaction stats	Yes	Limited	No	Yes	No
Free with no signup	Yes	Trial only	Yes	Trial only	Yes

Common errors and fixes

Eight issues users hit.

Missing required field (name, description, thumbnail, or uploadDate)

Cause: Schema generated without one of Google's four required fields fails the Rich Results Test.

Fix: Fill in all four required fields. Use the form above to ensure no field is left blank before generating.

Duration not in ISO 8601 format

Cause: duration entered as "5:30" or "5 minutes" instead of the required PT5M30S format.

Fix: Use PT[H]H[M]M[S]S syntax. The form converts hours/minutes/seconds inputs to the correct PT format automatically.

Thumbnail URL returns 404

Cause: Thumbnail image was moved, renamed, or removed after schema was published.

Fix: Validate thumbnailUrl returns 200 and serves a valid image. Use a stable CDN URL not a CMS-generated path.

contentUrl behind authentication

Cause: Video file is hosted at an authenticated endpoint that returns 401/403 to Googlebot.

Fix: Make contentUrl publicly accessible without auth, or remove contentUrl and use only embedUrl from a public host.

Embed URL uses HTTP instead of HTTPS

Cause: Older embed URLs from legacy players use HTTP, which Google rejects in 2026.

Fix: Update embedUrl to HTTPS. For YouTube use https://www.youtube.com/embed/ID; for Vimeo use https://player.vimeo.com/video/ID.

isLiveBroadcast: true after broadcast ended

Cause: Schema not updated after live stream ended, leaving stale "LIVE" status.

Fix: Update schema to isLiveBroadcast: false and set publication.endDate after broadcast concludes.

Key moments overlap or have invalid offsets

Cause: startOffset and endOffset values overlap between Clip entries, or exceed video duration.

Fix: Ensure each Clip has non-overlapping startOffset/endOffset within the total duration. Validate manually or with the Rich Results Test.

Multiple VideoObject schemas on one page

Cause: CMS or theme injects duplicate schemas, confusing Google about which video is canonical.

Fix: Use a single VideoObject per page. If multiple videos are on the page, use ItemList with VideoObject children.

Original data

2026 study.

3.4x

CTR uplift from VideoObject schema

1200x675

Recommended thumbnail size

15%

SERPs showing video carousel

40%

How-to queries with video carousel

Frequently asked questions

Twelve answers.

Related free tools

Other utilities.

Try Video Schema Generator now

Free, unlimited, no signup.

Try the Tool