Schema Forge

Schema guide

Video schema markup (VideoObject JSON-LD)

How to write VideoObject JSON-LD: name, thumbnail, upload date, duration and links, with a working example and notes on getting videos indexed.

Overview

Short answer

VideoObject markup describes a video on a page: its title, thumbnail, upload date, length and where the file or player lives. Google needs a name, a thumbnailUrl and an uploadDate. The video should be a main part of the page, not a small extra.

What it can do for you

Google Rich results: yes
Yes. It helps Google find and show the video in video results, as long as the video is the main content of the page.
AI and answer engines
Title, description, duration and upload date describe the video without having to watch it.

Use it when

  • A page where a video is the main content, or one of the main things on it

Skip it when

  • A page where a video is a small decoration beside other content
  • A video that visitors need to be logged in to watch

Properties

PropertyStatusNotes
nameRequiredThe video title.
thumbnailUrlRequiredA crawlable image address. Several sizes help.
uploadDateRequiredISO 8601, ideally with a time zone.
descriptionRecommendedA sentence or two about what happens in the video.
contentUrl, embedUrlRecommendedThe video file address, or the player page address. Give at least one.
durationOptionalAn ISO 8601 duration, such as PT5M12S.

Example

video.jsonld (example)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to glaze a mug in five minutes",
  "description": "A short walkthrough of dipping, wiping and firing a stoneware mug.",
  "thumbnailUrl": [
    "https://example.com/img/glaze-thumb.jpg"
  ],
  "uploadDate": "2026-05-02T08:00:00Z",
  "duration": "PT5M12S",
  "contentUrl": "https://example.com/video/glaze.mp4",
  "embedUrl": "https://example.com/embed/glaze"
}
</script>

It looks for a video element, a YouTube or Vimeo embed, or og:video meta tags. The thumbnail comes from the poster image or the page image; for a YouTube embed it is built from the video id and flagged so you can check it loads.

If no upload date is stated, the page publish date is used and flagged, because Google needs a date. Replace it with the real one when they differ.

Common mistakes

  • A missing or relative thumbnail address.
  • An upload date with no day, or in a format such as "May 2".
  • Only a contentUrl that points at a page instead of the video file.
  • Marking up videos that are not on the page.

Questions

What does Google require for video markup?

A name, a thumbnailUrl and an uploadDate. It recommends a description, a duration and a contentUrl or embedUrl.

Does the video have to be on my own site?

No. An embedded YouTube or Vimeo video can be marked up with its embedUrl. Google may show the video platform instead of your page, though, so check where you want the result to point.

What is the difference between contentUrl and embedUrl?

contentUrl is the address of the video file itself. embedUrl is the address of the player. Provide whichever you have, or both.

Why was my video not indexed?

Common causes are a video that is not a main part of the page, a page blocked from crawlers, or a thumbnail Google cannot fetch. The Search Console video report names the reason.

Generate this markup for your page

Paste the address of a public page and get a ready-to-paste block, with every gap listed.

Open the generator

Keep going