If you embed a YouTube video on your website, search engines cannot reliably tell that the page contains a video. The embed is an iframe pointing at somebody else’s domain, and what is inside it is not yours to describe.

Structured data is how you tell them. We added it to 31 commercial pages, and the interesting decision was a field we deliberately left empty.

What the markup has to contain

A block of machine-readable data describing the video. Four fields are required, and two more are read when present:

Field Required What it is
name Yes The video’s title
description Yes What it is about
thumbnailUrl Yes A real, reachable image
uploadDate Yes When it was published, in ISO format
duration Read if present Runtime, as an ISO 8601 duration
embedUrl Read if present The player URL

Two things about that table cause most of the problems.

duration is not 5:32. Schema.org expects an ISO 8601 duration — PT5M32S. A human-readable runtime is simply not parsed, and a wrong duration is worse than none, because it is a claim about the video that the video contradicts.

Every one of these should come from the platform’s own data, not from memory or from the page. We pull ours from the video platform’s API for the exact video being embedded, which means the values cannot drift from reality.

The field we left out

There is a seventh field, contentUrl, for the direct address of the video file itself.

We do not include it, because we do not host the file. YouTube does, and we have no stable, permitted URL to a raw video file to point at.

The temptation is to put something plausible there. Do not. A contentUrl that returns a 404 or an HTML page rather than a video is a broken claim in your structured data, and broken claims in structured data are how a site loses rich results across the board rather than on the one page. Search engines respond to invalid markup by distrusting the source, not by ignoring the field.

The correct arrangement when you embed rather than host: embedUrl only, and no contentUrl. Claim what you can support.

★ Insight ───────────────────────────────────── This is the same rule as any claim: the cost of an unsupported assertion is not the assertion, it is the credibility of everything alongside it. A page with slightly thinner structured data is worth more than a page with complete-looking structured data containing one field that does not resolve. The instinct to fill every available field is the problem, and it is strong because empty fields look like unfinished work. ─────────────────────────────────────────────────

Where the markup has to live

The mistake we designed around: structured data written separately from the thing it describes drifts.

If your video markup sits in a page template and your embed sits in the content, somebody will eventually swap the video and not the markup. The page then carries a machine-readable description of a video that is no longer there, indefinitely, with nothing failing.

We put both in one component. The thing that renders the player also emits the description of it, from the same values. They cannot disagree, because there is only one set of facts.

That principle generalises well past video. Any time you have structured data describing something rendered elsewhere on the page, ask what stops the two diverging. Usually the answer is nothing, and the divergence has no symptom.

What a small business actually gets from this

Honest expectations, because video markup is oversold.

It makes the page eligible for a video result. Eligible, not entitled. Eligibility is necessary and nowhere near sufficient.

It tells search engines the page contains a video, which they otherwise struggle to determine for an embed.

It provides the thumbnail and duration shown if the video does appear in a result.

What it does not do is improve your ranking for the page’s main topic, and it will not generate traffic on its own. It is a small, cheap correctness measure on pages that already have a video, not a growth tactic.

Where the values should come from

One more design point, because it determines whether this stays correct.

Every value in the markup should come from the video platform’s own data for that specific video — title, description, thumbnail, publication date and duration, fetched from the API rather than typed.

Two reasons. Typed values drift the moment the video is re-uploaded or retitled, and nobody updates markup they cannot see. And a wrong duration or a stale title is a claim the page makes that the video contradicts, which is worse than omitting the field.

The practical version for a site with a handful of videos: keep the values in one place per video, not scattered through page templates, and treat them as data rather than as markup somebody writes by hand.

If you have videos on your site now

Four checks:

  1. Do your pages with embeds have video structured data at all? Most do not. A structured data testing tool will tell you in seconds.
  2. Is duration in ISO format? PT5M32S, not 5:32.
  3. Is there a contentUrl, and does it actually return a video file? If it returns a page or a 404, remove it.
  4. Does the markup describe the video currently embedded? Check one page where the video has been changed since launch.

The fourth is the one that finds real problems, and it only takes one page to tell you whether you have a drift problem or not.

Cosmos Web Tech handles technical SEO, structured data and web builds for Hills District and Western Sydney small businesses. Hosting comes from Cloud Geeks, and we are part of Ganda Tech Services.