BreadcrumbList: Clarify position and how it interacts with itemListOrder

[pierrefar]

http://schema.org/BreadcrumbList
http://schema.org/itemListElement

For http://schema.org/BreadcrumbList, the example has an itemListElement with two ListItems. They each have a position but it's not clear what it means.

For example, what do these code examples mean?

The current code example:

{
            "@type": "BreadcrumbList",
            "itemListElement":
            [
                {
                    "@type": "ListItem",
                    "position": 1,
                    "item":
                    {
                        "@id": "https://example.com/dresses",
                        "name": "Dresses"
                    }
                },
                {
                    "@type": "ListItem",
                    "position": 2,
                    "item":
                    {
                        "@id": "https://example.com/dresses/real",
                        "name": "Real Dresses"
                    }
                }
            ]
        }

With an extra hint about the order:

{
            "@type": "BreadcrumbList",
            "itemListOrder": "ItemListOrderDescending",
            "itemListElement":
            [
                {
                    "@type": "ListItem",
                    "position": 1,
                    "item":
                    {
                        "@id": "https://example.com/dresses",
                        "name": "Dresses"
                    }
                },
                {
                    "@type": "ListItem",
                    "position": 2,
                    "item":
                    {
                        "@id": "https://example.com/dresses/real",
                        "name": "Real Dresses"
                    }
                }
            ]
        }

And should the itemListOrder be ItemListOrderDescending (going deeper into the leaf structure of a site) or ItemListOrderAscending (meaning???) for breadcrumbs?

[danbri]

Thanks @PFAR :)

@vholland - this is indeed a bit unclear, partly because the metaphor of 'ascending' pulls in two directions. For "top 10" lists, intuition says that being at the top of the list, at 0 or 1, is the highest you can be. But numerically, higher numbers are in the other direction.

For breadcrumbs it seems like the implicit model we've used is that the homepage or top of the site nav tree is position: 1, with each page's breadcrumbs asigning higher numbers to deeper (typically more specific) pages. Now how to express that in terms of ItemListOrderAscending?

[jvandriel]

As for the 'itemListorder', can we keep the working the same as it it is in HTML5? For example:

Acscending:

<ol>
  <li>Coffee</li>
  <li>Tea</li>
</ol>

Translates to:

{
            "@type": "ItemList",
            "itemListOrder": "ItemListOrderAscending",
            "itemListElement":
            [
                {
                    "@type": "ListItem",
                    "position": 1,
                    "item":
                    {
                        "@id": "https://example.com/coffee",
                        "name": "Coffee"
                    }
                },
                {
                    "@type": "ListItem",
                    "position": 2,
                    "item":
                    {
                        "@id": "https://example.com/tea",
                        "name": "Tea"
                    }
                }
            ]
        }

Both generate:

1. Coffee (first item in the list)
2. Tea (second item in the list)

Descending:

<ol reversed="reversed">
  <li>Coffee</li>
  <li>Tea</li>
</ol>

Translates to:

{
            "@type": "ItemList",
            "itemListOrder": "ItemListOrderDescending",
            "itemListElement":
            [
                {
                    "@type": "ListItem",
                    "position": 1,
                    "item":
                    {
                        "@id": "https://example.com/coffee",
                        "name": "Coffee"
                    }
                },
                {
                    "@type": "ListItem",
                    "position": 2,
                    "item":
                    {
                        "@id": "https://example.com/tea",
                        "name": "Tea"
                    }
                }
            ]
        }

Both generate:
2. Coffee (first item in the list)

1. Tea (second item in the list)

[pierrefar]

@jvandriel To make sure I understand, we'd be asking the parser to first order by position as ItemListOrderAscending by default, and then reversing the order if it's ItemListOrderDescending.

Another point to note: position can be an integer or text (e.g. "Episode 3"). How should that apply to breadcrumbs?

[jvandriel]

@pierrefar In regards to BreadCrumbList, personally I think it would be best if the default order is ItemListOrderAscending indeed, to be reversed if ItemListOrderDescending has been specified.

As for position's 'integer or text', if I recall the discussions about ItemList correctly, 'text' was added so folks would be able to express list styles 'a,b,c' or 'I, II, III' and such as well. However to me this doesn't seem to make much sense for BreadcrumbList, so I'm not quite sure how to deal with this. (I can't remember if this was actually discussed for BreadcrumbList. @danbri - Any thoughts?

And just to make sure you're aware, itemPosition isn't the only way to markup the order of elements. This can also be achieved by using prevItem and nextItem, eg:

<ol itemscope itemtype="http://schema.org/BreadcrumbList">
    <li itemid="#listElement-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
        <a itemprop="item" href="https://example.com/dresses">
            <span itemprop="name">Dresses</span>
        </a>
        <link itemprop="next" href="#listElement-2">
    </li>
    <li itemid="#listElement-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
        <a itemprop="item" href="https://example.com/dresses/real">
            <span itemprop="name">Real Dresses</span>
        </a>
        <link itemprop="previousItem" href="#listElement-1">
        <link itemprop="nextItem" href="#listElement-3">
    </li>
    <li itemid="#listElement-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
        <a itemprop="item" href="https://example.com/dresses/real/mini-skirts">
            <span itemprop="name">Mini skirts</span>
        </a>
        <link itemprop="previousItem" href="#listElement-2">
    </li>
</ol>

[danbri]

Summary as I see it:

ItemList

• ItemList gives schema.org a notion of lists, and that lists have beginnings and an order.
• Since ItemLists are described using an unordered data model (triples/graphs) we have to be able to reconstruct them from their description. The values of the position property are used for this.
• an itemListOrder of ItemListOrderAscending (lower values listed first) or ItemListOrderDescending (higher values listed first) tells us how to interpret the values of "position".
• Unless you have arranged otherwise, the specific values of "position" carry no meaning - they serve only to order items. A list whose itemListOrder was ItemListOrderAscending could begin at 0, at 1, or 100.
• In theory an ItemList could be partially described across several different Web pages. In practice there might be some complications. However the numberOfItems of an ItemList should tell you the full size of the ItemList, rather than e.g. the number of items from the list that are mentioned in some particular page.

BreadcrumbList

• The BreadcrumbList convention is that a breadcrumb list has an itemListOrder of ItemListOrderAscending (lower values listed first), and that the first items in this list correspond to the "top" or "beginning" of the breadcrumbs trail, e.g. with a site homepage or section entry point.
• As with ItemList in general, the specific values of 'position' carry no intrinsic meaning, they are only used to establish order. Starting from 1 would be a reasonable common pattern.

BTW there are some other points around BreadcrumbList worth attention, but unrelated to ordering. I've put some notes online at https://docs.google.com/document/d/1wspgGcdXLDzAa3l78rYF3weNZhcb3lfiuxRZ6xFxrjc/edit?usp=sharing

[danbri]

I've commited text to this effect, am closing this issue. If anyone here thinks more is needed, do let us know.

[danbri]

staged: http://sdo-gozer.appspot.com/BreadcrumbList

[jvandriel]

Looking back at this I have to say I am a bit uncomfortable with the microdata example as the item property's value is a URL, yet according to the specs item's expected value is a schema.org/Thing.

Shouldn't the expected value for item therefore be expanded with URL, or does that get us into trouble with schema.org/ItemList?

[danbri]

@jvandriel everything is a Thing. And any time we expect some kind of thing, we can also be handed a URL for it instead of an inline description of it. Microdata vs RDFa/JSON-LD (or schema.org and RDF for that matter) talk about these issues a bit differently, but it is OK. Related: when we say in schema.org that the range of a property includes URL, this is a bit different to everything else. It really means "we expect a lot of the time, this property will be used with URL identifiers rather than an inline description. It feels weird because it somewhat mixes up different layers of the system, but I think we can live with it.

[jvandriel]

Sorry, I realize I wasn't specific enough with my question, I was looking at it from a general webmaster perspective. One of the complaints I often get when explaining this to juniors/mediors is that they don't understand why, if a URL is allowed, the expected value just doesn't simply say so?

http://schema.org/image does so for example, and it's this type of inconsitancy in the specs that makes it difficult to come to grips with for many.

And looking at it from that POV the current microdata example doesn't really help to to support the notion that one should pay attention to the expected values indicated. Especially since many webmaster/devs aren't aware about what you just stated.