BreadcrumbList schema for web extraction

Breadcrumbs are the small navigational trail near the top of a page (Home > Electronics > Headphones > Sony WH-1000XM5) that tells you where the page sits inside a site's hierarchy. They are one of the cleanest signals you can extract for understanding how a site categorizes its content, because they encode the parent-child path a human would walk to reach the page. This reference gives you a ready-to-copy Extracto schema for the BreadcrumbList shape: an ordered array of trail steps, each with a position, a name and a URL, plus a derived depth count. With Extracto you describe the fields you want in plain JSON rather than writing CSS selectors against a `.breadcrumbs li a` structure that breaks the moment a site reships its markup. You send one URL and this schema, the page is rendered in a real headless browser, and you get back JSON validated against the schema. Breadcrumbs are notoriously inconsistent across sites: some emit JSON-LD BreadcrumbList structured data, some only render visible nav, some show a partial trail, and many pages have no breadcrumb at all. Extracto handles that honestly. When a trail step or the whole list is genuinely absent, the field comes back as null instead of a fabricated category path, so you can trust the hierarchy you store and never act on a guessed parent that does not exist on the page.

Fields in a BreadcrumbList schema

The fields teams most often extract for a breadcrumblist, what type each one is, and whether it is usually present.

Field	Type	Required	Notes
items	array	yes	The ordered breadcrumb trail as an array of step objects, mirroring the visible Home > Category > Subcategory > Page path. Returning it as a typed array preserves the exact ancestor ordering of the page, which is what lets you reconstruct site hierarchy programmatically instead of parsing a raw nav string. If the page has no breadcrumb at all, the whole array is null rather than an empty guess.
items[].position	number	yes	The 1-based ordinal of this step in the trail, matching the schema.org ListItem position convention where the homepage or site root is position 1 and the current page is highest. Typing it as a number (not a string) means you can sort, slice the first N ancestors, or detect gaps in the sequence without re-parsing, and a missing position returns null rather than being silently assumed.
items[].name	string	yes	The human-readable label of this trail step as it appears in the breadcrumb, such as a category name like 'Electronics' or the current page title. This is the field you index for categorization and taxonomy mapping. Because Extracto validates against the schema, a step whose label cannot be read comes back as null instead of a plausible-sounding category that was never on the page.
items[].url	string	optional	The canonical link target for this trail step, normally an absolute URL pointing at the category or section page. Returning it typed lets you build a clickable hierarchy graph and crawl parents deliberately one URL at a time. The final 'current page' step is often unlinked, so its url is correctly returned as null rather than fabricated, which keeps your hierarchy edges honest.
depth	number	yes	The total number of steps in the trail, a derived count equal to the length of items. Having depth as a first-class typed number lets you bucket pages by how deep they sit (top-level vs. deeply nested) and flag anomalies in a batch without iterating the array. When there is no breadcrumb, depth is null, distinguishing 'no trail found' from a genuine depth of zero.
currentPage	string	optional	The name of the last, current-page step in the trail, surfaced separately for convenience so you do not have to read the tail of items every time. It typically matches the page's own title and is the leaf of the hierarchy. If the trail does not mark a current page, this is returned as null instead of repeating an earlier ancestor as a stand-in.
sourceUrl	string	yes	The canonical URL of the page the breadcrumb trail was extracted from, echoed back so each result is self-describing in a batch. Typing and returning it lets you join breadcrumb hierarchy back to the originating page in your own store, and it is the URL whose position would be highest in items. It is null only if the page exposes no canonical reference.

The schema

Copy this and send it with any URL.

{
  "items": "array",
  "items[].position": "number",
  "items[].name": "string",
  "items[].url": "string",
  "depth": "number",
  "currentPage": "string",
  "sourceUrl": "string"
}

Example output

Validated JSON back, matching the schema.

{
  "items": [
    {
      "position": 1,
      "name": "Home",
      "url": "https://www.example-shop.com/"
    },
    {
      "position": 2,
      "name": "Electronics",
      "url": "https://www.example-shop.com/electronics"
    },
    {
      "position": 3,
      "name": "Headphones",
      "url": "https://www.example-shop.com/electronics/headphones"
    },
    {
      "position": 4,
      "name": "Sony WH-1000XM5 Wireless Headphones",
      "url": null
    }
  ],
  "depth": 4,
  "currentPage": "Sony WH-1000XM5 Wireless Headphones",
  "sourceUrl": "https://www.example-shop.com/electronics/headphones/sony-wh-1000xm5"
}

Try this breadcrumblist schema against a real page in the live demo, or read the docs to use it via the API.

BreadcrumbList schema: FAQ

What is the difference between this schema and scraping the breadcrumb HTML myself with CSS selectors?

With selectors you target a specific structure like '.breadcrumb li a' that varies site to site and breaks whenever the markup changes, and you still have to clean and order the results yourself. With Extracto you describe the fields (position, name, url, depth) and get typed, schema-validated JSON back regardless of whether the source used a JSON-LD BreadcrumbList, a visible nav element, or both. You maintain a small JSON schema instead of brittle, per-site selector code.

What happens when a page has no breadcrumb, or only a partial trail?

Extracto returns null for the missing pieces instead of guessing. If there is no breadcrumb at all, items and depth come back as null; if a single step has no link (common for the current page), just that url is null while the rest of the trail is intact. This null-not-guess behavior is the whole point: you never store a fabricated parent category, so the hierarchy you build from these results stays trustworthy across thousands of mixed pages.

Can Extracto read breadcrumbs on sites protected by Cloudflare or other anti-bot services?

Yes. Every request runs through a managed anti-bot bypass layer that handles protected sites such as Cloudflare, DataDome and PerimeterX, with proxies managed for you and no setup, and pages are rendered in a real headless browser so JavaScript-built breadcrumbs resolve correctly. It works on any public HTTPS URL. The one exception is login-gated content that needs session cookies, such as private profile pages, which is available on the Enterprise plan.

Why return depth as a separate number when I could just count the items array myself?

Surfacing depth as a typed first-class field lets you filter and bucket large batches without iterating every array. You can quickly find deeply nested pages, flag top-level pages, or detect anomalies across a crawl using a single numeric field. It also makes the 'no trail found' case explicit: depth is null when there is no breadcrumb, which is semantically clearer than an array length of zero and avoids ambiguous edge cases.