How to Create ItemList and Carousel Schema

ItemList is the most underused structured data type on ecommerce and publisher sites, and the reason is that it looks trivial. A list of things, with numbers. Most teams either skip it or emit a version so thin it conveys nothing.

The type is worth more than that. It is the only markup that tells a machine a page contains a deliberately ordered set, which items are in it, and what each item is. On a collection page that makes carousel eligibility possible. On a ranked listicle it makes the ranking retrievable, which matters for AI citation whether or not Google ever draws a carousel.

Google's carousel documentation describes two distinct patterns, and choosing the wrong one is the most common implementation error.

What ItemList Does

ItemList is defined by schema.org as a list of items of any sort. Three properties do the work.

itemListElement holds the members. Each is normally a ListItem carrying a position and either a url or a nested item object.

itemListOrder states whether the order is meaningful, using ItemListOrderAscending, ItemListOrderDescending, or ItemListUnordered. This property is skipped constantly and it is the one that tells a machine whether position 1 is a claim or an accident.

numberOfItems states the count, which lets a consumer know whether it has the full list or a page of it.

The important structural point is that ItemList describes the collection and the nested item type describes the thing. A carousel of products needs actual Product objects inside the list. An ItemList of bare URLs is valid but conveys almost nothing, because nothing in it says what those URLs are.

Which Content Types Qualify

Google restricts carousel treatments to a defined set of content types, and this is where to start rather than where to end up.

The qualifying types cluster around content where a visual set genuinely helps a searcher: products, recipes, restaurants, events, courses, and hotels are the recurring categories. Google's carousel documentation is the authority on the current list and it changes, so check it rather than trusting a blog post including this one.

Two consequences worth internalising.

If your content type is not on the list, you will not get a carousel no matter how correct the markup is. A list of blog posts, a list of services, or a list of team members is not carousel-eligible. Marking them up is still worth doing for retrieval reasons, covered below, but do not expect a visual result and do not spend a sprint chasing one.

If your content type is on the list, the nested items must carry the full property set that type requires. A carousel of products needs each Product to satisfy product markup requirements including offers with price and availability. A half-populated product inside a valid list still fails.

Our guide to product schema covers those requirements, and our post on merchant listing schema covers the shipping and returns properties that separate a basic snippet from the enhanced treatment.

The Summary Pattern

Use the summary pattern when each item lives on its own URL. This is the correct choice for a category page, a collection page, or a hub linking out to individual items.

The list carries minimal information per item and points at the destination, where the full detail lives.

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "@id": "https://example.com/collections/trail-shoes#list",
  "name": "Trail running shoes",
  "itemListOrder": "https://schema.org/ItemListUnordered",
  "numberOfItems": 4,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "url": "https://example.com/products/trail-runner-gtx"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "url": "https://example.com/products/ridgeline-2"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "url": "https://example.com/products/scree-lite"
    },
    {
      "@type": "ListItem",
      "position": 4,
      "url": "https://example.com/products/fell-pro-4"
    }
  ]
}

Note itemListUnordered there. A collection page sorted by whatever the shopper last clicked has no meaningful ordering, and claiming ascending order would be false. Declaring it unordered is the honest and correct signal.

Two rules for this pattern. Every URL must carry its own complete markup for the item type, because the summary page is deferring detail to those pages and Google will look. And the URLs must be the canonical ones, not filtered or parameterised variants, since a list pointing at non-canonical URLs distributes signals to pages you do not want ranking.

The All-in-One Pattern

Use the all-in-one pattern when the items are described on the current page. This is the correct choice for a ranked listicle, a best-of roundup, or a comparison where the reader gets the full answer without clicking away.

Here the list nests full item objects rather than pointing elsewhere.

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "@id": "https://example.com/best-trail-shoes-wet-rock#list",
  "name": "Best trail shoes for wet rock, tested",
  "itemListOrder": "https://schema.org/ItemListOrderDescending",
  "numberOfItems": 3,
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "Product",
        "name": "Northfell Trail Runner GTX",
        "image": "https://example.com/img/trail-runner-gtx-1x1.jpg",
        "description": "Best grip of the group on wet limestone. The Megagrip outsole held on slabs where the other two slid.",
        "brand": { "@type": "Brand", "name": "Northfell" },
        "offers": {
          "@type": "Offer",
          "url": "https://example.com/products/trail-runner-gtx",
          "price": "164.00",
          "priceCurrency": "USD",
          "availability": "https://schema.org/InStock"
        },
        "review": {
          "@type": "Review",
          "reviewRating": {
            "@type": "Rating",
            "ratingValue": 4.5,
            "bestRating": 5
          },
          "author": { "@type": "Person", "name": "Priya Raman" }
        }
      }
    },
    {
      "@type": "ListItem",
      "position": 2,
      "item": {
        "@type": "Product",
        "name": "Ridgeline 2",
        "image": "https://example.com/img/ridgeline-2-1x1.jpg",
        "description": "Lighter and faster on dry trail, noticeably less confident once the rock is wet.",
        "brand": { "@type": "Brand", "name": "Corvid" },
        "offers": {
          "@type": "Offer",
          "url": "https://example.com/products/ridgeline-2",
          "price": "139.00",
          "priceCurrency": "USD",
          "availability": "https://schema.org/InStock"
        }
      }
    },
    {
      "@type": "ListItem",
      "position": 3,
      "item": {
        "@type": "Product",
        "name": "Scree Lite",
        "image": "https://example.com/img/scree-lite-1x1.jpg",
        "description": "Cheapest of the three and the drainage is genuinely good, but the upper packed out after 200 miles.",
        "brand": { "@type": "Brand", "name": "Halden" },
        "offers": {
          "@type": "Offer",
          "url": "https://example.com/products/scree-lite",
          "price": "98.00",
          "priceCurrency": "USD",
          "availability": "https://schema.org/InStock"
        }
      }
    }
  ]
}

