What Is ItemList Schema? The Complete Guide (2026)

When to Use ItemList Schema

ItemList schema is used on "summary pages" — pages that aggregate and link to multiple individual item pages. The individual item pages must each contain their own schema markup (Recipe, Course, Movie, or Restaurant) for the carousel to be fully eligible.

Common use cases:

• A recipe index page linking to individual recipe pages
• A course catalog page listing each course with its own page
• A movie review index linking to individual film review pages
• A restaurant guide linking to individual restaurant pages
• "Best of" and "Top 10" articles where each item has its own dedicated page

ItemList is also used as the outer wrapper for carousel-style schemas — Course List (used by Course schema), Movie carousels, and Recipe collections all use ItemList as the container.

Google Carousel Eligibility Requirements

The Google Carousel is a rich result type that places your content in a horizontal scroll card above organic results. For carousel eligibility, all of the following conditions must be true:

Required Properties

ListItem Structure: url vs. item

Each ListItem in itemListElement can reference content in two ways:

The URL-only approach is simpler and the most common. The embedded item approach is used when the summary page schema is the primary or only source of structured data for the listed items.

ItemList Schema Code Example: Recipe Index

A summary page listing recipes using the URL-only approach:

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "Quick Weeknight Dinners",
  "description": "Our top 5 recipes ready in under 30 minutes.",
  "url": "https://example.com/recipes/quick-dinners",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "url": "https://example.com/recipes/pasta-primavera"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "url": "https://example.com/recipes/chicken-stir-fry"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "url": "https://example.com/recipes/shrimp-tacos"
    }
  ]
}

ItemList with Embedded Items: Course Catalog

Embedding course data directly in the ItemList for a course catalog page:

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "Course",
        "url": "https://example.com/courses/python-101",
        "name": "Python for Beginners",
        "description": "Learn Python from scratch in 4 weeks."
      }
    },
    {
      "@type": "ListItem",
      "position": 2,
      "item": {
        "@type": "Course",
        "url": "https://example.com/courses/web-dev",
        "name": "Full-Stack Web Development",
        "description": "Build web apps with React and Node.js."
      }
    },
    {
      "@type": "ListItem",
      "position": 3,
      "item": {
        "@type": "Course",
        "url": "https://example.com/courses/data-science",
        "name": "Data Science Fundamentals",
        "description": "Statistics, Python, and machine learning basics."
      }
    }
  ]
}

Common Mistakes to Avoid

• Duplicate URLs: Every ListItem must link to a unique URL. Greadme errors on duplicate URLs and deducts 10 points per duplicate. This is also a Google disqualifier for carousel eligibility.
• Duplicate positions: Every ListItem must have a unique position number. Greadme errors on duplicate positions.
• Non-sequential positions: Positions should be consecutive integers starting at 1 (1, 2, 3, …). Gaps (1, 2, 5) or starting above 1 (2, 3, 4) trigger a Greadme warning — this is Greadme's best-practice check, not an explicit Google requirement.
• Mixed content types: Mixing Recipe and Movie items in the same ItemList triggers a Greadme warning and reduces carousel eligibility. Each ItemList should represent a single content type.
• Cross-domain URLs: All item URLs should be on the same domain as the summary page. Linking to external sites (e.g., a recipe index linking to recipes on other domains) triggers a Greadme warning.
• Only one item: A single-item ItemList is valid schema but generates a Greadme warning — carousel requires at least 2 items.

How Greadme Validates ItemList Schema

Greadme runs a dedicated ItemList validator that checks both structural integrity (positions, URLs) and carousel eligibility signals. The score starts at 100:

Frequently Asked Questions