Content markup properties of live TV channels

This section provides the details of the content markup properties for the BroadcastService, CableOrSatelliteService, TelevisionChannel, Organization entity types. To better understand the relationship between these types, review the LiveTV Channels concepts.

BroadcastService Specification table

Property	Expected Type	Description
`@context`	Text	Required - Always set to `["http://schema.org", {"@language": "xx"}]` Where "xx" represents the language of the strings in the feed. Each root entity context should have it's @language set to the appropriate language code in BCP 47 format format. For example, if the language is set to Spanish, the names are assumed to be in Spanish even if the subtitle/dub language is in English.
`@type`	Text	Required - Always set to `BroadcastService`.
`@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.
`url`	URL	Required if applicable - The canonical URL of the broadcast service if the channel is available to view on the Internet. It is optional for a service delivered on cable/satellite/over the air. Google uses this URL to match the content in your feed to the content in Google's databases. `url` must meet the following requirements: `url` must be globally unique `url` must contain a working canonical URL that Google can crawl. For playback's deep link, see the target object's `urlTemplate` property instead.
`name`	Text	Required - The name of the network. Use an array to list the names in different languages. See the Multiple regions and languages example. Note that only one name is supported per locale (language-country pair).
`broadcastDisplayName`	Text	Required - The display name for the network that users may typically see in program guides etc. The value may be the same as the name value.
`callSign`	Text	The official government-issued callsign of the broadcast service.
`inLanguage`	Text or Language	Highly Recommended Why? The primary broadcast language of the channel. Please use one of the language codes from the IETF BCP 47 standard.
`category`	Text	Highly Recommended Why? A category for the item. Greater signs or slashes can be used to informally indicate a category hierarchy. e.g Sports, Sports > Football, News, Movie, Music, Documentary.`
`contentRating`	Text or Rating	Required for an adult only TV broadcast service - Most restrictive rating for the content broadcast on the channel. If the content rating is given in the form of a Text string, the rating agency needs to be prepended to the rating with whitespace in between; for example, a "TV-Y" rating from agency "TVPG" in the U.S. is described as "TVPG TV-Y". See the list of agencies.
`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.
`description`	Text	A description of the broadcast service. 300-character limit. Use an array to provide the descriptions in multiple languages and/or in different lengths.
`slogan`	Text	A slogan of the broadcast service.
`areaServed`	Country, State, City, or GeoShape	Required if applicable - This is required if the channel switch is fulfilled by TV service provider - The area in which users can expect to receive the broadcast service. Use the ISO 3166-1 country code to specify countries. Use an array to represent multiple areas. Do not mix Country, State, City with GeoShape.
`logo`	ImageObject	Required if integrating with GoogleTV. Highly Recommended otherwise Why? An image that represents this broadcast service. GoogleTV integrations require one logo that can be used on a dark background. It should have a transparent background with a colored or white logo, one that is clearly visible on a dark background. Image for logo should adhere to 1:1 or 4:3 or 16:9 aspect ratio (in that order of preference) and should have a resolution of 80x80px or greater. Use the `forDarkBackground` value for the custom property name `contentAttributes` as part of the `additionalProperty` property to indicate the type of background on which the logo should be used. Padding in either length or width (but not both) is acceptable if added to maintain the aspect ratio. See the Image section for other requirements and specifications. See example below
`potentialAction`	WatchAction	Required if applicable - An Action markup object that provides the details of the action. See the Action markup properties for details. Use an array to specify different deep links in multiple regions. See the Multiple regions and languages example. It's optional to provide deep links if the channel switch is fulfilled by TV service provider.
`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.
`broadcastTimezone`	Text	The timezone of this broadcast service in IANA format; for example, America/Los_Angeles. Use an array for multiple timezones.
`broadcastAffiliateOf`	Organization	Required - The TV network that provides programming for this broadcast service or the organization that this broadcast service belongs to.
`broadcastAffiliateOf.@id`	Text	Required - Set to `@id` of the TV network.
`broadcastAffiliateOf.@type`	Text	Required - Always set to `Organization`.
`identifier`	PropertyValue	Highly Recommended Why? - External or other ID that identifies this entity, such as _PARTNER_ID_. Multiple identifiers are allowed. See the Identifier properties section for details.
`popularityScore`	PopularityScoreSpecification	Highly Recommended Why? A score that Google uses, plus other signals, to determine which media to play for users. This score represents the popularity of the content in relation to other content in your catalog; therefore, the score's scale needs to be consistent across your feeds, among all the entities in your catalog. By default, an entity's popularity score is set to 0.
`popularityScore.@type`	Text	Always set to `PopularityScoreSpecification`.
`popularityScore.value`	Number	A non-negative numeric value that indicates the popularity of the entity; a higher score means higher popularity.
`popularityScore.eligibleRegion`	Country	Region(s) where this popularity score is applicable. If the popularity score is globally applicable, set to `EARTH`. By default, this property is set to `EARTH`. `Note:` Locale-specific popularity takes precedence over global (EARTH) popularity

