Breadcrumb Structured Data: Mark Up BreadcrumbList in JSON-LD

A breadcrumb trail is the row of links near the top of a page that shows where you are: Home, then Books, then Science Fiction, then the page itself. It helps visitors move up a level. Breadcrumb structured data describes the same trail in a format search engines can read, so they can understand how your pages fit together.

This guide shows how to add BreadcrumbList markup in JSON-LD, what each property means, how to handle pages with more than one path, and how to test the result. It is for site owners and developers who already have a visible breadcrumb trail, or who are about to add one. You do not need a developer for a small site, but you do need to be able to edit templates.

Set expectations carefully. Google's documentation says the breadcrumb feature is available on desktop in all regions and languages where Google Search is available. Valid markup does not mean Google will show breadcrumbs for your pages, and Google describes structured data as something that can enable enhanced results, not something that promises them.

Before you begin

You need a site with a real hierarchy (categories, sections, parent pages), edit access to the page template or your SEO plugin, and a few example URLs to test. Plan about an hour. If an SEO plugin or theme already outputs breadcrumb markup, check the page source first so you do not add a second copy.

The rule that matters most comes from Google's general structured data guidelines: do not mark up content that is not visible to readers of the page. Your markup must describe a breadcrumb trail that users can actually see. Add the visible trail first if you do not have one. Google also says structured data issues can lead to a manual action that makes the page ineligible for rich results, so keep the markup honest.

What the markup looks like

Google supports JSON-LD, Microdata and RDFa for structured data, and recommends JSON-LD because it is easiest to implement and maintain at scale. A breadcrumb trail is a BreadcrumbList, which is an ordered list of ListItem entries. Here is the structure Google documents, using a neutral example:

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Guides",
      "item": "https://example.com/guides"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "On-Page SEO",
      "item": "https://example.com/guides/on-page-seo"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Breadcrumb Structured Data"
    }
  ]
}

Place this JSON inside a script element with the type application/ld+json, in the page's HTML.

The properties:

itemListElement holds the ordered array of breadcrumbs. Google requires at least two ListItem entries.
position is an integer. Position 1 is the start of the trail. Schema.org says that markup order alone does not define sequence, so always include position.
name is the title shown to users for that step.
item is the URL of that step. Google lists it as required, with one exception: for the last item in the trail, item is not required. If you leave it out, Google uses the URL of the page that contains the markup.

Schema.org describes BreadcrumbList as a chain of linked pages, typically ending with the current page, and as a subtype of ItemList.

Step-by-step instructions

Step 1: Decide what the trail should show

Why: Google recommends providing breadcrumbs that represent a typical user path to a page, instead of mirroring the URL structure. A product at /p/48213 might sit under Home, Kitchen, Knives. The trail should reflect how a person would navigate, not how the file system is arranged.

You do not need a ListItem for the top-level domain or for the page itself, according to Google's page. Many sites still include the current page as the final item, which Google's own example does. Choose one approach and use it consistently.

How to confirm: you can write down the trail for a sample page from each template, and it matches what a visitor sees.

Why: the markup must match visible content. Use a simple list of links inside a navigation landmark.

<nav aria-label="Breadcrumb">
  <ol>
    <li><a href="/guides">Guides</a></li>
    <li><a href="/guides/on-page-seo">On-Page SEO</a></li>
    <li aria-current="page">Breadcrumb Structured Data</li>
  </ol>
</nav>

How to confirm: the trail appears on the page, each step except the last is a working link, and the text matches the name values you will put in the markup.

Step 3: Generate the JSON-LD from the same data

Why: if the visible trail and the markup come from different code, they drift apart. In your template or framework, build both from one list of (name, URL) pairs. Number the positions from 1. Use absolute URLs in item. Escape special characters in names, such as quotation marks, so the JSON stays valid.

How to confirm: view the page source and compare the JSON-LD names and URLs with the visible links, one by one.

Step 4: Place it in the page

Why: the script block can sit in the <head> or the <body>. Output it in the server-delivered HTML where possible so crawlers see it without needing to run scripts.

How to confirm: the JSON-LD block appears in the view-source output, not only in the rendered DOM.

Step 5: Handle pages with several paths

Why: a page can belong to more than one category. Google says that for a page reachable by more than one path you can provide multiple BreadcrumbList objects, for example a JSON-LD array with one object per trail. Include only trails that real visitors can follow and that reflect the page.

