Schema Markup·4 min read

ItemList Schema and Carousels: A Practical Guide

You've published a top ten roundup of note-taking apps and it's sitting on page two. ItemList markup gives each entry an explicit position, name and URL, the shape Google's list features expect. It won't force a carousel, and for most list types no carousel exists, but it states clearly what the list contains and in what order. Here's where carousels actually apply, how ordering and layouts work, what a real block looks like, and the numbering slips that quietly break lists.

Open the free ItemList Schema Generator All insights

Carousels: the honest version

Carousel eligibility comes with fine print. Google supports carousels for four item types: Course, Movie, Recipe and Restaurant. A list of any of those, marked up in one of two layouts, can qualify. A roundup of apps, boots or hotels has no carousel, whatever its markup says.

So why bother for a blog roundup? Because the structure is still useful. An explicit ranked list tells search engines and other tools that the page is a list, how long it is and what sits at number one. The tool writes it in minutes, and it can't hurt as long as every item appears on the page.

Summary page or all-in-one page

For the carousel types, choose the item type and a layout in the ItemList Schema Generator. Summary page fits a list that links out: each ListItem holds only a position and the URL of the item's own detail page, which carries its own full markup. All-in-one page fits a list where everything is on one URL: each ListItem holds the complete item, with its name, image and an anchor URL to its section.

Google's course list is a special case worth knowing: it needs at least three courses, and the tool warns if you have fewer.

Ordered vs unordered lists

The optional itemListOrder property says how the list is sorted: ascending, descending or unordered. A countdown from 10 to 1 is descending. For a ranked roundup the order is the editorial point, so positions must mirror your headline order exactly. For a plain catalog, ten shops in a district, order carries no meaning, so leave it unset.

Positions are needed either way; every ListItem has one, starting at 1. Maintaining ten sequential numbers through every edit is exactly the bookkeeping the reorder arrows take over: move an entry and every position renumbers. The tool also counts the items into numberOfItems for you.

A worked ItemList example from a top ten post

Suppose the roundup is titled "Top 10 Note-Taking Apps for 2026" and Notion leads. The output starts: {"@context":"https://schema.org","@type":"ItemList","name":"Top 10 Note-Taking Apps for 2026","itemListElement":[{"@type":"ListItem","position":1,"name":"Notion","url":"https://example.blog/reviews/notion"},{"@type":"ListItem","position":2,"name":"Obsidian","url":"https://example.blog/reviews/obsidian"}]} and continues through position 10.

Each URL points at the blog's own review of that app. If everything lived on the roundup page itself, you'd swap those URLs for section anchors such as #obsidian. You don't have to type any of this: paste the article URL and press Import items, and the tool reads the H2 headings, or H3s if there are fewer than three H2s, taking each heading's link or anchor, the first image after it and the first paragraph as a description.

ItemList position mistakes that break lists

Nearly every broken list fails on one of these:

Gaps or duplicates in the sequence, positions 1, 2, 2, 4, usually left behind by a hand edit that deleted an entry.
Markup order contradicting visible order, so the page says Obsidian is second while the markup ranks it fifth.
Every item pointing at the same URL with no anchors, which collapses the list into ten copies of one link.
Mixing layouts: some items with detail page URLs, others with full inline data, leaving the list neither summary nor all-in-one.
Starting at position 0 because arrays start at zero; ListItem positions start at 1.

Getting cleaner ItemList markup out of the tool

Check the List preview before copying: it shows the numbered items and thumbnails in final order, and an off-by-one entry is far easier to spot there than in JSON. Keep each item's name identical to the heading it corresponds to on the page, then clear the warnings in the Validation panel and test the block with Test in Google Rich Results Test.

The List type dropdown can also output HowToSection for numbered steps. It is valid Schema.org, but Google stopped showing HowTo rich results in 2023, so it won't change how the page looks in Google.

Keeping ItemList markup current after re-ranks

Roundups age in a predictable way: the content is refreshed every year, the title becomes Top 10 Note-Taking Apps for 2027, two entries swap places and one app is replaced. The markup rarely gets the same treatment, which leaves last year's ranking in the JSON contradicting this year's ranking on the page.

The cheap fix is to regenerate the block as part of the same edit that changes the article. Import items again from the updated page, check the order, and re-copy. Renumbering is automatic, which removes the step people skip when editing raw JSON under deadline.

ItemList next to the neighboring schema tools

The CollectionPage Schema Generator describes category and archive pages and already nests an ItemList of their products or posts, so use it for shop categories. The Article Schema Generator covers the roundup post itself, with headline, author and dates, and shipping Article plus ItemList together on a top ten post is a common, valid pairing.

For a course catalog page, build each course page with the Course Schema Generator, then list them here with Course as the item type. After publishing, confirm both blocks are on the live URL with the Schema Markup Extractor.