SportsEvents - Modelling, Best Practices and Sample Feed

Definition

A SportsEvent is an entity type representing a sports game or a full replay of a sports game.

What can be modeled as a SportsEvent?

A sports game

What can't be modeled as a SportsEvent?

Any short form or clip content or shoulder content. Here's the list:

Random recap or replay short clips
Previews of the game
Highlights of the game
Game bloopers
Player interview clips
Behind the scene videos
Game reviews (user generated or otherwise)
Random short clips from the game

How do I handle such shoulder content?

Common Use-cases for SportsEvents

S.No.	Description	Entities Required
Case 1	I need to model a `SportsEvent` that's part of my Video on demand catalog.	`SportsEvent` representing the game.
Case 2	I need to model a `SportsEvent` that's part of my live TV catalog and streams online The game streams over the internet and is not attached to any channel.	`SportsEvent` representing the game. `BroadcastEvent` representing the broadcast of the game.
Case 3	I need to model a SportsEvent that's part of my live TV catalog and is streamed online on a channel.	`SportsEvent` representing the game. `Broadcast` representing the airing of the game. `BroadcastService`, `Organization`, `TelevisionChannel`, `CableOrSatelliteService` entities representing the channel and the lineup.
Case 4	Combinations of the preceding three cases.	If you combine a subset of the earlier use-cases, then you must provide the entity types in the corresponding "Entities required" column.

Best practices and insights into a few checks that we do

S.No. Entities Required Guidelines

Case 1

S.No.	Entities Required	Guidelines
Case 1	I need to model a `SportsEvent` that's part of my Video on demand catalog. Entities Required `SportsEvent` representing the game	Modeling guidelines The deep link to the game must be provided on the SportsEvent entity using the SportsEvent.potentialAction property.
Case 2	I need to model a `SportsEvent` that's part of my live TV catalog and streams online. The game streams over the internet and is not attached to any channel. Entities Required `SportsEvent` representing the game `BroadcastEvent` representing the airing of the game	Modeling guidelines Sub-case 1: The game is only available live (and not as part of the Video on demand catalog) The `BroadcastEvent` entity must be provided to share the schedule of the broadcast. The deep link to the game must be provided on the `BroadcastEvent` entity using the `BroadcastEvent.potentialAction` property. Since the game is only available to view live, the `SportsEvent` entity must not have any deep links. That is, the `SportsEvent.potentialAction` must not be provided. `BroadcastEvent.broadcastOfEvent` must be provided because the game is not tied to any channel broadcast. Sub-case 2: The game is available live and as part of the Video on demand catalog (this could happen when a game replay is being broadcast) The `BroadcastEvent` entity must be provided to share the schedule of the broadcast. The deep link to the game must be provided on the `BroadcastEvent` entity using the `BroadcastEvent.potentialAction` property. Since the game is available to view live as part of the Video on demand catalog, the `SportsEvent` entity must also have a deep link. The `SportsEvent.potentialAction` must be provided to redirect the user to the Video on demand catalog. `BroadcastEvent.publishedOn` must not be provided because the game is not tied to any channel broadcast. Quality checks to perform Set the `BroadcastEvent.isLiveBroadcast` property to `true` when the game is actually live. Don't set the property to `true` for a game replay. For `BroadcastEvents` that aren't live, `BroadcastEvent.startDate` usually can't be earlier than the actual `SportsEvent` `startDate`. `BroadcastEvents` shouldn't have a `publishedOn` property because the broadcast streams on the internet and doesn't attach to a channel.
Case 3	I need to model a `SportsEvent` that's part of my live TV catalog and streams online on a channel. Entities Required `SportsEvent` that represents the game. `BroadcastEvent` that represents the airing of the game. `BroadcastService`, `Organization`, `TelevisionChannel`, `CableOrSatelliteService` entities representing the channel and the lineup.	Modeling guidelines Sub-case 1: The game is only available live (and not as part of the Video on demand catalog) Share the schedule of the broadcast. To do so, provide the `BroadcastEvent` entity. Represent the channel and the provider lineup. To do so, provide the `BroadcastService`, `Organization`, `TelevisionChannel`, and `CableOrSatelliteService` entities. Provide the `BroadcastService` deep link. Represent it with the `BroadcastService.potentialAction` property. Don't provide the `BroadcastEvent.potentialAction` property. Since the game is only available to view Live, the `SportsEvent` entity must not have any deep link. For example, don't provide `SportsEvent.potentialAction`. Provide `BroadcastEvent.publishedOn` and point it to the `BroadcastService` entity representing the channel on which the Broadcast will happen. Sub-case 2: The game is available live and as part of the Video on demand catalog (this could happen when a game replay is being broadcast) Provide the `BroadcastEvent` entity to share the schedule of the broadcast. Provide the `BroadcastService`, `Organization`, `TelevisionChannel`, and `CableOrSatelliteService` entities representing the channel and the provider lineup. Provide the `BroadcastService` deep link to the channel on which the game broadcast will happen, represented by the `BroadcastService.potentialAction` property. Don't provide the `BroadcastEvent.potentialAction` property. Since the game is available to view live and as part of the Video on demand catalog, the `SportsEvent` entity must also have a deep link. For example, `SportsEvent.potentialAction` can be provided that redirects the user to the Video on demand catalog. Provide `BroadcastEvent.publishedOn` and point it to the `BroadcastService` entity representing the channel on which the Broadcast will happen. Quality checks to perform Set the `BroadcastEvent.isLiveBroadcast` property to `true` when the game is actually live. Don't set the property to `true` for a game replay. For `BroadcastEvents` that aren't live, `BroadcastEvent.startDate` usually can't be earlier than the actual `SportsEvent` `startDate`. Since the game airs on a channel, add a deep link using the `BroadcastService.potentialAction` property. `BroadcastEvent` entity can't have a deep link in this case.

I need to model a SportsEvent that's part of my Video on demand catalog.

Entities Required

SportsEvent representing the game

Modeling guidelines

The deep link to the game must be provided on the SportsEvent entity using the SportsEvent.potentialAction property.

Case 2

I need to model a SportsEvent that's part of my live TV catalog and streams online.

The game streams over the internet and is not attached to any channel.

Entities Required

SportsEvent representing the game
BroadcastEvent representing the airing of the game

Modeling guidelines

Sub-case 1: The game is only available live (and not as part of the Video on demand catalog)

The BroadcastEvent entity must be provided to share the schedule of the broadcast.
The deep link to the game must be provided on the BroadcastEvent entity using the BroadcastEvent.potentialAction property.
Since the game is only available to view live, the SportsEvent entity must not have any deep links. That is, the SportsEvent.potentialAction must not be provided.
BroadcastEvent.broadcastOfEvent must be provided because the game is not tied to any channel broadcast.

Sub-case 2: The game is available live and as part of the Video on demand catalog (this could happen when a game replay is being broadcast)

The BroadcastEvent entity must be provided to share the schedule of the broadcast.
The deep link to the game must be provided on the BroadcastEvent entity using the BroadcastEvent.potentialAction property.
Since the game is available to view live as part of the Video on demand catalog, the SportsEvent entity must also have a deep link. The SportsEvent.potentialAction must be provided to redirect the user to the Video on demand catalog.
BroadcastEvent.publishedOn must not be provided because the game is not tied to any channel broadcast.

Quality checks to perform

Set the BroadcastEvent.isLiveBroadcast property to true when the game is actually live. Don't set the property to true for a game replay.
For BroadcastEvents that aren't live, BroadcastEvent.startDate usually can't be earlier than the actual SportsEvent startDate.
BroadcastEvents shouldn't have a publishedOn property because the broadcast streams on the internet and doesn't attach to a channel.

Case 3

I need to model a SportsEvent that's part of my live TV catalog and streams online on a channel.

Entities Required

SportsEvent that represents the game.
BroadcastEvent that represents the airing of the game.
BroadcastService, Organization, TelevisionChannel, CableOrSatelliteService entities representing the channel and the lineup.

Modeling guidelines

Sub-case 1: The game is only available live (and not as part of the Video on demand catalog)

Share the schedule of the broadcast. To do so, provide the BroadcastEvent entity.
Represent the channel and the provider lineup. To do so, provide the BroadcastService, Organization, TelevisionChannel, and CableOrSatelliteService entities.
Provide the BroadcastService deep link. Represent it with the BroadcastService.potentialAction property.
Don't provide the BroadcastEvent.potentialAction property.
Since the game is only available to view Live, the SportsEvent entity must not have any deep link. For example, don't provide SportsEvent.potentialAction.
Provide BroadcastEvent.publishedOn and point it to the BroadcastService entity representing the channel on which the Broadcast will happen.

Sub-case 2: The game is available live and as part of the Video on demand catalog (this could happen when a game replay is being broadcast)

Provide the BroadcastEvent entity to share the schedule of the broadcast.
Provide the BroadcastService, Organization, TelevisionChannel, and CableOrSatelliteService entities representing the channel and the provider lineup.
Provide the BroadcastService deep link to the channel on which the game broadcast will happen, represented by the BroadcastService.potentialAction property.
Don't provide the BroadcastEvent.potentialAction property.
Since the game is available to view live and as part of the Video on demand catalog, the SportsEvent entity must also have a deep link. For example, SportsEvent.potentialAction can be provided that redirects the user to the Video on demand catalog.
Provide BroadcastEvent.publishedOn and point it to the BroadcastService entity representing the channel on which the Broadcast will happen.

Quality checks to perform

Set the BroadcastEvent.isLiveBroadcast property to true when the game is actually live. Don't set the property to true for a game replay.
For BroadcastEvents that aren't live, BroadcastEvent.startDate usually can't be earlier than the actual SportsEvent startDate.
Since the game airs on a channel, add a deep link using the BroadcastService.potentialAction property. BroadcastEvent entity can't have a deep link in this case.

Examples

Case 1: A sports event that's part of Video on demand catalog


{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type":"SportsEvent",
  "@id": "http://example.com/basketball/professional/final_game_6",
  "name":"2019 Professional Basketball Finals, Game 6: Team A at Team B",
  "sport":"https://en.wikipedia.org/wiki/Basketball",
  "description": {
      "@language": "en",
      "@value": "Game 6 of the 2019 Professional Basketball Finals. Team A leads the series 3-2 against Team B."
    },
  "startDate": "2018-09-16T10:00-08:00",
  "endDate": "2018-09-16T13:00-08:00",
  "homeTeam":{
    "@type":"SportsTeam",
    "name":"Team B",
    "sport":"https://en.wikipedia.org/wiki/Basketball",
    "parentOrganization":{
      "@type":"SportsOrganization",
      "name":"Professional Basketball League",
      "sameAs":"http://www.example.com/professional_basketball_league"
    },
    "athlete":[
      {
        "@type":"Person",
        "name":"John doe"
      }
    ]
  },
  "awayTeam":{
    "@type":"SportsTeam",
    "name":"Team A",
    "sport":"https://en.wikipedia.org/wiki/Basketball",
    "athlete":[
      {
        "@type":"Person",
        "name":"Jane Doe"
      }
    ]
  },
  "location":{
    "@type":"Place",
    "name":"Example Stadium",
    "address":{
      "@type":"PostalAddress",
      "streetAddress":"1600 Amphitheatre Pkwy",
      "addressLocality":"Mountain View",
      "addressRegion":"CA",
      "postalCode":"94043",
      "addressCountry":"US"
    }
  }
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "TMS_ID",
      "value":  "TMS ID of this game"
    }
  ],
"potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/pbl_semis_game?autoplay=true",
      "inLanguage": "en",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.org/AndroidTVPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "subscription",
      "availabilityStarts": "2018-09-17T10:00-08:00",
      "availabilityEnds": "2019-10-21T10:35:29Z",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "name": "Example Package",
        "commonTier": true,
        "@id": "http://www.example.com/example_package"
       },
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        }
      ]
    }
  }
}

Case 2: A sports event that's part of live TV catalog and is streamed online

Broadcast event


{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "BroadcastEvent",
  "@id": "http://example.com/live_eevent/basketball/professional/final_game_6",
  "name": "2019 Professional Basketball Finals, Game 6: Team A at Team B",
  "description": "Game 6 of the 2019 Professional Basketball Finals. Team A leads the series 3-2 against Team B.",
  "startDate": "2018-09-16T10:00-08:00",
  "endDate": "2018-09-16T13:00-08:00",
  "videoFormat": "HD",
  "isLiveBroadcast": "False",
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/pbl_semis_game?autoplay=true",
      "inLanguage": "en",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.org/AndroidTVPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "subscription",
      "availabilityStarts": "2018-09-16T10:00-08:00",
      "availabilityEnds": "2018-09-16T10:00-08:00",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "name": "Example Package",
        "commonTier": true,
        "@id": "http://www.example.com/example_package"
      },
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        }
      ]
    }
  },
  "broadcastOfEvent": {
    "@type": "SportsEvent",
    "@id": "http://example.com/basketball/professional/final_game_6"
  }
}

Sports event


