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

[travelton]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

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>

Your environment

• Public source code: https://github.com/travelton/docusaurus-schema-bug
• Public site URL: N/A (Simply run yarn start and utilize the local dev instance)
• Docusaurus version used: 3.7.0
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node v18.19.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS 15.2 (Chrome Version 132.0.6834.84 (Official Build) (arm64))

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Looks like a duplicate of #9319