ItemList

ItemList is a Schema.org type that represents an ordered list of items. Unlike an unordered collection, the sequence defined by an ItemList carries semantic meaning—search engines interpret the position of each item as a deliberate ranking or step. This is critical for generating carousel rich results, where Google displays a horizontally scrollable list of entities directly in the SERP. Common use cases include:

• Top 10 rankings and curated lists
• Step-by-step recipe instructions
• Course catalogs and syllabus outlines
• Product feature comparison tables

The itemListElement property is the backbone of ItemList markup. It accepts an array of ListItem objects, each representing one entry in the sequence. Every ListItem must define a position property (an integer starting at 1) to establish explicit ordering. The actual entity being listed is referenced via the item property, which can point to any Schema.org type—Article, Product, Event, or even another ItemList for nested structures.

• position: Integer defining rank (1, 2, 3...)
• item: The entity being referenced (full object or URL)
• name: Optional label for the list item itself

numberOfItems is an integer property that declares the total count of entries in the list. While not strictly required, providing this value helps search engines validate the completeness of the parsed data and can improve rich result eligibility. It serves as a data integrity signal—if the parsed itemListElement array length doesn't match numberOfItems, it indicates a markup error. This property is particularly useful for:

• Paginated lists where items span multiple pages
• Dynamic lists where the total count is known upfront
• Summary cards displaying "X items" in search previews

itemListOrder specifies the ordering methodology of the list using an ItemListOrderType enumeration. This property explicitly tells search engines whether the sequence is arbitrary or follows a defined logic. Accepted values include:

• ItemListOrderAscending: Items ordered from lowest to highest by some criteria
• ItemListOrderDescending: Items ordered from highest to lowest
• ItemListUnordered: No intentional ordering exists Omitting this property when a clear ranking exists (e.g., "Top 10 Movies") misses an opportunity to provide semantic clarity about the list's intent.

ItemList markup is the primary mechanism for qualifying content for carousel rich results on Google. When implemented correctly, a carousel displays a horizontally scrollable set of cards extracted from the list items. Key eligibility requirements include:

• The list must contain at least 2 items
• Each item must reference a distinct entity with its own structured data (e.g., Recipe, Course, Movie)
• The host page must be the canonical source for the list content
• Summary carousels display items from a single host; all-carousels aggregate across domains Common carousel types: Recipe, Course, Movie, and Article.

ItemList supports recursive nesting, allowing complex hierarchical data to be represented. A ListItem's item property can itself be another ItemList, enabling multi-level outlines, course modules with lessons, or categorized rankings. This nesting must be expressed using full entity embedding in JSON-LD rather than URL references to ensure search engines can parse the complete structure without additional HTTP requests.

• Top-level ItemList: "Computer Science Curriculum"
• Nested ItemList: "Module 1: Data Structures" containing individual lecture items
• Each nested list maintains its own numberOfItems and ordering properties

A Schema.org property that explicitly identifies the primary entity a webpage describes. This is a high-confidence signal for search engines performing entity extraction and disambiguation.

• Usage: "mainEntity": { "@type": "ItemList", ... } declares the list as the page's core subject
• Impact: Strengthens the association between the URL and the structured data, reducing ambiguity
• Contrast: Without mainEntity, a page with multiple schema blocks forces the parser to guess which is primary
• Best Practice: Always wrap your dominant schema type with mainEntity when it represents the page's purpose