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"}]
  • 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 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
  • 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 - 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.
  • 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).
titleEIDR Text Highly Recommended Why? - An EIDR (Entertainment Identifier Registry) identifier representing at the most general/abstract level, a work of film or television.

For example, titleEIDR for the TVSeries known as "Game of Thrones" is "10.5240/C1B5-3BA1-8991-A571-8472-W".
potentialAction WatchAction Required if applicable - An Action markup object that provides the details of the action.
  • If the content is available on Video on Demand (VoD), this property is required; the Action markup object needs to provide the deep link of the content.
  • If the content is available on a LiveTV channel, this property is optional; the associated BroadcastService entity provides the deep link of the channel instead.
  • A TVSeries can be available on both VoD and LiveTV.
Use an array to specify different deep links in multiple regions. See the Multiple regions and languages example.
sameAs URL Highly Recommended Why? 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.
inLanguage Text Original language of the series in BCP 47 format.
genre Text An ordered list of all relevant genres. For example : ["Action", "Fashion", "Environment", "Football"]
keywords Text Keywords or tags used to describe this content. An array of keywords is also allowed. For example, ["feature, biography"] can be an array of keywords to describe the content.
releasedEvent PublicationEvent, FeaturedEvent, or ExclusiveEvent Highly Recommended Why? - A PublicationEvent is used to specify the original (global or local) release of content by a publisher, such as the original theatrical release date of a movie.

Additionally, use FeaturedEvent to indicate that your service markets this content as either an original, featured, special, and so forth.

ExclusiveEvent specifies that your service has exclusive distribution rights and include where and when.

See the example section for details and examples.
releasedEvent.@type Text Required - Be sure to always set this property to one of the following:
  • PublicationEvent
  • ExclusiveEvent
  • FeaturedEvent
releasedEvent.location Country Required - The regions that are associated with this event.

For a PublicationEvent, this is the region where the content was published.

For FeaturedEvent and ExclusiveEvent, this is the region where the content is featured or exclusive.

Use ISO 3166 codes for countries. To indicate everywhere in the world, set to EARTH.
releasedEvent.startDate Date or DateTime Recommended - Required for ExclusiveEvent - The start date of the entity's publication.

For a PublicationEvent, this denotes the initial release date of this entity, such as the date a movie was first released in theaters.

For ExclusiveEvent and FeaturedEvent, this represents the start date of when the entity is exclusive or featured.
releasedEvent.endDate Date or DateTime Recommended - Required for ExclusiveEvent - This is only applicable to the ExclusiveEvent and FeaturedEvent types.

For ExclusiveEvent, this represents the date when the rights to the content expire.

For FeaturedEvent, this represents the last date when the provider features the entity.

If the content is perpetually exclusive or featured, set the endDate to 20 years from the current date.
releasedEvent.publishedBy Organization or Person Optional - The organization or person that published this entity.
description Text Highly Recommended Why? A synopsis of the show. Plot synopses are preferred to factual summaries. 300-character limit.
actor Person or PerformingGroup or PerformanceRole Highly Recommended Why? An array of the cast members of the series. See modeling guidance here.
director Person Highly Recommended Why? The director(s) of the show.
producer Organization or Person Highly Recommended Why? The producer(s) of the show.
image ImageObject Required for Google TV - The images related to the TVSeries. For more details on the required and optional properties to include with image, see Image properties.
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 publicly and 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 Highly Recommended Why? - External or other ID that unambiguously identifies this entity. 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
review Review Review ratings for the TV series
review.reviewRating Rating Required if review is provided This is used to specify the rating given in the review.
contentRating Text or Rating Required for adult content, highly recommended otherwise - Overall content rating. 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 "TV-MA" rating from agency "TVPG" in the U.S. should be described as "TVPG TV-MA". See the list of agencies.
  • A value of "RATING NOT KNOWN" (case insensitive) to indicate you don't know the rating for the content.
contentRating.author Text or Organization Required if contentRating uses Rating - The name of the rating agency. See the Content Rating Agencies page for a list of accepted rating agencies
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.

