---
title: "Video Schema Markup: VideoObject Fields and Example | FoxCue"
description: "Add VideoObject JSON-LD to the page that plays your video. Google's required fields, a YouTube embed example, key moments, how to test it, and what it won't do."
url: "https://foxcue.com/video-seo/videoobject-schema/"
updated: "2026-11-19"
---

# VideoObject schema: fields, a JSON-LD example, YouTube embeds

Add VideoObject to the page that plays your video. The fields Google asks for, a copy-ready example, and how to test it.

VideoObject is the schema.org type that describes a video on a web page. Add it as JSON-LD on the page where the video plays. Google's documentation lists name, thumbnailUrl and uploadDate as required, and description, duration and embedUrl or contentUrl as recommended. For a YouTube embed, use the player URL as embedUrl. Every value must match what a visitor sees.

## What is VideoObject schema?

A way to give Google facts about a video, in a format it reads.

### A schema.org type

VideoObject is a type in the schema.org vocabulary. It describes one video: its title, thumbnail, upload date, length, and where its player or file lives.

### Added as JSON-LD

Google's structured data guidelines (Search Central, read 18 Nov 2026) list JSON-LD as the recommended format. It goes in a script block on the page that shows the video.

### Metadata, not a switch

Google's video documentation (read 18 Nov 2026) says videos can appear in the main results, Video mode, Google Images and Discover. The markup gives Google facts. The page must still be indexed and the video found.

## Add VideoObject in five steps

The code is in the example below. Your web team can do this in an afternoon.

1. **Find the watch page**: Use the page whose main purpose is to show this one video.

2. **Fill the required fields**: Google lists name, thumbnailUrl and uploadDate as required.

3. **Add the player or file**: Use embedUrl for a player such as YouTube, or contentUrl for a file you host.

4. **Paste the JSON-LD**: Put one script block on that page, with values that match the visible text.

5. **Test, then recheck**: Run the Rich Results Test, then URL Inspection, then read the video indexing report.

## Which VideoObject properties does Google require?

From Google's video structured data page, read 18 Nov 2026. Some guides call description required. Google lists it as recommended.

| Property | Google lists it as | What it holds |
| --- | --- | --- |
| name | Required | The video's title |
| thumbnailUrl | Required | A URL for the video's thumbnail image |
| uploadDate | Required | When it was first published, ISO 8601 |
| description | Recommended | Text that describes this video |
| duration | Recommended | Length in ISO 8601, such as PT3M4S |
| contentUrl | Recommended | The video file's own URL |
| embedUrl | Recommended | The player URL, such as a YouTube embed |
| creator | Recommended | Who made it: a name and a URL |
| hasPart | Recommended | Clip items that mark key moments |

## A VideoObject JSON-LD example for a YouTube embed

