Using JSON-LD for video SEO
Many videos are uploaded to our system because you want a private link to them. You can specifically require authentication (using SAML2, or a JWT in its URL). However you may want a video to be found by the public. For example a video embedded on your company’s website describing your service or demonstrating your product. These are the videos that you want to appear in search engines.
Recognising this we added a public option within our privacy settings. When our video CMS sees that option, we add additional metadata to the video’s landing page and embed code to help search engines and social sites recognise the video.
Since Google remains the dominant search engine it is a priority to have it properly recognise your content as part of video seo. Since JSON-LD is the default tab on Google’s documentation for adding structured data to a page, clearly it is a recommended approach. And JSON-LD, added as a block to the page, usually in the <head>, is simpler than wrapping separate HTML tags with Microdata (an alternative approach to marking up content).
That saves you from having to spend any time manually generating it. Some atttributes, like “name” are self-explanatory and easy to add. But the format of some of the values can be a bit tricky. For example the “uploadDate” needs to be formatted as ISO 8601. Similarly for the “duration”. It’s simple to write a time-code. A video that is 20 minutes and 5 seconds long would be “0:20:05” (as H:MM:SS). However JSON-LD needs the duration formatted using ISO 8601, so PT00H20M5S.
What actually is JSON-LD?
It stands for JavaScript Object Notation for Linked Data.
Based on JSON, it is designed to markup data to help automated systems understand it. It is based on the schema.org vocabulary. That schema was initially agreed around 10 years ago by the large internet companies so they could consistently understand data.
In our case we are interested in marking up videos. So we need to examine the VideoObject: https://schema.org/VideoObject.
It contains a series of name and value pairs. All within a script block, which needs to be correctly labelled so that the browser knows not to execute it as JavaScript:
<script type="application/ld+json">
...
</script>Why add JSON-LD?
It can make the video stand out in search results. While Google can not guarantee to index a page, or indeed to list your video, by adding the data it recommends we give it the best chance.
Without any structured data to help Google understand a video, it may still list your page but using its standard blue link. Adding a thumbnail and additional attributes means it may be presented in a much more visible way. For example one of our old videos:
You can test your own URL to see if Google is able to locate a video and how it understands it using their free rich results test.
What values are needed for a video?
Google requires the following four attributes in the JSON-LD to help it recognise a video:
1. name
The title of the video.
2. description
A longer description of the video.
3. thumbnailUrl
An array of URLs. A thumbnail should be at least 60x30 in size but should be larger. The thumbnail image is important as without this, Google won’t list it within their Videos tab or present it with an image in the main organic search results.
4. uploadDate
The time the video was added, formatted using the ISO 8601 standard.
They also support additional recommended values to help it understand and present the video. So we automatically include additional ones for you, such as the duration and embedUrl.
So if you set one of your videos as public you should see an additional JSON-LD script in its <head> tag. Like this:
Note: we normally will not incude their suggested contentUrl attribute. That is because Google requires a stable URL to fetch your video file from. Since we use a CDN to deliver video files, often the CDN URL will have an expiry built in to it using a secure token in its path or query string. And once that link expires, Google would no longer be able to fetch the file. As such we use their alternative embedUrl attribute which is generally the same URL used as the embed code’s iframe src attribute.
Updated: July 13, 2021