Content markup properties of live TV events

  • This section details the content markup properties for the BroadcastEvent entity type.

  • Required properties for BroadcastEvent include @context, @type, @id, name, and startDate.

  • Depending on the content, other properties like publishedOn, workPerformed, or broadcastOfEvent may be required.

  • Additional properties like endDate, description, videoFormat, isLiveBroadcast, and content rating information can also be included.

  • Examples demonstrate how to use BroadcastEvent markup for a TV episode broadcast, a content-to-be-announced scenario, and an off-air timeslot.

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 broadcast slot's identifier in URI format; for example, https://example.com/live/channel1/20191012T2100.
@id must meet the following requirements:
  • Globally unique across your catalog and distinct from workPerformed.@id or broadcastOfEvent.@id (for example, incorporate the channel/service and broadcast start time into the URI)
  • Static; 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.
  • In the form of Unified Resource Identifier (URI)
  • The domain used for the @id value must be owned by your organization.
Important: Do not include a url property on BroadcastEvent or SportsEvent. Provide the canonical url only on the underlying content entity (Movie, TVSeries, or TVEpisode). 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 limit. Use an array to include descriptions in multiple languages (one per language).
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 - Set to true when there is no planned content broadcast for the timeslot on a BroadcastService channel.
  • Set both name and description to "Off Air".
  • Each offAir BroadcastEvent must span 4 hours or less (do not emit 24-hour continuous blocks). When a channel is off air for more than 4 hours, emit multiple contiguous, non-overlapping BroadcastEvent entities of at most 4 hours each so the channel maintains complete 24x7 schedule coverage with no gaps at the start or end of the feed window.
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 boolean true (unquoted) if this airing is a live broadcast (for example, a live sports game or live daily news), or false for non-live programming and replays.
potentialAction WatchAction Required if applicable - Never provide potentialAction on a BroadcastEvent when broadcastOfEvent references a SportsEvent (place all sports deep links on SportsEvent.potentialAction) or when publishedOn references a BroadcastService channel (place channel deep links on BroadcastService.potentialAction). Only provide BroadcastEvent.potentialAction for channel-less live streams that do not reference a SportsEvent (such as standalone live shoulder content with contentToBeAnnounced and offAir omitted or false).
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": "Content To Be Announced",
  "description": "Content 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 8 pm (modeled as two contiguous 4-hour Off Air blocks) and broadcasts one show named My favorite show between 8 pm and 12 am:

BroadcastEvent 

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "BroadcastEvent",
  "@id": "http://example.com/randomUniqueEventId1",
  "name": "Off Air",
  "description": "Off Air",
  "startDate": "2019-10-12T12:00-08:00",
  "endDate": "2019-10-12T16: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",
  "name": "Off Air",
  "description": "Off Air",
  "startDate": "2019-10-12T16: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/randomUniqueEventId3",
  "name": "My favorite show",
  "description": "Evening broadcast of My favorite show.",
  "startDate": "2019-10-12T20:00-08:00",
  "endDate": "2019-10-13T00:00-08:00",
  "videoFormat": "HD",
  "isLiveBroadcast": false,
  "workPerformed": {
    "@type": "TVSeries",
    "@id": "http://example.com/tv_series/my_favorite_show"
  },
  "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: