ItemList Schema Generator — Order Your Collections

Generate valid ItemList JSON‑LD with ordered ListItems (names and URLs) to make collection and category pages clearer.

Try the ItemList Generator

Why many lists underperform

Pain points we solve

• Collections are not represented as ordered lists in markup.
• List items use relative URLs or don’t link to crawlable pages.
• List order is missing or inconsistent across pages.
• Manual JSON‑LD is hard to keep consistent in templates.

How SwiftSchema helps

Solution

The ItemList generator creates a proper ItemList with `itemListElement` entries using 1‑based positions, names, and absolute URLs.

It pairs with CollectionPage for category pages and improves clarity of navigation and ordering.

How it works

How it works

1. Choose ItemList in the generator below.
2. Add each item’s name and absolute URL in the intended order.
3. Set `itemListOrder` and optionally `numberOfItems`.
4. Pair with CollectionPage for category pages and validate in the Rich Results Test.

Generate ItemList JSON‑LD

Keep positions 1‑based. Validate. Ship.

What is ItemList structured data?

ItemList is Schema.org’s way of expressing an ordered or unordered set of things — usually links — that appear together on a page. Think of horizontal category scrollers, “Top 10” rankings, comparison tables, or search result summaries. The markup publishes the exact order, label, and destination of each item so crawlers understand what the page is curating. When combined with CollectionPage, Product, Article, or Recipe schema, ItemList gives Google a structured window into how you’ve organized content for humans.

Instead of letting bots infer ordering from DOM structure, ItemList spells it out with

(1-based), , and . You can also embed nodes for richer detail when necessary. That explicit contract pays off when search results display key shopping links, FAQ sections, or best-of lists, because the JSON-LD guarantees each entry maps to a crawlable URL with supporting content. Rich internal data like this convinces Google you’ve invested in curation rather than thin auto-generated pages.

Why structured lists still matter

Publishing dozens of category or roundup pages is easy; keeping them high-quality is harder. ItemList helps in four areas:

• Transparency: Users and search engines can see the exact ordering logic (“ascending price”, “editor’s picks”).
  itemListOrder
  and
  position
  make that explicit.
• Crawl efficiency: Absolute URLs in the list ensure crawlers revisit the right products or articles even when template links are obfuscated behind carousels or JS.
• Analytics alignment: Editorial and SEO teams can diff ItemList JSON-LD over time to verify that placements reflect business priorities (e.g., certain SKUs always top the list).
• Experience parity: When the schema reflects what’s visible, you avoid thin experiences where a page title promises “Top 15 air purifiers” but structured data only mentions three.

Even without a dedicated rich result, the markup reinforces that the page curates a finite, well-maintained collection — a key signal in avoiding thin content penalties.

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
  . If the item already has its own schema (Product, Article, etc.), you can include it inside the
  item
  property for richer graphs.
• 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 (“Best Portable Air Conditioners 2025”). This context helps downstream systems determine when to surface the list.
• 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 metadata (optional): When you paginate, keep each page’s ItemList limited to the items actually visible and provide standard pagination links in HTML. For aggregated “view all” hubs, create a separate ItemList that contains every item.

Document these expectations in your content guidelines so editors provide the necessary data before you open SwiftSchema.

Preparing content and data for ItemList

1. Define the objective: Clarify what the list represents (editorial ranking, alphabetized directory, chronological release list). This determines
   itemListOrder
   and copy tone.
2. Collect canonical URLs: Each item must point to a unique, crawlable page. Avoid querystring-heavy tracking links; supply clean canonical URLs.
3. Lock the ordering: Use analytics or editorial logic to finalize the 1-based order. If ties occur, document tie-breakers so you can defend the structure during reviews.
4. Draft supporting blurbs: Even though ItemList only requires names, your MDX should include paragraphs or cards that describe why each entry matters. This maintains word count and quality while aligning with the structured data.
5. Decide on metadata depth: Determine whether each ListItem will simply contain
   name
   /
   url
   or embed a full
   item
   node (Product, Article, Event). Mixing approaches across a single list is a common source of confusion; pick one strategy per list.

Having this prep work ready makes SwiftSchema entry straightforward and keeps the resulting JSON-LD tightly aligned with your on-page experience.

Implementation workflow inside SwiftSchema

1. Launch the ItemList generator and confirm the metadata (
   name
   ,
   slug
   ,
   description
   ) matches the page or template you’re editing.
2. Set
   itemListOrder
   up front. If the list is editorial (descending importance), note that in the description so reviewers know the rationale.
3. Add each item in order. Include the public-facing title as
   name
   and paste the absolute URL. Validate that every URL resolves with a 200 status; broken links quickly lead to thin content complaints.
4. If embedding richer schema, toggle the advanced fields and supply the nested
   item
   object (e.g., a Product with price and sku). Keep the nested data consistent with what appears on the destination page.
5. Provide
   numberOfItems
   to show completeness. For dynamic modules (e.g., “Top Sellers” that update daily), wire your CMS to refresh this count automatically.
6. Export the JSON-LD, embed it within the CollectionPage or Article, and reference it from the parent schema via the
   mainEntity
   or
   about
   relationships when applicable.
7. Validate using the Rich Results Test or the Schema Markup Validator to catch typos, duplicate positions, or invalid URLs before shipping.

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://example.com/...
  ). 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: Schedule crawls that compare ItemList items to inventory or publishing systems. Remove discontinued products or archived posts promptly to avoid thin, outdated recommendations.
• 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.
• Nested item drift: When you embed Product or Article data inside
  item
  , keep it synced with the canonical page. For example, if a product price changes, update both the product page JSON-LD and the ItemList entry in the roundup.

In addition to validators, consider automated tests that ensure

equals the actual count of cards rendered and that each belongs to your allowed domain list.

Maintenance and scaling best practices

Curated lists demand editorial upkeep. Build a calendar to revisit evergreen roundups quarterly, verifying that the top picks are still in stock, reviews are current, and internal stakeholders agree with the ranking. When you update the content, regenerate the ItemList JSON-LD so

remains honest. Tie list updates to analytics: if engagement drops for specific items, either swap them out or strengthen the supporting copy so the page doesn’t read like boilerplate.

For large catalogs, automate generation. Maintain a CSV or headless CMS collection that stores item names, URLs, positions, and statuses. Feed that into SwiftSchema via bulk copy/paste or a short script so editors can refresh dozens of lists rapidly without copying errors. When localization is involved, ensure each locale owns its own ItemList with translated names and localized URLs rather than reusing a single English block.

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.
• Thin supporting copy: accompany every ItemList with meaningful prose or cards so the page delivers real value beyond the markup.

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListOrder": "ItemListOrderAscending",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Jacket A",
      "url": "https://example.com/jackets/a"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Jacket B",
      "url": "https://example.com/jackets/b"
    }
  ]
}