No ItemList schema on a collection page

What Is This Issue

List pages, category pages, and collection pages are missing ItemList schema. Without it, Google cannot represent the page’s items as a rich result list in search, reducing eligibility for carousel-style search appearances and list-based featured snippets.

Without ItemList schema:

Your list/collection pages won’t be eligible for carousel-style rich results
Google can’t display your page as a list-style rich result
Listicle articles won’t appear in carousel format
Category/collection pages miss opportunities for enhanced search appearance
AI search engines can’t properly understand list-based content

A proper ItemList schema should include: @type (ItemList), name, itemListElement with ListItem items, each having position, name, and url.

Why Is This Important

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.

How XeoPix Detects This

XeoPix follows these logical steps to detect missing ItemList schema:

Detect list pages: The crawler identifies pages with:
- Repeating list structure (<ul>/<ol> with 3+ items)
- Card grids or collection layouts
- Category-page layouts
- URL patterns indicating list pages (/top-, /best-, /list-)
Extract structured data: The crawler looks for JSON-LD, Microdata, or RDFa blocks on the page
Check for ItemList schema: The crawler verifies if any schema block has:
- @type set to ItemList
- itemListElement property containing an array of ListItem objects
Validate schema completeness: If ItemList schema is found, the crawler checks for:
- At least one ListItem in the itemListElement array
- Each ListItem has position, name, and url properties
Trigger conditions: The issue is flagged when:
- Page has list structure but no ItemList schema
- ItemList exists but itemListElement array is empty
- Any ListItem is missing position, name, or url properties

How To Fix

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…”)

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"
    }
  ]
}

Ensure each ListItem has required properties:
- position: Sequential number starting from 1
- name: Item name
- url: URL pointing to the individual item page
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
Validate with Google’s Rich Results Test

What We Store

Storage Level

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

Database Table / Prisma Model

PageStructuredData

Stored Fields

Field	Type	Description
schemaType	SchemaType	The type of schema (e.g., Organization, Person)
schemaFormat	SchemaFormat	The format of the schema (JSON-LD, Microdata, RDFa)
schemaIdentifier	String?	Unique identifier for the schema
rawJson	Json?	The raw JSON-LD or structured data content
schemaErrors	Json?	Array of validation errors found in the schema
isValidSchema	Boolean?	Whether the schema is valid according to validation
missingFields	Json?	Array of required fields that are missing

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

Examples

Example 1: Missing ItemList Schema on Listicle Page

Problematic state:


<!-- Listicle page without 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>

Corrected state:


<!-- Listicle page with ItemList schema -->
<html>
  <head>
    <title>Top 5 SEO Tools for 2024</title>
    <script type="application/ld+json">
      {
        "@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"
          }
        ]
      }
    </script>
  </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>

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"
    }
  ]
}

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/structuredDataRichResults/issue-151-itemlist-schema.test.js

Purpose

Validates that the crawler correctly validates ItemList JSON-LD schemas and does not report false positives when the schema is properly formed.

Tested Function

runStructuredDataRichResults()

Issue Information

Issue Number: 151
Issue Code: itemlist_schema_list
Toggle Group: structuredDataRichResults

Test Scenarios

Positive Test Cases

Valid ItemList schema: Page has an ItemList schema with itemListElement containing ListItem entries — no issue reported.

Negative Test Cases

None — the test only validates that valid schemas pass.

Boundary Cases

None.

Edge Cases

Empty HTML: <html></html> — no crash.

Expected Outcome

Pass

Issue should not be reported when a valid ItemList schema with required properties is present.

Fail

No negative test cases are defined.

Validation

Correct pass-through of valid ItemList schemas
Graceful handling of empty HTML

xeopix-crawling-v2/toggleGroups/structuredDataRichResults.js
xeopix-crawling-v2/issueCodes.js
xeopix-crawling-v2/utils/context.js
xeopix-crawling-v2/utils/issues.js
xeopix-crawling-v2/utils/schema.js

Coverage Summary

Covers valid ItemList schema detection
Covers empty HTML resilience

References

Schema.org — ItemList — Schema.org
Schema.org — ListItem — Schema.org
Google — Carousel Structured Data — Google Search Central

No ItemList schema on a collection page

What Is This Issue

Why Is This Important

How XeoPix Detects This

How To Fix

What We Store

Storage Level

Database Table / Prisma Model

Stored Fields

Detection Dependencies

Examples

Example 1: Missing ItemList Schema on Listicle Page

Example 2: ItemList for Category Page

Example 3: Incomplete ItemList Schema

Unit Test

Test File

Purpose

Tested Function

Issue Information

Test Scenarios

Positive Test Cases

Negative Test Cases

Boundary Cases

Edge Cases

Expected Outcome

Pass

Fail

Validation

Related Production Files

Coverage Summary

References