Identify the relationship between entity types

Some entity types require you to provide the relationship between the content in your feed. This information helps Google display the proper order and structure of your content to users and identify the correct content when a user's query is ambiguous.

Select the type of content that you provide:

TV show

If you're a TV show provider, you need to provide the relationships for all the TVEpisode, TVSeason, and TVSeries entity types in your catalog. This information helps Google display the proper order and structure of your content to users and identify the correct TV shows when a user query is ambiguous.

TVSeries, TVSeason, and TVEpisode relations

Watch Actions' TVSeries, TVSeason, and TVEpisode entity types describe the following:

TVEpisode - A single episode of a TV series.
- For example, Episode 3 of My Favorite TV Show (season 7).
TVSeries - A television program that contains a series of episodes.
- For example, My Favorite TV Show.
TVSeason - A single season of a TV series; a season contains a group of episodes are broadcast in the same run.
- For example, My Favorite TV Show (season 7).
- Providing TVSeason as a full entity is optional.
  - However, if you choose to provide TVSeason entities for a TV series, those TVSeason entities must cover all the episodes of the TV series in your catalog. For instance, My Favorite TV Show has 8 seasons and each season has 5 episodes. Your feed contains all 40 episodes of My Favorite TV Show. If you provide TVSeason entities for the show, then your feed must include all 8 TVSeason entities.

**Figure 1**. The `partOfSeries` and `partOfSeason` properties connect the TV show entity types together.

These entity types have the following relations:

A TVEpisode entity requires you to provide the partOfSeries property, which specifies the @id and name of the episode's TVSeries entity.

"partOfSeries": {
  "@type": "TVSeries",
  "@id": "http://www.example.com/my_favorite_tv_show",
  "name": "My Favorite TV Show",
},

If your feed contains TV seasons, a TVSeason entity also requires you to specify its TVSeries entity in the partOfSeries property.
A TVEpisode entity requires you to provide the partOfSeason property, which specifies the @id and seasonNumber of the episode's TVSeason entity.
```
"partOfSeason": {
  "@type": "TVSeason",
  "@id": "http://www.example.com/my_favorite_tv_show/s7",
  "seasonNumber": 7
},
```
If a TVEpisode entity doesn't have a corresponding TVSeason entity in the feed, take the following steps to provide the partOfSeason.@id and partOfSeason.seasonNumber properties for the TVEpisode entity:
- Take its partofSeries.@id and attach a placeholder query field (for example, ?season1) to create a unique partOfSeason.@id (for example, http://www.example.com/my_favorite_tv_show?season1).
- Set partOfSeason.seasonNumber to 1.
Later, if you decide to provide TV seasons in the feed, you can either reuse the existing partOfSeason.@id for the corresponding TVSeason entity or replace this placeholder partOfSeason.@id with the actual @id of the TVSeason entity.

TVSeries, TVSeason, and TVEpisode examples

TVSeries

My Favorite TV Show

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "TVSeries",
  "@id": "http://www.example.com/my_favorite_tv_show",
  "url": "http://www.example.com/my_favorite_tv_show",
  "name": "My Favorite TV Show",
  "potentialAction":{ … },
  ...
}

TVSeason

My Favorite TV Show (season 7)

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "TVSeason",
  "@id": "http://www.example.com/my_favorite_tv_show/s7",
  "url": "http://www.example.com/my_favorite_tv_show/s7",
  "name": "My Favorite TV Show, Season 7",
  "seasonNumber": 7,
  "partOfSeries": {
    "@type": "TVSeries",
    "@id": "http://www.example.com/my_favorite_tv_show",
    "name": "My Favorite TV Show",
  },
  "potentialAction":{ … },
  ...
}

TVEpisode

Episode 3 of My Favorite TV Show (season 7)

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "TVEpisode",
  "@id": "http://www.example.com/my_favorite_tv_show/s7/e3",
  "url": "http://www.example.com/my_favorite_tv_show/s7/e3",
  "name": "John Doe returns at night",
  "episodeNumber": 3,
  "partOfSeason": {
    "@type": "TVSeason",
    "@id": "http://www.example.com/my_favorite_tv_show/s7",
    "seasonNumber": 7
  },
  "partOfSeries": {
    "@type": "TVSeries",
    "@id": "http://www.example.com/my_favorite_tv_show",
    "name": "My Favorite TV Show",
  },
  "potentialAction":{ … },
  ...
}