BroadcastService Example

{
    "@context": [
        "http://schema.org",
        {
            "@language": "en"
        }
    ],
    "@type": "BroadcastService",
    "@id": "http://example.com/stations/example-tv",
    "name": "EXAMPLE-TV",
    "broadcastDisplayName": "ABCD",
    "url": "http://example.com/stations/example-tv",
    "callSign": "EXA-TV",
    "videoFormat": "SD",
    "inLanguage": "en",
    "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"
        }
    ],
    "popularityScore": {
        "@type": "PopularityScoreSpecification",
        "value": 178,
        "eligibleRegion": [
            {
                "@type": "Country",
                "name": "US"
            }
        ]
    },
    "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",
                "authenticator": {
                    "@type": "Organization",
                    "name": "TVE"
                }
            },
            "eligibleRegion": [
                {
                    "@type": "Country",
                    "name": "US"
                }
            ]
        }
    },
    "logo": [
        {
            "@context": "http://schema.org",
            "@type": "ImageObject",
            "name": "Example Logo Light",
            "contentUrl": "http://example.com/images/example-logo-light.jpg",
            "additionalProperty": [
                {
                    "@type": "PropertyValue",
                    "name": "contentAttributes",
                    "value": [
                        "forLightBackground"
                    ]
                }
            ]
        },
        {
            "@context": "http://schema.org",
            "@type": "ImageObject",
            "name": "Example Logo Dark",
            "contentUrl": "http://example.com/images/example-logo-dark.jpg",
            "additionalProperty": [
                {
                    "@type": "PropertyValue",
                    "name": "contentAttributes",
                    "value": [
                        "forDarkBackground"
                    ]
                }
            ]
        }
    ]
}

CableOrSatelliteService specification table

