Managing Composition Assets

Note: The YouTube Content ID API is intended for use by YouTube content partners and is not accessible to all developers or to all YouTube users. If you do not see the YouTube Content ID API as one of the services listed in the Google API Console, see the YouTube Help Center to learn more about the YouTube Partner Program.

Note: The information in this guide applies specifically to composition assets.

In YouTube's rights management system, an asset represents a piece of intellectual property. YouTube recognizes different types of assets, such as movies, music videos, sound recordings, and compositions.

Due to the complex nature of composition ownership and rights, however, YouTube uses a two-tiered asset model for composition assets. The model is designed to account for the following:

  • Every sound recording is associated with a composition.
  • Content owners often need to apply ownership of the publishing rights for the same song or composition to different sound recordings.

This document provides an overview of YouTube's composition asset model. It also explains how the two types of composition assets are used in YouTube Content ID API methods.

Understanding the composition asset model

YouTube's asset model defines two different representations of composition assets:

  • A composition share represents the information that a particular publisher provides about a composition asset. Thus, a composition share only identifies the metadata, ownership, and policy data that that single publisher provides for the composition.

    A composition share can be associated with many sound recordings.

  • A composition view represents the composition asset that is embedded in a sound recording. Each sound recording maps to exactly one composition view, and the composition view represents the canonical set of information that YouTube displays about a composition. The composition view's metadata, ownership data, and policy are determined using data from all of the associated composition share assets.

    A composition view can map to zero or more composition shares. However, a composition view only maps to multiple composition shares when a composition has multiple owners.

    Note that it is possible for a single content owner using the API to represent multiple owners of a composition and, therefore, own multiple shares of that composition. For example, an aggregator of digital rights could obtain rights to the same composition from different parties in different territories. The aggregator would have discrete entities representing those rights, which would map to different composition shares in YouTube's model. The different composition shares could still be linked to the same composition view(s).

The following diagram illustrates this model. In the diagram:

  • Circles are sound recordings.
  • Squares are composition views.
  • Triangles are composition shares. Each triangle color represents a different content owner. The small triangles inside the squares show which data is merged to generate the canonical set of information that YouTube displays about a composition. YouTube uses that data to calculate a composition's ownership and policy.
Diagram showing relationships between sound recordings, composition views, and composition shares.

Two types of asset IDs

YouTube assigns IDs to composition shares and composition views, and both are considered asset IDs. However, they are not interchangeable in the API. With that in mind, the rest of this document uses the terms shareId and viewId to refer to the IDs assigned to composition shares and composition views, respectively.

In general, when you are retrieving or updating information that you provide about an asset, you will use a shareId. If you are retrieving the canonical set of information that YouTube displays about an asset, you will use a viewId.

If you look back to the diagram in the previous section, you'll see that the sound recordings and composition views are marked with numbers (SR1, CV1, etc.). The numbers reflect the 1:1 relationship between sound recordings and composition views. So, if you wanted to retrieve the canonical set of information about the composition in a particular sound recording, you would use the viewId for that composition.

On the other hand, composition shares are marked with letters (CSb, etc.). The letters represent different content owners. So, if you are the green content owner, and you wanted to retrieve the metadata or ownership data that you had provided for a composition asset, you would use the shareId to retrieve that information.

Using asset IDs in API methods

The remainder of this document explains how individual API methods handle shareIds and viewIds when those IDs are used as parameter or property values. Since the API methods are listed alphabetically, it might be useful to first walk through the typical steps associated with creating a composition asset and linking it to a sound recording.

  1. Call the assets.insert method to create a composition asset. The API response is an asset resource in which the id property is a shareId.

  2. Call the ownership.update method to set ownership data for the composition share. Set the method's assetId parameter to the shareId obtained in step 1.

  3. Call the assetMatchPolicy.update method to set policy data for the composition share. The policy is applied to claimed videos that contain the composition. Set the method's assetId parameter to the shareId obtained in step 1.

  4. Call the assetRelationships.insert method to identify sound recordings that contain the composition. In the assetRelationship resource that you are inserting, set the parentAssetId property to the sound recording's asset ID. Set the childAssetId property to the shareId obtained in step 1.

  5. If you store a mapping of viewIds to shareIds, you can retrieve the viewId by calling the assetRelationships.list method and setting the assetId parameter to the sound recording's asset ID. One relationship in the result set will identify the sound recording's asset ID as the parentAssetId. In that relationship, the childAssetId identifies the viewId that maps to the shareId obtained in step 1.

After the asset is created, you might use any of the methods discussed in the rest of this document to retrieve information about it, to update it, or to delete it.

assets.get/assets.list

The assets.get and assets.list methods retrieve information about an asset or list of assets. Both methods support the same set of request parameters.

