Data Specification - Artists, Albums and Songs

Actions should be provided for all the artist, album and song content in your catalog.

For artists, albums and songs, Google supports two types of actions:

  • Entity Action - An Action that plays a specific artist, album, or song
  • Entity-seeded Action - An Action that plays content similar to an artist, album, or song. Entity-seeded Actions may include playback of the seed entity, but this is not required.

For more information about expected behavior for Entity and Entity-seeded Artist, Album, and Song Actions, please see: Listen Actions - Action Behavior.

The Content markup is different for Entity Actions and Entity-seeded Actions. These differences are detailed within the specification for Content markup for Artist, Album, and Song Actions below. If you support both Entity and Entity-seeded Actions, you should provide the required attributes for each within the same MusicGroup, MusicAlbum and MusicRecording block.

Content Markup Properties

In the context of Content markup, artist, albums, and songs are referred to as MusicGroup, MusicAlbum, and MusicRecording respectively.

MusicGroup

Property Expected Type Description
@context Text Required - Always set to http://schema.googleapis.com.
@type Text Required - Always set to MusicGroup for artists and groups.
@id URL Required - A globally unique ID for the artist/group 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 artist/group 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 artist/group.
potentialAction ListenAction Required for Entity Actions - Listen action(s) for the artist/group content. See ListenAction Properties for details.
subjectOf MusicPlaylist Required for Entity-seeded Actions - Details for the entity seeded action.
subjectOf.@type Text Required for Entity-seeded Actions - Always set to MusicPlaylist for this property.
subjectOf.@id URL Required for Entity-seeded Actions - A globally unique ID for the artist/group 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. It must be distinct from the @id for the artist/group.
subjectOf.url URL Required for Entity-seeded Actions - The canonical URL for the artist/group on your site, must be globally unique. You can leave this out if its the same as the url for the artist/group.
subjectOf.potentialAction ListenAction Required for Entity-seeded Actions - Listen action(s) for the artist/group similar content. See ListenAction Properties for details.
image ImageObject Recommended - Image which represents the MusicGroup. See Image Markup Properties.
sameAs URL Recommended - URL to a reference web page that unambiguously identifies the artist/group, eg Wikipedia page for the artist. This should be distinct from the url property above.
description Text Recommended - A brief biography of the artist. Please limit to 300 words.

MusicAlbum

Property Expected Type Description
@context Text Required - Always set to http://schema.googleapis.com.
@type Text Required - Always set to MusicAlbum for albums.
@id URL Required - A globally unique ID for the album 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 album 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 album.
byArtist MusicGroup Required - The artist or group that recorded this album. At a minimum, you must specify the unique @id you use for that artist and the name of the artist. If the album has multiple associated artists, you may provide an array of values in byArtist.
byArtist.@type Text Required - Always set to MusicGroup for this property.
byArtist.@id URL Required - A globally unique ID for the artist/group 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. It must match the @id you use for the artist/group elsewhere in your feed.
byArtist.name Text Required - The name of the artist/group.
potentialAction ListenAction Required for Entity Actions - Listen action(s) for the album content. See ListenAction Properties for details.
subjectOf MusicPlaylist Required for Entity-seeded Actions - Details for the album similar content playlist.
subjectOf.@type Text Required for Entity-seeded Actions - Always set to MusicPlaylist for this property.
subjectOf.@id URL Required for Entity-seeded Actions - A globally unique ID for the album 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. It must be distinct from the @id for the album.
subjectOf.url URL Required for Entity-seeded Actions - The canonical URL for the album on your site, must be globally unique. You can leave this out if its the same as the url for the album.
subjectOf.potentialAction ListenAction Required for Entity-seeded Actions - Listen action(s) for the album similar content. See ListenAction Properties for details.
image ImageObject Recommended - Image which represents the MusicAlbum. See Image Markup Properties.
sameAs URL Recommended - URL to a reference web page that unambiguously identifies the album, eg Wikipedia page for the album. This should be distinct from the url property above.
numTracks Integer Recommended - The number of songs or tracks on this album.
timeRequired Duration Recommended - The length of the album, in ISO 8601 duration format.
description Text Recommended - A brief description of the album. Please limit to 300 words.

MusicRecording

