ItemList Schema for Product Collections

What ItemList does on a collection page

An ItemList is the schema.org type for an ordered or unordered collection of items. On an ecommerce category page, a search results page, or a curated collection, it states which items are in the list and in what order. Each member is an itemListElement of type ListItem, and each ListItem has a position and points at the underlying thing with a url or an inline item. That explicit ordering is the value: search engines no longer have to infer the sequence from your HTML.

Be precise about what ItemList does and does not buy you. It communicates list structure and can support list style carousel treatments in the contexts Google supports them, but the rich product details a shopper sees, price, availability, review stars, come from Product and Offer markup on the individual product pages. Think of ItemList as the table of contents and Product markup as the chapters.

Pattern one: summary page

Use this when the collection page links out to separate product detail pages, which is the normal ecommerce case. Each ListItem carries only a position and a url. The order of the entries must match the order the products appear on the page.

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListOrder": "ItemListOrderAscending",
  "numberOfItems": 4,
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "url": "https://site.com/shop/item-1" },
    { "@type": "ListItem", "position": 2, "url": "https://site.com/shop/item-2" },
    { "@type": "ListItem", "position": 3, "url": "https://site.com/shop/item-3" },
    { "@type": "ListItem", "position": 4, "url": "https://site.com/shop/item-4" }
  ]
}

Pattern two: all in one page

Use this when every item is fully described on the same page, for example a single page ranking or a guide that lists products inline with all their details. Here each ListItem nests a full item object, typically a Product, so the details live inside the list itself.

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@type": "Product",
        "name": "Extra virgin olive oil, 500ml",
        "url": "https://site.com/shop/item-1",
        "image": "https://site.com/img/item-1.jpg",
        "offers": { "@type": "Offer", "price": "18.00", "priceCurrency": "USD" }
      }
    }
  ]
}

Do not mix the two patterns inside one ItemList. Either every entry uses url only, or every entry uses a full item. A half and half list confuses parsers and can invalidate the whole block.

Property reference

Common mistakes

The most common error is a position sequence that does not match the page: positions must start at 1 and increment by 1 in the order items are shown, not the order they exist in your database. The second is marking items that are not visible, for example including paginated results from page 2 in the ItemList for page 1. The third is a mismatch between numberOfItems and the actual number of itemListElement entries. The fourth is expecting product rich results from ItemList alone: add Product markup on each detail page for price and review treatments.

Testing

Validate the markup in Google's Rich Results Test for the supported content types and in the Schema Markup Validator at validator.schema.org for a pure schema check. Confirm the number of ListItem entries detected matches numberOfItems, that positions run 1, 2, 3 with no gaps, and that each url returns a live 200 page. In Search Console, watch the relevant enhancement report for parse errors after deployment.

Frequently asked questions

Related reading

ItemList is one entry in the wider practice of schema and structured data, part of the broader technical SEO glossary.