Define relationships

The YouTube XML format is being replaced by DDEX (music only) and CSV templates (all industries). YouTube strongly discourages any new implementations of the YouTube XML format. This page should be used solely as reference material for existing implementations. Visit Using the YouTube DDEX feed for more information about the new format.
The features described in this article are available only to partners who use YouTube's Content Manager to manage their copyrighted content.

A relationship associates an entity, such as an asset, a reference file, or a policy, with one or more related entities. The asset model diagram below helps to illustrate the function of content feed relationships.

The diagram shows how an asset is a combination of asset metadata, ownership data, reference material and embedded assets. In your content feed, however, these items appear as separate objects defined with separate tags: an <asset> tag contains asset metadata, an <ownership> tag contains ownership data, and a <file> tag identifies reference material. You use a relationship to tie these objects together.

There are two types of relationship:

  • A "contains" relationship specifies that one asset in the relationship embeds the other item in the relationship. For example, a music video may contain a sound recording asset, and a sound recording contains a composition asset. A "contains" relationship is always a relationship between assets.

  • An "associate" relationship creates a link between different types of objects. For example, this type of relationship allows you to unify asset metadata (<asset>), reference file(s) (<file>) and ownership data (<ownership>) into a single entity.

The default relationship type is the more flexible "associate". For that reason, many of the sample relationships in this document omit the type attribute.

Defining "contains" relationships

When you create a "contains" relationship, policies that administrators set for the embedded asset could affect the policies that YouTube enforces for the parent, or embedding, asset.

You can define a "contains" relationship from the perspective of the parent asset or the child asset. If a particular asset is embedded in multiple parents, such as a composition used in multiple sound recordings, you can use <relationship type="contained_by"> and specify the multiple parent assets as related items. The resulting parent-child relationship is the same regardless of which option you use in your feed.

To add child asset(s) to a parent asset:

  1. Use the tag <relationship type="contains">.

  2. Use exactly one <item> tag to identify the asset that embeds (contains) one or more other assets.

  3. Use one <related_item> tag to identify each embedded (or contained) asset.

To embed a child asset into multiple parent assets:

  1. Use the tag <relationship type="contained_by">.

  2. Use exactly one <item> tag to identify the asset that is contained within one or more other assets.

  3. Use one <related_item> tag to identify each asset that embeds the asset identified in the <item> tag.

Linking a trailer with a movie

If your feed includes information for new movie and trailer assets, the feed must define a "contains" relationship that identifies the movie that the trailer promotes. (The trailer contains content from the movie.) The example below shows a relationship that links a trailer and a movie.

<relationship type="contains">
  <item path="/feed/asset[@tag='trailer1'][@type='trailer']"/>
  <related_item path="/feed/asset[@tag='movie1'][@type='movie']"/>


To link a new trailer with an existing movie, you must define an "associate" relationship between the video objects rather than a "contains" relationship between the assets.

  <item path="/feed/video[@tag='foo'][@type='trailer']"/>
  <related_item path="/external/video[@id='VIDEO_ID_1']"/>


Linking a television season with its episodes

The relationship in the example below specifies that a television season contains a number of episodes. This example contains one item (the season asset) and several related items (the episode assets).

<relationship type="contains">
  <item path="/feed/asset[title='Season Two']"/>
  <related_item path="/feed/asset[episode='23']"/>
  <related_item path="/feed/asset[episode='24']"/>
  <related_item path="/feed/asset[episode='25']"/>


Linking a composition and sound recordings

In the examples below, two different sound recordings contain the same composition. The examples show two alternative ways to define the relationship between the recordings and the composition.

The first example uses two relationships to link the composition to each sound recordings. Each relationship contains one item and one related item.

<relationship type="contains">
  <item path="/feed/asset[isrc='USZZ99900001']"/>
  <related_item path="/external/asset[iswc='T3452468001']"/>

