Skip to the indexed answers
Digital Marketing Index

usdigitalmarketingindex.com SEO

How should VideoObject schema describe a video embedded in a written article?

It should describe the video itself, the one a reader can play on that page, with its own title, thumbnail, and upload date, and with an address for the video file or its player. Those describe the video, not the article around it. Google’s documentation lists three required properties, name, thumbnailUrl, and uploadDate, and recommends others, including contentUrl or embedUrl, description, and duration (Google’s video structured data documentation). One expectation needs setting at the start: Google treats an article with a supporting video differently from a page built to show a video, and accurate markup does not change which of the two a page is.

Video identity and URL

Three addresses are involved, and they are easy to confuse.

Address What it is Where it goes
The article URL The page the reader visits Not a video property; it is where the markup lives
The player URL The address of the embedded player for this one video embedUrl
The file URL The address of the video file itself contentUrl

The documentation is specific about the last two. For contentUrl: “Don’t link to the page where the video lives; this must be the URL of the video file’s actual content bytes itself”. For embedUrl, the value is the player for the specific video, which the documentation describes as usually “the information in the src attribute” of the embed element. It also states a preference: “If contentUrl isn’t available, provide embedUrl as an alternative”.

For a video hosted on a third-party platform and embedded in the article, the file URL may not be yours to give. In that case embedUrl is the property to use.

An example for an article with one embedded video. All names and addresses are placeholders.

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "Replacing a tap washer: the three steps",
  "description": "A plumber shows how a worn tap washer is identified and replaced.",
  "thumbnailUrl": [
    "https://www.example.com/images/tap-washer-video-16x9.jpg"
  ],
  "uploadDate": "2026-05-14T08:00:00+00:00",
  "duration": "PT3M42S",
  "embedUrl": "https://video.example.net/embed/abc123"
}

Thumbnail and upload data

The required properties, in the documentation’s terms:

Property Content Note from the documentation
name The title of the video "Make sure to use unique text in the name property for each video on your site"
thumbnailUrl The address of the video's thumbnail image A thumbnail unique to the video, at a stable address
uploadDate The date and time the video was first published, in ISO 8601 format Timezone information is recommended

Recommended properties worth including for an article video:

  • description: a description of the video, again unique to it. This is not the article’s summary.
  • duration: the length in ISO 8601 form, such as PT3M42S for three minutes and forty-two seconds.
  • contentUrl or embedUrl, as above.

Use the video’s own facts. The upload date is when the video was published, which may differ from the article’s date. The name is the video’s title, which may differ from the headline.

Visible page correspondence

The markup describes something the reader can see and play. Google’s structured data guidelines say “Don’t mark up content that is not visible to readers of the page” (Google’s structured data general guidelines), and its video guidance adds that a video “can’t be hidden behind other elements”.

Element In the markup On the page
Video One VideoObject The same video, embedded and playable
Title name The video's title, shown with or in the player
Thumbnail thumbnailUrl The image the player shows before playing
Description description Consistent with what the video shows
Player embedUrl The player that is embedded

Rules that follow:

  • No VideoObject for a video that is linked to and not embedded.
  • No VideoObject left behind after the video is removed from the article.
  • One VideoObject per video. An article with two videos has two, each with its own values.
  • If the video sits behind a click, a tab, or a consent wall, check that it is still present in the rendered page Google sees.

The VideoObject can stand alone on the page or be attached to the article’s own markup through the Article type’s video property. Either way it describes the same single video.

Validation

What to expect is the part that the validation tools do not state. Google’s video guidance separates watch pages from pages where a video supports other content. A watch page’s “main purpose is to show users a single video”. By contrast, the guidance lists pages that are not watch pages “because the video is complementary to the rest of the content”, and its examples include a “blog post that reviews an embedded video” (Google’s video SEO best practices). For eligibility for video features, the same page says the video “must be embedded on a watch page”.

So for a written article in which the video is a supplement:

  • the markup is still an accurate description of the video and can be kept;
  • the article “can still be eligible to appear as a text result”, in the guidance’s words, and as an image result with a video badge;
  • video features are tied to watch pages, and the guidance says it is fine for the same video to appear on both a watch page and an article.

Checks to run:

Check Method Pass condition
Markup is read Rich Results Test Video item detected; required properties present
Thumbnail Open the thumbnailUrl Loads an image; address does not expire
Player or file Open the embedUrl or contentUrl Loads the player or the file, not the article
Dates and duration Read the values ISO 8601 format; match the real video
Rendering URL Inspection, rendered HTML The embedded video is present
Site-wide Search Console video indexing report Read the reasons given for pages where no video is indexed
After changes Retest when the player, host, or template changes Values still correct

A report that a video is not indexed on an article page is, under the guidance quoted above, consistent with the page not being a watch page. It is not by itself a markup error.

Whether a particular video deserves a page of its own is a separate decision, with its own criteria, covered in the guide to when a video should have its own watch page instead of appearing only within an article.

The rule: mark up the video that is on the page, with the video’s own title, thumbnail, date, and player address, and judge the result by what kind of page it is.

Link trail

Reader comments on this answer

Add your comment to this answer

Your email address will not be published. Required fields are marked *