Content markup properties of TV shows

This section provides the details of the content markup properties for the TVSeries, TVEpisode, and TVSeason entity types.

Providing TVSeason as a full entity is optional. See the TVSeries, TVSeason, and TVEpisode relations section for details.

Specification table

TVSeries

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]
  • Replace xx with the entity's language code; for example, "en".
@type Text Required - Always set to TVSeries.
@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 for more details.
url URL Required - The content's canonical URL, which Google uses 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 show.
potentialAction WatchAction Required - An Action markup object that provides the details of the action. See the Action markup properties for details.
sameAs URL A URL to a reference web page that can identify the show; for example, the Wikipedia page of the show. This must be distinct from the url property.
releasedEvent PublicationEvent Details about the original release of the show.
  • You can use an array to represent multiple releases.
description Text A synopsis of the show. Plot synopses are preferred to factual summaries. 300-character limit.
actor Person The cast member(s) of the show.
image ImageObject Images related to the show. Must be a minimum of 140px wide by 210px tall, with a 2:3 aspect ratio. Provide highest-resolution available, PNG or JPG.
trailer.description Text The description of the trailer. See the Trailer example.
trailer.inLanguage Text The language of the trailer in BCP 47 format.
trailer.url URL A URL of a trailer hosted on YouTube uploaded by respective production studios or authorized sources.
trailer.regionsAllowed Place The regions where the media is allowed. If not specified, then it’s assumed to be allowed everywhere. Specify the countries in ISO 3166 format..
identifier PropertyValue External or other ID that unambiguously identifies this entity. Multiple identifiers are allowed. See Identifier Properties section for details.
popularityScore Number A number 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.

TVEpisode

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]
  • Replace xx with the entity's language code; for example, "en".
@type Text Required - Always set to TVEpisode.
@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 for more details.
url URL Required - The content's canonical URL, which Google uses 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 episode.
episodeNumber Integer Required - The number that indicates this episode's position in the order of episodes in a season. episodeNumber need to restart for each season; that is, the first episode of each season needs to be 1.
partOfSeason TVSeason Required - The TV season that this episode belongs to.