Property	Expected Type	Description
`@context`	Text	Required - Always set to `["http://schema.org", {"@language": "xx"}]` Where "xx" represents the language of the strings in the feed. Each root entity context should have it's @language set to the appropriate language code in BCP 47 format format. For example, if the language is set to Spanish, the names are assumed to be in Spanish even if the subtitle/dub language is in English.
`@type`	Text	Required - Always set to `CableOrSatelliteService`.
`@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 In the form of Unified Resource Identifier (URI) 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 name of the TV service. Use an array to list the names in different languages. See the Multiple regions and languages example. Note that only one name is supported per locale (language-country pair).
`areaServed`	Country, State, City, or GeoShape	Required - The area in which users can expect to receive the broadcast service. Use the ISO 3166-1 country code to specify countries. Use an array to represent multiple areas. Do not mix Country, State, City with GeoShape. See the GeoShape properties section for detailed requirements.
`provider`	Organization	Required - The parent provider of the service, if applicable. For example, ExampleTV is the provider of its regional services ExampleTV San Francisco and ExampleTV San Diego.
`provider.@id`	Text	Required - The ID of the TV operator.
`provider.@type`	Text	Required - Always set to `Organization`.
`identifier`	PropertyValue	Highly Recommended Why? - External or other ID that identifies this entity, such as a Gracenote TMS ID for this broadcast service. Multiple identifiers are allowed. See the Identifier properties section for details.

CableOrSatelliteService examples

Example of a cable or satellite service:

{
  "@context":["http://schema.org", {"@language": "en"}],
  "@type":"CableOrSatelliteService",
  "@id":"http://example.com/provider-lineups/exampletv-san-francisco",
  "name":"ExampleTV San Francisco",
  "provider": {
    "@type": "Organization",
    "@id": "http://example.com/providers/exampletv"
  },
  "areaServed":[
    {
      "@type":"GeoShape",
      "@id": "http://example.com/area1"
    }
  ],
  "identifier": {
    "@type": "PropertyValue",
    "propertyID": "TMS_ID",
    "value": "12345"
  }
}

{
  "@type": "GeoShape",
  "@id": "http://example.com/area1",
  "addressCountry": "US",
  "postalCode": [
    "94118",
    "94119"
  ]
}

Example of a Virtual Multichannel Video Programming Distributor (vMVPD):

{
  "@context":["http://schema.org", {"@language": "en"}],
  "@type":"CableOrSatelliteService",
  "@id":"http://example.com/providers/my-online-example-tv",
  "name":"My Online Example TV",
  "provider": {
    "@type": "Organization",
    "@id": "http://my-online-tv.com"
  },
  "areaServed":[
    {
      "@type":"Country",
      "name": "US",
    },
    {
      "@type":"Country",
      "name": "CA",
    }
  ]
}

TelevisionChannel specification table

Property	Expected Type	Description
`@context`	Text	Required - Always set to `["http://schema.org", {"@language": "xx"}]` Where "xx" represents the language of the strings in the feed. Each root entity context should have it's @language set to the appropriate language code in BCP 47 format format. For example, if the language is set to Spanish, the names are assumed to be in Spanish even if the subtitle/dub language is in English.
`@type`	Text	Required - Always set to `TelevisionChannel`.
`@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 In the form of Unified Resource Identifier (URI) 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.
`broadcastChannelId`	Text	Required - A unique identifier by which this `BroadcastService` can be identified as a cable, satellite, or Internet TV service. In the US, this is typically a number for cable or satellite TV. For an Internet TV service (for example, a vMVPD), provide the channel name.
`channelOrder`	Number	Required for GoogleTV, optional otherwise - Use this property to indicate the order in which the channels should be displayed in the electronic programming guide for Google TV integrations. The `channelOrder` should be unique across the channels in the feed and should ideally start from 1. `channelOrder` cannot have a negative or 0 value.
`broadcastServiceTier`	Text	Use the following values: `Free` for the channel that do not require subscriptions. `Standard` for the channels included with a basic subscription. `Premium` for the channels that require a payment on top of the basic subscription. Use an array to provide multiple values.
`inBroadcastLineup`	CableOrSatelliteService	Required - The `@id` of the `CableOrSatelliteService` that provides this channel to the viewers.
`providesBroadcastService`	BroadcastService	Required - The `@id` of the `BroadcastService` whose programming this channel provides.

TelevisionChannel examples

Example of a cable or satellite TV channel:

{
  "@context":["http://schema.org", {"@language": "en"}],
  "@type":"TelevisionChannel",
  "@id":"http://example.com/channels/exampleTV/example-tv-7",
  "broadcastChannelId":"7",
  "channelOrder": 1,
  "broadcastServiceTier":["Premium", "Standard"],
  "inBroadcastLineup":{
    "@type":"CableOrSatelliteService",
    "@id":"http://example.com/providers/exampleTV-san-francisco"
  },
  "providesBroadcastService":{
    "@type":"BroadcastService",
    "@id":"http://example.com/stations/example-tv"
  }
}

Example for an online TV channel:

{
  "@context":["http://schema.org", {"@language": "en"}],
  "@type":"TelevisionChannel",
  "@id":"http://example.com/channels/my-online-example-tv/sport-channel",
  "broadcastChannelId":"sport-channel",
  "channelOrder": 3,
  "broadcastServiceTier":"Premium",
  "inBroadcastLineup":{
    "@type":"CableOrSatelliteService",
    "@id":"http://example.com/providers/my-online-example-tv"
  },
  "providesBroadcastService":{
    "@type":"BroadcastService",
    "@id":"http://example.com/stations/sport-channel"
  }
}

Organization specification table

Property	Expected Type	Description
`@context`	Text	Required - Always set to `["http://schema.org", {"@language": "xx"}]` Where "xx" represents the language of the strings in the feed. Each root entity context should have it's @language set to the appropriate language code in BCP 47 format format. For example, if the language is set to Spanish, the names are assumed to be in Spanish even if the subtitle/dub language is in English.
`@type`	Text	Required - Always set to `Organization`.
`@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 In the form of Unified Resource Identifier (URI) 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 name of the TV network, TV content provider, or TV operator. Use an array to list the names in different languages. See the Multiple regions and languages example. Note that only one name is supported per locale (language-country pair).
`description`	Text	A description of the organization. 300-character limit. Use an array to provide the descriptions in multiple languages and/or in different lengths.
`sameAs`	URL	Highly Recommended Why? A URL to a Wikipedia page that can identify the TV network. This must be distinct from the url property. Only populate with Wikipedia page that talks about a single channel/network entity. Note that Wikipedia pages might use terminology "channel".
`potentialAction`	WatchAction	Required if applicable - This is required if you have multiple channels (BroadcastService) referring to the Organization. An Action markup object that provides the details of the action. See the Action markup properties for details. Use an array to specify different deep links in multiple regions. See the Multiple regions and languages example. It's optional to provide deep links if the channel switch is fulfilled by TV service provider.
`url`	URL	The URL of the organization. Google uses this URL to accurately reconcile this organization with the organization in Google's databases.
`identifier`	PropertyValue	Highly Recommended Why? - External or other ID that identifies this entity, such as a TMS ID for this organization. Multiple identifiers are allowed. See the Identifier properties section for details.
`popularityScore`	PopularityScoreSpecification	Highly Recommended Why? A score that Google uses, plus other signals, to determine which media to play for users. This score represents the popularity of the content in relation to other content in your catalog; therefore, the score's scale needs to be consistent across your feeds, among all the entities in your catalog. By default, an entity's popularity score is set to 0.
`popularityScore.@type`	Text	Always set to `PopularityScoreSpecification`.
`popularityScore.value`	Number	A non-negative numeric value that indicates the popularity of the entity; a higher score means higher popularity.
`popularityScore.eligibleRegion`	Country	Region(s) where this popularity score is applicable. If the popularity score is globally applicable, set to `EARTH`. By default, this property is set to `EARTH`. `Note:` Locale-specific popularity takes precedence over global (EARTH) popularity

Organization example

{
  "@context":["http://schema.org", {"@language": "en"}],
  "@type":"Organization",
  "@id":"http://example.com/networks/abcd-network",
  "name":"ABCD",
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "TMS_ID",
      "value": "12345"
    },
    {
      "@type": "PropertyValue",
      "propertyID": "_PARTNER_ID_",
      "value": "exampletv-12345"
    }
  ],
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://example.com/networkstream",
      "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": "2050-10-21T10:35:29Z",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "@id": "http://example.com/subscription",
        "name": "ABCD",
        "sameAs": "http://example.com/subscription",
      },
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        }
      ]
    }
  },
  "popularityScore": {
    "@type": "PopularityScoreSpecification",
    "value": 178,
    "eligibleRegion": [
      {
        "@type": "Country",
        "name": "US"
      }
    ]
  }
}

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