Data Specification - Music Mixes

If you have actions that play a mix of music based on a grouping, for example, a genre mix, or a specially curated list of songs, use MusicPlaylist to mark up the collection. Use the creator, genre and numTracks properties to provide more detailed information about the collection. Note that mixes based on an artist, album or track are covered in the specifications for those types. Each of these properties will have a specific meaning for the collection you're marking up:

  • creator - This property will be used to indicate the creator of the mix/playlist. You should provide this property for any playlists specially curated by your team or a high interest user of your service
  • genre - This property will be used to determine whether the playlist is intended to be a genre mix (eg Jazz, Heavy Metal, Rock etc)
  • numTracks - This property will be used to determine whether the playlist is a curated list or an auto-generated mix

Content Markup Properties

Property Expected Type Description
@context Text Required - Always set to http://schema.googleapis.com.
@type Text Required - Always set to MusicPlaylist for mixes.
@id URL Required - A globally unique ID for the playlist in URI format. The ID should be stable and not change over time. It will be treated as an opaque string and does not have to be a working link. The domain used for the @id value must be owned by your organization.
url URL Required - The canonical URL for the playlist on your site, must be globally unique. This link is used to help accurately reconcile the content in your feed with the content in Google's databases. For playback, the target.urlTemplate detailed in the Action Markup Properties section of the documentation will be used.
name Text Required - The name of the playlist, for example "Funky Jazz Mix". Use an array to mark up the name in multiple languages. An example is available in the "Multiple Language Representation" section of the Listen Action Examples page.
genre Text Required if playlist is a genre mix - A list of keywords specific to the genre that the playlist represents. The presence of this property will signal that you intend this playlist to be a genre playlist.
numTracks Integer Required if playlist is a curated mix - The number of tracks in the playlist. The presence of this property will signal that this playlist is hand curated. The absence of this property will signal that the playlist is an endless auto-generated playlist.
potentialAction ListenAction Required - Listen action(s) for the playlist. See ListenAction Properties for details.

Note: If you have deeplinks into your media content available in multiple regions, use an array to mark up the potentialAction for each region. An example is available in the "Multiple Language Representation" section of the Listen Action Examples page.
image ImageObject Recommended - A playlist image which represents the playlist or music mix.
creator Organization or Person Recommended if creator is of high interest - Use this property to indicate playlists created by your service (typed as Organization with name property indicating your service) or a high interest user of your service (typed as Person with name property indicating the user of interest)
keywords Text Recommended - A list of keywords ("rock", "pop"), moods ("happy", "morose"), activities ("exercise", "chillin' like Magellan"), or other terms related to the playlist.
description Text Recommended - A brief description of the playlist. Please limit to 300 characters. Use an array to mark up the description in multiple languages. An example is available in the "Multiple Language Representation" section of the Listen Action Examples page.
isFamilyFriendly Boolean Recommended - Indicates whether this content is family friendly (content that is considered to be suitable for all members of a family with children). Google products may use isFamilyFriendly when determining a song to play.

Quick Checks

  • For the entity level url property, please ensure that you are providing the canonical URL. The URL you provide should be unique for each entity, for example do not use the same URL for a MusicRecording as you would for a MusicAlbum.
  • @id is intended to be a unique ID for an entity across your entire catalog and should comply with the following guidelines:
    • Does not ever change
    • Unique per content type and across content types. For example, you may not use the same @id for a MusicRecording and a MusicAlbum
    • The same @id should be used throughout your structured data wherever the entity is referenced, for example the partOfSeries.@id for a TVEpisode should match the @id used for the main TVSeries definition
    • Must be in the form of a URI (does not need to be a working URL).
    • The domain used for the @id value must be owned by your organization.

In general we recommend that you use the same value for url and @id as long as the URL for the entity is unique across your catalog.

Action Markup Properties

Your Action markup specifies:

  • The deeplink(s) to use for a given piece of content on each of your platforms (e.g. iOS, Cast)
  • The availability information (e.g. geo-restrictions, availability windows) for a given piece of content on your service

For music content, Action markup takes the form of a ListenAction. These are nested/marked up in the potentialAction block of the Content markup.


You must supply a deeplink for every platform where you are able to serve content.
Property Expected type Description
potentialAction.@type Text Required - Always set to `ListenAction` for a listen actions.
target EntryPoint Required - A container for the action target.
target.@type Text Required - Always set to `EntryPoint` for the target container.
target.urlTemplate URL Required - This is the link that will be used to initiate playback of your content on your app. For voice-activated speaker integrations, for example, this link will be passed to the receiver app on the voice-activated speaker. See Deeplink Requirements for detailed requirements.
target.actionPlatform Text Required - The platform(s) on which the link works. One or more of the following:
  • http://schema.org/DesktopWebPlatform: Works on desktop web browsers.
  • http://schema.org/MobileWebPlatform: Works on mobile web browsers.
  • http://schema.org/AndroidPlatform: Works on Android native app.
  • http://schema.org/IOSPlatform: Works on iOS native app.
  • http://schema.googleapis.com/GoogleVideoCast: Works on a Chromecast device.
  • http://schema.googleapis.com/GoogleAudioCast: Works on a Chromecast Audio only device.
Note: If a link you're providing also works on your AndroidTV app, also include http://schema.org/AndroidTVPlatform in the list of platforms for that link. Do not use this type to provide a distinct link for AndroidTV that's different from your Android mobile or universal link.
expectsAcceptanceOf Offer Required - A container for the action conditions.
expectsAcceptanceOf.@type Text Required - Always set to `Offer` for the target container.
expectsAcceptanceOf.category Text Required - One of the following values:
  • nologinrequired: The action is available to the user with no purchase or login to access content.
  • free: The action is available with no purchase or paid subscription required of the user. The action does require a user to login.
  • subscription: The action is included with a paid subscription to your service.