<relationship type="contains">
  <item path="/feed/asset[isrc='USZZ32857251']"/>
  <related_item path="/external/asset[iswc='T3452468001']"/>


The second example defines the relationship from the perspective of the composition ("contained_by"). It uses one relationship with two related items.

<relationship type="contained_by">
  <item path="/feed/asset[iswc='T3452468001']"/>
  <related_item path="/external/asset[isrc='USZZ99900001']"/>
  <related_item path="/external/asset[isrc='USZZ32857251']"/>


Defining "associate" relationships

An "associate" relationship links objects of different types. The effect of the relationship depends on the nature of the objects being related, as detailed in the table below.

To associate objects of different types:

  1. Use the tag <relationship type="associate">, or just <relationship>. without a type argument.

  2. Use one or more <item> tags to identify the object(s) that will then be associated with the related item(s).

  3. Use one <related_item> tag to identify each associated object.

Note that if a relationship specifies multiple <item>s, YouTube will view those items as a single entity for the purpose of the relationship. The pseudo-example below shows a <relationship> tag that defines two relationships, "AB1" and "AB2":

<relationship type="associate">
  <item path="A"/>
  <item path="B"/>
  <related_item path="1"/>
  <related_item path="2"/>


The table below identifies the different kinds of "associate" relationships that your feed can define.

Type of entity (or entities) identified by <item> tag(s) Type of entity identified by <related_item> tag(s) Effect of relationship
<asset> <file> Each file identified as a related item is reference material for the asset.
<file> The file identified as a related item is reference material for the asset. The time intervals identified in the <reference_exclusions> tag are not considered when determining Content ID matches for the reference.
<reference_exclusions> <reference> The time intervals identified in the <reference_exclusions> tag are not considered when determining Content ID matches for the reference.
<asset> <video> Use the content for the specified video to create a reference for the asset. Note: The video must have been uploaded to a YouTube user account that is linked to your content owner.
<file> <asset>
Note: This option is only valid for sound recording assets.

The file is reference material for the sound recording asset identified as a related item, and the sound recording is also included in YouTube's AudioSwap program.
<ownership> <asset> The ownership data applies to each asset identified as a related item.
<asset> The two <item> tags identify the administrator who administers rights for the asset as well as the policy that the administrator is applying for each asset identified as a related item.
  • If the value of the <rights_admin> tag's type attribute is usage, then the relationship sets the default usage policy for the asset.
  • If the value of the <rights_admin> tag's type attribute is match, then the relationship sets the default match policy for the asset.
<video> <file> The reference file content will be the content used for the related YouTube video.

Replacing a video's existing content: If the reference file is being associated with an existing video (that already has video content), and the file content depicts the same video, then the file content will replace the existing video content. As such, you can remove imperfections in the previous version of the video or switch to a nearly identical video that has a different resolution, aspect ratio, sound quality, etc.
<video type="trailer"> <video type="movie"> Associates a trailer with the movie that it promotes.
<video> A caption track will be associated with the video. The <caption> tag contains the metadata for the caption track, and the <file> tag identifies the caption track itself.
<caption> <video> A caption certification will be associated with the video. The <caption> tag contains a certification reason that explains why captions are unavailable for the video.
<content_rating> <video> The YouTube Content Rating will be assigned to each video identified as a related item in the relationship. YouTube Content Ratings allow partners to identify the presence (or absence) of explicit language, violence and other potentially objectionable content in their videos. See YouTube content ratings for more information.
<video_breaks> <video> The video breaks identify the times when mid-roll ads could run for the related video. If you are providing ad targeting information for a third-party ad server, then the <video_breaks> tag will also provide this targeting information for the video's ad breaks.
<ad_policy> <video> The ad policy applies to each video specified as a related item.
<video> The rights administrator claims each video specified as a related item. The video is specified as a match for the asset, and YouTube applies the rights policy. The claim indicates whether the administrator is claiming the audio, video or audiovisual portion of the video.
Was this article helpful?
How can we improve it?