ItemList schema for ranked lists and tables

01What is ItemList schema?

ItemList is the schema.org type for a list of items of any sort. The schema.org definition gives "Top 10 Movies About Weathermen" as an example and adds that it is not to be confused with HTML lists, which are often used only for formatting. Its main property, itemListElement, holds the entries.

Each entry is usually a ListItem, defined by schema.org as a list item such as a step in a checklist. A ListItem has a position in the sequence and an item, the thing it stands for. ItemList also has numberOfItems for the total, which counts the whole list even when a page shows only part of it, and itemListOrder for the kind of ordering: ascending, descending or unordered.

This guide belongs to the schema types section of the handbook. The rest of our structured data guides start from the home page.

02Where does Google use ItemList?

Google's carousel documentation describes a host carousel: a list-like rich result people can swipe through on mobile, showing several cards from the same site. To be eligible, you add ItemList markup in combination with one of four supported features: Course list, Movie, Recipe or Restaurant.

That list is short on purpose, and it is the main thing people miss. A ranking of hosting companies, a list of the best plugins or a top ten of anything outside those four types does not become a carousel, however valid its ItemList is. Google also notes that carousel-like features such as Top stories, which show results from different sites, cannot be controlled with carousel markup.

ItemList appears in one more place in Google's documentation. On editorial product review pages, the product snippet documentation uses ItemList inside a Review's positiveNotes and negativeNotes to state pros and cons, with at least two statements in total. Our guide to product schema and AI shopping answers covers that pattern.

03Summary page or single page list?

Google's carousel guide describes two ways to build a list. A summary page gives a short description of each item and links to a separate detail page for each one. An all-in-one page holds the full text of every item and does not link out.

On a summary page, each detail page must carry valid markup for its own type: a Recipe on each recipe page, for example. On an all-in-one page, each item's URL must be the current page plus an anchor near the visible text, such as #apple-pie, so a reader landing on it sees the right entry.

04How do ListItem and position work?

In Google's carousel guide, position is a 1-based integer, so the first item is 1. Items shown as a list appear in the order of their position values. An ItemList needs at least two ListItem elements, and the markup must include every item the page lists, with visible text similar to what the markup says.

For a ranked list, position is the rank. It describes order, not quality: position 1 is first, but the markup says nothing about why. If the list is alphabetical or has no meaningful order, schema.org's itemListOrder can say so with ItemListUnordered, and position then simply records the sequence on the page.

Long lists split across several pages need one more decision. Mark up the items each page shows, number them continuously across pages so that page two starts where page one ended, and use numberOfItems for the total of the whole list, which schema.org describes for exactly this case.

Keep the list and the markup in step when you edit. Moving an item from fourth to second in the article and forgetting the JSON-LD leaves two different rankings on one page, which is the kind of mismatch the guidelines warn against.

05Why should comparison tables be HTML first?

A comparison table does not need markup to be useful, and none of the list features above are built for tables. The table itself is the asset. A real HTML table, with a caption, header cells and one row per item, is readable by people, by screen readers and by any crawler that fetches the raw page.

1. Use a table element with a caption that says what is compared.
2. Put column names in header cells, and the item name in the first cell of each row.
3. Keep one fact per cell, with units in the header rather than repeated in every cell.
4. State the date the figures were checked, close to the table.
5. If the page ranks the items, add an ItemList whose positions match the table order.

A good comparison table also answers the question a reader brought to it. Put the column that decides most choices, such as price or the main limit, near the left, and keep rows in the same order as any ranking in the text so the two never disagree.

When the compared items are software, each row can link to a page with its own SoftwareApplication schema, which keeps the facts for each product on that product's page. The table then summarizes, and the linked pages hold the detail.

06How do lists show up in AI answers?

Answer engines often respond with ranked or bulleted lists, and they build them from the visible text of the pages they read. None of the documentation read for this guide says ItemList markup makes a list more likely to be quoted. What helps is a list that already reads well out of context: a clear heading, one item per line, and a short reason beside each item.

• Give the list a heading that states what is ranked and by what measure.
• Write each item's name in plain text at the start of its entry.
• Add one sentence of reasoning per item, close to its name.
• Date the list, and update the date only when the list changes.

The page structure that makes passages easy to lift, including tables, is covered in how to get cited by ChatGPT and AI answers. ItemList can confirm the order you chose. It cannot make a weak list worth repeating.

07ItemList JSON-LD examples

The first example is a summary page of fictional recipes, a type Google supports for host carousels. The second is an all-in-one ranking of fictional apps, which is valid schema.org but not eligible for a carousel. All values are examples.

1{2  "@context": "https://schema.org",3  "@type": "ItemList",4  "itemListElement": [5    {6      "@type": "ListItem",7      "position": 1,18      "url": "https://example.com/recipes/example-lemon-cake/"29    },10    {11      "@type": "ListItem",12      "position": 2,13      "url": "https://example.com/recipes/example-apple-pie/"14    },15    {16      "@type": "ListItem",17      "position": 3,18      "url": "https://example.com/recipes/example-oat-cookies/"19    }20  ]21}

1{2  "@context": "https://schema.org",3  "@type": "ItemList",4  "name": "Example ranking of habit tracking apps",5  "itemListOrder": "https://schema.org/ItemListOrderDescending",6  "numberOfItems": 2,17  "itemListElement": [8    {9      "@type": "ListItem",10      "position": 1,11      "item": {12        "@type": "SoftwareApplication",13        "name": "Example Habit Tracker",14        "url": "https://example.com/best-habit-apps/#example-habit-tracker"215      }16    },17    {18      "@type": "ListItem",19      "position": 2,20      "item": {21        "@type": "SoftwareApplication",22        "name": "Example Streak Counter",23        "url": "https://example.com/best-habit-apps/#example-streak-counter"24      }25    }26  ]27}