Free Item List Schema Generator

Why many lists underperform

How SwiftSchema helps

How it works

What is ItemList structured data?

ItemList is Schema.org’s way of describing an ordered or unordered set of things that appear together on a page. Common examples include “Top 10” articles, product category pages, comparison tables, directories, playlists, and collections of related resources. The markup identifies the list, its order, and the destination of each item.

Each entry is represented as a ListItem with a 1-based position, a name, and an absolute url. ItemList does not guarantee a special Google rich result or a ranking improvement. Its job is to make the same list visitors can see easier for search engines and other systems to understand.

When ItemList schema is useful

ItemList works best when the page presents a real list and each entry has a clear destination:

• Ranked articles: Preserve the visible 1-to-10 order with matching positions.
• Category and collection pages: Describe the products, articles, recipes, or resources shown on the page.
• Directories: Mark up a visible set of profiles, locations, tools, or organizations.
• Comparison pages: Keep the JSON-LD in the same order as the comparison table or cards.

The markup should mirror the page. If visitors see 10 items, do not include 50 hidden entries in the schema. If filters or sorting change the order, update the ItemList or mark up the stable default view.

Essential properties to capture

• itemListElement: The backbone of the schema. Each entry should be a ListItem with position (starting at 1), name, and an absolute url.
• itemListOrder: Declare how the list is sorted (ItemListOrderAscending, Descending, or Unordered). For editorial rankings, reference the logic in your visible copy (“Ranked descending by customer rating”).
• numberOfItems: State how many entries appear on the current page. Keep it synchronized with the actual count to avoid validator mismatches.
• name / description: Provide a concise title and summary for the list, such as “Best Portable Air Conditioners for Small Rooms.”
• url: The canonical URL of the page hosting the list. Include it so the ItemList is clearly tied to the CollectionPage or Article in your graph.
• Pagination: Keep each page’s ItemList limited to the items visible on that page. A separate “view all” page can use its own complete list when all entries are genuinely displayed there.

Preparing content and data for ItemList

1. Define the list: Decide whether the page is a ranking, alphabetical directory, chronological list, or unordered collection. This determines itemListOrder.
2. Collect canonical URLs: Each item must point to a unique, crawlable page. Avoid querystring-heavy tracking links; supply clean canonical URLs.
3. Confirm the visible order: Number entries from 1 in the same order visitors see on the page.
4. Check names and links: Use the public item names and final destination URLs, not internal labels or redirecting links.
5. Count the visible entries: The generator calculates numberOfItems from the rows you add.

With those details ready, you can generate markup that matches the page without manually numbering every JSON-LD object.

How to use the ItemList schema generator

1. Enter the list name, a short description, and the canonical URL of the page containing the list.
2. Choose ItemListOrderAscending, ItemListOrderDescending, or ItemListUnordered to match the visible presentation.
3. Add each item in order. Use its public name and absolute URL.
4. Remove empty or outdated entries. The generator assigns positions and calculates numberOfItems automatically.
5. Copy the JSON-LD or script tag and add it to the page that displays the list.
6. Validate the finished markup with Schema.org’s validator. You can also use Google’s Rich Results Test to inspect the page, even though ItemList does not have a dedicated Google rich result.

Troubleshooting and QA

• Duplicate positions: Ensure each ListItem uses a unique, sequential number. Validators may not flag duplicates, but Google could treat them as errors.
• Relative URLs: Always convert to absolute URLs (https://your-site.invalid/item). Relative paths can break when crawlers resolve them from different hostnames (CDNs, AMP caches).
• Mismatch with on-page order: If the schema lists items 1–10 but the UI reorders them via client-side sorting, you’ve created a trust issue. Either lock the UI order or regenerate the schema to match how users actually see the content.
• Stale entries: Remove discontinued products, deleted pages, and archived posts from both the visible list and the JSON-LD.
• Pagination confusion: Only include the items visible on the current page. If you syndicate the same ItemList on multiple pages, update url, position, and numberOfItems accordingly.
• Wrong item count: Make sure numberOfItems matches the number of ListItem entries and the number of items shown on the page.

Maintenance and scaling best practices

Revisit the markup whenever the visible list changes. If an item moves, update its position. If a page is removed or redirected, replace its URL. If the list is generated dynamically, make sure the JSON-LD is generated from the same data and ordering rules as the visible cards or table.

For localized pages, create a separate ItemList with translated names and locale-specific URLs. Do not reuse one English list across pages that show different items or ordering.

Common Errors & Fixes

• Missing positions: ensure each ListItem has a 1‑based position.
• Relative or redirecting URLs: supply canonical absolute links for every entry.
• Outdated counts: keep numberOfItems synchronized with the visible list.
• Unclear ordering: set itemListOrder and describe the logic in the body copy.
• Hidden or extra entries: include only the items visitors can see on the page.