Fictional video and product. Replace every value, and keep each one matching the page.

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to import customers into Tallgrass",
  "description": "Import customers with one CSV file: prepare the columns, upload the file, then fix any rows that fail.",
  "thumbnailUrl": [
    "https://tallgrass.example/images/import-customers-1x1.jpg",
    "https://tallgrass.example/images/import-customers-4x3.jpg",
    "https://tallgrass.example/images/import-customers-16x9.jpg"
  ],
  "uploadDate": "2026-11-18T08:00:00+00:00",
  "duration": "PT3M4S",
  "embedUrl": "https://www.youtube.com/embed/VIDEO_ID",
  "creator": {
    "@type": "Organization",
    "name": "Tallgrass",
    "url": "https://tallgrass.example"
  }
}
</script>
```

## contentUrl or embedUrl on a YouTube embed?

Use the player URL. Leave contentUrl out unless you have the file.

### embedUrl is the player

schema.org defines embedUrl as a URL to a player, and contentUrl as the media file itself. A YouTube iframe gives you the player URL, so its src goes in embedUrl.

### contentUrl is the file

Do not point contentUrl at your page or at the YouTube watch page. Neither is the video file. With no file URL, leave contentUrl out, as the example does.

### Two homes for one video

Google's video documentation (read 18 Nov 2026) says it may index a third-party embed on your page and on the host's page. Your page should still carry structured data, and the host must let Google fetch the file.

## Clip and SeekToAction: when to add them

Both mark moments inside a video. Neither is required.

### Clip

Clip needs name, startOffset and url; endOffset is recommended. Google says the video must run at least 30 seconds, allow deep links past its start, and no two clips on a page may share a start time.

### SeekToAction

SeekToAction needs a target URL that uses the {seek_to_second_number} placeholder. Google says it must be able to fetch your video files, so check that your host allows it.

### On YouTube instead

For a video hosted on YouTube, Google says key moments can come from timestamps in the description, one per line in time order, each with a label. Google says it prioritizes moments you set.

## What has to match on the page?

Google checks the markup against the page, and the page against its watch-page rules.

### Same words

Google's guidelines say not to mark up content readers cannot see, and to put the markup on the page it describes. Use the visible title in name, and the opening answer in description.

### A watch page

Google says a watch page's main purpose is to show one video. A blog post or product page where the video supports the text is not one, and Search Console reports only videos on watch pages.

### One video

Search Console's video indexing report says Google indexes one video per page. If a page holds several, mark up the one the page exists to show.

### Loaded with the page

Google says not to rely on a click, swipe or typing to load the video. A click-to-play image can be reported as "Cannot determine video position and size".

## Help-center pages: answer, player, transcript

A player gives a crawler little text. Put the words beside it, in the page's HTML.

### Answer above the player

Open with a short direct answer to the question in the title, then the player. Put the same answer in description so the markup says what the page says.

### Transcript below it

Publish a cleaned transcript as ordinary HTML under the player, with a heading for each step. Wistia (23 Jan 2026) says a title, description or transcript should not sit in an iframe or need JavaScript to show.

### Why not the iframe

An iframe is a separate document. Wistia says YouTube embeds use iframes that LLM crawlers cannot see. That is Wistia's claim about crawlers, so keep the words in your own HTML either way.

## Where the player goes in two help centers

Vendor documentation, read 18 Nov 2026. Other platforms differ, so check yours.

| Platform | How to add the player | Watch for |
| --- | --- | --- |
| Zendesk Guide | Embed button, paste the video URL | Shorts unsupported |
| Zendesk, other hosts | Embed code in source view | Needs unsafe HTML allowed |
| HubSpot knowledge base | Rich text module, Insert, Video | Updated 20 Jun 2026 |

## How to test the markup

Three Google tools, then one check of your own for the words beside the player.

### Rich Results Test

Run the page URL and fix critical errors. Google's video page says warnings can improve the markup but are not required.

### URL Inspection

Deploy, open the page in URL Inspection, and check the rendered page. Google says it may take several days to find and crawl a new page.

### Video indexing report

In Search Console, the report shows how many videos are indexed and why others are not. It is separate from the rich result reports.

### Raw HTML check

Fetch the page without running scripts and count three markers: an answer sentence, a transcript sentence and VideoObject. Zero means the server did not send it.

## Check the server's HTML with curl

curl does not run scripts. Each count should be 1 or more. The page must be public.

```sh
curl -sL https://your-site.example/help/import-customers > page.html
grep -c "VideoObject" page.html
grep -c "a sentence copied from your answer" page.html
grep -c "a sentence from the middle of your transcript" page.html
```

## Does video schema help AI Overviews?

Google says no special markup is needed. One large study found no major uplift.

### What Google says

Google's AI features page (read 18 Nov 2026) says there are no additional requirements for AI Overviews or AI Mode, and no special schema.org markup to add. A page must be indexed and snippet-eligible, and meeting that does not mean Google will show it.

### What the study found

Ahrefs matched 1,885 pages that added JSON-LD to 4,000 controls and measured 30 days of citations. It found no major uplift on AI Overviews, AI Mode or ChatGPT. All schema types were pooled, not only VideoObject.

### What it is for

VideoObject describes a video for Google's video features. The AI features page lists matching structured data to the visible text as good practice. Treat it as accuracy, not a citation lever.

> **1,885** pages added JSON-LD. Ahrefs found no major AI citation uplift versus matched controls.
> Source: [Ahrefs, We tracked 1,885 pages adding schema](https://ahrefs.com/blog/schema-ai-citations/), 11 May 2026

## Who does what: FoxCue and your web team

FoxCue makes the video and the text you reuse. The markup and the embed are your web team's.

| Step | Who | FoxCue today |
| --- | --- | --- |
| The video | You, in FoxCue | Live. Teleprompter, recorder, AI edit |
| Title and description text | You, from the draft | Live. Drafted from the script |
| Caption files and transcript | You, downloaded | Live. SRT, VTT and transcript |
| Upload to YouTube | You, in FoxCue | Live. Private, published now, or scheduled |
| VideoObject markup | Your web team | Not a FoxCue step |
| Embed and sitemap | Your web team | Not a FoxCue step |
| AI-answer checks | You, in FoxCue | Live. Four engines, on the questions you choose |

## The video and its text files

FoxCue edits the video, then gives you the video, SRT and VTT caption files, and a transcript to publish beside it.

[See the whole video SEO workflow](https://foxcue.com/video-seo/)

## Related guides

The parts of this page that have their own guide.

- **[YouTube chapters](https://foxcue.com/youtube-seo/chapters/)**: Description timestamps and YouTube's own key moments.
- **[YouTube descriptions](https://foxcue.com/youtube-seo/descriptions/)**: The text you reuse in the description field.
- **[Rank YouTube videos on Google](https://foxcue.com/youtube-seo/rank-on-google/)**: Pick searches that show video, then embed on a page.
- **[Help article to YouTube video](https://foxcue.com/docs-to-video/help-center-youtube/)**: Turn one help article into a how-to video.

## Questions

### How do you create video schema?

Write a VideoObject JSON-LD script block with name, thumbnailUrl and uploadDate, plus description, duration and embedUrl or contentUrl. Put it on the page where the video plays, then run the Rich Results Test. The example above is a starting point.

### Does VideoObject work for YouTube embeds?

Yes, on your page. Use the iframe's player URL as embedUrl and leave contentUrl out. Google's video documentation (read 18 Nov 2026) says it may index the video on your page and on YouTube, and your page should carry structured data.

### Which VideoObject fields are required?

Google's video structured data page (read 18 Nov 2026) lists name, thumbnailUrl and uploadDate as required. Everything else, including description, duration, contentUrl and embedUrl, is recommended.

### Is VideoObject valid without thumbnailUrl?

No. Google lists thumbnailUrl as required, with name and uploadDate. contentUrl or embedUrl does not stand in for it.

### Is schema still relevant for video?

Google still documents VideoObject, Clip and SeekToAction for video features (read 18 Nov 2026). It is not needed for AI Overviews, and the page still has to be indexed with the video findable.

### Does video schema help AI Overviews?

Google says no special schema is needed for AI Overviews or AI Mode. Ahrefs found no major citation uplift from adding JSON-LD across 1,885 pages (11 May 2026). Use it for accuracy, not as a citation lever.

### Will FoxCue write the markup?

No. FoxCue makes the video, drafts the title and description, and exports caption files and a transcript. Your web team adds the VideoObject markup and the embed.

## Related

- [Video SEO](https://foxcue.com/video-seo/): Video SEO gets your videos found on Google, in Video mode, on YouTube and in AI Overviews. The strategy, the on-page and YouTube steps, and how to check it.
- [YouTube SEO](https://foxcue.com/youtube-seo/): YouTube SEO is the supporting step to getting cited in Google's AI Overviews. The study behind it, every step in order, and which steps FoxCue automates.
- [YouTube chapters](https://foxcue.com/youtube-seo/chapters/): Add YouTube chapters in Studio: timestamps from 00:00, at least three, each 10+ seconds. Why chapters don't show, automatic chapters, and a list to copy.
- [Docs to video](https://foxcue.com/docs-to-video/): Docs to video: FoxCue reads your help center, finds the questions worth a video, writes the script from your docs, and edits your take for YouTube.
- [Rank YouTube videos on Google](https://foxcue.com/youtube-seo/rank-on-google/): Google shows YouTube videos for searches with video intent. Pick those searches, write the title and description, embed the video, then check.
- [Video is not the main content](https://foxcue.com/video-seo/video-not-main-content/): Search Console says your video is not the main content, or isn't on a watch page. What it means, when to leave it, and how to build a watch page.

---

Start with Studio: https://app.foxcue.com/ · Book a demo: https://foxcue.neetocal.com/intro · Plans: https://foxcue.com/pricing/