Even if a TVEpisode doesn't have a corresponding TVSeason, you still need to provide the partOfSeason.@id and partOfSeason.seasonNumber properties. A workaround is:
  • Take partofSeries.@id (for example, http://www.example.com/my_favorite_tv_show) and attach a dummy query field (for example, ?season1) to create a unique partOfSeason.@id (for example, http://www.example.com/my_favorite_tv_show?season1).
  • Set partOfSeason.seasonNumber to 1.
partOfSeason.@type Text Required - Always set to TVSeason.
partOfSeason.@id URL Required - The @id of the TVSeason that this episode is part of.
partOfSeason.seasonNumber Integer Required - The number that indicates this season's position in the order of seasons in the TV series.
partOfSeries TVSeries Required - The TV series that this episode belongs to.
partOfSeries.@type Text Required - Always set to TVSeries.
partOfSeries.@id URL Required - The @id of the TVSeries that this episode is part of.
partOfSeries.name Text Required - The name of the TV series.
partOfSeries.sameAs Text A URL to a reference web page that can identify the show; for example, the Wikipedia page of the show. This must be distinct from the url property.
potentialAction WatchAction Required - An Action markup object that provides the details of the action. See the Action markup properties for details.
sameAs URL A URL to a reference web page that can identify the episode; for exam ple, the Wikipedia page of the episode. This must be distinct from the url property.
releasedEvent PublicationEvent Details about the original release of the episode.
  • You can use an array to represent multiple releases.
description Text A synopsis of the episode. Plot synopses are preferred to factual summaries. 300-character limit.
actor Person The cast member(s) of the episode.
image ImageObject Images related to the episode. Must be a minimum of 140px wide by 210px tall, with a 2:3 aspect ratio. Provide highest-resolution available, PNG or JPG.
trailer.description Text The description of the trailer. See the Trailer example.
trailer.inLanguage Text The language of the trailer in BCP 47 format.
trailer.url URL A URL of a trailer hosted on YouTube uploaded by respective production studios or authorized sources.
trailer.regionsAllowed Place The regions where the media is allowed. If not specified, then it’s assumed to be allowed everywhere. Specify the countries in ISO 3166 format..
identifier PropertyValue External or other ID that unambiguously identifies this entity. Multiple identifiers are allowed. See Identifier Properties section for details.
popularityScore Number A number 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 entitiy; 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.

TVSeason

Property Expected Type Description
@context Text Required - Always set to ["http://schema.org", {"@language": "xx"}]
  • Replace xx with the entity's language code; for example, "en".
@type Text Required - Always set to TVSeason.
@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 for more details.
url URL Required - The content's canonical URL, which Google uses 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 this TV season.
seasonNumber Integer Required - The number that indicates this season's position in the order of seasons in the TV series.
partOfSeries TVSeries Required - The TV series that this season belongs to.
partOfSeries.@type Text Required - Always set to TVSeries.
partOfSeries.@id URL Required - The @id of the TVSeries that this season is part of.
partOfSeries.name Text Required - The name of the TV series.
partOfSeries.sameAs Text A URL to a reference web page that can identify the show; for example, the Wikipedia page of the show. This must be distinct from the url property.
potentialAction WatchAction Required - An Action markup object that provides the details of the action. See the Action markup properties for details.
sameAs URL A URL to a reference web page that can identify the season; for example, the Wikipedia page of the season. This must be distinct from the url property.
releasedEvent PublicationEvent Details about the original release of the season.
  • You can use an array to represent multiple releases.
description Text A synopsis of the season. Plot synopses are preferred to factual summaries. 300-character limit.
actor Person The cast member(s) of the season.
image ImageObject Images related to the season. Must be a minimum of 140px wide by 210px tall, with a 2:3 aspect ratio. Provide highest-resolution available, PNG or JPG.
trailer.description Text The description of the trailer. See the Trailer example.
trailer.inLanguage Text The language of the trailer in BCP 47 format.
trailer.url URL A URL of a trailer hosted on YouTube uploaded by respective production studios or authorized sources.
trailer.regionsAllowed Place The regions where the media is allowed. If not specified, then it’s assumed to be allowed everywhere. Specify the countries in ISO 3166 format..
identifier PropertyValue External or other ID that unambiguously identifies this entity. Multiple identifiers are allowed. See Identifier Properties section for details.

Examples

Examples of TVSeries, TVEpisode, and TVSeason.

TVSeries

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "TVSeries",
  "@id": "http://www.example.com/my_favorite_tv_show/",
  "url": "http://www.example.com/my_favorite_tv_show/",
  "name": "My Favorite TV Show",
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/my_favorite_tv_show/watch?autoplay=true",
      "inLanguage": "en",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
       "requiresSubscription": {
         "@type": "MediaSubscription",
         "@id": "http://www.example.com/premium_subscription",
         "name": "Example Premium",
         "sameAs": "http://www.example.com/premium_subscription"
       },
       "eligibleRegion": [
         {
            "@type": "Country",
            "name": "US"
         },
         {
            "@type": "Country",
            "name": "CA"
         }
       ]
    }
  },
  "sameAs": "https://en.wikipedia.org/wiki/my_favorite_tv_show",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2008-01-20",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "popularityScore": {
    "@type": "PopularityScoreSpecification",
    "value": 4.1,
    "eligibleRegion": [
      {
        "@type": "Country",
        "name": "US"
      },
      {
        "@type": "Country",
        "name": "CA"
      }
    ]
  },
  "description": "This is my favorite TV show.",
  "actor": [
    {
      "@type": "Person",
      "name": "John Doe",
      "sameAs": "https://en.wikipedia.org/wiki/john_doe"
    },
    {
      "@type": "Person",
      "name": "Jane Doe",
      "sameAs": "https://en.wikipedia.org/wiki/jane_doe"
    }
  ],
  "identifier": [
     {
       "@type": "PropertyValue",
       "propertyID": "IMDB_ID",
       "value":  "tt0903747"
     }
   ]
}

