Skip to main content

ItemList Schema Missing

Issue No: 151

Category: Structured Data & Rich Results

Issue type: Suggestion

Priority: STANDARD

Description​

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.

How do we capture it​

  • Detect pages with a repeating list structure: <ul>/<ol> with 3+ items, or card grids, or category-page layouts
  • Check JSON-LD for "@type": "ItemList"
  • If list pattern is present but ItemList schema is absent → trigger suggestion

What to store​

StructuredDataAudit record with schemaType = ItemList, issueNumber = 151, plus StructuredDataField rows:

FieldTypeComment
item_countintegerNumber of itemListElement entries found
has_list_elementsbooleanitemListElement array present in schema
has_item_positionsbooleanAll ListItem nodes have a position property
has_item_urlsbooleanAll ListItem nodes have a url property
has_item_namesbooleanAll ListItem nodes have a name property

Core audit fields used: isPresent, rawJson

Condition for trigger​

  • Trigger Rule 1: ItemList schema absent on list/collection page

    • Target Field: isPresent
    • Evaluation Logic: isPresent = false AND page has 3+ repeating list items in HTML
    • Severity: STANDARD
    • Diagnostic Message: "Page has a repeating list structure but no ItemList schema found. Add ItemList schema to improve search carousel eligibility."

  • Trigger Rule 2: Items missing position numbers

    • Target Field: has_item_positions
    • Evaluation Logic: has_item_positions = false
    • Severity: STANDARD
    • Diagnostic Message: "ItemList schema found but position property is missing on one or more ListItem entries. position is required by Google."

  • Trigger Rule 3: Items missing URL

    • Target Field: has_item_urls
    • Evaluation Logic: has_item_urls = false
    • Severity: STANDARD
    • Diagnostic Message: "ItemList schema found but url property is missing on one or more ListItem entries."

Sources​

Long description​

ItemList marks up a collection of related items on a single page, enabling Google to display the page as a carousel or list-style rich result in search. This is particularly valuable for:

  • 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

Each item in the list is represented as a ListItem with a sequential position, a name, and a url pointing to the individual item page. Optionally, an item property can link to a full schema entity.

Example — Listicle page:

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

Key points:

  • position must be a number starting at 1 and incrementing by 1
  • url values must be absolute URLs (not relative)
  • For category pages, each url should point to an individual product/article page
  • Can be combined with other schema types (e.g., each linked page can have Product, Article, or Recipe schema)

How to Fix​

  1. Identify list pages, category pages, and collection pages
  2. Add JSON-LD ItemList schema with itemListElement array
  3. Each ListItem must include: position (integer, starting at 1), name, and url (absolute URL)
  4. Validate with Google Rich Results Test
  5. Monitor Google Search Console for carousel rich result eligibility in the Enhancements section