Using the YouTube content feed

Content feeds use XPath syntax to identify the items and related items in a relationship. You can specify an XPath that identifies an element or a group of elements in the current XML feed, or identify previously created entities – assets, references, etc. – stored in YouTube’s database.

Please keep the following rules in mind when constructing XPaths:

• YouTube may process XPaths that refer to stored entities before creating new items specified in a feed. As such, your feed should not use an XPath that refers to a stored entity if that entity is actually being created in the same feed.For example, if your feed creates a new asset, you should not use an external XPath that identifies that asset using its custom ID and asset type since that path could be processed before the new asset is actually created. Instead, use a path that identifies the asset as an item within the feed using either a tag attribute value, field values, or ordinal syntax.
• By assigning unique custom IDs to assets and specifying unique tag attribute values for entities specified in a feed, you can ensure that your XPaths will identify specific, individual items.
• YouTube supports much more of the XPath syntax for paths that identify items within a feed than for paths that identify stored entities.

The following instructions explain the supported syntax for XPaths in your feeds.

• Identifying items within a feedYouTube provides extensive XPath support for identifying items within a feed. The XPath for an item in a feed begins with /feed. The examples below demonstrate some of these different techniques:
  • The tag attribute lets you assign values to uniquely identify each item in your feed. The XPaths in a relationship can then use the tag attribute values to identify the items that are included in that relationship. All child elements of <feed> can use the tag attribute, including <asset>, <file>, <ownership>, and so on.In the sample feed below, the provider uses the same tag attribute value to identify an asset, a reference file, and a YouTube video. This practice assumes that each asset has exactly one reference file, which the provider makes available as a YouTube video. (Each file must have a unique filename.)

    <asset tag="foo.mpg">   
       ... 
    </asset> 
    <file tag="foo.mpg" type="video">
       <filename>foo.mpg</filename>
    </file>
    <video tag="foo.mpg">
       ... 
    </video>
    <relationship>
       <item path="/feed/asset[@tag='foo.mpg']" />   
       <related_item path="/feed/file[@tag='foo.mpg']" /> 
    </relationship> 
    <relationship>   
      <item path="/feed/file[@tag='foo.mpg']" />   
      <related_item path="/feed/video[@tag='foo.mpg']" /> 
    </relationship>

  • Field values let you identify items in a feed based on XML field values that may, or may not, be unique. The feed snippet below shows sample relationships that use field values to identify the relationship components:

    <relationship>
       <item path="/feed/rights_admin[@type='match']" />
       <item path="/external/rights_policy[@name='Block everywhere']" />   
       <related_item path="/feed/asset[@type='episode'][season='2'][show_custom_id='BC']" /> 
    </relationship> 
    <relationship>   
       <item path="/feed/rights_admin[@type='match']" />
       <item path="/external/rights_policy[@name='Monetize everywhere']" />   
       <related_item path="/feed/asset[@type='episode'][season='1'][show_custom_id='BC']" /> 
    </relationship>

    These relationships specify the following information:

    • The first relationship sets the match policy to “Block everywhere” for all episodes in season 2 of a particular show.
    • The second relationship sets the match policy to “Monetize everywhere” for all episodes in season 1 of the same show.
  • Ordinal syntax lets you identify an item based on its position in the feed. The relationships in the XML snippet below associate the first <asset> element in the feed with the first and second <file> elements in the feed. It also associates the first <file> element with the first <video> element, and the second <file> element with the second <video> element.

    <relationship>
       <item path="/feed/asset[1]" />   
       <related_item path="/feed/file[1]" />   
       <related_item path="/feed/file[2]" /> 
    </relationship> 
    <relationship>   
       <item path="/feed/file[1]" />   
       <related_item path="/feed/video[1]" /> 
    </relationship> 
    <relationship>   
       <item path="/feed/file[2]" />
       <related_item path="/feed/video[2]" /> 
    </relationship>

    This practice may be useful if your code selects all of the information for an asset, including its metadata, reference files and YouTube video information, and then writes that information in the XML feed before proceeding to the next asset. The pseudo-code below demonstrates how this feed generation might work:

    var assetCount = 0;
    var fileCount = 0; 
    var videoCount = 0;
      
    var query = "select metadata_fields, files, video_data from DB for assets";
    
    for asset in query->results {
       assetCount++;
       add asset metadata (<asset>) to feed;
       for file in asset's reference_files {
         fileCount++;
         add file information (<file>) to feed;
         add relationship to feed where asset XPath = "/file/asset[assetCount]"
                                     and file XPath = "/feed/file[fileCount]"
         if you are creating a YouTube video from the file {
           videoCount++;
           add video data (<video>) to feed
           add relationship to feed where file XPath = "/file/asset[fileCount]"
                                     and video XPath = "/feed/file[videoCount]"
         }
       }
     }