TVEpisode

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "TVEpisode",
  "@id": "http://www.example.com/my_favorite_tv_show/s7/e14",
  "url": "http://www.example.com/my_favorite_tv_show/s7/e14",
  "name": "John Doe returns with a horse.",
  "episodeNumber": 14,
  "partOfSeason": {
    "@type": "TVSeason",
    "@id": "http://www.example.com/my_favorite_tv_show/s7",
    "seasonNumber": 7
  },
  "partOfSeries": {
    "@type": "TVSeries",
    "@id": "http://www.example.com/my_favorite_tv_show",
    "name": "My Favorite TV Show",
    "sameAs": "https://en.wikipedia.org/wiki/my_favorite_tv_show"
  },
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/my_favorite_tv_show/s7/e14?autoplay=true",
      "inLanguage": "en",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
       "requiresSubscription": {
         "@type": "MediaSubscription",
         "@id": "http://www.example.com/premium_subscription",
         "name": "Example Premium",
         "sameAs": "http://www.example.com/premium_subscription"
       },
       "eligibleRegion": [
         {
            "@type": "Country",
            "name": "US"
         },
         {
            "@type": "Country",
            "name": "CA"
         }
       ]
    }
  },
  "sameAs": "https://en.wikipedia.org/wiki/john_doe_returns_with_a_horse",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2014-01-09",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "popularityScore": {
    "@type": "PopularityScoreSpecification",
    "value": 3.9,
    "eligibleRegion": "EARTH"
  },
  "description": "John Doe returns to the village three years after his disappearance.",
  "actor": [
    {
      "@type": "Person",
      "name": "John Doe",
      "sameAs": "https://en.wikipedia.org/wiki/john_doe"
    },
    {
      "@type": "Person",
      "name": "Jane Doe",
      "sameAs": "https://en.wikipedia.org/wiki/jane_doe"
    }
  ],
  "identifier": {
     "@type": "PropertyValue",
     "propertyID": "IMDB_ID",
     "value":  "tt3453320"
   }
}

TVSeason

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "TVSeason",
  "@id": "http://www.example.com/my_favorite_tv_show/s7",
  "url": "http://www.example.com/my_favorite_tv_show/s7",
  "name": "Season 7",
  "seasonNumber": 7,
  "partOfSeries": {
    "@type": "TVSeries",
    "@id": "http://www.example.com/my_favorite_tv_show",
    "name": "My Favorite TV Show",
    "sameAs": "https://en.wikipedia.org/wiki/my_favorite_tv_show"
  },
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/my_favorite_tv_show/s7/watch?autoplay=true",
      "inLanguage": "en",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/MobileWebPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.org/AndroidPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
       "requiresSubscription": {
         "@type": "MediaSubscription",
         "@id": "http://www.example.com/premium_subscription",
         "name": "Example Premium",
         "sameAs": "http://www.example.com/premium_subscription"
      },
      "eligibleRegion": [
       {
          "@type": "Country",
          "name": "US"
       },
       {
          "@type": "Country",
          "name": "CA"
       }
      ]
     }
  },
  "sameAs": "https://en.wikipedia.org/wiki/my_favorite_tv_show_(season_7)",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2010-09-23",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "description": "The seventh season of My Favorite TV Show.",
  "actor": [
    {
      "@type": "Person",
      "name": "John Doe",
      "sameAs": "https://en.wikipedia.org/wiki/john_doe"
    },
    {
      "@type": "Person",
      "name": "Jane Doe",
      "sameAs": "https://en.wikipedia.org/wiki/jane_doe"
    }
  ]
}

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