TVEpisode

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 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
  • 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 - 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.
  • Use an array to list the names in different languages. See the Multiple language representation example.
  • Note that only one name is supported per locale (language-country pair).
titleEIDR Text Highly Recommended Why? - An EIDR (Entertainment Identifier Registry) identifier representing at the most general/abstract level, a work of film or television.

For example, titleEIDR for the first episode of the first season of TVSeries known as "Game of Thrones" is "10.5240/B6A6-1B32-B5E5-D5CB-6B84-X".
editEIDR Text Highly Recommended Why? - An EIDR (Entertainment Identifier Registry) identifier representing a specific edit / edition for a work of film or television.

For example, the first episode of the first season of TVSeries known as "Game of Thrones", whose titleEIDR is "10.5240/B6A6-1B32-B5E5-D5CB-6B84-X", has one edit e.g. "10.5240/FB97-C847-2969-D0AB-ECD1-C".

titleEIDR property is required when editEIDR is provided.
inLanguage Text Original language of the series in BCP 47 format.
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 placeholder 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 if applicable - An Action markup object that provides the details of the action.
  • If the content is available on Video on Demand (VoD), this property is required; the Action markup object needs to provide the deep link of the content.
  • If the content is available on a LiveTV channel, this property is optional; the associated BroadcastService entity provides the deep link of the channel instead.
  • A TVEpisode can be available on both VoD and LiveTV.
Use an array to specify different deep links in multiple regions. See the Multiple regions and languages example.
sameAs Highly Recommended Why? 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.
duration Duration Runtime of the episode in ISO 8601 format. Please use the format: "PT00H00M".
releasedEvent PublicationEvent, FeaturedEvent, or ExclusiveEvent Highly Recommended Why? - A PublicationEvent is used to specify the original (global or local) release of content by a publisher, such as the original theatrical release date of a movie.

Additionally, use FeaturedEvent to indicate that your service markets this content as either an original, featured, special, and so forth.

ExclusiveEvent specifies that your service has exclusive distribution rights and include where and when.

See the example section for details and examples.
releasedEvent.@type Text Required - Be sure to always set this property to one of the following:
  • PublicationEvent
  • ExclusiveEvent
  • FeaturedEvent
releasedEvent.location Country Required - The regions that are associated with this event.

For a PublicationEvent, this is the region where the content was published.

For FeaturedEvent and ExclusiveEvent, this is the region where the content is featured or exclusive.

Use ISO 3166 codes for countries. To indicate everywhere in the world, set to EARTH.
releasedEvent.startDate Date or DateTime Recommended - Required for ExclusiveEvent - The start date of the entity's publication.

For a PublicationEvent, this denotes the initial release date of this entity, such as the date a movie was first released in theaters.

For ExclusiveEvent and FeaturedEvent, this represents the start date of when the entity is exclusive or featured.
releasedEvent.endDate Date or DateTime Recommended - Required for ExclusiveEvent - This is only applicable to the ExclusiveEvent and FeaturedEvent types.

For ExclusiveEvent, this represents the date when the rights to the content expire.

For FeaturedEvent, this represents the last date when the provider features the entity.

If the content is perpetually exclusive or featured, set the endDate to 20 years from the current date.
releasedEvent.publishedBy Organization or Person Optional - The organization or person that published this entity.
description Text Highly Recommended Why? A synopsis of the episode. Plot synopses are preferred to factual summaries. 300-character limit.
genre Text An ordered list of all relevant genres. For example : ["Action", "Fashion", "Environment", "Football"]
keywords Text Keywords or tags used to describe this content. An array of keywords is also allowed. For example, ["feature, biography"] can be an array of keywords to describe the content.
actor Person or PerformingGroup or PerformanceRole Highly Recommended Why? An array of the cast members of the episode. See modeling guidance here.
director Person Highly Recommended Why? The director(s) of the episode.
producer Organization or Person Highly Recommended Why? The producer(s) of the season.
image ImageObject Highly Recommended Why? for Google TV - Various images related to the TVEpisode. For more details on the required and optional properties to include with image, see Image properties.
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 publicly and 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.
review Review Review ratings for the TV episode
review.reviewRating Rating Required if review is provided This is used to specify the rating given in the review.
contentRating Text or Rating Required for adult content, highly recommended otherwise - Overall content rating. 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 "TV-MA" rating from agency "TVPG" in the U.S. should be described as "TVPG TV-MA". See the list of agencies.
  • A value of "RATING NOT KNOWN" (case insensitive) to indicate you don't know the rating for the content.
