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`	Text or 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:

Content markup properties of live TV events

BroadcastEvent specification table

Examples

BroadcastEvent

BroadcastService

BroadcastEvent

BroadcastService

BroadcastEvent

BroadcastService

Related pages