Content markup properties of live TV events

This section provides the details of the content markup properties for the BroadcastEvent entity type. To better understand the relationship between these types, review the LiveTV Events concepts.

BroadcastEvent specification table

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]
  • Replace xx with the entity's language code in BCP 47 format format, for example, "en".
@type Text Required - Always set to BroadcastEvent.
@id URL Required - The content's identifier in URI format; for example, https://example.com/1234abc.
@id must meet the following requirements:
  • Globally unique across your catalog
  • Static; The ID should be stable and not change over time (even if the url property of the show changes). It will be treated as an opaque string and does not have to be a working link.
  • In the form of Unified Resource Identifier (URI)
  • The domain used for the @id value must be owned by your organization.
Because an entity's url meets all the requirements as an identifier, we recommend you use an entity's url as @id. See the Identifier section for more details.
name Text Required - The title of the show or event.
description Text The description of the show or event. 300-character limist. Use an array to include the descriptions in multiple languages and lengths.
startDate Date Required - The start time of the event in ISO 8601 format with time zone.
endDate Date The end time of the event in ISO 8601 format with time zone.
publishedOn BroadcastService Required if applicable - Specify the BroadcastService entity that broadcasts this show or event.

If the content is broadcast on a TV channel, this property is required. If the content is not associated with any TV channel, don't provide this property.
publishedOn.@type Text Set to BroadcastService.
publishedOn.@id URL The @id of the BroadcastService entity that broadcasts this show or event.
workPerformed CreativeWork Required if applicable - Use this property when the content is one of the following entity types: Movie, TVSeries, and TVEpisode.
It is highly recommended that a BroadcastEvent entity include at least one of:
  • workPerformed
  • broadcastOfEvent
  • contentToBeAnnounced set to true
  • offAir set to true
workPerformed.@type Text Set to Movie, TVSeries, or TVEpisode.
workPerformed.@id URL The @id of the content entity.
broadcastOfEvent SportsEvent Required if applicable - Use this property if the content is a live event:
  • For a sports event, this property needs to refer to a SportsEvent entity.

It is highly recommended that a BroadcastEvent entity include at least one of:
  • workPerformed
  • broadcastOfEvent
  • contentToBeAnnounced set to true
  • offAir set to true
broadcastOfEvent.@type Text Set to SportsEvent.
broadcastOfEvent.@id URL The @id of the event entity. The event entity must exist in the feed and has a @id different from that of BroadcastEvent.
location Text or Country Required if BroadcastEvent is for a SportsEvent, i.e. has broadcastOfEvent property - The country that the underlying SportsEvent can be broadcast in. This field can be a list of countries if multiple countries can broadcast the SportsEvent.
videoFormat Text The highest quality definition supported on this broadcast service; for example,
  • "SD" for standard-definition.
  • "HD" for high-definition.
  • "2K" for 2K resolution.
  • "4K" for 4K resolution.
  • "8K" for 8K resolution.
contentToBeAnnounced Boolean Required if applicable - Use this property if the content is unknown at the time of creation of the feed.

Set to true when the provider does not have up-to-date information on what will be broadcast, false otherwise.
It is highly recommended that a BroadcastEvent entity include at least one of:
  • workPerformed
  • broadcastOfEvent
  • contentToBeAnnounced set to true
  • offAir set to true
offAir Boolean Required if applicable - Use this property if there is no planned content broadcast for the timeslot.
It is highly recommended that a BroadcastEvent entity include at least one of:
  • workPerformed
  • broadcastOfEvent
  • contentToBeAnnounced set to true
  • offAir set to true
isLiveBroadcast Boolean Set to true if this is a live event; for example, a sports event or a concert.
potentialAction WatchAction Required if applicable - If the content is broadcast as a channel less live streaming event (with contentToBeAnnounced set to false or offAir set to false) , use this property to provide the deep link of the event.
identifier PropertyValue External ID that identifies the broadcast content. See the Identifier properties section for details.
  • Note: BroadcastEvent entity type only accepts propertyID values of either TMS_ID or TMS_ROOT_ID.
  • This property should only be provided for cases when a fully formed top-level Movie, TVSeries, TVEpisode or SportsEvent entity is not referenced using the workPerformed or broadcastOfEvent property.
  • The value of the property should reflect the TMS_ID or TMS_ROOT_ID of the Movie, TVSeries, TVEpisode or SportsEvent entity you would ideally referenced using the workPerformed or broadcastOfEvent property.
  • TMS_ID is preferred over the TMS_ROOT_ID value.
contentRating Text or Rating Required for adult content, highly recommended otherwise Why? - Overall content rating of the broadcast content. If the content rating is given in the form of a text string, two variations are accepted:
  • The rating agency prepended to the rating with a whitespace in between. For example, a "PG-13" rating from agency "MPAA" in the U.S. should be described as "MPAA PG-13". See the list of agencies.
  • A value of "RATING NOT KNOWN" (case insensitive) to indicate you don't know the rating for the Movie.
contentRating.author Organization Required if contentRating uses Rating - The name of the rating agency.
contentRating.ratingValue Text Required if contentRating uses Rating - The value of the rating.
contentRating.advisoryCode Text The advisory code for the content. Accepted values include D, FV, L, S, and V. D = Dialogue, FV = Fantasy Violence , L = Language, S = Sexual Content, V = Violence.

Examples

A TV episode is broadcast on the television network Example TV (BroadcastService) between 9 pm and 9:30 pm on October 12th, 2019:

BroadcastEvent 

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "BroadcastEvent",
  "@id": "http://example.com/live/event/my_favorite_tv_series/new_episode",
  "name": "My Favorite TV Series - Season 6 - Episode 2 - Three Mice",
  "description": "Three mice leave the town and the trip turns into something more.",
  "startDate": "2019-10-12T21:00-08:00",
  "endDate": "2019-10-12T21:30-08:00",
  "videoFormat": "HD",
  "isLiveBroadcast": false,
  "publishedOn": {
    "@type": "BroadcastService",
    "@id": "http://example.com/stations/example_tv"
  },
  "workPerformed": {
    "@type": "TVEpisode",
    "@id": "http://example.com/tv_series/my_favorite_tv_series/s6/e2_three_mice"
  }
}

BroadcastService 

{
  "@context":"http://schema.org",
  "@type":"BroadcastService",
  "@id":"http://example.com/stations/example_tv",
  "name":"EXAMPLE-TV",
  "broadcastDisplayName":"ABCD",
  "callSign": "EXA-TV",
  "videoFormat":"SD",
  "broadcastTimezone":"America/Los_Angeles",
  "broadcastAffiliateOf":{
    "@type":"Organization",
    "@id":"http://example.com/networks/abcd-network"
  },
  "identifier": [
   {
     "@type": "PropertyValue",
     "propertyID": "TMS_ID",
     "value": "12258"
   },
   {
     "@type": "PropertyValue",
     "propertyID": "_PARTNER_ID_",
     "value": "exampletv-123456"
   }
  ],
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://example.com/livestream",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast",
        "http://schema.org/AndroidTVPlatform"
      ]
    },
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "externalsubscription",
      "availabilityStarts": "2018-07-21T10:35:29Z",
      "availabilityEnds": "2019-10-21T10:35:29Z",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "@id": "http://example.com/subscription",
        "name": "ABCD",
        "sameAs": "http://example.com/subscription",
        "identifier": "example.com:basic",
        "commonTier": false
      },
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        }
      ]
    }
  }
}

Example showing the use of contentToBeAnnounced property when the content to be broadcast on the television network Example TV (BroadcastService) between 9 pm and 9:30 pm on October 12th, 2019 is not known at the time of creation of the feed:

BroadcastEvent 

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "BroadcastEvent",
  "@id": "http://example.com/randomUniqueEventId",
  "name": "To Be Announced"
  "startDate": "2019-10-12T21:00-08:00",
  "endDate": "2019-10-12T21:30-08:00",
  "publishedOn": {
    "@type": "BroadcastService",
    "@id": "http://example.com/stations/example_tv"
  },
  "contentToBeAnnounced": true
}

BroadcastService 

{
  "@context":"http://schema.org",
  "@type":"BroadcastService",
  "@id":"http://example.com/stations/example_tv",
  "name":"EXAMPLE-TV",
  "broadcastDisplayName":"ABCD",
  "callSign": "EXA-TV",
  "videoFormat":"SD",
  "broadcastTimezone":"America/Los_Angeles",
  "broadcastAffiliateOf":{
    "@type":"Organization",
    "@id":"http://example.com/networks/abcd-network"
  },
  "identifier": [
   {
     "@type": "PropertyValue",
     "propertyID": "TMS_ID",
     "value": "12258"
   },
   {
     "@type": "PropertyValue",
     "propertyID": "_PARTNER_ID_",
     "value": "exampletv-123456"
   }
  ],
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://example.com/livestream",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast",
        "http://schema.org/AndroidTVPlatform"
      ]
    },
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "externalsubscription",
      "availabilityStarts": "2018-07-21T10:35:29Z",
      "availabilityEnds": "2019-10-21T10:35:29Z",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "@id": "http://example.com/subscription",
        "name": "ABCD",
        "sameAs": "http://example.com/subscription",
        "identifier": "example.com:basic",
        "commonTier": false
      },
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        }
      ]
    }
  }
}

Television network Example TV(BroadcastService) Channel is off air between 12 pm and 8pm and broadcasts 1 show named My favorite show between 8 pm and 12pm:

BroadcastEvent 

{
   "@context": ["http://schema.org", {"@language": "en"}],
   "@type": "BroadcastEvent",
   "@id": "http://example.com/randomUniqueEventId1",
   "name": “Off Air”,
   "startDate": "2019-10-12T00:00-08:00",
   "endDate": "2019-10-12T20:00-08:00",
   "publishedOn": {
       "@type": "BroadcastService",
       "@id": "http://example.com/stations/example_tv"
   },
   "offAir": true
},
{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "BroadcastEvent",
  "@id": "http://example.com/randomUniqueEventId2",
  "startDate": "2019-10-12T20:00-08:00",
  "endDate": "2019-10-13T00:00-08:00",
  "videoFormat": "HD",
  "isLiveBroadcast": false,
  "name": "My favorite show",
  "workPerformed": {
    ...
  },
  "publishedOn": {
    "@type": "BroadcastService",
    "@id": "http://example.com/stations/example_tv"
  },

}

BroadcastService 

{
  "@context":"http://schema.org",
  "@type":"BroadcastService",
  "@id":"http://example.com/stations/example_tv",
  "name":"EXAMPLE-TV",
  "broadcastDisplayName":"ABCD",
  "callSign": "EXA-TV",
  "videoFormat":"SD",
  "broadcastTimezone":"America/Los_Angeles",
  "broadcastAffiliateOf":{
    "@type":"Organization",
    "@id":"http://example.com/networks/abcd-network"
  },
  "identifier": [
   {
     "@type": "PropertyValue",
     "propertyID": "TMS_ID",
     "value": "12258"
   },
   {
     "@type": "PropertyValue",
     "propertyID": "_PARTNER_ID_",
     "value": "exampletv-123456"
   }
  ],
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://example.com/livestream",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast",
        "http://schema.org/AndroidTVPlatform"
      ]
    },
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "externalsubscription",
      "availabilityStarts": "2018-07-21T10:35:29Z",
      "availabilityEnds": "2019-10-21T10:35:29Z",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "@id": "http://example.com/subscription",
        "name": "ABCD",
        "sameAs": "http://example.com/subscription",
        "identifier": "example.com:basic",
        "commonTier": false
      },
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        }
      ]
    }
  }
}

Check out the following pages for the topics related to these properties: