---
title: "VideoObject schema: the required properties Google actually documents"
url: https://seomadman.com/research/videoobject-schema-required-properties
section: research
published: 2026-07-21T00:00:00.000Z
modified: 2026-07-21T00:00:00.000Z
author: Adam Hafez
topics: ["Structured data"]
---

# VideoObject schema: the required properties Google actually documents

## The short answer

Google's own VideoObject documentation lists three required properties: name, thumbnailUrl and uploadDate. contentUrl and embedUrl are recommended, not required, contradicting a common claim. Dates need full ISO 8601 with a timezone offset; durations use ISO 8601 duration format like PT00H30M5S. A valid block still does not guarantee a rich result.

## Key takeaways

- Google's VideoObject documentation lists only three required properties: name, thumbnailUrl and uploadDate.
- contentUrl and embedUrl are recommended properties, not required ones, and Google treats them as alternatives to each other rather than a mandatory pair.
- uploadDate must be full ISO 8601 with a time and timezone offset, matching Google's own example of 2024-03-31T08:00:00+08:00.
- duration uses ISO 8601 duration format, with Google's own example PT00H30M5S standing for thirty minutes and five seconds.
- Google states plainly that valid structured data does not guarantee a rich result will appear in Search.

VideoObject is one of the schema.org types where a specific, wrong-sounding claim travels further
than the source it is supposedly quoting. A four-property required list circulates in SEO advice:
name, thumbnailUrl, uploadDate, and either contentUrl or embedUrl. Checked directly against Google's
own current VideoObject documentation, that fourth requirement does not exist. Getting this
distinction wrong matters in practice, since a validator or a checklist that treats a recommended
property as required will flag pages that are, by Google's own definition, already compliant.

## The real required and recommended lists

Google's structured data page for Video draws a firm line between two tables, and only three
properties sit in the required one: `name`, the video's title; `thumbnailUrl`, a URL to the
video's unique thumbnail image; and `uploadDate`, the date and time the video was first published.
Nothing else appears in that table.

`contentUrl` and `embedUrl` both live in the recommended table instead, and Google frames them as
alternatives rather than a pair to satisfy together: it recommends providing `contentUrl` if
possible, since that is the most effective way for Google to fetch the video content directly, and
recommends falling back to `embedUrl` only if `contentUrl` isn't available. The rest of the
recommended table covers `description`, `duration`, `expires`, `hasPart`, `ineligibleRegion`,
`interactionStatistic`, `publication` and `regionsAllowed`, none of which is required either. A page
missing all of these still satisfies Google's required set as long as `name`, `thumbnailUrl` and
`uploadDate` are present and correctly formatted.

## The two formats that fail silently

Both dated properties use ISO 8601, but in different notations, and a mismatch will not throw a
JSON syntax error, it will simply be wrong data that Google either discards or misreads.
`uploadDate` needs a full timestamp with a timezone offset; Google's own documented example is
`2024-03-31T08:00:00+08:00`. A bare calendar date like `2024-03-31` is not the documented format,
even though it happens to parse as valid JSON.

`duration` uses ISO 8601 duration notation instead of timestamp notation, and Google's own example
is `PT00H30M5S`, which its documentation glosses directly as "thirty minutes and five seconds." The
leading `PT` marks a time duration, `H`/`M`/`S` mark hours, minutes and seconds, and the value has
no colons or slashes anywhere in it, a format this site's own video schema uses the same way (see
`duration` in the research collection's video entries, expressed as `PT12M30S` for twelve minutes
thirty seconds).

Google's thumbnail guidance is worth treating as a required check even though `thumbnailUrl` itself
is the only formally required property touching it: the file "must be accessible by Googlebot and
Googlebot Images," with Google specifically warning not to block it "with robots.txt or a login
requirement," and to keep it "consistently available at a stable URL." A thumbnail that returns a
login wall, a 404 after a redesign, or a redirect chain fails this requirement even when the
`thumbnailUrl` string itself is well-formed.

## Markup passing does not mean the video ranks

Google states its general caveat for structured data directly: it "does not guarantee that features
that consume structured data will show up in search results," even for markup that satisfies every
documented required and recommended property. A `VideoObject` block that validates cleanly still
depends on the underlying video file being reachable, the thumbnail staying accessible over time,
and the page's actual content matching what the markup asserts. None of that is something a schema
check can confirm from the JSON-LD alone; it can only confirm the markup is internally correct.

## Why we care

The gap between what circulates as VideoObject's required properties and what Google's own page
actually requires is exactly the kind of error this site's editorial rule exists to catch:
name, thumbnailUrl and uploadDate are required, contentUrl and embedUrl are recommended alternatives
to each other, and the date and duration formats have exact documented examples that are easy to
get subtly wrong without a syntax error ever surfacing. This site's [JSON-LD
validator](/tools/json-ld-validator/) already checks required and recommended properties for
Article, Product, FAQPage, HowTo, Organization, BreadcrumbList and Recipe against Google's own
documentation the same way this piece did for Video; VideoObject is not one of its seven supported
types yet, and adding it is a natural extension rather than a new category of check, since the
underlying method, reading Google's documented tables directly, is identical.

## Frequently asked questions

### Are contentUrl and embedUrl required for VideoObject?

No. Google's own required properties table lists only name, thumbnailUrl and uploadDate. contentUrl and embedUrl are both recommended, and Google presents them as alternatives to each other, with contentUrl preferred because it is the more effective way for Google to fetch the video file directly.

### What exact date format does uploadDate need?

Full ISO 8601 with a time and timezone offset. Google's own documentation example is 2024-03-31T08:00:00+08:00, not a bare calendar date, which is the format a validator should check for.

### What exact format does duration need?

ISO 8601 duration notation, not a timestamp. Google's own example is PT00H30M5S, which it describes as thirty minutes and five seconds, the same pattern used elsewhere on this site's VideoObject-adjacent schemas.

### Does valid VideoObject markup guarantee a video rich result?

No. Google states directly that it does not guarantee a rich result will appear even for markup that follows every documented guideline. The thumbnail, video file and page itself must also be genuinely accessible and match what the markup claims.

## Sources

1. [Video (VideoObject, Clip, BroadcastEvent) structured data](https://developers.google.com/search/docs/appearance/structured-data/video) - Google Search Central (primary)
2. [Video best practices](https://developers.google.com/search/docs/appearance/video) - Google Search Central