Collection Page Schema
One page that lists several recipes, each with a page of its own: a CollectionPage with an ItemList of every recipe page in page order, which is what makes the set eligible for a carousel.
When To Use It
Use on a page that lists several items of one kind, where each item has its own page: a recipe collection, a course index, a film list or a restaurant guide. The list holds the address of every item page, in the order the page shows them.
Google only shows a carousel for recipes, courses, movies and restaurants. A category of products is not one of them, so on a product category page the builder leaves the list out and outputs the page and its breadcrumb. Product markup belongs on the product pages, not on the page that lists them.
Frameworks On This Page
Each card opens the framework for that feature, with its own rules and property reference. Cards marked "Linked by @id" are defined on the homepage and only referenced here.
Carousel
On this page. ItemList with a position and the address of each item page. Schema framework OpenBreadcrumb
On this page. Home, Journal, Camp Recipes. Schema framework OpenRecipe
Linked by address. Each address in the list is a recipe page that carries its own Recipe. Schema framework OpenOrganization
Linked by @id. Publisher of the page, by @id from the homepage. Schema framework OpenHow The Pieces Connect
Every node has a stable @id. A node is written out once, where it belongs, and everywhere else it is referenced by that @id alone. This is the map for this page, generated from the output below.
| @id | Defined on | Type | Referenced by |
|---|---|---|---|
/journal/camp-recipes/#webpage | This page | CollectionPage | Top-level node |
/journal/camp-recipes/#breadcrumb | This page | BreadcrumbList | CollectionPage.breadcrumb |
/journal/camp-recipes/#list | This page | ItemList | CollectionPage.mainEntity |
/#organization | Homepage | OnlineStore | CollectionPage.publisher |
/#website | Homepage | WebSite | CollectionPage.isPartOf |
The Builder
One function turns the page's data into the whole graph. It drops anything Google would reject instead of shipping it half built. A list is all or nothing, because it has to hold every item the page shows: one item that fails and the whole list is left out. The input below is a list that passes.
// Collection page schema: a page that lists several items, each with its own
// page. A CollectionPage with its BreadcrumbList and, when the list is one
// Google shows as a carousel, an ItemList of the item pages in page order.
//
// Google only shows a carousel for recipes, courses, movies and restaurants,
// and only when the list holds every item on the page, each with its own
// address on this site. A list that falls short is left out whole: half a
// list is worse than none, because it no longer matches the page.
const clean = (v) => (typeof v === 'string' ? v.trim() : v);
const isUrl = (v) => typeof v === 'string' && /^https:\/\/[^\s]+$/.test(v);
const compact = (obj) => {
if (Array.isArray(obj)) {
const out = obj.map(compact).filter((v) => v !== undefined);
return out.length ? out : undefined;
}
if (obj && typeof obj === 'object') {
const out = {};
for (const [k, v] of Object.entries(obj)) {
const c = compact(v);
if (c !== undefined) out[k] = c;
}
return Object.keys(out).length ? out : undefined;
}
return obj === null || obj === '' ? undefined : obj;
};
function breadcrumb(trail, id) {
const items = (trail || []).filter((c) => c.name && isUrl(c.url));
if (items.length < 2) return undefined;
return {
'@type': 'BreadcrumbList',
'@id': id,
itemListElement: items.map((c, i) => ({ '@type': 'ListItem', position: i + 1, name: clean(c.name), item: c.url })),
};
}
// The item types Google shows as a carousel.
const CAROUSEL_TYPES = ['recipe', 'course', 'movie', 'restaurant'];
// Every listed item, in page order, or nothing.
function carouselItems(list, pageUrl) {
const items = list.items || [];
if (!CAROUSEL_TYPES.includes(list.itemType)) return undefined;
// A course list needs three courses. Any other list needs two.
if (items.length < (list.itemType === 'course' ? 3 : 2)) return undefined;
const host = new URL(pageUrl).hostname;
const urls = items.map((i) => i.url);
if (!urls.every((u) => isUrl(u) && new URL(u).hostname === host)) return undefined;
if (new Set(urls).size !== urls.length) return undefined;
return urls.map((url, i) => ({ '@type': 'ListItem', position: i + 1, url }));
}
function buildCollectionPageSchema(source) {
const site = source.site || {};
const page = source.page || {};
const list = source.collection || {};
if (!isUrl(site.url) || !isUrl(page.url) || !list.name) return null;
const root = site.url.replace(/\/+$/, '');
const pageUrl = page.url;
const listId = `${pageUrl}#list`;
const elements = carouselItems(list, pageUrl);
const itemList = elements
? { '@type': 'ItemList', '@id': listId, name: clean(list.name), itemListElement: elements }
: undefined;
const crumbs = breadcrumb(page.breadcrumbs, `${pageUrl}#breadcrumb`);
const webpage = compact({
'@type': 'CollectionPage',
'@id': `${pageUrl}#webpage`,
url: pageUrl,
name: clean(page.title) || clean(list.name),
description: clean(list.description),
isPartOf: { '@id': `${root}/#website` },
publisher: { '@id': `${root}/#organization` },
breadcrumb: crumbs ? { '@id': crumbs['@id'] } : undefined,
mainEntity: itemList ? { '@id': listId } : undefined,
});
return { '@context': 'https://schema.org', '@graph': [webpage, crumbs, itemList].filter(Boolean) };
}
{
"site": {
"url": "https://www.example.com"
},
"page": {
"url": "https://www.example.com/journal/camp-recipes/",
"title": "Camp Recipes | Harbor & Pine Journal",
"breadcrumbs": [
{
"name": "Home",
"url": "https://www.example.com/"
},
{
"name": "Journal",
"url": "https://www.example.com/journal/"
},
{
"name": "Camp Recipes",
"url": "https://www.example.com/journal/camp-recipes/"
}
]
},
"collection": {
"name": "Camp Recipes",
"description": "One-pot dinners, trail breakfasts and bakes that work on a camp stove.",
"itemType": "recipe",
"items": [
{
"name": "One-Pot Camp Chili",
"url": "https://www.example.com/journal/one-pot-camp-chili/"
},
{
"name": "Skillet Cornbread",
"url": "https://www.example.com/journal/skillet-cornbread/"
},
{
"name": "Overnight Trail Oats",
"url": "https://www.example.com/journal/overnight-trail-oats/"
},
{
"name": "Foil Packet Salmon",
"url": "https://www.example.com/journal/foil-packet-salmon/"
}
]
}
}
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "CollectionPage",
"@id": "https://www.example.com/journal/camp-recipes/#webpage",
"url": "https://www.example.com/journal/camp-recipes/",
"name": "Camp Recipes | Harbor & Pine Journal",
"description": "One-pot dinners, trail breakfasts and bakes that work on a camp stove.",
"isPartOf": {
"@id": "https://www.example.com/#website"
},
"publisher": {
"@id": "https://www.example.com/#organization"
},
"breadcrumb": {
"@id": "https://www.example.com/journal/camp-recipes/#breadcrumb"
},
"mainEntity": {
"@id": "https://www.example.com/journal/camp-recipes/#list"
}
},
{
"@type": "BreadcrumbList",
"@id": "https://www.example.com/journal/camp-recipes/#breadcrumb",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://www.example.com/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Journal",
"item": "https://www.example.com/journal/"
},
{
"@type": "ListItem",
"position": 3,
"name": "Camp Recipes",
"item": "https://www.example.com/journal/camp-recipes/"
}
]
},
{
"@type": "ItemList",
"@id": "https://www.example.com/journal/camp-recipes/#list",
"name": "Camp Recipes",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"url": "https://www.example.com/journal/one-pot-camp-chili/"
},
{
"@type": "ListItem",
"position": 2,
"url": "https://www.example.com/journal/skillet-cornbread/"
},
{
"@type": "ListItem",
"position": 3,
"url": "https://www.example.com/journal/overnight-trail-oats/"
},
{
"@type": "ListItem",
"position": 4,
"url": "https://www.example.com/journal/foil-packet-salmon/"
}
]
}
]
}
The Logic As A Flowchart
The same logic as the builder above, drawn for readers who do not write code. Every Yes moves down. A No that runs out to the line on the right stops everything, and no schema is output. Where the path splits, exactly one branch is taken. Each step was run against the builder itself before this page was published: 30 test cases, all passing.
-
A page that lists items which each have their own page
-
1Site has an https URL?the home page addressNo: no schemaYes
-
2Page has an https URL?the address of this pageNo: no schemaYes
-
3Collection has a name?the title of the listNo: no schemaYes
-
Is it a list Google shows as a carousel?recipes, courses, movies or restaurants, each with its own page on this siteYesAn ItemList holds the address of every item page, in page orderNoNo ItemList. The page and its breadcrumb are still output
-
Two or more breadcrumbs with a name and an https link?the trail shown on the pageYesA BreadcrumbList is added and linked from the pageNoNo BreadcrumbList
-
Build the linked nodesCollectionPage, with its publisher pointing at the homepage Organization by @id. Anything optional that is missing or invalid is left out
-
Output CollectionPageNo schema
Validation
The output above was run through the SchemaCDN validator, which checks every rule in Google's documentation for each feature. It was validated together with the homepage graph, so the @id links resolve. Result: no errors, and eligible for:
The validator reads this page alone and cannot open the links in the list, so it does not show the carousel among the features below. A list of links is eligible when each linked page carries its own Recipe markup, as the Recipe page type does.
Left Out On Purpose
- The recipes themselves. Each is described once, on its own page, and the list only points at those pages.
- Names and images on the list items. In a list of links, Google reads them from the pages the links open.
- numberOfItems. It adds nothing the list does not already say, and it goes stale when a recipe is added.
Implementation Checklist
- List every item the page shows, in the same order. A list with items missing no longer matches the page.
- Give every item its own address on this site. Two items that share an address, or a link to another site, stop the list.
- Make sure each linked page carries its own markup: a Recipe on a recipe page, a Course on a course page.
- Keep one kind of item per list. Recipes and courses on one page need two pages or no list.
- Rebuild the list whenever an item is added, removed or moved.