Three of those parameters – fetchMatchPolicy, fetchMetadata, and fetchOwnership – use the values effective and mine to indicate whether you want to retrieve the canonical set of data about the asset or if you want to retrieve data that you provided about the asset. Those values are a vestige of YouTube's old composition asset model, which treated a composition view and its composition shares as a single entity.

The values are still supported in the two-tiered model, however, and the API response's content is dependent on both the parameter value and on whether the requests are providing shareIds or viewIds. Note that the assets.get method uses the assetId parameter to specify the asset ID, while the assets.list method uses the id parameter.

The list below explains how request parameter values affect the content of the API responses for these two methods.

  • fetchMatchPolicy
    • If the asset ID (id or assetId parameter) specifies a shareId:
      • If the fetchMatchPolicy parameter is mine, the API response contains the policy that the content owner authorizing the API request set for the composition share.
      • If the fetchMatchPolicy parameter is effective, the API returns a 400 error.
    • If the asset ID specifies a viewId:
      • If the fetchMatchPolicy parameter is mine, and the content owner authorizing the request owns only one composition share that is linked to the view ID, then the API returns the match policy that is set for that composition share.
      • If the fetchMatchPolicy parameter is mine, and the content owner authorizing the request owns multiple composition shares linked to the view ID, then the API returns a 400 error.
      • If the fetchMatchPolicy parameter is effective, the API returns the canonical match policy for the composition view. That match policy accounts for the match policies of all composition shares linked to the viewId, regardless of which content owners own those shares.
  • fetchMetadata
    • If the asset ID specifies a shareId:
      • If the fetchMetadata parameter is mine, the API response contains the asset metadata that the content owner authorizing the API request set for the composition share.
      • If the fetchMetadata parameter is effective, the API returns a 400 error.
    • If the asset ID specifies a viewId:
      • If the fetchMetadata parameter is mine, and the content owner authorizing the request owns only one composition share that is linked to the view ID, then the API returns the metadata that is set for that composition share.
      • If the fetchMetadata parameter is mine, and the content owner authorizing the request owns multiple composition shares linked to the view ID, then the API returns a 400 error.
      • If the fetchMetadata parameter is effective, the API returns the canonical set of metadata for the composition view. That metadata accounts for the asset metadata provided for all composition shares linked to the viewId, regardless of which content owners own those shares.
  • fetchOwnership
    • If the asset ID specifies a shareId:
      • If the fetchOwnership parameter is mine, the API response contains the ownership data that the content owner authorizing the API request set for the composition share.
      • If the fetchOwnership parameter is effective, the API returns a 400 error.
    • If the asset ID specifies a viewId:
      • If the fetchOwnership parameter is mine, and the content owner authorizing the request owns only one composition share that is linked to the view ID, then the API returns the ownership data that is set for that composition share.
      • If the fetchOwnership parameter is mine, and the content owner authorizing the request owns multiple composition shares linked to the view ID, then the API returns a 400 error.
      • If the fetchOwnership parameter is effective, the API returns the canonical ownership data for the composition view. That data accounts for the ownership data of all composition shares linked to the viewId, regardless of which content owners own those shares.
  • fetchOwnershipConflicts
    • If the asset ID specifies a shareId, the API returns a 400 error response.
    • If the asset ID specifies a viewId, the API returns a list of ownership conflicts associated with the composition view.

assets.insert

This method creates an asset resource, and YouTube assigns an ID to uniquely identify that resource. That ID, which is returned as the value of the id property in the API response, is a shareId.

Note: As a reminder, shareIds and viewIds are only used for composition assets. Other types of assets do not use a two-tiered model for managing asset data.

assets.update and assets.patch

These methods update metadata for an asset. In both requests, the assetId parameter identifies the asset being updated. In addition, in both requests, the request body is an asset resource in which the id property value must match the assetId parameter value.

  • If the assetId parameter and id property specify a shareId, then the API request updates the specified composition share.
  • If the assetId parameter and id property specify a viewId, and the content owner authorizing the request only owns one composition share that is linked to that viewId, then the API request updates that composition share.
  • If the assetId parameter and id property specify a viewId, and the content owner authorizing the request owns multiple composition shares linked to that viewId, then the API request returns a 400 error.

assetMatchPolicy.get

This method returns the match policy defined for a specified asset. The request's assetId parameter identifies the asset.

  • If the assetId parameter specifies a shareId, the API response contains the asset metadata that the content owner authorizing the API request set for the composition share.
  • If the assetId parameter specifies a viewId, the API returns the canonical set of metadata for the composition view. That metadata accounts for the asset metadata provided for all composition shares linked to the viewId, regardless of which content owners own those shares.

assetMatchPolicy.update and assetMatchPolicy.patch