expectsAcceptanceOf.availabilityStarts Date Optional - Date after which the action is available, in ISO 8601 format (including timezone). Can be a date in the future. Use this property to limit action availability by date/time. If not included, we will assume that action has no time limitation.
expectsAcceptanceOf.availabilityEnds Date Optional - Date after which the action is no longer available, in ISO 8601 format (including timezone). Use this property to limit action availability by date/time. If not included, we will assume that action has no time limitation.
expectsAcceptanceOf.eligibleRegion Country Required - Countries in which the action is available.
expectsAcceptanceOf.eligibleRegion.@type Text Required - Always set to `Country` for the eligibleRegion block.
expectsAcceptanceOf.eligibleRegion.name Text Required - The ISO 3166 country code.
  • Please adhere to the following restrictions for deeplink styles by platform:
    • For iOS and Chromecast, universal links are required.
    • For Android, universal links are recommended. If you do not yet support the universal link format on Android, the old style android-app://{package_id}/{scheme}/{path}/... URL format can be used.
  • We highly recommend that you implement universal links across all your platforms. For instructions on implementing Universal Links, see: iOS Documentation | Android Documentation.
  • Deeplinks do not need to be canonical
  • Deeplinks may include parameters/tags (e.g. for tracking purposes).

General Action Markup Guidelines

  • You may have an array of targets when you have different deeplinks for different platforms, and you may also have an array of offers when there are multiple ways to access the content. However, if your intent is to have different offers across different platforms, you should break those up into different ListenAction blocks.
  • Consolidate to as few ListenAction blocks as possible. For example, if all properties are the same across platforms (other than the deeplink), you should use a single action block.
  • To allow for freshness and processing time, we highly recommend that you provide ListenActions in advance of your content being available to users by using availabilityStarts to indicate when we can start serving.

If you encounter a scenario not discussed here, please reach out to your Google contact for assistance.

Image Markup Properties

Property Expected type Description
image.@type ImageObject Required - Always set to `ImageObject`.
contentUrl URL Required - The URL to the image.
dateModified Date Optional - The date on which the image was most recently modified/changed, in ISO 8601 format (including timezone).
regionsAllowed Place Recommended - The countries where the media is allowed. Specify countries in ISO 3166 format.
  • If not specified, then it's assumed the image is allowed to displayed in all locales.
  • To submit different images per region, add multiple ImageObjects, each with it's own set of countries and a corresponding image url.

Image Requirements

  • Image URLs must be crawlable and indexable.
  • Images must represent the playlist or music mix.
  • Images must be in .jpg, .png, or. gif format.
  • Images must not contain the following:
    • Any image that's blurry, pixelated, rotated, or poor quality
    • Unlicensed/stock photography
    • Nudity
    • Illegal content
  • You must have rights to use the image and rights to allow the image to be shown on Google devices and properties.
  • For best results, provide a high-resolution image (recommended 600x600 pixels or higher, minimum of 300x300 pixels) with a 1x1 aspect ratio.
  • Image should be updated as frequently as needed to reflect the playlist appropriately.

Example

The following example shows a curated genre playlist for top pop songs from the 2010s. The genre property indicates that this playlist should be considered a genre playlist for the terms Pop and 2010s, the presence of numTracks indicates that the playlist is hand curated, and the creator property indicates that the playlist is curated by the music service. For more music actions examples, see here.

<script type="application/ld+json">
{
  "@context":"http://schema.googleapis.com/",
  "@type":"MusicPlaylist",
  "@id":"http://www.example.com/playlist/top-pop-songs/",
  "url":"http://www.example.com/playlist/top-pop-songs/",
  "name":"Top Pop Songs of the 2010s",
  "image":[
  {
    "@type": "ImageObject",
    "contentUrl" : "http://www.example.com/playlist/top-pop-songs/1x1/photo1.jpg",
    "dateModified" : "2018-01-05T22:11:33+00:00",
    "regionsAllowed" : ["US","UK","MX"]
  },
  {
    "@type": "ImageObject",
    "contentUrl" : "http://www.example.com/playlist/top-pop-songs/1x1/photo2.jpg",
    "dateModified" : "2018-01-05T22:11:33+00:00",
    "regionsAllowed" : ["UA", "IR"]
  }],
  "genre": [
     "pop",
     "2010s"
  ],
  "numTracks":"46",
  "potentialAction":{
    "@type":"ListenAction",
    "target":[
      {
        "@type":"EntryPoint",
        "urlTemplate":"http://www.example.com/playlist/top-pop-songs?autoplay=true",
        "actionPlatform":[
          "http://schema.org/DesktopWebPlatform",
          "http://schema.org/IOSPlatform",
          "http://schema.org/AndroidPlatform",
          "http://schema.googleapis.com/GoogleAudioCast",
          "http://schema.googleapis.com/GoogleVideoCast"
        ]
      },
      {
        "@type": "EntryPoint",
        "urlTemplate": "android-app://com.app.example/playlist/top-pop-songs?autoplay=true",
        "actionPlatform": "http://schema.org/AndroidPlatform"
      }
    ],
    "expectsAcceptanceOf":{
      "@type":"Offer",
      "category":"free",
      "eligibleRegion": {
        "@type":"Country",
        "name":"US"
      }
    }
  },
  "creator": {
    "@type": "Organization",
    "name": "example.com"
  },
  "keywords": [
    "pop",
    "Party music"
  ],
  "description":"Top pop songs from the last decade"
}
</script>