{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type":"SportsEvent",
  "@id": "http://example.com/basketball/professional/final_game_6",
  "name":"2019 Professional Basketball Finals, Game 6: Team A at Team B",
  "sport":"https://en.wikipedia.org/wiki/Basketball",
  "description": {
      "@language": "en",
      "@value": "Game 6 of the 2019 Professional Basketball Finals. Team A leads the series 3-2 against Team B."
    },
  "startDate": "2018-09-16T10:00-08:00",
  "endDate": "2018-09-16T13:00-08:00",
  "homeTeam":{
    "@type":"SportsTeam",
    "name":"Team B",
    "sport":"https://en.wikipedia.org/wiki/Basketball",
    "parentOrganization":{
      "@type":"SportsOrganization",
      "name":"Professional Basketball League",
      "sameAs":"http://www.example.com/professional_basketball_league"
    },
    "athlete":[
      {
        "@type":"Person",
        "name":"John doe"
      }
    ]
  },
  "awayTeam":{
    "@type":"SportsTeam",
    "name":"Team A",
    "sport":"https://en.wikipedia.org/wiki/Basketball",
    "athlete":[
      {
        "@type":"Person",
        "name":"Jane Doe"
      }
    ]
  },
  "location":{
    "@type":"Place",
    "name":"Example Stadium",
    "address":{
      "@type":"PostalAddress",
      "streetAddress":"1600 Amphitheatre Pkwy",
      "addressLocality":"Mountain View",
      "addressRegion":"CA",
      "postalCode":"94043",
      "addressCountry":"US"
    }
  },
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "TMS_ID",
      "value":  "TMS ID of this game"
    }
  ]
}

Case 3: A sports event that's part of live TV catalog and is streamed online on a channel

Broadcast event


{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "BroadcastEvent",
  "@id": "http://example.com/live_eevent/basketball/professional/final_game_6",
  "name": "2019 Professional Basketball Finals, Game 6: Team A at Team B",
  "description": "Game 6 of the 2019 Professional Basketball Finals. Team A leads the series 3-2 against Team B.",
  "startDate": "2018-09-16T10:00-08:00",
  "endDate": "2018-09-16T13:00-08:00",
  "videoFormat": "HD",
  "isLiveBroadcast": "False",
  "publishedOn": {
    "@type": "BroadcastService",
    "@id": "http://example.com/stations/example_tv"
  },
  "broadcastOfEvent": {
    "@type": "SportsEvent",
    "@id": "http://example.com/basketball/professional/final_game_6"
  }
}

Sports event


{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type":"SportsEvent",
  "@id": "http://example.com/basketball/professional/final_game_6",
  "name":"2019 Professional Basketball Finals, Game 6: Team A at Team B",
  "sport":"https://en.wikipedia.org/wiki/Basketball",
  "description": {
      "@language": "en",
      "@value": "Game 6 of the 2019 Professional Basketball Finals. Team A leads the series 3-2 against Team B."
    },
  "startDate": "2018-09-16T10:00-08:00",
  "endDate": "2018-09-16T13:00-08:00",
  "homeTeam":{
    "@type":"SportsTeam",
    "name":"Team B",
    "sport":"https://en.wikipedia.org/wiki/Basketball",
    "parentOrganization":{
      "@type":"SportsOrganization",
      "name":"Professional Basketball League",
      "sameAs":"http://www.example.com/professional_basketball_league"
    },
    "athlete":[
      {
        "@type":"Person",
        "name":"John doe"
      }
    ]
  },
  "awayTeam":{
    "@type":"SportsTeam",
    "name":"Team A",
    "sport":"https://en.wikipedia.org/wiki/Basketball",
    "athlete":[
      {
        "@type":"Person",
        "name":"Jane Doe"
      }
    ]
  },
  "location":{
    "@type":"Place",
    "name":"Example Stadium",
    "address":{
      "@type":"PostalAddress",
      "streetAddress":"1600 Amphitheatre Pkwy",
      "addressLocality":"Mountain View",
      "addressRegion":"CA",
      "postalCode":"94043",
      "addressCountry":"US"
    }
  }
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "TMS_ID",
      "value":  "TMS ID of this game"
    }
  ]
}

BroadcastService, CableOrSatelliteService, TelevisionChannel, Organization entities as defined in Live TV Channel section under Concepts

How do I handle shoulder content?

What qualifies as shoulder content?

Random recap or replay short clips
Previews of the game
Highlights of the game
Game bloopers
Player interview clips
Behind the scene videos
Game reviews (user generated or otherwise)
Other random short clips from the game

S.No. Use case Modeling guidelines

Case 1

I have shoulder content in my Video on demand catalog.

