Invalid Breadcrumb SEO Microdata: "Position" Property Not Recognized by Schema.org Vocabulary

[travelton]

Bug submitted upstream in docusaurus repo.

facebook/docusaurus#10859

Description

The position property in the breadcrumb SEO microdata generated by Docusaurus is invalid according to the Schema.org vocabulary when a breadcrumb item (e.g., a category item in the sidebar) has no associated link. According to the Schema.org documentation, position is only valid within the context of ListItem, not directly under BreadcrumbList.

While this is not a high severity issue, it does cause a large amount of (noisy) "structured data items are invalid" errors within SEO auditing tools like SEMRush.

position: The property position is not recognized by Schema.org vocabulary.

This might have some relation to #7241.

The solution seems as simple as adding a conditional to the following line to only include when addMicroData evaluates to true. However, I do not have much experience under the hood with docusaurus to know if this has repercussions.
https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/src/theme/DocBreadcrumbs/index.tsx#L74

  return (
    <li
      {...(addMicrodata && {
        itemScope: true,
        itemProp: 'itemListElement',
        itemType: 'https://schema.org/ListItem',
      })}
      className={clsx('breadcrumbs__item', {
        'breadcrumbs__item--active': active,
      })}>
      {children}
      {addMicrodata && <meta itemProp="position" content={String(index + 1)} />}
    </li>
  );

Reproducible demo

https://github.com/travelton/docusaurus-schema-bug

Steps to reproduce

1. Clone the example repo. (https://github.com/travelton/docusaurus-schema-bug)
2. Run npm start
3. Go to http://localhost:3000/docs/tutorial-basics/create-a-document
4. Within the breadcrumb on the page, right click and inspect "Tutorial".
5. Observe the position microdata <meta itemprop="position" content="1"> outside of the ListItem, but within the BreadcumbList.
6. Copy the full HTML of the page
7. Go to https://validator.schema.org/ and paste the code into the validator. Run the validator.
8. Observe the error The property position is not recognized by the schema (e.g. schema.org) for an object of type BreadcrumbList.

Expected behavior

The position property should only appear within the ListItem context. For example:

<nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs">
    <ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList">
        <li class="breadcrumbs__item">
            <a aria-label="Home page" class="breadcrumbs__link" href="/">
                <svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT">
                    <path
                        d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z"
                        fill="currentColor"></path>
                </svg>
            </a>
        </li>
        <li class="breadcrumbs__item">
            <span class="breadcrumbs__link">Tutorial</span>
        </li>
        <li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem"
            class="breadcrumbs__item breadcrumbs__item--active">
            <span class="breadcrumbs__link" itemprop="name">Create a Document</span>
            <meta itemprop="position" content="1">
        </li>
    </ul>
</nav>

Actual behavior

The position property is being included within the BreadcumbList context, outside of the ListItem context. For example:

<nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs">
    <ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList">
        <li class="breadcrumbs__item">
            <a aria-label="Home page" class="breadcrumbs__link" href="/">
                <svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT">
                    <path
                        d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z"
                        fill="currentColor"></path>
                </svg>
            </a>
        </li>
        <li class="breadcrumbs__item">
            <span class="breadcrumbs__link">Tutorial</span>
            <meta itemprop="position" content="1">
        </li>
        <li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem"
            class="breadcrumbs__item breadcrumbs__item--active">
            <span class="breadcrumbs__link" itemprop="name">Create a Document</span>
            <meta itemprop="position" content="2">
        </li>
    </ul>
</nav>