[
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
      { "@type": "ListItem", "position": 1, "name": "Kitchen", "item": "https://example.com/kitchen" },
      { "@type": "ListItem", "position": 2, "name": "Knives" }
    ]
  },
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
      { "@type": "ListItem", "position": 1, "name": "Gifts", "item": "https://example.com/gifts" },
      { "@type": "ListItem", "position": 2, "name": "Knives" }
    ]
  }
]

How to confirm: each object is valid on its own and has its own position numbering starting at 1.

Step 6: Test before and after launch

Why: Google recommends validating with the Rich Results Test and, once deployed, checking pages with the URL Inspection tool. The Rich Results Test validates structured data during development and can preview some features. Search Console rich result reports help you monitor pages after deployment, because template or serving problems can break markup later. For a deeper walk-through of testing, see JSON-LD Validation: Test and Debug Structured Data.

How to confirm: the test finds a valid BreadcrumbList with the expected number of items and no errors.

Step 7: Roll out by template and monitor

Why: breadcrumbs are templated, so fix one template at a time. Start with your most common page type. After the rollout, give Google time to crawl. Google's page tells you to submit a sitemap and allow several days for crawling and indexing. Keep your sitemap current, as described in How to Create a Valid XML Sitemap for Your Website.

How to confirm: after crawling, the Search Console report for breadcrumbs, if it appears for your site, shows valid items. If no report appears, that does not mean the markup is wrong; it may mean Google has not processed enough pages yet.

It does not create breadcrumbs in search results on its own. Google decides whether to show them.
It does not fix a confusing site structure. See Site Architecture for SEO: Plan a Flat, Clear Structure Before Launch for that.
The old data-vocabulary.org markup is no longer eligible for Google rich result features, according to Google's page. Use schema.org.
It does not replace internal links. Crawlers still discover pages through links; see Internal Linking Strategy: Link Pages So People and Crawlers Find What Matters.

Crawvix's structured data check parses the JSON-LD blocks on sampled pages and reports blocks that do not parse or are missing key fields; for BreadcrumbList it looks for itemListElement.

Final verification checklist

A visible breadcrumb trail exists on every page that has markup.
The JSON-LD uses @type: BreadcrumbList with itemListElement.
There are at least two ListItem entries (or two steps in each trail).
Every ListItem has an integer position, starting at 1 and increasing.
Every item except possibly the last has a name and an absolute item URL.
Names and URLs in the markup match the visible links.
The JSON-LD is in the delivered HTML and parses without errors.
The Rich Results Test shows no errors for sample pages from each template.

Common mistakes to avoid

Marking up a trail nobody can see. Add the visible trail, then the markup.
Mirroring the URL structure. Use a path that makes sense to people.
Forgetting position. Sequence is not defined by order alone.
Relative URLs or wrong hostnames in item. Use full absolute URLs of the final, canonical pages.
Leaving staging URLs in the markup. Test the live site.
Duplicate markup from a plugin and a theme. Remove one.
Breaking JSON with unescaped quotes. Use a JSON encoder, not string concatenation.

Frequently asked questions

Do breadcrumbs improve rankings?

Google does not say so in its breadcrumb documentation. It says breadcrumb trails help users understand and explore a site. Do not expect a ranking change from the markup alone.

Does Google show breadcrumbs on mobile?

Google's breadcrumb page states that the feature is available on desktop in all regions and languages where Google Search is available, and does not mention mobile. Treat mobile display as not documented.

Should the last item have a URL?

It does not have to. Google says item is not required for the last item, and that Google then uses the URL of the containing page. Including it is also fine.

At least two items are required. Beyond that, include the levels a visitor would actually use to move up the site, not more.

Can I use Microdata or RDFa instead of JSON-LD?

Yes. Google supports all three formats, but recommends JSON-LD.

Will invalid markup hurt my pages?

Invalid markup usually makes the page ineligible for the rich result. Misleading markup that breaks Google's guidelines can lead to a manual action, which removes eligibility for rich results; Google states it does not affect ranking in web search.

Official references

Next step: See how Crawvix checks a website and capture a baseline once scanning opens. This guide provides technical information, not a guarantee of rankings, traffic or index inclusion.