Skip to main content

Schema piece - Breadcrumb

Describes the hierarchical position a WebPage within a WebSite.

Triggers

Should be added as top-level node in the graph, on all public pages which have a valid WebPage, except for 4xx and 5xx range error pages/scenarios.

Required properties

A valid BreadcrumbList must have the following properties.

  • @type: BreadcrumbList.
  • @id: The site's home URL appended by #/schema/BreadcrumbList/{{ID}}, where {{ID}} is a unique identifier for the 'parent' webpage.
  • itemListElement: An array of ListItem objects, representing the position of the current page in the site hierarchy, each with the following properties:
    • position: An integer (starting at 1), counting the 'depth' of the page from (including) the homepage.
    • name: The name of the page in question, as it appears in the breadcrumb navigation.
    • item: The unmodified canonical URL of the page in question.

Also note that:

  • Paginated states should not be included/represented in the list.
  • The final/current 'crumb' should omit the item property.

Failure scenarios

If any of the required fields are missing or invalid, the node should not be output.

If the node is not output, any entities which would otherwise have declared a relationship with the BreadcrumbList should remove those references.

Examples

Minimum criteria

{
"@context": "https://schema.org",
"@graph": [
{
"@type": "BreadcrumbList",
"@id": "https://www.example.com/#/schema/BreadcrumbList/abc123",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://www.example.com/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Example Section",
"item": "https://www.example.com/example-section/"
},
{
"@type": "ListItem",
"position": 3,
"name": "Example Page"
}
]
}
]
}

WordPress API: Change Breadcrumb Schema output

To make changes to the Breadcrumb schema that Yoast SEO outputs, you can use our wpseo_schema_breadcrumb filter. Here is an example:

Replace domain name in the breadcrumb schema


If you want to replace the domain name in the breadcrumb schema, you can use the `wpseo_schema_breadcrumb` filter to hook into the breadcrumb schema piece individually.
add_filter( 'wpseo_schema_breadcrumb', 'replace_domain_name_to_breadcrumb_schema', 11, 2 );
/**
* Replace domain name in the breadcrumb schema piece individually.
*
*
* @param array $piece Schema.org Breadcrumb data array.
* @return array Altered Schema.org Breadcrumb data array.
*/
function replace_domain_name_to_breadcrumb_schema( $piece ) {
$piece['@id'] = str_replace( 'olddomain.tld', 'newdomain.tld', $piece['@id'] );
foreach ( $piece['itemListElement'] as &$list ) {
$list['item'] = str_replace( 'olddomain.tld', 'newdomain.tld', $list['item'] );
if ( $list['item'] ) {
}
}
return $piece;
}

To make more changes to our Schema output, see the Yoast SEO Schema API.