No ItemList schema on a collection page

This issue reports an ItemList schema block your page already declares that is missing its itemListElement property — not a page that shows a list or category grid with no ItemList schema at all.

What this issue is not: it does not guess that a page with a repeating card grid, or a URL like /top-10-, ought to declare ItemList schema. A page with none declared is never reported. It also does not currently check individual list entries for position, name or url — only that itemListElement itself is present (this is different from BreadcrumbList, #91, whose entries are checked one by one).

ItemList schema is important for list-based content visibility:

• Carousel rich results: Enables pages to appear as carousels in search results
• List-style snippets: Google can display your page as a list-style rich result
• Listicle articles: "10 best SEO tools" type articles can appear in carousel format
• Category pages: Product category or blog topic pages can get enhanced search appearance
• AI search readiness: AI engines use ItemList schema to understand list-based content
• User engagement: Carousel and list-style results have higher click-through rates

Resolving this issue improves your SEO health score by ensuring list-based content is properly structured for enhanced search appearance.

If this issue was raised, your page already declares an ItemList missing itemListElement — open the finding and add it. The steps below are for a page that declares no ItemList schema yet: worthwhile to add, and never reported as a defect while absent. PixyScan checks only that itemListElement is present; filling in position, name and url for each entry below is good practice, not something this check verifies.

1. Identify list/collection pages: Look for pages with:

   • Repeating list structure (<ul>/<ol> with 3+ items)
   • Card grids or collection layouts
   • Category-page layouts
   • Listicle articles ("10 best...", "Top 5...")

2. Add ItemList JSON-LD structured data to the page's <head> or before </body>:

   {
     "@context": "https://schema.org",
     "@type": "ItemList",
     "name": "Top 5 SEO Tools",
     "itemListElement": [
       {
         "@type": "ListItem",
         "position": 1,
         "name": "Ahrefs",
         "url": "https://www.example.com/tools/ahrefs"
       },
       {
         "@type": "ListItem",
         "position": 2,
         "name": "SEMrush",
         "url": "https://www.example.com/tools/semrush"
       },
       {
         "@type": "ListItem",
         "position": 3,
         "name": "Screaming Frog",
         "url": "https://www.example.com/tools/screaming-frog"
       }
     ]
   }

3. Ensure each ListItem has required properties:

   • position: Sequential number starting from 1
   • name: Item name
   • url: URL pointing to the individual item page

4. Use for appropriate content types:

   • Listicle articles ("10 best SEO tools")
   • Category/collection pages (product category, blog topic pages)
   • How-to step summaries (when used alongside HowTo schema)
   • Recipe collection pages

5. Validate with Google's Rich Results Test

Example 1: No Schema Declared — Not This Issue

<!-- Listicle page with a visible ordered list, but no ItemList schema -->
<html>
  <head>
    <title>Top 5 SEO Tools for 2024</title>
  </head>
  <body>
    <h1>Top 5 SEO Tools for 2024</h1>
    <ol>
      <li><a href="/tools/ahrefs">Ahrefs</a></li>
      <li><a href="/tools/semrush">SEMrush</a></li>
      <li><a href="/tools/screaming-frog">Screaming Frog</a></li>
    </ol>
  </body>
</html>

Nothing is reported, however clearly the page presents a ranked list.

Example 1b: The Same Page, With ItemList Declared (passes)

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "Top 5 SEO Tools for 2024",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Ahrefs", "url": "https://www.example.com/tools/ahrefs" },
    { "@type": "ListItem", "position": 2, "name": "SEMrush", "url": "https://www.example.com/tools/semrush" },
    { "@type": "ListItem", "position": 3, "name": "Screaming Frog", "url": "https://www.example.com/tools/screaming-frog" }
  ]
}

Example 2: ItemList for Category Page

Corrected state:

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "SEO Blog Posts",
  "description": "Latest articles about SEO best practices",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "How to Optimize Title Tags",
      "url": "https://www.example.com/blog/title-tags"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Technical SEO Checklist",
      "url": "https://www.example.com/blog/technical-seo"
    }
  ]
}

Example 3: Incomplete ItemList Schema

Problematic state:

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "Best SEO Tools"
}

Missing required itemListElement property

Corrected state:

{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "name": "Best SEO Tools",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Ahrefs",
      "url": "https://www.example.com/tools/ahrefs"
    }
  ]
}

1. Read the declared structured data: every JSON-LD block is parsed, and @graph wrappers are flattened.

2. Select declared ItemList entities: any schema block whose @type is ItemList. A page that declares none is not examined — this check does not infer a collection or category page from a repeating <ul>/<ol>, a card grid, or a URL like /best-, /top-.

3. Check the required property: a declared ItemList must have an itemListElement property.

4. This is reported when: the page declares an ItemList missing itemListElement. A page showing a list, grid or ranked collection with no ItemList schema at all is never reported.

Note: unlike BreadcrumbList (#91), this check only verifies that itemListElement is present — it does not currently validate each entry's position, name or url individually.

Storage Level

Page Level — This issue is evaluated for each individual URL that contains structured data.

Database Table / Prisma Model

PageStructuredData

Stored Fields

Detection Dependencies

• The following data sources are required to evaluate this issue:
• HTML Document — The crawler parses the HTML to find structured data (JSON-LD, Microdata, RDFa)
• Structured Data Validation — The extracted schema is validated against Schema.org definitions
• Schema Parser — JSON-LD scripts, Microdata attributes, and RDFa markup are parsed