ListItem

ListItem is an entry within an ItemList or BreadcrumbList. It pairs a position with an item (a URL, a Thing, or an inline object) so consumers can render an ordered sequence.

Full example of schema.org/ListItem json-ld markup

The markup is verified as valid with Rich Results Test from Google.

Highlight legend:Required by GoogleRecommendedOptional

schema.org/ListItem

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "item": {
        "@id": "https://xoocode.com/",
        "name": "Home"
      }
    },
    {
      "@type": "ListItem",
      "position": 2,
      "item": {
        "@id": "https://xoocode.com/json-ld-code-examples",
        "name": "JSON-LD Code Examples"
      }
    },
    {
      "@type": "ListItem",
      "position": 3,
      "item": {
        "@id": "https://xoocode.com/json-ld-code-examples/offershippingdetails",
        "name": "OfferShippingDetails"
      }
    },
    {
      "@type": "ListItem",
      "position": 4,
      "item": {
        "@id": "https://xoocode.com/json-ld-code-examples/shippingdeliverytime",
        "name": "ShippingDeliveryTime"
      }
    }
  ]
}
</script>

Direct properties (4)

position: 1-indexed Integer (schema.org's convention; 0-indexed breaks Google's breadcrumb rich result).
item: the Thing represented by the entry. For breadcrumbs, usually { "@id": "url", "name": "label" }. For product carousels, a full Product node inline.
previousItem / nextItem: ListItem references for doubly-linked sequences (chapter navigation, paginated search results). Optional but helpful for AI crawlers following sequence.

Breadcrumb vs carousel

BreadcrumbList feeds Google's breadcrumb rich result: compact items with URL + name. ItemList with ListItems feeds carousel results (Article / Product / Course carousels). The ListItem shape is identical; the containing list type selects the rich-result treatment.

Minimal valid version

The smallest markup that still produces a valid ListItem entity. Use it as the floor. Reach for the advanced example above when you want search engines and AI agents to understand more about your content.

schema.org/ListItem (minimal)

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "ListItem",
  "position": 1,
  "item": { "@id": "https://xoocode.com/", "name": "Home" }
}
</script>

Google rich results this unlocks

Markup matching this example makes your page eligible for the following Google Search rich results. The primary target drives the required / recommended property classification in the advanced code block above.

Breadcrumb / Carousel rich results (via BreadcrumbList or ItemList)primary
Google docs

Common ListItem mistakes

Mistakes that pass validation but silently fail to earn rich results or mislead consumers walking the graph. Avoid these and your markup will be ahead of most sites in the wild.

01
0-indexed positions
Wrong
```
First ListItem at position: 0
```
Right
```
position: 1
```
schema.org positions are 1-indexed. Google's breadcrumb rich result rejects 0-indexed lists.
02
item as a bare URL string
Wrong
```
"item": "https://example.com"
```
Right
```
"item": { "@id": "url", "name": "label" }
```
Google needs the label for rendering; a bare URL loses it.
03
Out-of-order positions
Wrong
```
Gaps or duplicates in position numbers
```
Right
```
Contiguous 1, 2, 3, … 1-indexed
```
Gaps confuse rendering; duplicates cause Google to drop the entire breadcrumb.

Schema properties in this example

ListItem Intangible BreadcrumbList itemListElement position item name previousItem nextItem

Also mentioned in 16 other examples

ListItem also appears in AboutPage, BreadcrumbList, CollectionPage, Guide, HowToDirection, HowToItem, HowToSection, HowToTip, and 8 more. See the full ListItem schema page for every reference.

About the example data

The xoocode.com breadcrumb trail from home → JSON-LD Code Examples → Shipping and fulfillment → ShippingDeliveryTime.

Comments

Loading comments...