• Identifying other items in YouTube’s databaseYouTube feeds also let you identify entities that are stored in YouTube’s database. The following list identifies several use cases for identifying external entities:
  • Specify that an existing asset embeds a newly defined asset.
  • Update the metadata for an existing asset.
  • Associate an additional reference file with an existing asset.
  • Use a saved policy for a claim or as the default match or usage policy for a reference.

  An XPath in your XML feed that identifies a stored entity – asset, saved policy, etc. – will begin with /external. The following list identifies the XPaths that your feed can use to identify stored entities:

  • Assets
    • /external/asset[@id=’ASSET_ID’] – YouTube assigns an asset ID to uniquely identify every asset. If a feed creates an asset, YouTube will provide the new asset ID in the status report for the feed.
    • /external/asset[@custom_id=’CUSTOM_ID_FOR_ASSET’][@type=’ASSET_TYPE’] – This XPath identifies an asset using the custom ID that you provided for the asset as well as the asset type. You should only use this method to identify assets if your custom IDs uniquely identify your assets.
  • References
    • /external/reference[@id=’REFERENCE_ID’] – YouTube assigns a reference ID to uniquely identify every reference. If a feed creates a reference, YouTube will provide the new reference ID in the status report for the feed.
  • Videos
    • /external/video[@id=’VIDEO_ID’] – YouTube assigns a video ID to uniquely identify every YouTube video. If a feed creates a video, YouTube will provide the new video ID in the status report for the feed.
  • Rights administrators
    • /external/rights_admin[owner=’True’] – This XPath indicates that the rights administration rules used in a claim or relationship mirror the ownership rules specified for the asset identified in the claim or relationship.
    • /external/rights_admin[owner=’True’][type=’RIGHTS_ADMIN_TYPE’] – This XPath indicates that, for either partner-uploaded or user-uploaded videos, the rights administration rules used in a claim or relationship mirror the ownership rules specified for the asset identified in the claim or relationship.
  • Rights policy
    • /external/rights_policy[name=’SAVED_POLICY_NAME’] – This XPath identifies a saved policy by the name that you have given to the policy. If you plan to identify saved policies in your XML feed, please ensure that your policies have unique names.

  XML samples for external XPaths

  The examples below demonstrate some common use cases for external XPaths:

  • Using a saved policy as a default usage or match policyIn this example, the <relationship> tag identifies an asset that is being associated with a rights administrator and a saved policy, which is identified with an external XPath.

    <relationship>
       <item path="/feed/rights_admin[1]"/>
       <item path="/external/rights_policy[@name='Monetize Everywhere']"/>
       <related_item path="/feed/asset[@tag='foo.mpg']"/>
     </relationship>

  • Creating a claim with a saved policyIn this example, the <claim> tag identifies a video being claimed, the asset that matches the video, the administrator for the asset and the policy that the administrator is applying. The policy is a saved policy identified with an external XPath.

    <claim type="audiovisual"
            asset="/feed/asset[@tag='foo.mpg']"
            video="/feed/video[@tag='foo.mpg']"
            rights_admin="/feed/rights_admin[@type='match']"
            rights_policy="/external/rights_policy[@name='Monetize Everywhere']"/>

For more information on Multi Channel Network’s and YouTube how to videos please check back weekly or subscribe here.