XooCode(){

ItemList

ItemList describes an ordered or unordered list of items. Google uses it to render carousel rich results: a row of cards in search results where each card links to a different page. This is how "best of" listicles, recipe collections, and course catalogs get the multi-card treatment in Google Search. The markup is also used by AI systems to understand ranked lists and recommendations.

There are two patterns for ItemList. The summary page pattern (shown here) lists items by URL only, with each ListItem pointing to a separate detail page. The detail page pattern embeds full markup for each item (full Product, Recipe, or Course) inline. Google generates carousels from summary pages. Detail pages are for single-page listicles where all items live on one URL.

Full example of schema.org/ItemList json-ld markup

The markup is verified as valid with Rich Results Test from Google.

Highlight legend:Required by GoogleRecommendedOptional
schema.org/ItemList
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@id": "https://xoocode.com/top-products#list",
  "@type": "ItemList",
  "name": "Top 5 Products from the Xoo Universe",
  "description": "Our curated ranking of the most popular products across the Xoo Code ecosystem, from graphic tees to developer tools.",
  "url": "https://xoocode.com/top-products",
  "numberOfItems": 5,
  "itemListOrder": "https://schema.org/ItemListOrderAscending",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "url": "https://xoocode.com/shop/xootee-classic"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "url": "https://xoocode.com/xoostructured"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "url": "https://roydanmedjournal.dk/books/children-first"
    },
    {
      "@type": "ListItem",
      "position": 4,
      "url": "https://xoocode.com/tools/xoolint"
    },
    {
      "@type": "ListItem",
      "position": 5,
      "url": "https://xoocode.com/tools/xoosnippets"
    }
  ]
}
</script>

ListItem and position

Each entry in the itemListElement array is a ListItem with a position (1-indexed integer) and a url pointing to the item's detail page. The position must be sequential and start at 1. Google reads the position to determine card order in the carousel. If positions are missing or out of order, Google may skip the carousel entirely.

Summary page vs detail page

On a summary page (like a "Top 10" article), each ListItem has only a url pointing to a separate page. Google crawls those pages for their own structured data (Product, Recipe, etc.) and builds the carousel from that. On a detail page (like a recipe roundup where all recipes are on one page), each ListItem contains the full item markup inline. Do not mix the two patterns on the same page.

itemListOrder

itemListOrder tells consumers whether the list is ranked. Use https://schema.org/ItemListOrderAscending for ordered/ranked lists (position 1 is best), https://schema.org/ItemListOrderDescending for reverse-ranked lists, and https://schema.org/ItemListUnordered for unordered collections. Google uses this to decide whether position numbers matter for display.

Carousel eligibility

Not every ItemList gets a carousel. Google generates carousels when the listed items are all the same type (all Products, all Recipes, all Courses) and each detail page has valid structured data for that type. Mixed-type lists ("5 products and 3 recipes") do not get carousels. The summary page itself must also rank well enough for the query to earn the carousel placement.

Minimal valid version

The smallest markup that still produces a valid ItemList entity. Use it as the floor. Reach for the advanced example above when you want search engines and AI agents to understand more about your content.

schema.org/ItemList (minimal)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "url": "https://xoocode.com/shop/xootee-classic" },
    { "@type": "ListItem", "position": 2, "url": "https://xoocode.com/xoostructured" },
    { "@type": "ListItem", "position": 3, "url": "https://roydanmedjournal.dk/books/children-first" }
  ]
}
</script>

Google rich results this unlocks

Markup matching this example makes your page eligible for the following Google Search rich results. The primary target drives the required / recommended property classification in the advanced code block above.

Common ItemList mistakes

Mistakes that pass validation but silently fail to earn rich results or mislead consumers walking the graph. Avoid these and your markup will be ahead of most sites in the wild.

  1. 01

    Positions starting at 0

    Wrong
    { "@type": "ListItem", "position": 0, "url": "..." }
    Right
    { "@type": "ListItem", "position": 1, "url": "..." }

    ListItem positions are 1-indexed, not 0-indexed. Google expects position 1 for the first item. Starting at 0 causes Google to misinterpret the list order or skip the carousel entirely.

  2. 02

    Gaps or duplicates in position numbers

    Wrong
    Positions: 1, 2, 5 (skipped 3 and 4) or 1, 1, 2 (duplicate)
    Right
    Positions: 1, 2, 3, 4, 5 (sequential, no gaps)

    Positions must be sequential integers with no gaps or duplicates. Google validates the sequence and may ignore the entire list if positions are inconsistent. If you remove an item from the list, renumber the remaining items.

  3. 03

    Mixing summary and detail patterns

    Wrong
    Some ListItems have only a url, others have full Product markup inline
    Right
    All ListItems use url-only (summary page) OR all ListItems have full inline markup (detail page)

    Google expects consistency within a single ItemList. On a summary page, every ListItem should have just a url. On a detail page, every ListItem should have full item markup. Mixing the two patterns confuses the carousel logic.

  4. 04

    Mixed item types in a carousel list

    Wrong
    ItemList where some urls point to Products and others point to Recipes
    Right
    ItemList where all urls point to the same type (all Products, all Recipes, etc.)

    Google only generates carousels when all listed items are the same type. A list mixing Products and Recipes will not get a carousel even if each detail page has valid structured data. Group items by type into separate lists if needed.

  5. 05

    itemListOrder as a plain string

    Wrong
    "itemListOrder": "ascending"
    Right
    "itemListOrder": "https://schema.org/ItemListOrderAscending"

    itemListOrder expects a full schema.org URL. Valid values are ItemListOrderAscending, ItemListOrderDescending, and ItemListUnordered. Plain strings may validate in some tools but are not reliably parsed by Google.

Schema properties in this example

ItemListListItemnamedescriptionurlnumberOfItemsitemListOrderitemListElementposition

About the example data

The list is "Top 5 Products from the Xoo Universe," a curated ranking page linking to detail pages for each product. The URLs reference existing Xoo universe entities: the XooTee Classic t-shirt, the XooStructured IDE, the Children First textbook, plus two additional fictional products (XooLint and XooSnippets).

Comments

Loading comments...

Leave a comment