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. Breadcrumbs refer to the breadcrumbs we output in Schema.org structured data, not the HTML breadcrumbs that are visible on a website. Please be aware that this article contains technical jargon.

Breadcrumbs schema before v16.2

To show the changes, this is the breadcrumbs schema for the example page https://staging.yoast.com/wordpress/plugins/seo/. Below, you’ll see the schema output looked before Yoast SEO version 16.2.

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

The breadcrumb schema is a list, containing 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 final breadcrumb piece changed. It now looks like below:

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

In the final breadcrumb entry, all properties in the item are removed except for the @id.

Why did we remove those properties?

The final entry in our breadcrumb schema should always describe the current page, the page you’re on. But our schema already contains a description of that page. It may look like the following code:

"@type": "WebPage",
"@id": "https://staging.yoast.com/wordpress/plugins/seo/#webpage",
"url": "https://staging.yoast.com/wordpress/plugins/seo/",
"name": "Yoast SEO: the #1 WordPress SEO Plugin \u2022 Yoast",
"isPartOf": {
  "@id": "https://staging.yoast.com/#website"
},
"primaryImageOfPage": {
  "@id": "https://staging.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.yoast.com/wordpress/plugins/seo/#breadcrumb"
},
"inLanguage": "en-US"

We don’t want 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.

Intead of describing the webpage in both places and to clarify it’s the same webpage, we can reference the existing description via its @id property.

You can see that the ID of the webpage is the same as the ID used in the final breadcrumb entry. 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 cause 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 doesn’t 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. 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 cases 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 include further changes to our breadcrumb schema output.

Breadcrumb schema in Yoast SEO v16.5 onwards

Following the release of Yoast SEO 16.2, Google wasn’t displaying our breadcrumb schema correctly in the search results in some cases. 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 below.

"@type": "BreadcrumbList",
"@id": "https://staging.yoast.com/wordpress/plugins/seo/#breadcrumb",
"itemListElement": [
  {
    "@type": "ListItem",
    "position": 1,
    "name": "Home",
    "item": "https://staging.yoast.com/"
    }
  },
  {
    "@type": "ListItem",
    "position": 2,
    "name": "WordPress plugins"
    "url": "https://staging.yoast.com/wordpress/plugins/"
    }
  },
  {
    "@type": "ListItem",
    "position": 3,
    "item": "https://staging.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.