What Is Movie Schema? The Complete Guide (2026)

Single Movie Page vs Movie Listing Page

Greadme validates two Movie schema patterns, each with a different structure:

Required Properties

Recommended Properties

aggregateRating Rules

aggregateRating is what makes your star rating appear next to the movie title in search. The rules Greadme enforces:

• ratingValue is required — an error if missing.
• At least one of ratingCount (number of ratings) or reviewCount (number of written reviews) is required — an error if both are missing.
• Use a dot as the decimal separator: 4.4, not 4,4 — Greadme warns on comma-separated decimals.
• bestRating defaults to 5 and worstRating defaults to 1 if not specified. Set them explicitly if your rating scale is different (e.g., a 10-point scale).

Review Object Rules

Each Review object inside the review array has strict field requirements:

ItemList for Movie Carousels

To make a listing page (e.g., "Best Horror Films of 2026") eligible for Google's movie carousel, wrap each movie in an ItemList structure. Google requires at least 2 movies for a carousel to appear.

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "Movie",
        "name": "Dune: Part Three",
        "url": "https://example.com/movies/dune-part-three",
        "image": "https://example.com/img/dune-3.jpg",
        "dateCreated": "2026-11-20",
        "director": { "@type": "Person", "name": "Denis Villeneuve" },
        "aggregateRating": {
          "@type": "AggregateRating",
          "ratingValue": 4.7,
          "ratingCount": 8420
        }
      }
    },
    {
      "@type": "ListItem",
      "position": 2,
      "item": {
        "@type": "Movie",
        "name": "The Midnight Atlas",
        "url": "https://example.com/movies/midnight-atlas",
        "image": "https://example.com/img/midnight-atlas.jpg",
        "dateCreated": "2026-09-05",
        "director": { "@type": "Person", "name": "Ava DuVernay" },
        "aggregateRating": {
          "@type": "AggregateRating",
          "ratingValue": 4.2,
          "ratingCount": 3150
        }
      }
    }
  ]
}

Key rules for the ItemList structure:

• Each ListItem must have a position (integer, starting from 1). Greadme errors if missing or non-numeric.
• Each ListItem.item.url must be unique. Greadme errors on duplicate URLs.
• Positions should be sequential (1, 2, 3…). Greadme warns if a position doesn't match its array index.
• Google recommends at least 2 movies for carousel eligibility. Greadme warns for single-item lists.

Single Movie Review Page Example

{
  "@context": "https://schema.org",
  "@type": "Movie",
  "name": "Dune: Part Three",
  "image": "https://example.com/img/dune-3-poster.jpg",
  "dateCreated": "2026-11-20",
  "director": { "@type": "Person", "name": "Denis Villeneuve" },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": 4.7,
    "bestRating": 5,
    "worstRating": 1,
    "ratingCount": 8420
  },
  "review": {
    "@type": "Review",
    "author": { "@type": "Person", "name": "Sarah Miller" },
    "datePublished": "2026-11-21",
    "reviewBody": "A stunning conclusion to the trilogy.",
    "reviewRating": {
      "@type": "Rating",
      "ratingValue": 5,
      "bestRating": 5
    }
  }
}

5 Common Movie Schema Mistakes

1. Using VideoObject Instead of Movie

Movie schema and VideoObject schema are not interchangeable. Use Movie for review and listing pages about a film as a creative work. Use VideoObject for pages that embed a playable video file. A movie review page should use Movie, not VideoObject.

2. Using a Comma in ratingValue

"ratingValue": "4,7" is invalid. Greadme warns on comma decimal separators. Always use a dot: "ratingValue": 4.7 or "ratingValue": "4.7".

3. Missing ratingCount and reviewCount

aggregateRating requires at least one of ratingCount or reviewCount. A ratingValue alone is not enough — without a count, Google cannot verify the rating is based on real feedback. Greadme errors if both are absent.

4. Author Name Over 100 Characters or Containing Promotional Text

Review author names must be under 100 characters, and must not contain promotional language (characters like % or terms like discount). Greadme errors on both conditions. Use a real person or organization name.

5. Duplicate URLs in ItemList

Every movie in an ItemList carousel must point to a unique URL. Greadme errors on duplicate ListItem.item.url values. If two pages cover the same film, only one can appear in a single carousel.

How to Validate Your Movie Schema

Paste your movie page or listing page URL into Greadme to validate your Movie schema. Greadme automatically detects whether you're using a single Movie or a carousel ItemList and applies the appropriate rules for each. It validates image URLs, rating value format, review author constraints, ItemList position sequencing, and duplicate URL detection.