Movie schema and the mobile movie carousel

JSON-LD example

Copy this into a <script type="application/ld+json"> tag and replace the values with your own.

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "Movie",
        "name": "The Lighthouse Keeper's Daughter",
        "url": "https://example.com/lists/best-rainy-day-films/#lighthouse-keepers-daughter",
        "image": "https://example.com/wp-content/uploads/posters/lighthouse-keepers-daughter-600x900.jpg",
        "dateCreated": "2019-10-11",
        "director": {
          "@type": "Person",
          "name": "Imogen Farrow"
        }
      }
    },
    {
      "@type": "ListItem",
      "position": 2,
      "item": {
        "@type": "Movie",
        "name": "Small Hours",
        "url": "https://example.com/lists/best-rainy-day-films/#small-hours",
        "image": "https://example.com/wp-content/uploads/posters/small-hours-600x900.jpg",
        "dateCreated": "2023-02-24",
        "director": {
          "@type": "Person",
          "name": "Tomasz Wren"
        }
      }
    }
  ]
}

Properties

The carousel needs a list

A single film page with Movie markup won't produce the carousel. Google builds it from carousel markup, meaning an ItemList of at least two films, using either layout:

• All-in-one page: a post such as "The best rainy-day films" that covers every film on one page. Each ListItem holds the full Movie object, and its url points to an anchor on that page. The example uses this layout.
• Summary page: a list that links to a separate page per film. ListItems hold only position and url, and each film page carries its own Movie markup.

All items must be films. A list that mixes films and TV series doesn't meet the same-type rule.

Poster images at 6:9

Six by nine reduces to 2:3, a portrait shape: 600 by 900 pixels, or 1000 by 1500. Google can crop images that are close to that shape, but anything far off, such as the 16:9 landscape still most themes use for featured images, isn't eligible.

On WordPress, register a poster size so every upload also gets a correctly shaped crop:

add_action( 'after_setup_theme', function () {
    add_image_size( 'movie-poster', 600, 900, true ); // Hard crop to 2:3.
} );

Existing uploads need their thumbnails regenerated before the new size exists for them. Use that size's URL in image, and check that your uploads folder isn't blocked in robots.txt.

Ratings on film review sites

aggregateRating and review follow Google's review snippet rules. An average must come from ratings users gave on your page. A critic's single review can go in review with your writer as author. Scores from other review aggregators don't belong in your markup, even if you display them.

For a page that reviews one film rather than listing several, the carousel isn't in play. Use review snippet markup with the Movie as the reviewed item, which is a separate feature with its own requirements.

Generating film lists in WordPress

Film lists are usually ordinary posts, so the markup has to come from somewhere structured: a custom field per film, or a block that stores title, director, release date and poster ID. Build the ItemList from that data with Hydrogen SEO's hydrogen_seo_schemas filter, which lets you append one block per list post, and keep the order identical to the page.

When a list is updated, say moving a film from fourth to first, the positions must change too. Generating the markup from the same data that renders the list is the simplest way to guarantee that. Test the finished post with the JSON-LD checker, then check it in the Rich Results Test on a mobile view.