ItemList

The core property that defines the items in the list. Each element can be specified using one of two approaches:

• Simple text values: For basic lists of strings like step-by-step instructions
• Full entity objects: For complex items like Product, Article, or Event types with their own properties

Each element should include a position property to explicitly define its order in the sequence. This property is critical for maintaining the intended ranking or step order when search engines parse the list.

An integer value indicating the total count of items contained in the list. This property serves as a verification signal for search engines:

• Helps crawlers validate that all declared items were successfully parsed
• Provides a quick summary without requiring full list traversal
• Useful for lists where the total count carries semantic meaning, such as 'Top 10' rankings

While optional, including this property improves data integrity checks during automated processing.

Defines the ordering methodology of the list using an enumeration value:

• ItemListOrderAscending: Items arranged from lowest to highest according to the sorting criteria
• ItemListOrderDescending: Items arranged from highest to lowest
• ItemListUnordered: No intentional ordering exists

This property is essential for lists where the sequence carries meaning, such as ranked results, chronological timelines, or priority-ordered tasks. It prevents search engines from misinterpreting the list's intent.

When combined with Summary page markup, ItemList enables the carousel rich result in Google Search. This visual format displays a horizontally scrollable collection of items directly in search results.

Key requirements for eligibility:

• Each list item must be a fully defined entity (Recipe, Course, Movie, etc.)
• Images must be specified for each item
• The host page must provide a summary of each item with a link to a dedicated detail page

This is one of the most visually impactful Schema.org implementations for content-driven sites.

Within each ListItem element, the position property assigns an explicit integer rank starting from 1. This is not the same as array index ordering in JSON-LD.

Critical implementation details:

• Position values must be sequential integers without gaps
• Search engines use position to verify and reconstruct the intended order
• Essential for 'Top 10' lists, step-by-step guides, and ranked directories

Omitting position values can cause search engines to fall back on document order, which may not match the intended display sequence.

ItemList supports hierarchical nesting, allowing sub-lists within parent list items. This is particularly useful for:

• Multi-level directories: Categories containing subcategories
• Course curricula: Modules containing individual lessons
• Recipe collections: Meal plans containing individual recipes

Each nested ItemList maintains its own independent ordering and item count properties, enabling precise representation of complex content hierarchies while preserving semantic clarity for AI parsers.

A specialized subtype of ItemList designed exclusively for marking up navigational breadcrumb trails. It indicates a page's hierarchical position within a site's architecture.

• Key difference: Uses ListItem with position and item properties
• Rich result: Eligible for breadcrumb display in search snippets
• SEO impact: Helps search engines understand site structure and URL hierarchy

A Schema.org property that explicitly identifies the primary entity a page describes. When applied to an ItemList, it signals to parsers that the list itself—not surrounding content—is the page's central subject.

• Disambiguation: Prevents search engines from misidentifying the page topic
• Use case: A rankings page where the ordered list is the core value
• Syntax: "mainEntity": { "@type": "ItemList", ... }

The process of connecting textual mentions to their canonical knowledge base entries. Each ListItem within an ItemList can reference entities disambiguated via @id or sameAs properties.

• Wikidata IDs: Link list items to Q-identifiers for unambiguous identity
• AI benefit: Helps generative engines resolve entity references precisely
• Example: A list of 'Top CEOs' where each person links to their Wikidata URI

A visual search result format where an ItemList powers a horizontally scrollable gallery of items. Eligible for recipes, courses, movies, and articles.

• Requirements: Must use ItemList with sequential ListItem entries
• Properties needed: Each item requires url, image, and descriptive text
• Visibility: Significantly increases SERP real estate and click-through rates

A top-level JSON-LD construct that encapsulates multiple interconnected nodes within a single structured data block. An ItemList can be declared as one node within a broader @graph array.

• Purpose: Defines relationships between entities on the same page
• Efficiency: Single script tag contains all structured data
• Pattern: "@graph": [ { "@type": "ItemList" }, { "@type": "Organization" } ]