S.No.	Use case	Modeling guidelines
Case 1	I have shoulder content in my Video on demand catalog.	This isn't supported and can't be provided in the feed. ViTA can be used to provide a subset of this content though. Contact your Google representative to learn more about ViTA.
Case 2	I have shoulder content in my live catalog	Sub-case 1: Content is available to stream live on the internet Provide the `BroadcastEvent` entity to share the schedule of the broadcast. Provide the deep link of the content using the `BroadcastEvent.potentialAction` property. Add any associated metadata (to the clip) directly to the `BroadcastEvent`. For example, images can be added using the `BroadcastEvent.image` property. Age ratings can be added using the `BroadcastEvent.contentRating` property. Since this content type isn't a `SportsEvent`, the feed must not contain a `SportsEvent` entity. As such, the `broadcastOfEvent` property on the `BroadcastEvent` must not be provided. Since it's not tied to a channel, don't provide the `publishedOn` property on the `BroadcastEvent`. Sub-case 2: Content is available to stream live on the internet on a channel The `BroadcastEvent` entity must be provided to share the schedule of the broadcast. The `BroadcastService`, `Organization`, `TelevisionChannel`, `CableOrSatelliteService` entities must be provided to represent the channel and the provider lineup. The deep link to the game must simply be the `BroadcastService` deep link, represented by the `BroadcastService.potentialAction` property, which must be provided. The `BroadcastEvent.potentialAction` property must not be provided. Any associated metadata (to the clip) must be directly added to the `BroadcastEvent`. For example, images can be added using the `BroadcastEvent.image` property. Age ratings can be added using the `BroadcastEvent.contentRating` property. Since this content type isn't a `SportsEvent`, the feed must not contain a `SportsEvent` entity. As such, the `broadcastOfEvent` property on the `BroadcastEvent` must not be provided. Since it's tied to a channel, provide the `publishedOn` property on the `BroadcastEvent`.
Case 3	I have shoulder content available as part of both Video on demand and live TV catalog	Given that Video on demand sports shoulder content isn't accepted in the feed today, this is similar to case 2. See the instructions from there.

This isn't supported and can't be provided in the feed.
ViTA can be used to provide a subset of this content though. Contact your Google representative to learn more about ViTA.

Case 2

I have shoulder content in my live catalog

Sub-case 1: Content is available to stream live on the internet

Provide the BroadcastEvent entity to share the schedule of the broadcast.
Provide the deep link of the content using the BroadcastEvent.potentialAction property.
Add any associated metadata (to the clip) directly to the BroadcastEvent. For example, images can be added using the BroadcastEvent.image property. Age ratings can be added using the BroadcastEvent.contentRating property.
Since this content type isn't a SportsEvent, the feed must not contain a SportsEvent entity. As such, the broadcastOfEvent property on the BroadcastEvent must not be provided.
Since it's not tied to a channel, don't provide the publishedOn property on the BroadcastEvent.

Sub-case 2: Content is available to stream live on the internet on a channel

The BroadcastEvent entity must be provided to share the schedule of the broadcast.
The BroadcastService, Organization, TelevisionChannel, CableOrSatelliteService entities must be provided to represent the channel and the provider lineup.
The deep link to the game must simply be the BroadcastService deep link, represented by the BroadcastService.potentialAction property, which must be provided.
The BroadcastEvent.potentialAction property must not be provided.
Any associated metadata (to the clip) must be directly added to the BroadcastEvent. For example, images can be added using the BroadcastEvent.image property. Age ratings can be added using the BroadcastEvent.contentRating property.
Since this content type isn't a SportsEvent, the feed must not contain a SportsEvent entity. As such, the broadcastOfEvent property on the BroadcastEvent must not be provided.
Since it's tied to a channel, provide the publishedOn property on the BroadcastEvent.

Case 3

I have shoulder content available as part of both Video on demand and live TV catalog

Given that Video on demand sports shoulder content isn't accepted in the feed today, this is similar to case 2. See the instructions from there.

Commonly Asked Questions

Q: Where can I find the associated specifications for the entities mentioned earlier?

A: You can find the required specifications here.

Overall documentation	Link
`SportsEvent`	Link
`BroadcastService`, `Organization`, `TelevisionChannel`, `CableOrSatelliteService`	Link
`BroadcastEvent`	Link

Q: Is there a more detailed document that explains how to model the live TV channels and lineups?

A: Yes, you can find more details in Live TV Channel section under Concepts. Please feel free to request view access if you aren't able to view the document.

Q: Does ViTA support full live games and full game replays as well?

A: ViTA supports metadata on league based full live games and full game replays (in addition to a subset of shoulder content)

For partners that already have a functional Media Actions feed with Google or have a Video on demand or live TV offering, Google requires the feed to expand and include the supported SportsEvent types as well.
- For the short term, the partners can use ViTA for shoulder content ingestion. Support all types of content through the feed should roll out over the long term.
For partners that don't have a Video on demand or live TV offering but carry only league based sports and related shoulder content, ViTA is a great option to begin with. Contact your Google representative to learn more about ViTA.