contentRating.author Text or Organization Required if contentRating uses Rating - The name of the rating agency. See the Content Rating Agencies page for a list of accepted rating agencies
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.
identifier PropertyValue Highly Recommended Why? - External or other ID that unambiguously identifies this entity. 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

TVSeason

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 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
  • 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 - 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.
  • Use an array to list the names in different languages. See the Multiple language representation example.
  • Note that only one name is supported per locale (language-country pair).
titleEIDR Text Highly Recommended Why? - An EIDR (Entertainment Identifier Registry) identifier representing at the most general/abstract level, a work of film or television.

For example, titleEIDR for the first season of TVSeries known as "Game of Thrones" is "10.5240/FD91-C72C-4161-FCBA-058B-1".
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 if applicable - An Action markup object that provides the details of the action.
  • If the content is available on Video on Demand (VoD), this property is required; the Action markup object needs to provide the deep link of the content.
  • If the content is available on a LiveTV channel, this property is optional; the associated BroadcastService entity provides the deep link of the channel instead.
  • A TVSeason can be available on both VoD and LiveTV.
Use an array to specify different deep links in multiple regions. See the Multiple regions and languages example.
sameAs URL Highly Recommended Why? 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, FeaturedEvent, or ExclusiveEvent Highly Recommended Why? - A PublicationEvent is used to specify the original (global or local) release of content by a publisher, such as the original theatrical release date of a movie.

Additionally, use FeaturedEvent to indicate that your service markets this content as either an original, featured, special, and so forth.

ExclusiveEvent specifies that your service has exclusive distribution rights and includes where and when.

See the example section for details and examples.
releasedEvent.@type Text Required - Be sure to always set this property to one of the following:
  • PublicationEvent
  • ExclusiveEvent
  • FeaturedEvent
releasedEvent.location Country Required - The regions that are associated with this event.

For a PublicationEvent, this is the region where the content was published.

For FeaturedEvent and ExclusiveEvent, this is the region where the content is featured or exclusive.

Use ISO 3166 codes for countries. To indicate everywhere in the world, set to EARTH.
releasedEvent.startDate Date or DateTime Recommended - Required for ExclusiveEvent - The start date of the entity's publication.

For a PublicationEvent, this denotes the initial release date of this entity, such as the date a movie was first released in theaters.

For ExclusiveEvent and FeaturedEvent, this represents the start date of when the entity is exclusive or featured.
releasedEvent.endDate Date or DateTime Recommended - Required for ExclusiveEvent - This is only applicable to the ExclusiveEvent and FeaturedEvent types.

For ExclusiveEvent, this represents the date when the rights to the content expire.

For FeaturedEvent, this represents the last date when the provider features the entity.