Property Expected Type Description
@context Text Required - Always set to http://schema.googleapis.com.
@type Text Required - Always set to MusicRecording for songs/tracks.
@id URL Required - A globally unique ID for the song 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 song 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 song.
byArtist MusicGroup Required - The artist or group that recorded this song. At a minimum, you must specify the unique @id you use for that artist and the name of the artist. If the song has multiple associated artists, you may provide an array of values in byArtist.
byArtist.@type Text Required - Always set to MusicGroup for this property.
byArtist.@id URL Required - A globally unique ID for the artist/group 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. It must match the @id you use for the artist/group elsewhere in your feed.
byArtist.name Text Required - The name of the artist/group.
potentialAction ListenAction Required for Entity Actions - Listen action(s) for the song. See ListenAction Properties for details.
subjectOf MusicPlaylist Required for Entity-seeded Actions - Details for the song similar content playlist.
subjectOf.@type Text Required for Entity-seeded Actions - Always set to MusicPlaylist for this property.
subjectOf.@id URL Required for Entity-seeded Actions - A globally unique ID for the song 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. It must be distinct from the @id for the song.
subjectOf.url URL Required for Entity-seeded Actions - The canonical URL for the song on your site, must be globally unique. You can leave this out if its the same as the url for the song.
subjectOf.potentialAction ListenAction Required for Entity-seeded Actions - Listen action(s) for the song similar content. See ListenAction Properties for details.
image ImageObject Recommended - Image which represents the MusicRecording. See Image Markup Properties.
sameAs URL Recommended - URL to a reference web page that unambiguously identifies the song, eg Wikipedia page for the song. This should be distinct from the url property above.
inAlbum MusicAlbum Recommended - The album on which the track appears (if any).
inAlbum.@type Text Required - Always set to MusicAlbum for this property.
inAlbum.@id URL Recommended - A globally unique ID for the album 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. It must match the @id you use for the album elsewhere in your feed.
inAlbum.name Text Recommended - The name of the artist/group.
duration Duration Recommended - The length of the song, in ISO 8601 duration format.
description Text Recommended - A brief description of the song Please limit to 300 words.

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.

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.
You must supply a deeplink for every platform where you are able to serve content.
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.
  • Image is not guaranteed to be used/displayed.

Examples

Click to expand for an example of each type. A more extensive set of examples is available here.

MusicGroup

<script type="application/ld+json">
{
  "@context":"http://schema.googleapis.com/",
  "@type":"MusicGroup",
  "@id":"http://www.example.com/artist/Katy-Perry/",
  "url":"http://www.example.com/artist/Katy-Perry/",
  "name":"Katy Perry",
  "sameAs":"http://www.katyperry.com",
  "description":"Katy Perry is a pop music artist.",
  "image":[
  {
    "@type": "ImageObject",
    "contentUrl" : "http://www.example.com/artist/katy-perry/1x1/photo1.jpg",
    "dateModified" : "2018-01-05T22:11:33+00:00",
    "regionsAllowed" : ["US","UK","MX"]
  },
  {
    "@type": "ImageObject",
    "contentUrl" : "http://www.example.com/artist/katy-perry/1x1/photo2.jpg",
    "dateModified" : "2018-01-05T22:11:33+00:00",
    "regionsAllowed" : ["UA", "IR"]
  }],
  "potentialAction": {
    "@type":"ListenAction",
    "target": {
      "@type":"EntryPoint",
      "urlTemplate":"http://www.example.com/artist/Katy-Perry?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"
      ]
    },
    "expectsAcceptanceOf":{
      "@type":"Offer",
      "category":"subscription",
      "eligibleRegion": {
        "@type":"Country",
        "name":"US"
      }
    }
  },
  "subjectOf": {
    "@type":"MusicPlaylist",
    "@id":"http://www.example.com/artist_mix/Katy-Perry/",
    "url":"http://www.example.com/artist_mix/Katy-Perry/",
    "name":"Katy Perry Mix",
    "description":"A mix of music similar to Katy Perry",
    "potentialAction":{
      "@type":"ListenAction",
      "target": {
        "@type":"EntryPoint",
        "urlTemplate":"http://www.example.com/artist_mix/Katy-Perry?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"
        ]
      },
      "expectsAcceptanceOf":{
        "@type":"Offer",
        "category":"free",
        "eligibleRegion": {
          "@type":"Country",
          "name":"US"
        }
      }
    }
  }
}
</script>

MusicAlbum

