Breadcrumb schema changes in Yoast SEO

In Yoast SEO for WordPress 16.2, we changed how we format the Schema.org markup for a webpage’s breadcrumb navigation. Following this release, we received numerous reports about third-party SEO tools mistakenly showing warnings relating to this change. In most cases, these warnings can be safely ignored. However, in some cases, the changes we made might have revealed other, pre-existing Schema.org issues.

As a result, we’ve made several further changes and improvements to our breadcrumb schema, and we’re likely to make further refinements in the future.

If you’re seeing issues or errors on your website, or in SEO tools, this article aims to help you to understand whether you need to take any action. Please be aware that this article may be a bit technical. Though we try to document it as accessible as possible, you will still need to know a bit of jargon to understand the full story.

From this point onward, when we talk about breadcrumbs, we mean the breadcrumbs we output in Schema.org structured data, and not the HTML breadcrumbs that are visible on a website.

Breadcrumbs schema before v16.2
Breadcrumbs schema between v16.2 and v16.5
Breadcrumb schema in Yoast SEO v16.5 onwards

Breadcrumbs schema before v16.2

To show you what changed, we’ll look at the breadcrumbs schema for this example page: https://staging-platform.yoast.com/wordpress/plugins/seo/. This is what the schema output looked like before Yoast SEO version 16.2.

"@type": "BreadcrumbList",
"@id": "https://staging-platform.yoast.com/wordpress/plugins/seo/#breadcrumb",
"itemListElement": [
  {
    "@type": "ListItem",
    "position": 1,
    "item": {
      "@type": "WebPage",
      "@id": "https://staging-platform.yoast.com/",
      "url": "https://staging-platform.yoast.com/",
      "name": "Home"
    }
  },
  {
    "@type": "ListItem",
    "position": 2,
    "item": {
      "@type": "WebPage",
      "@id": "https://staging-platform.yoast.com/wordpress/plugins/",
      "url": "https://staging-platform.yoast.com/wordpress/plugins/",
      "name": "WordPress plugins"
    }
  },
  {
    "@type": "ListItem",
    "position": 3,
    "item": {
      "@type": "WebPage",
      "@id": "https://staging-platform.yoast.com/wordpress/plugins/seo/#webpage",
      "url": "https://staging-platform.yoast.com/wordpress/plugins/seo/",
      "name": "Yoast SEO: the #1 WordPress SEO Plugin \u2022 Yoast"
    }
  }
]

We can see that our breadcrumb schema is a list, which contains three individual ListItem ‘pieces’. Each of those pieces contains an item, which provides information about a WebPage. Collectively, this describes where the user, and the ‘current page’, are on the website.

Breadcrumbs schema between v16.2 and v16.5

From version 16.2 onward, the way in which we build the final breadcrumb piece changed. It now looks like this:

"@type": "BreadcrumbList",
"@id": "https://staging-platform.yoast.com/wordpress/plugins/seo/#breadcrumb",
"itemListElement": [
  {
    "@type": "ListItem",
    "position": 1,
    "item": {
      "@type": "WebPage",
      "@id": "https://staging-platform.yoast.com/",
      "url": "https://staging-platform.yoast.com/",
      "name": "Home"
    }
  },
  {
    "@type": "ListItem",
    "position": 2,
    "item": {
      "@type": "WebPage",
      "@id": "https://staging-platform.yoast.com/wordpress/plugins/",
      "url": "https://staging-platform.yoast.com/wordpress/plugins/",
      "name": "WordPress plugins"
    }
  },
  {
    "@type": "ListItem",
    "position": 3,
    "item": {
      "@id": "https://staging-platform.yoast.com/wordpress/plugins/seo/#webpage"
    }
  }
]

Notice the difference? In the final breadcrumb entry, we’ve removed all of the properties in the item except for the @id.

Why did we remove those properties?

The final entry in our breadcrumb schema should always describe the ‘current’ page – the one that you’re on. But our schema already contains a description of that page, elsewhere. That might look something like this:

"@type": "WebPage",
"@id": "https://staging-platform.yoast.com/wordpress/plugins/seo/#webpage",
"url": "https://staging-platform.yoast.com/wordpress/plugins/seo/",
"name": "Yoast SEO: the #1 WordPress SEO Plugin \u2022 Yoast",
"isPartOf": {
  "@id": "https://staging-platform.yoast.com/#website"
},
"primaryImageOfPage": {
  "@id": "https://staging-platform.yoast.com/wordpress/plugins/seo/#primaryimage"
},
"datePublished": "2010-10-11T20:07:47+00:00",
"dateModified": "2021-04-23T11:29:05+00:00",
"description": "Yoast SEO is the #1 WordPress SEO plugin.",
"breadcrumb": {
  "@id": "https://staging-platform.yoast.com/wordpress/plugins/seo/#breadcrumb"
},
"inLanguage": "en-US"

It doesn’t make sense for us to describe the page you’re on twice. And, we want to make it clear in our schema that the page you’re on is the same page as the one we’re describing in the breadcrumb list; not a different or duplicate page.

So, instead of describing the webpage in both places, and to make it clear that we’re talking about the same webpage, we can reference the existing description via its @id property.

That’s what we’ve done here. You can see that the ID of the webpage is the same as the ID used in the final breadcrumb entry. That’s just a way of saying: “These are the same thing”. This is a big improvement to our schema, in terms of semantics, and in terms of efficiency.

With this approach, our final breadcrumb entry has a name, because, it’s the same thing as the WebPage.

Errors with relating to missing ‘name’ properties in third-party tools

Google’s breadcrumb rich results require each breadcrumb item to have a name property. You can see what that looks like in our example breadcrumb markup above.

In our 16.2 update, we intentionally removed the name property from the final breadcrumb entry, and instead reference the existing WebPage schema on the page (and use the name from that). This approach might have caused you to receive name-related error messages in third-party tools for one of two reasons:

1. The third-party tool that you use isn’t reading the schema code correctly

Even though we removed the name property from the final breadcrumb entry, it still has a name – it’s just located in the schema markup where we describe the WebPage which we’re referencing by ID.

If the SEO tool you’re using isn’t smart enough to ‘follow’ those connections and references (e.g., if it’s just scanning the code to see if it can find a name attached to the final breadcrumb entry), it may misreport this as having a missing name property.

Google shouldn’t have any problems in this case; which you can validate by testing your page with the Google Rich results tool or the official Schema.org validator. These tools should show that the final entry in your breadcrumbs list is ‘merged’ with the WebPage schema.

2. The name of the page you are on is empty

In some cases, it appears that the name of the WebPage – not of the breadcrumb entry – may be missing on your page. That means that, when we ‘merge’ the final breadcrumb entry with the WebPage piece, it ‘inherits’ that missing name.

This is a known type of bug, and in most of the cases we’ve come across, it’s a compatibility issue with another plugin or theme. These problems didn’t previously result in errors, because the name property that we used to have on the breadcrumb entry ‘hid’ the missing value. This warning will also show up in tools that can correctly traverse schema data and use references.

What can you do?

Most cases that we see are caused by the first issue. If you experience that, your best bet is to contact the people who develop the tool that you’re using. You can point them to this article for more information.

However, if you see this warning in a tool that can correctly traverse schema and apply references, like the Schema validator, your page is most likely suffering from the second issue.

Most importantly, you should make sure that you’re running the most up-to-date version of Yoast SEO, as later releases included further changes to our breadcrumb schema output.

Following the release of Yoast SEO 16.2, we discovered several cases where Google wasn’t displaying our breadcrumb schema correctly in the search results. Despite our output being technically and semantically correct, Google’s implementation didn’t adhere to schema.org’s documentation.

To protect our users, we made an immediate decision to ‘roll back’ and radically simplify our breadcrumb schema output. We chose, in the short-term, to align precisely to Google’s breadcrumb documentation. Our output now looks like this:

"@type": "BreadcrumbList",
"@id": "https://staging-platform.yoast.com/wordpress/plugins/seo/#breadcrumb",
"itemListElement": [
  {
    "@type": "ListItem",
    "position": 1,
    "name": "Home",
    "item": "https://staging-platform.yoast.com/"
    }
  },
  {
    "@type": "ListItem",
    "position": 2,
    "name": "WordPress plugins"
    "url": "https://staging-platform.yoast.com/wordpress/plugins/"
    }
  },
  {
    "@type": "ListItem",
    "position": 3,
    "item": "https://staging-platform.yoast.com/wordpress/plugins/seo/#webpage"
  }
]

Whilst this approach reduces the quality of our schema overall, it guarantees that our users can take advantage of rich breadcrumb results.

We may revisit this approach in future updates, and explore opportunities to gradually ‘re-enrich’ our breadcrumb markup.