Content markup properties of movies

This section provides the details of the content markup properties for the Movie entity type.

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 Movie for movies.
@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.
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 movie.
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 Movie 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 A URL to a reference web page that can identify the movie; for example, the Wikipedia page of the movie. This must be distinct from the url property.
releasedEvent PublicationEvent Details about the original release of the movie.
  • You can use an array to represent multiple releases.
description Text A synopsis of the movie. Plot synopses are preferred to factual summaries. 300-character limit.
duration Duration Runtime of the movie in ISO 8601 format.
director Person The director(s) of the movie.
actor Person The cast member(s) of the movie.
image ImageObject Images related to the movie. 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 the Identifier properties section for details.
popularityScore PopularityScoreSpecification 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

Example

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "Movie",
  "@id": "http://www.example.com/my_favorite_movie",
  "url": "http://www.example.com/my_favorite_movie",
  "name": "My Favorite Movie",
  "potentialAction": {
    "@type": "WatchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "http://www.example.com/my_favorite_movie?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": "2018-07-21T10:35:29Z",
      "availabilityEnds": "2019-10-21T10:35:29Z",
      "eligibleRegion": [
        {
          "@type": "Country",
          "name": "US"
        },
        {
          "@type": "Country",
          "name": "CA"
        }
      ]
    }
  },
  "sameAs": "https://en.wikipedia.org/wiki/my_favorite_movie",
  "releasedEvent": {
    "@type": "PublicationEvent",
    "startDate": "2008-01-20",
    "location": {
      "@type": "Country",
      "name": "US"
    }
  },
  "popularityScore": {
    "@type": "PopularityScoreSpecification",
    "value": 78,
    "eligibleRegion": [
      {
        "@type": "Country",
        "name": "US"
      },
      {
        "@type": "Country",
        "name": "CA"
      }
    ]
  },
  "description": "This is my favorite movie.",
  "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":  "tt0123456"
    }
  ]
}

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