If the content is perpetually exclusive or featured, set the endDate to 20 years from the current date.
releasedEvent.publishedBy Organization or Person Optional - The organization or person that published this entity.
description Text Highly Recommended Why? A synopsis of the season. Plot synopses are preferred to factual summaries. 300-character limit.
actor [Person or PerformingGroup or PerformanceRole Highly Recommended Why? An array of the cast members of the season. See modeling guidance here.
director Person Highly Recommended Why? An array of the directors of the show.
producer Organization or Person Highly Recommended Why? The producer(s) of the season.
image ImageObject The images related to the TVSeason. For more details on the required and optional properties to include with image, see Image properties.
genre Text An ordered list of all relevant genres. For example : ["Action", "Fashion", "Environment", "Football"]
keywords Text Keywords or tags used to describe this content. An array of keywords is also allowed. For example, ["feature, biography"] can be an array of keywords to describe the content.
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 publicly and 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 Highly Recommended Why? - External or other ID that unambiguously identifies this entity. 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
review Review Review ratings for the TV season
review.reviewRating Rating Required if review is provided This is used to specify the rating given in the review.
contentRating Text or Rating Required for adult content, highly recommended otherwise - Overall content rating. 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 "TV-MA" rating from agency "TVPG" in the U.S. should be described as "TVPG TV-MA". See the list of agencies.
  • A value of "RATING NOT KNOWN" (case insensitive) to indicate you don't know the rating for the content.
contentRating.author Text or Organization Required if contentRating uses Rating - The name of the rating agency. See the Content Rating Agencies page for a list of accepted rating agencies
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.

Actor specifications

The actor property in the TVSeries, TVEpisode and TVSeason entity types allows you to specify more details about the actors, including the name of their characters and the roles they play in the TV show. The following section(s) capture the same, along with a few examples clarifying the usage.

Property Expected Type Description
actor Person or PerformingGroup or PerformanceRole Highly Recommended Why? : An array of the cast members.
  • Use the type PerformanceRole when the role played and (optionally) the character name of the cast member(s) is known. The actor Person or PerformingGroup is embedded inside the PerformanceRole object in this case.
  • Use the type Person to indicate the indivual actor(s) or PerformingGroup to provide details of the performing group(s)/band(s) when the role(s) played by the cast member(s) are unknown.

Use an array to represent multiple Persons, PerformingGroups, or PerformanceRoles.

Using the Person or PerformingGroup types

Provide the following properties when the Person or PerformingGroup type is used

Property Expected Type Description
@type Person or PerformingGroup Required - Always set to Person or PerformingGroup
@id URL Highly Recommended Why? - The actors or performing group identifier in URI format; for example, https://example.com/actor/abc. @id must meet the following requirements:
  • Globally unique across your catalog per actor/performing group
  • 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)
  • Your organization must own the domain used for the @id value.

Note that the @id used in the actor property should be consistently used throughout the feed. For example, if there are two Movies featuring the same actor, then the @id value should be kept the same across these two actor objects.

name Text Required - The name of the actor/actress/cast member/performing group.
sameAs URL Highly Recommended Why? - A URL to a reference web page that can identify the actor or the performing group; for example, the Wikipedia page of the actor. This must be distinct from the @id property.

Using the PerformanceRole type

Provide the following properties when the PerformanceRole type is used

Property Expected Type Description
@type PerformanceRole Required - Always set to PerformanceRole
roleName Text Highly Recommended Why? - A role played, performed or filled by the cast member. Please see the list of acceptable values here.
characterName Text The name of a character played in some acting or performing role. Do not set this field if the actor type is PerformingGroup.
actor Person or PerformingGroup Required -
  • The cast member(s) of the content when the data type Person is used.
  • The performing group(s)/band(s) of the content when the data type PerformingGroup is used.
actor.@type Person or PerformingGroup Required - Always set to Person or PerformingGroup
actor.@id URL Highly Recommended Why? - The actor or performing group identifier in URI format; for example, https://example.com/actor/abc. @id must meet the following requirements:
  • Globally unique across your catalog per actor/performing group
  • 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)
  • Your organization must own the domain used for the @id value.

Note that the @id used in the actor property should be consistently used throughout the feed. For example, if there are two Movies featuring the same actor, then the @id value should be kept the same across these two actor objects.

actor.name Text Required - The name of the actor/actress/cast member/performing group.
actor.sameAs URL Highly Recommended Why? - A URL to a reference web page that can identify the actor or the performing group; for example, the Wikipedia page of the actor. This must be distinct from the actor.@id property.

Acceptable role names

These values require the actor.@type to be Person.

