usdigitalmarketingindex.com SEO
How should VideoObject schema describe a video embedded in a written article?
Updated November 15, 2026
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.
Add your comment to this answer