Identify the relationships

Do the following:

For each TVEpisode,
- Collect @id and name of its TVSeries.
- If the TVEpisode has a corresponding TVSeason, collect @id and seasonNumber of its TVSeason.
For each TVSeason,
- Collect @id and name of its TVSeries.

Radio

If you're a radio provider, identify the details of the radio station. For RadioBroadcastService, collect the following information:

description: The description of the radio station.
broadcastDisplayName: The display name of the radio station.
areaServed: The area where the radio station is available.
callSign: The official government-issued callsign of the radio station.
- For North America radio stations, this property is required.
broadcastFrequency: The frequency specification of the radio station.
- For terrestrial AM/FM radio stations, this property is required.
- For online streaming-only content, the value is set to INTERNET_STREAM.
broadcastAffiliateOf: The network of which this radio station provides programming.
- If the radio station is not part of any affiliation, this property is not required.
broadcaster: The organization who owns and operates the radio station.
- See the Organization section for details.
parentService: The parent radio station.
- If the radio station is a repeater or translator of another radio station, this property is required.

Example of RadioBroadcastService:

{
  "@context": "http://schema.googleapis.com",
  "@type": "RadioBroadcastService",
  "@id": "https://www.example.com/stations?id=1",
  "url": "https://www.example.com/stations?id=1",
  "name": "KABC",
  "callSign": "KABC-FM",
  "broadcastDisplayName": "KABC",
  "description": "Local News & Information",
  "broadcastFrequency": {
    "@type": "BroadcastFrequencySpecification",
    "broadcastFrequencyValue": "89.5",
    "broadcastSignalModulation": "FM",
    "broadcastSubChannel": "HD1"
  },
  "areaServed": {
    "@type": "City",
    "name": "San Francisco, CA"
  },
  "broadcastAffiliateOf": [
    {
      "@id": "https://www.example.com/networks/xyz",
      "@type": "Organization",
      "name": "XYZ",
      "sameAs": "https://en.wikipedia.org/wiki/XYZ"
    },
    {
      "@id": "https://www.example.com/networks/efg",
      "@type": "Organization",
      "name": "EFG",
      "sameAs": "https://www.example.com/"
    }
  ],
  "broadcaster": [
    {
      "@type": "Organization",
      "name": "California Local Public Broadcasting",
      "sameAs": "https://www.example.org/w/clpb/"
    },
    {
      "@type": "Organization",
      "sameAs": "https://www.example.org/kabc",
      "name": "KABC Inc"
    }
  ],
  "potentialAction": { … },
  …
}

Music

If you're a music provider, you need to provide the relationships for all the MusicGroup, MusicAlbum, and MusicRecording entity types in your catalog. This information helps Google display the proper order and structure of your content to users and identify the correct songs, albums, and artists when a user query is ambiguous.

Additionally, Listen Actions' main entity types (MusicGroup, MusicAlbum, and MusicRecording) let your app or platform play more content from a playlist (MusicPlaylist) once all the content from the seed entity is played. Check out the following scenario:

A MusicAlbum entity contains a list of songs from Album XYZ (a seed entity).
A MusicPlaylist entity contains a playlist of songs that are similar to the songs from Album XYZ.
The MusicAlbum entity includes the MusicPlaylist entity as an Entity-seeded Action.

In this setup, once all the songs from Album XYZ are played, your app can continue to play songs from the playlist provided by the MusicPlaylist entity.

Entity Action and Entity-seeded Action

Listen Actions support two types of Actions:

Entity Action: Plays a specific artist, album, or song (a seed entity).
- It includes MusicGroup, MusicAlbum, MusicRecording.
Entity-seeded Action: Plays content similar to the seed entity.
- It includes MusicPlaylist.
- After completing an Entity Action, your app or platform may initiate an Entity-seeded Action.
- An Entity-seeded Action can include playback of the content from the seed entity.

We recommend you include an Entity-seeded Action in every Entity Action.

MusicGroup, MusicAlbum, MusicRecording, and MusicPlaylist relations

Listen Actions' MusicGroup, MusicAlbum, MusicRecording, and MusicPlaylist have the following relations:

MusicAlbum and MusicRecording need to identify which MusicGroup they belong to.
MusicGroup, MusicAlbum, and MusicRecording can have MusicPlaylist as an Entity-seeded Action.
- MusicPlaylist cannot have an Entity-seeded Action.

MusicGroup, MusicAlbum, MusicRecording, and MusicPlaylist examples

MusicGroup

Artist: My Favorite Artist

{
  "@context":"http://schema.googleapis.com/",
  "@type":"MusicGroup",
  "@id":"http://www.example.com/artist/my_favorite_artist/",
  "url":"http://www.example.com/artist/my_favorite_artist/",
  "name":"My Favorite Artist",
  "potentialAction":{ … },
  "subjectOf": {
    "@type":"MusicPlaylist",
    "@id":"http://www.example.com/artist_mix/my_favorite_artist/",
    "url":"http://www.example.com/artist_mix/my_favorite_artist/",
    "name":"My Favorite Artist Mix",
    "potentialAction":{ … },
  },
  ...
}

MusicAlbum

Album: My Favorite Album
Artist: My Favorite Artist

{
  "@context":"http://schema.googleapis.com/",
  "@type":"MusicAlbum",
  "@id":"http://www.example.com/album/my_favorite_album",
  "url":"http://www.example.com/album/my_favorite_album",
  "name":"My Favorite Album",
  "byArtist":{
    "@type":"MusicGroup",
    "@id": "http://www.example.com/artist/my_favorite_artist/",
    "name":"My Favorite Artist"
  },
  "potentialAction":{ … },
  "subjectOf": {
    "@type":"MusicPlaylist",
    "@id":"http://www.example.com/album_mix/my_favorite_album",
    "url":"http://www.example.com/album_mix/my_favorite_album",
    "name":"My Favorite Album Mix",
    "potentialAction":{ … },
  },
  ...
}

MusicRecording

Song: My Favorite Song
Artist: My Favorite Artist

{
  "@context":"http://schema.googleapis.com/",
  "@type":"MusicRecording",
  "@id":"http://www.example.com/track/my_favorite_song",
  "url":"http://www.example.com/track/my_favorite_song",
  "name":"My Favorite Song",
  "byArtist":{
    "@type":"MusicGroup",
    "@id": "http://www.example.com/artist/my_favorite_artist/",
    "name":"My Favorite Artist"
  },
  "potentialAction":{ … },
  "subjectOf": {
    "@type":"MusicPlaylist",
    "@id":"http://www.example.com/track_mix/my_favorite_song",
    "url":"http://www.example.com/track_mix/my_favorite_song",
    "name":"My Favorite Song Mix",
    "potentialAction":{ … },
  },
  ...
}

MusicPlaylist

A custom playlist: "Top Pop Songs of the 2010s"

{
  "@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",
  "genre": [
     "pop",
     "2010s"
  ],
  "numTracks":"46",
  "potentialAction":{ … },
  ...
}

Identify the relationships

Do the following:

For MusicGroup,
- If you provide an Entity-seeded Action, identify @id and name of its MusicPlaylist.
For MusicAlbum and MusicRecording,
- Identify @id and name of its MusicGroup.
- If you provide an Entity-seeded Action, identify @id and name of its MusicPlaylist.
For MusicPlaylist,
- If applicable, identify genre that best represents the content in the playlist.
- If the playlist is hand curated, identify numTracks.
  - The absence of numTracks tells Google that the playlist is an auto-generated, endless playlist.

Live TV

If you're a live TV provider, you need to provide the relationships for all the Organization, BroadcastService, CableOrSatelliteService, and TelevisionChannel entity types in your catalog. This information helps Google display the proper order and structure of your content to users and identify the correct live TV channels when a user query is ambiguous.

Live TV entity types

BroadcastService, CableOrSatelliteService, TelevisionChannel, and Organization describe the following entities:

BroadcastService describes a broadcast service that is affiliated with a TV network (Organization).
Organization describes both a TV network and a TV operator. The feed must include Organization entities that represent each of them.

TV network - An organization that produces and distributes TV programming. There will typically be a 1-1 relationship between the Organization and BroadcastService, except in the following cases:
- Network has local channels. In this case, there should be a one (Organization) to Many (BroadcastService) relationship between the Organization and BroadcastService.
- Network has time-shifted streaming (e.g., "AMC" and "AMC Pacific" have the same programming but they are time shifted). In this case, there should be two BroadcastServices (AMC and AMC Pacific) connecting to one Organization / Network.
- Network has streaming of different video quality (e.g., "SD" and "HD"). In this case, each video quality stream should each be represented as a BroadcastService connecting to one Organization / Network entity. Note that sometimes a network with name "HD" carries different sets of programming (e.g., "MTV Live HD" versus "MTV Live"), this should be represented as separate Network (Organization) entities.
TV operator - Also known as TV service provider, an organization that delivers a bundle of TV programming to subscribers.

CableOrSatelliteService identifies a regional cable, satellite, or Internet TV service provided by a TV operator (Organization).
TelevisionChannel identifies the channel ID (that is, a string or number) of a TV station (BroadcastService) on a regional cable, satellite, or Internet TV service (CableOrSatelliteService).

**Figure 1**. The links between the Live TV channel entity types.

BroadcastService

BroadcastService allows you to describe the details that are specific to Media Actions; for instance, you can use an Action markup object in BroadcastService to provide the deep links and access requirements of a broadcast service.

You need to provide a separate BroadcastService for the following cases:

A broadcast service has its own TV channel.
- For instance, a TV network has channels in different definitions (for example, "HD" and "SD").
A broadcast service consists of different TV programming.
- For instance, a TV network distributes different TV programming based on regions (for example, New York and California).

BroadcastService lets you restrict access to a TV channel based on the user's current device location with the eligibleRegion and ineligibleRegion properties. (See the Entitlements use cases - Live TV section for details.)

Live TV examples

The following example describes a fictional Internet Protocol TV (IPTV) service provider and its TV channels:

Organization

A fictional Internet Protocol Television service provider, ExampleTV Digital Service (Organization), provides Live TV service on the Internet, which contains the following two channels: ExampleTV-Movie (Organization) and ExampleTV-Comedy (Organization):

{
  "@context":"http://schema.org",
  "@type":"Organization",
  "@id":"http://example.com/exampletv/digital",
  "name":"ExampleTV Digital Service",
  "sameAs": "https://en.wikipedia.org/wiki/exampletv_digital_service"
},
{
  "@context":"http://schema.org",
  "@type":"Organization",
  "@id":"http://example.com/exampletv/movie",
  "name":"ExampleTV Movie",
  "sameAs": "https://en.wikipedia.org/wiki/exampletv_movie"
},
{
  "@context":"http://schema.org",
  "@type":"Organization",
  "@id":"http://example.com/exampletv/comedy",
  "name":"ExampleTV Comedy",
  "sameAs": "https://en.wikipedia.org/wiki/exampletv_comedy"
}

BroadcastService

These two BroadcastService entities provide the details of deep links and access requirement for the fictional channels ExampleTV-Movie and ExampleTV-Comedy:

{
  "@context":"http://schema.org",
  "@type":"BroadcastService",
  "@id":"https://www.example.com/exampletv/broadcast/movie",
  "name": "ExampleTV-Movie",
  "alternateName": [
    "Example Television Movie",
    "Example TV Movie"
  ],
  "description": "A fictional Internet Protocol TV movie channel.",
  "broadcastDisplayName":"ExampleTV-Movie",
  "broadcastAffiliateOf":{
    "@type":"Organization",
    "@id":"http://www.example.com/exampletv/movie",
  },
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/exampletv/broadcast/movie?autoplay=true",
      "inLanguage": "en",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "subscription",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "@id": "http://www.example.com/exampletv/basic_subscription",
        "name": "Basic subscription",
        "commonTier": true
      },
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        }
      ]
    }
  },
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "TMS_ID",
      "value": "12345"
    },
    {
      "@type": "PropertyValue",
      "propertyID": "_PARTNER_ID_",
      "value": "exampletv-movie-33345"
    }
  ]
},
{
  "@context":"http://schema.org",
  "@type":"BroadcastService",
  "@id":"https://www.example.com/exampletv/broadcast/comedy",
  "name": "ExampleTV-Comedy",
  "alternateName": [
    "Example Television Comedy",
    "Example TV Comedy"
  ],
  "description": "A fictional Internet Protocol TV comedy channel.",
  "broadcastDisplayName":"ExampleTV-Comedy",
  "broadcastAffiliateOf":{
    "@type":"Organization",
    "@id":"http://www.example.com/exampletv/comedy",
  },
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/exampletv/broadcast/comedy?autoplay=true",
      "inLanguage": "en",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "subscription",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "@id": "http://www.example.com/exampletv/basic_subscription",
        "name": "Basic subscription",
        "commonTier": true
      },
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        }
      ]
    }
  },
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "TMS_ID",
      "value": "15555"
    },
    {
      "@type": "PropertyValue",
      "propertyID": "_PARTNER_ID_",
      "value": "exampletv-comedy-12323"
    }
  ]
}

CableOrSatelliteService

This CableOrSatelliteService describes the service provider ExampleTV Digital Service that has national coverage:

{
  "@context":"http://schema.org",
  "@type":"CableOrSatelliteService",
  "@id":"http://example.com/example_iptv/us",
  "name":"Example TV Digital Service - US",
  "provider": {
    "@type": "Organization",
    "@id": "http://example.com/exampletv/digital",
    "name": "ExampleTV Digital Service",
  },
  "areaServed":[
    {
      "@type":"Country",
      "name": "US",
    }
  ]
}

TelevisionChannel

These TelevisionChannel entities indicate that ExampleTV Digital Service IPTV has the ExampleTV Movie programming on channel ExTV-Movie and the ExampleTV Comedy programming on channel ExTV-Comedy:

{
  "@context":"http://schema.org",
  "@type":"TelevisionChannel",
  "@id":"http://example.com/exampletv/extv-movie",
  "broadcastChannelId":"ExTV-Movie",
  "broadcastServiceTier":"Basic",
  "inBroadcastLineup":{
    "@type":"CableOrSatelliteService",
    "@id":"http://example.com/example_iptv/us"
  },
  "providesBroadcastService":{
    "@type":"BroadcastService",
    "@id":"https://www.example.com/exampletv/broadcast/movie"
  }
},
{
  "@context":"http://schema.org",
  "@type":"TelevisionChannel",
  "@id":"http://example.com/exampletv/extv-comedy",
  "broadcastChannelId":"ExTV-Comedy",
  "broadcastServiceTier":"Basic",
  "inBroadcastLineup":{
    "@type":"CableOrSatelliteService",
    "@id":"http://example.com/example_iptv/us"
  },
  "providesBroadcastService":{
    "@type":"BroadcastService",
    "@id":"https://www.example.com/exampletv/broadcast/comedy"
  }
}

See the Live TV examples section for more examples.

Identify the relationships

For Organization,

Collect the @id and name of the TV network or TV operator.

For BroadcastService,

Collect the @id and name of the broadcast service.
For the broadcastAffiliateOf property, collect the @id of the TV network (Organization) whose programming this broadcast service provides.

The following entity types are required if your broadcast service supports the channel switch by channel number (see the Fulfilled by Google section for details).

For CableOrSatelliteService,

Collect the @id and name of the regional cable, satellite, or Internet TV service.
For the provider property, collect the @id and name of the TV operator (Organization), which is the parent organization of this regional service.

For TelevisionChannel,

Collect the @id and name of the television channel.
For the inBroadcastLineup property, collect the @id of the regional cable, satellite, or Internet TV service (CableOrSatelliteService) that provides this channel to the viewers.
For the providesBroadcastService property, collect the @id of the broadcast service (BroadcastService) whose programming this channel provides.

Collect the ID, URL, and Name

Collect the Metadata