roleName value Description
“Cameo” A cameo role, also called a cameo appearance is a brief appearance of a well-known person in a work of the performing arts.
"VoiceActor" A voice performance is one in which the actor's voice is used but the actor does not appear on-screen. This is most commonly found in animation, but also occurs when an actor's voice is dubbed in over another actor's speech.
"Double" A double is a person who substitutes for another actor such that the person's face is not shown.
"MotionCaptureActor" A MotionCaptureActor refers to a person recording actions of human actors, and using that information to animate digital character models in 2D or 3D computer animation.

These values are generally accepted for Person and PerformingGroup types.

roleName value Description
"Actor" An actor or actress is a person who portrays a character in a performance in the traditional medium of the theater or in modern media such as film, radio, and television.
"GuestStar" "A guest star is an actor who plays a fictional role and appears in one or a few episodes. In some cases a guest star may play an important recurring character and may appear many times in a series, despite not being a member of the main cast. Set value to "GuestStar" when the cast has a guest performance or is a guest on the show. Guest stars should only be provided at the episode level, and should not be added at the TVSeries level.
"Guest" "A guest on a talk show. Note that while "GuestStar" is a fictional role, "Guest" is a non fictional appearance.
"Announcer" An announcer is a person who delivers opening and closing spiels for the show, introduces the host, contestants and/or celebrity guests, describes the prizes available, and warms up the audience before taping and keeps them entertained during breaks.
"Commentator" A commentator provides a real-time commentary of a game or event, usually during a live broadcast.
"Impressionist" An impressionist or a mimic is a performer whose act consists of imitating sounds, voices and mannerisms of celebrities and cartoon characters.
"Host" A person who introduces, presents or hosts television programs, often serving as a mediator for the program and the audience. The "Host" is generally a non-fiction role.
"CoHost" A person who hosts an event/program jointly with another person(s).
"GuestHost" A guest host is a host, usually of a talk show, that hosts the program in lieu of the regular host when not available.
"Newscaster" A person who presents/informs the public about news and events happening on a local, national, and international scale through a TV news program.
"Correspondent" A correspondent or on-the-scene reporter is usually a journalist or commentator for a magazine, or an agent who contributes reports to a newspaper, or radio or television news, or another type of company, from a remote, often distant, location.
"ShowJudge" A judge is a person who is often considered an expert in the field of the show and is given the role of "judge" to critique contestants that audition for and enter the competition of the TV series.
"Panelist" A member of a discussion or advisory panel of a radio or television panel.
"Contestant" A contestant in a competition or game show is a person who takes part in it.
"StoryNarrator" Narrator is a person who narrates something, especially a character who recounts the events of a novel or narrative poem
"MusicalArtist" "A Musical artist can be a person or a group or a fictional character that have typically performed in front of an audience on a regular basis or have recorded musical tracks or musical albums. Composers and lyricists should only have this type if the credits of some musical work imply they also contribute as main performer. This type can be used to associate permanent Musicians or Musician Groups, and guest Musicians or Musician Groups to shows.

Differentiating between a main and supporting role of an actor

To differentiate between the main/regular and guest/supporting actors in a TV show, add the main cast on TVSeries entities only and add only the guest cast or cast with supporting roles on the TVEpisode entities. Make sure the main/regular cast is not added to the TVEpisode entities.

Examples