These methods update the match policy for a specified asset. The request's assetId parameter identifies the asset.

  • If the assetId parameter specifies a shareId, the API request updates the match policy for that composition share.
  • If the assetId parameter specifies a viewId, and the content owner authorizing the request only owns one composition share that is linked to that viewId, then the API request updates the match policy for that composition share.
  • If the assetId parameter specifies a viewId, and the content owner authorizing the request owns multiple composition shares linked to that viewId, then the API request returns a 400 error.

assetRelationships.list

This method returns a list of asset relationships for a specified asset. The request's assetId parameter identifies the asset.

  • If the assetId parameter specifies a shareId, the API response contains a list of linked sound recording assets. The list may contain multiple items. In each assetRelationship resource, the sound recording's asset ID is the parentAssetId, and the shareId is the childAssetId.
  • If the assetId parameter specifies a viewId, the API response identifies the sound recording linked to that viewId. The response contains a maximum of one resource.
  • If the assetId parameter identifies a sound recording asset, the API response can contain multiple relationships.
    • If the sound recording's asset ID is the parentAssetId in a returned assetRelationship resource, then the childAssetId identifies the composition view (viewId) linked to that sound recording. Each sound recording has exactly one such relationship.
    • If the sound recording's asset ID is the childAssetId, then the parentAssetId identifies a video that contains the sound recording, such as a music video or art track video. Each sound recording can have multiple such relationships.

assetRelationships.insert

This method creates a relationship between two assets. You would call this method to indicate that you own a share of the composition linked to a sound recording.

In the assetRelationship resource in the request body, set the parentAssetId property to the sound recording's asset ID. Set the childAssetId property to the shareId.

assetSearch.list

This method searches for assets based on asset metadata. The API response contains a list of assetSearch resources, in which each resource's id property identifies an asset ID. The id property value is, in fact, an asset ID.

  • If the assetSearch resource identifies a composition, then the id property value will be a shareId.

assetShares.list

This method returns a mapping of composition views to composition shares. The request's assetId parameter can specify a viewId or a shareId.

  • If the assetId parameter specifies a viewId, then the API response contains a list of assetShare resources. Each resource identifies one composition share that is linked to the specified composition view and that is owned by the content owner authorizing the request.

    The API response can contain multiple assetShare resources. The common use case in which one viewId is mapped to multiple shareIds that are owned by the same content owner is described in the Understanding the composition asset model section of this document.

  • If the assetId parameter specifies a shareId, then the API response contains a list of assetShare resources. Each resource identifies a composition view associated with the specified composition share. The response will contain one resource for each sound recording that the composition share is linked to. (Each sound recording is linked to exactly one composition view.)

claimSearch.list

This method returns a list of claims matching specified search criteria. The method's assetId parameter enables you to search for claims associated with a particular asset.

  • If the API request specifies a shareId, the API returns a 400 response code.

  • If the API request specifies a viewId, the API returns a list of claims associated with the specified composition view, which maps to exactly one sound recording asset.

metadataHistory.list

This method returns a list of all metadata provided for an asset, regardless of which content owner provided the data. The request's assetId parameter identifies the asset for which data is being retrieved.

  • If the API request specifies a shareId, the API returns the most recent set of metadata for that composition share.

  • If the API request specifies a viewId, the API returns a list in which each entry contains the latest set of metadata provided for any composition share linked to that composition view.

ownership.get

This method returns the ownership data defined for a specified asset. The request's assetId parameter identifies the asset.

  • If the assetId parameter specifies a shareId, the API response contains the ownership data that the content owner authorizing the API request set for the composition share.
  • If the assetId parameter specifies a viewId, the API returns the canonical set of ownership data for the composition view. The response synthesizes the ownership data provided for all composition shares linked to the viewId, regardless of which content owners own those shares.

ownership.update and ownership.patch

These methods update the ownership data for a specified asset. The request's assetId parameter identifies the asset.

  • If the assetId parameter specifies a shareId, the API request updates the ownership data for that composition share.
  • If the assetId parameter specifies a viewId, and the content owner authorizing the request only owns one composition share that is linked to that viewId, then the API request updates the ownership data for that composition share.
  • If the assetId parameter specifies a viewId, and the content owner authorizing the request owns multiple composition shares linked to that viewId, then the API request returns a 400 error.

ownershipHistory.list

This method returns a list of all ownership data provided for an asset, regardless of which content owner provided the data. The request's assetId parameter identifies the asset for which data is being retrieved.

  • If the API request specifies a shareId, the API returns the most recent set of ownership data for that composition share.

  • If the API request specifies a viewId, the API returns a list in which each entry contains the latest set of ownership data provided for any composition share linked to that composition view.