VideoObject markup, field by field

VideoObject is the schema.org type that describes a video to a machine. It is not complicated, but the difference between markup that produces a rich result and markup that is quietly ignored is usually one field.

The required fields

• name — the video’s title. What the video is, not what the campaign was called.
• description — a sentence or two describing what is shown. This is a real description, not a keyword list; it is also frequently what gets displayed.
• thumbnailUrl — a publicly reachable image. Multiple sizes are allowed and preferred.
• uploadDate — ISO 8601, with a timezone. A date with no timezone is a common and silent cause of the whole block being ignored.

Miss any of these and you do not have valid VideoObject markup, whatever else is present.

The ones worth adding

• duration — ISO 8601 duration (PT30S for thirty seconds). This is what puts the length on the search result, which is a real click-through signal.
• contentUrl — a direct link to the video file. Lets the engine fetch and understand the video rather than guessing from the page.
• embedUrl — if the video is in a player, the player’s URL.
• publisher — who published it, normally referencing your Organization node.

The mistakes

Describing a video that is not there

The most serious. Markup for a video the page does not render, or that requires an interaction before it exists. Treated as an attempt to obtain a rich result the page does not deserve, and penalised accordingly.

A thumbnail that is not reachable

Behind authentication, blocked in robots.txt, or on a CDN that refuses unknown user agents. The crawler cannot fetch it, so the rich result cannot be built. Test the URL in a private browser window.

A date with no timezone

“2026-03-14” is ambiguous. “2026-03-14T09:00:00+00:00” is not. Cheap to get right and easy to get wrong by hand.

Keyword-stuffed names

“Linen shirt video buy linen shirt best linen shirt 2026” is not a video title. It reads exactly as badly to a classifier as it does to you.

Where it should live

JSON-LD in the page’s head, rather than microdata sprinkled through the markup. It is the format Google recommends, it can be generated in one place, and it does not break every time someone changes a template.

If your page has other structured data — an Organization, a breadcrumb trail, a product — put everything in one graph and cross-reference by identifier rather than repeating the same organisation three times in three blocks. One coherent description of the page beats several partial ones.

Checking it

Google’s Rich Results Test on a live URL, and the video report in Search Console over time. The test tells you the markup is valid; the report tells you whether it is being used, which is the question you actually care about.