<script type="application/ld+json">
{
  "@context":"http://schema.googleapis.com/",
  "@type":"MusicAlbum",
  "@id":"http://www.example.com/album/teenage-dream",
  "url":"http://www.example.com/album/teenage-dream",
  "name":"Teenage Dream",
  "sameAs":"https://en.wikipedia.org/wiki/Teenage_Dream_(Katy_Perry_album)",
  "description":"Katy Perry's 2010 album featuring \"California Gurls\", \"Teenage Dream\" and \"Firework\"",
  "datePublished":"2010-08-24",
  "numTracks":"12",
  "timeRequired":"P44M02S",
  "byArtist":{
    "@type":"MusicGroup",
    "@id": "http://www.example.com/artist/Katy-Perry/",
    "name":"Katy Perry"
  },
  "image":[
  {
    "@type": "ImageObject",
    "contentUrl" : "http://www.example.com/album/teenage-dream/1x1/photo1.jpg",
    "dateModified" : "2018-01-05T22:11:33+00:00",
    "regionsAllowed" : ["US","UK","MX"]
  },
  {
    "@type": "ImageObject",
    "contentUrl" : "http://www.example.com/album/teenage-dream/1x1/photo2.jpg",
    "dateModified" : "2018-01-05T22:11:33+00:00",
    "regionsAllowed" : ["UA", "IR"]
  }],
  "potentialAction": {
    "@type":"ListenAction",
    "target": {
      "@type":"EntryPoint",
      "urlTemplate":"http://www.example.com/album/teenage-dream?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"
      ]
    },
    "expectsAcceptanceOf":{
      "@type":"Offer",
      "category":"subscription",
      "eligibleRegion": {
        "@type":"Country",
        "name":"US"
      }
    }
  },
  "subjectOf": {
    "@type":"MusicPlaylist",
    "@id":"http://www.example.com/album_mix/teenage-dream",
    "url":"http://www.example.com/album_mix/teenage-dream",
    "name":"Teenage Dream Mix",
    "description":"A mix of music similar to Teenage Dream",
    "potentialAction":{
      "@type":"ListenAction",
      "target": {
        "@type":"EntryPoint",
        "urlTemplate":"http://www.example.com/album_mix/teenage-dream?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"
        ]
      },
      "expectsAcceptanceOf":{
        "@type":"Offer",
        "category":"free",
        "eligibleRegion": {
          "@type":"Country",
          "name":"US"
        }
      }
    }
  }
}
</script>

MusicRecording

<script type="application/ld+json">
{
  "@context":"http://schema.googleapis.com/",
  "@type":"MusicRecording",
  "@id":"http://www.example.com/track/firework",
  "url":"http://www.example.com/track/firework",
  "name":"Firework",
  "sameAs":"https://en.wikipedia.org/wiki/Firework_(song)",
  "description":"Katy Perry's hit song from Teenage Dream",
  "datePublished":"2010-08-24",
  "duration":"PT3M54S",
  "byArtist":{
    "@type":"MusicGroup",
    "@id": "http://www.example.com/artist/Katy-Perry/",
    "name":"Katy Perry"
  },
  "inAlbum":{
    "@type":"MusicAlbum",
    "@id":"http://www.example.com/album/<albumID(Teenage Dream)>",
    "name":"Teenage Dream"
  },
  "image":[
  {
    "@type": "ImageObject",
    "contentUrl" : "http://www.example.com/track/firework/1x1/photo1.jpg",
    "dateModified" : "2018-01-05T22:11:33+00:00",
    "regionsAllowed" : ["US","UK","MX"]
  },
  {
    "@type": "ImageObject",
    "contentUrl" : "http://www.example.com/track/firework/1x1/photo2.jpg",
    "dateModified" : "2018-01-05T22:11:33+00:00",
    "regionsAllowed" : ["UA", "IR"]
  }],
  "potentialAction": {
    "@type":"ListenAction",
    "target": {
      "@type":"EntryPoint",
      "urlTemplate":"http://www.example.com/track/firework?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"
      ]
    },
    "expectsAcceptanceOf": {
      "@type":"Offer",
      "category":"subscription",
      "eligibleRegion": {
        "@type":"Country",
        "name":"US"
      }
    }
  },
  "subjectOf": {
    "@type":"MusicPlaylist",
    "@id":"http://www.example.com/track_mix/firework",
    "url":"http://www.example.com/track_mix/firework",
    "name":"Firework Mix",
    "description":"A mix of music similar to Firework",
    "potentialAction":{
      "@type":"ListenAction",
      "target": {
        "@type":"EntryPoint",
        "urlTemplate":"http://www.example.com/track_mix/firework?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"
        ]
      },
      "expectsAcceptanceOf":{
        "@type":"Offer",
        "category":"free",
        "eligibleRegion": {
          "@type":"Country",
          "name":"US"
        }
      }
    }
  }
}
</script>