VideoObject schema: the required properties Google actually documents

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 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.