TVSeries, TVEpisode, and TVSeason example

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/AndroidTVPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "requiresSubscription": {
          "@type": "MediaSubscription",
          "name": "Example Package",
          "commonTier": true,
          "@id": "https://example.com/package/example"
       },
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
       "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.",
  "contentRating": "RATING NOT KNOWN",
  "actor": [
    {
      "@type": "Person",
      "@id": "http://www.example.com/actor/john_doe",
      "name": "John Doe",
      "sameAs": "https://en.wikipedia.org/wiki/john_doe"
    },
    {
      "@type": "Person",
      "@id": "http://www.example.com/actor/jane_doe",
      "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,
  "contentRating": "TVPG TV-MA",
  "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.org/AndroidTVPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "requiresSubscription": {
          "@type": "MediaSubscription",
          "name": "Example Package",
          "commonTier": true,
          "@id": "https://example.com/package/example"
        },
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
       "eligibleRegion": [
         {
            "@type": "Country",
            "name": "US"
         },
         {
            "@type": "Country",
            "name": "CA"
         }
       ]
    }
  },
  "sameAs": "https://en.wikipedia.org/wiki/john_doe_returns_with_a_horse",
  "duration": "PT00H25M",
  "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",
      "@id": "http://www.example.com/actor/john_doe",
      "name": "John Doe",
      "sameAs": "https://en.wikipedia.org/wiki/john_doe"
    },
    {
      "@type": "Person",
      "@id": "http://www.example.com/actor/jane_doe",
      "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.org/AndroidTVPlatform",
        "http://schema.googleapis.com/GoogleVideoCast"
      ]
    },
     "actionAccessibilityRequirement": {
       "@type": "ActionAccessSpecification",
       "category": "subscription",
       "requiresSubscription": {
          "@type": "MediaSubscription",
          "name": "Example Package",
          "commonTier": true,
          "@id": "https://example.com/package/example"
        },
       "availabilityStarts": "2017-07-21T10:35:29Z",
       "availabilityEnds": "2018-10-21T10:35:29Z",
      "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",
      "@id": "http://www.example.com/actor/john_doe",
      "name": "John Doe",
      "sameAs": "https://en.wikipedia.org/wiki/john_doe"
    },
    {
      "@type": "Person",
      "@id": "http://www.example.com/actor/jane_doe",
      "name": "Jane Doe",
      "sameAs": "https://en.wikipedia.org/wiki/jane_doe"
    }
  ]
}

Actor property examples

Role of actor is unknown

When the role of an actor is unknown, our recommendation is to just provide the actor information using either the Person or PerformingGroup type

"actor": [
    {
      "@type": "Person",
      "@id": "https://example.com/actor/john_doe",
      "name": "John Doe",
      "sameAs": "https://en.wikipedia.org/wiki/john_doe"
    },
    {
      "@type": "PerformingGroup",
      "@id": "https://example.com/artists/ramones",
      "name": "Ramones",
      "sameAs": "https://en.wikipedia.org/wiki/Ramones"
    }
  ]

Role of actor is known

When the role of an actor is known, our recommendation is to provide the actor information using the PerformanceRole type

"actor": [
  {
      "@type": "PerformanceRole",
      "roleName": "GuestStar",
      "characterName": "Dr. Peter Venkman",
      "actor": {
        "@type": "Person",
        "@id": "https://example.com/actor/john_doe",
        "name": "John Doe",
        "sameAs": "https://en.wikipedia.org/wiki/john_doe"
      }
  },
  {
      "@type": "PerformanceRole",
      "roleName": "Host",
      "actor": {
        "@type": "Person",
        "@id": "https://example.com/actor/jane_doe",
        "name": "Jane Doe",
        "sameAs": "https://en.wikipedia.org/wiki/jane_doe"
      }
  }
]

Known roles for subset of actors

When performance role metadata is not known, our recommendation is to provide the actor information using either the Person or PerformingGroup type. For the other case where this info is known use the PerformanceRole type. These types can be added in the same array together.

"actor": [
  {
      "@type": "PerformanceRole",
      "roleName": "Host",
      "actor": {
        "@type": "Person",
        "@id": "https://example.com/actor/john_doe",
        "name": "John Doe",
        "sameAs": "https://en.wikipedia.org/wiki/john_doe"
      }
  },
  {
      "@type": "Person",
      "@id": "https://example.com/actor/jane_doe",
      "name": "Jane Doe",
      "sameAs": "https://en.wikipedia.org/wiki/jane_doe"
  },
  {
      "@type": "PerformingGroup",
      "@id": "https://example.com/artists/ramones",
      "name": "Ramones",
      "sameAs": "https://en.wikipedia.org/wiki/Ramones"
  }
]

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