Two things that example does that most listicles do not.

itemListOrderDescending declares that position 1 is the top pick. That is a real claim and the markup states it.

Each description says something differentiating, including what is wrong with each option. A list where every description is positive is a list a retrieval system cannot use to answer which one, and that is the question being asked.

Does Your Order Mean Anything?

This is the question that separates useful ItemList markup from noise, and it deserves an honest answer per page.

Position numbers imply a ranking. If your collection page renders products in whatever order the CMS returned them, and you emit positions 1 through 24, you have asserted a ranking that does not exist. The markup is structurally valid and semantically false.

Three cases and the right handling for each.

• A genuine editorial ranking, where you tested and chose an order. Use ItemListOrderDescending and mean it. This is the strongest case for the markup.
• A sorted list, ordered by price, rating, or date. The order is real but it is not an editorial judgement. Declare the appropriate ascending or descending value and consider whether name explains the sort.
• An arbitrary or user-controlled order, which covers most collection pages. Use ItemListUnordered. Positions still enumerate the set, which is useful, without claiming a ranking.

The reason this matters beyond correctness is retrieval. An engine that trusts your ordering can answer a superlative query by taking your position 1. If your position 1 is whatever the database returned first, you have volunteered a wrong answer with your name on it.

ItemList for AI Retrieval

Even where a carousel is impossible, ItemList earns its place, and this is the argument most implementation guides miss.

Superlative and comparison queries are among the most commercially valuable things people ask an AI engine. Which is best, which is cheapest, which should I buy for this use case. Answering those requires a ranked set with attributes attached, and that is precisely what a well-built ItemList is.

Three specific benefits.

The ranking becomes explicit rather than inferred. An engine reading prose has to work out that your third heading is your third pick. Markup states it.

The set becomes bounded. numberOfItems tells a consumer whether it has your whole list or a fragment, which matters when only part of a long page gets retrieved.

The attributes travel with each item. Price, rating, and brand attached to each entry mean an engine can answer a filtered question, such as the best option under a hundred dollars, without re-reading the page.

This is why marking up a list of blog posts is still worth doing despite carousel ineligibility. Our guide to schema markup for AI search covers which types earn citations, and our post on content chunking covers how retrieval segments a page in the first place.

Validation and Common Errors

Validate with the Rich Results Test for carousel eligibility and the Schema.org validator for type correctness, and check the markup against what actually renders.

Seven errors account for most failures.

• Mixing the two patterns. A list that both points at URLs and nests full items confuses what the page is claiming. Pick one.
• Positions that do not start at 1 or that skip numbers. Position is an ordinal sequence and gaps break it.
• numberOfItems disagreeing with the array length. On a paginated collection, the markup should describe the current page.
• Asserting an order that does not exist. Use ItemListUnordered for arbitrary ordering.
• Nested items missing required properties. A carousel of products needs complete Product objects, including offers.
• Markup listing items that are not on the page. Do not emit all 200 products when the page renders 24.
• Pointing at non-canonical URLs. Filter and sort parameter variants should not appear as list item URLs.

One further check worth building into a crawl: confirm the order in the markup matches the order rendered in the HTML. Template changes reorder the visible list without touching the JSON-LD generator surprisingly often, and the result is markup that contradicts the page.

Our guide to ecommerce SEO covers where collection page markup sits in the wider technical picture, and our post on optimising Shopify collection and product pages covers the platform-specific implementation.

Frequently Asked Questions

What is the difference between the summary and all-in-one patterns?

The summary pattern points each list item at a separate URL where the detail lives, which suits collection and category pages. The all-in-one pattern nests complete item objects because the content is on the current page, which suits ranked listicles and roundups.

Does ItemList guarantee a carousel?

No. Carousels are limited to specific content types and Google decides whether to render one. The markup makes a page eligible, and it delivers retrieval value for AI engines regardless of whether a visual carousel ever appears.

Should I mark up a blog post list with ItemList?

It will not produce a carousel, since article lists are not among the eligible types. It is still worth doing, because it makes the set and any ordering machine-readable, which helps on comparison and superlative queries.

What if my collection page order is arbitrary?

Declare itemListOrder as ItemListUnordered. Positions then enumerate the set without asserting a ranking. Claiming a ranking your page does not have invites an engine to answer a best-of question with an arbitrary item.

How many items should the markup include?

Whatever the page actually renders. If you paginate at 24, mark up those 24 and set numberOfItems to match. Emitting the full catalogue on a paginated page describes content that is not there.