SEO Structured Data¶
Badger puts schema.org structured data (JSON-LD) in the <head> of storefront pages so search engines can identify the site, its owner and its search box, read blog posts as articles, and show breadcrumb trails in results.
| Markup | Where | Built by |
|---|---|---|
WebSite + Organization (+ SearchAction) |
Every storefront page: home, CMS pages, collections, products, search, basket and checkout | SiteStructuredDataService |
BlogPosting |
Blog posts (pages using the blog/blogPost template) |
BlogPostingStructuredDataService |
Event |
Event product pages (products with the Event Ticket type and a start) | EventStructuredDataService |
BreadcrumbList |
Product and collection pages (Nova family) | BreadcrumbJsonLdRenderer |
Product › Offer (microdata) |
Product cards and product pages, every theme, only for a fixed-price product | the theme's productFragment/listingPageProduct.html (in Brock, Depot, Pop and Spec the shared ui/product-card.html) and productDetail.html, from DProduct.isMerchantListing() |
Product › AggregateRating (microdata) |
Product pages, every theme, only for a fixed-price product with a rating from reviews | the theme's productFragment/productDetail.html, from DProduct.isReviewed() |
This page covers the site-wide graph, blog posts and link previews. Breadcrumbs are covered by the breadcrumb fragment (templates/nova/fragment/breadcrumb.html).
Site-wide graph¶
Each page carries one <script type="application/ld+json"> holding an @graph with two nodes that point at each other by @id:
WebSite(<siteUrl>#website): the site name, its canonical URL, andpublisherpointing at the Organization. When search is available it also has apotentialActionSearchAction, which is what Google uses for the sitelinks search box.Organization(<siteUrl>#organization): the name, the URL, and then each of the following that is set:logosameAs: the social profileslegalName,address,identifier(company number) andvatID
Example, for a site with search available, a logo, two social accounts and legal entity details:
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebSite",
"@id": "https://acme.example.com#website",
"name": "Acme Outdoors",
"url": "https://acme.example.com",
"publisher": { "@id": "https://acme.example.com#organization" },
"potentialAction": {
"@type": "SearchAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://acme.example.com/search?q={search_term_string}"
},
"query-input": "required name=search_term_string"
}
},
{
"@type": "Organization",
"@id": "https://acme.example.com#organization",
"name": "Acme Outdoors",
"url": "https://acme.example.com",
"logo": "https://cdn.example.com/media/logo.png",
"sameAs": [
"https://www.facebook.com/acmeoutdoors",
"https://www.instagram.com/acmeoutdoors"
],
"legalName": "Acme Outdoors Limited",
"address": "1 High Street, Buxton, SK17 6AA",
"identifier": { "@type": "PropertyValue", "propertyID": "Company number", "value": "01234567" },
"vatID": "GB123456789"
}
]
}
Where each value comes from¶
| Property | Source |
|---|---|
url, the @ids |
https:// + the site's primary domain (domainURL). Other domains are not used, because they redirect to the primary one. |
name |
The site name (Site Identity). |
logo |
The site logo (Site Identity). CDN URLs that start with // get https:, and site-relative paths get the site URL. |
sameAs |
The social accounts (Site Identity). A bare handle becomes a profile URL using the same prefixes as the storefront's social links (SocialProfiles) (Facebook, Instagram, Twitter/X, LinkedIn company, YouTube channel, Pinterest, TikTok). A value that is already a URL is used as it is. A handle for an unknown network is dropped. |
legalName |
legal-entity-name, otherwise giftaid-org-name, so a charity that has set up Gift Aid doesn't have to enter its name twice. |
address |
legal-entity-registered-address. It is stored as one line, so it is output as text and not split into a PostalAddress. |
identifier |
legal-entity-company-number. |
vatID |
legal-entity-vat-number. |
The legal entity keys are the ones an admin confirms for Subject Access Requests (see Subject Access Requests).
When the SearchAction appears¶
The /search?q= page only answers on a site that has search: useSearch on (it is off by default) and Typesense configured; elsewhere it is a 404. The SearchAction is therefore added only when SiteSearchSettings.isEnabled says so, the same check the search page, the header search box and the indexer use (see Search on or off).
Blog posts¶
A blog post gets a second <script type="application/ld+json">, after the site graph, holding one BlogPosting:
{
"@context": "https://schema.org",
"@type": "BlogPosting",
"@id": "https://www.derbymrt.org.uk/p/news/5-callouts-in-7-hours#article",
"mainEntityOfPage": "https://www.derbymrt.org.uk/p/news/5-callouts-in-7-hours",
"url": "https://www.derbymrt.org.uk/p/news/5-callouts-in-7-hours",
"headline": "5 Callouts in 7 Hours for Derby Mountain Rescue Team",
"description": "A busy evening for the team.",
"image": "https://images.bdgr.co.uk/dmrt/media/callout.jpg",
"datePublished": "2026-04-10T18:30:00Z",
"dateModified": "2026-04-11T09:00:00Z",
"author": { "@type": "Person", "name": "Derby Press" },
"publisher": {
"@type": "Organization",
"@id": "https://www.derbymrt.org.uk#organization",
"name": "Derby Mountain Rescue Team",
"logo": "https://images.bdgr.co.uk/dmrt/logo.png"
}
}
| Property | Source |
|---|---|
url, mainEntityOfPage, @id |
The post's canonical path when it has one, otherwise /p/{seoName}, on the primary domain. |
headline |
The post name, shortened to 110 characters (Google's limit for article headlines). |
description |
The post's meta description, using the same rule as <meta name="description"> (see Meta descriptions). Left out when empty. |
image |
The masthead image, found the same way as og:image (the post's own masthead, else its stereotype's). Left out when there is none. |
datePublished, dateModified |
The post's created and last-modified dates, in UTC. The blog admin edits the created date directly. |
author |
A Person named by the post's author attribute (the "Posted by" name on the masthead). Without one, the site's Organization. |
publisher |
The site's Organization, with the same @id as in the site graph, plus its name and logo so the object stands on its own. |
PageController adds it (as blogPostingJsonLd) for pages whose template is blog/blogPost, on both GET and form-post renders. The structuredData fragment prints it after the site graph. It follows the structured-data-enabled switch, is escaped the same way, and is left off rather than failing the page if it can't be built.
The blog templates (post, masthead, related articles, latest posts) carry no microdata. They used to put itemscope itemtype="BlogPosting" on <body>, so every related-post card became a nested blogPost of the post being read, title appeared as a property, and author and publisher were bare text. Validators flagged every post. BlogTemplatesMicrodataTest stops it coming back.
Events¶
An event's product page (an Event Ticket product with a start) gets an Event after the site graph, so search engines can show its date, venue and prices:
| Property | Value |
|---|---|
name, url, @id |
The product name; the canonical URL, else /product/{seoName}; that URL plus #event. |
description |
The product's mini description, when it has one. |
startDate, endDate |
The event's start and end, ISO-8601 with the site's offset. No endDate when the event has no end. |
location |
A Place named after the venue; the venue text is also its address, as it is all the shop records. |
image |
Up to three product images. |
organizer |
The site's Organization, by the @id the site graph gives it. |
eventStatus, eventAttendanceMode |
EventScheduled and OfflineEventAttendanceMode. |
offers |
One Offer per ticket type (each enabled variant, or the product itself): name, price, currency, availability (InStock, or SoldOut for a type with none left and for every type once sales have closed or the event has ended), validFrom (when the product was published, else created) and validThrough (when sales close). Stock comes from the inventory service. |
EventStructuredDataInterceptor adds it as eventJsonLd when the model's product is an event; fragment/structuredData prints it. It follows structured-data-enabled like the rest. The product templates' Product microdata stays as it is.
Products and offers¶
Product cards and product pages carry schema.org microdata: a Product (name, image, description) with an Offer (price, currency, availability), which Google reads as a merchant listing.
Only a product with a fixed price gets it (DProduct.isMerchantListing()). An open-amount product, where the shopper picks the amount (a donation with no quantity type, a wishlist gift, any price-as-quantity product), has no price to offer, and Google rejects a merchant listing whose Offer has no price ("Missing field 'price' (in 'offers')"). So these cards and pages carry no Product, Offer or AggregateRating at all. A fixed-price donation (FIXED or SELECTABLE quantity type) is still a listing.
The hidden product image is a <link itemprop="image" href="…">: a <link> property takes its value from href, not content.
Link previews (Open Graph and Twitter cards)¶
When someone pastes a storefront link into Slack, iMessage, WhatsApp or X, the app reads the page's <head> and builds a preview card. OpenGraphExtension (the metaTags slot) writes those tags for products, collections, category pages, CMS pages and search.
| Page | Title | Description | Image |
|---|---|---|---|
| Product | Product name (a supporter's fundraiser, on the fundraiserProductStereotype: "Support …"; the shop's own donation keeps its name) |
Leads with the price, then the meta description, mini description or, failing those, the description as plain text: £24.50 — Cool and crisp. "Sold out" is added when stock is known to be zero. An amount the shopper chooses (a donation) has no price in the description and no price tags |
Up to four product images, with alt text |
Category (/c/…) |
Meta title, else the name | Meta description, else the description as plain text | The category's image |
| Collection and CMS page | Meta title, else the name (the home page: the shop's name) |
Meta description, else the description as plain text | Blog posts: the masthead image |
| Search | Search results for “<query>” |
Shop “<query>” at <site>. |
The site logo |
An image on the shop's own image host is shared through its resize, at most 1200 pixels on its longer side (/fit-in/1200x1200/…), not as the uploaded original: WhatsApp shows no picture at all when the image is over about 600 KB, and camera originals are often several MB. An image hosted elsewhere, or an address that is already resized, is used as it is.
A page with no image of its own (a collection, including a home page that is a collection, a CMS page without a masthead, search) uses the shop's link preview image (share-image), shared resized like any other. Without one it uses the site logo, made absolute: a logo stored as a full address is used as it is, a path is put on the shop's domain. An SVG is never shared, because WhatsApp, Facebook and X show no picture for one: an SVG logo gives way to the shop icon (Site identity, or the hand-named appleTouchIconPath), and with no raster icon either the page has no og:image. Every page also gets twitter:* tags copied from the Open Graph values. A real photo (the page's own or the link preview image) gets the large summary_large_image card; a page that only has the logo or icon gets the compact summary card. Products also carry product:price:* and product:brand, which Facebook and Pinterest read, alongside the older og:price:* tags.
The extension's output is cached per page for five minutes. The search page is the exception: its preview depends on the query, so a request with q skips the cache (BadgerExtension.cacheableFor).
Configuration¶
| Key | Type | Default | Category | Effect |
|---|---|---|---|---|
share-image |
String (image address) | none | seo-config |
The link preview picture for pages with no image of its own: an image from the media library, relative to the image host or absolute. Landscape, 1200 pixels wide or more, works best. An SVG is ignored. |
structured-data-enabled |
Boolean | true |
seo-config |
Turn it off to remove the WebSite/Organization graph from every page, the BlogPosting from blog posts and the Event from event pages, for example on a site that adds its own Organization markup. Breadcrumbs are not affected. |
Changes appear within five minutes. The graph is cached per site and catalogue in the per-pod in-memory cache.
How it is wired¶
SiteStructuredDataService (commerce-core, seo package)
builds the graph, serialises it with the app's ObjectMapper, escapes it, caches it per site
|
SiteStructuredDataInterceptor (web-mvc, registered in WebMvcConfiguration)
postHandle: puts it on every rendered view as `siteStructuredDataJsonLd`
|
templates/nova/fragment/structuredData.html :: siteJsonLd
prints it; included from every theme's fragment/head.html
- Built in Java. Templates only print the attribute. They never build JSON.
- Escaped for
<script>. After serialising, the service writes<,>and&as<,>and&. These characters only occur inside JSON strings, where the escapes mean the same thing, so a site name such as</script>can't close the element. This is why the fragment can useth:utext. - One fragment for every theme. The fragment is in Nova, the root theme that every theme falls back to, so every theme picks it up. Each theme's head has a single
th:replaceline for it. - An interceptor, not an extension. It covers every page, including those rendered outside the extension pipeline, without each site having to place an extension. Like
StorefrontChromeInterceptor, it skips redirects and leaves the attribute off if anything fails. It never fails a page. - Not on error pages. Exception-handler views don't run interceptor
postHandle, so error pages have no site graph.
Testing¶
SiteStructuredDataServiceImplTest: the graph with search on and off, social accounts tosameAs, missing logo, legal entity details and the Gift Aid fallback, the disabled flag, a missing domain, and</script>escaping.SiteStructuredDataInterceptorTest: adds the attribute, skips redirects and views without a model, and never fails a page.SiteStructuredDataHeadRenderTest: renders each theme's realfragment/headand checks the script is inside<head>, exactly once, and that a blog post'sBlogPostingfollows it.EventStructuredDataServiceImplTest: the event, offers per ticket type with price, availability and dates, sold out after sales close, no end date, escaping, and nothing for other products or when switched off.EventInterceptorsTestcovers the interceptor.BlogPostingStructuredDataServiceImplTest: the post's own properties, no nested posts, author as Person or Organization, the publisher, the masthead image, the canonical URL, headline length, empty descriptions, escaping, the disabled flag and a failing image lookup.BlogTemplatesMicrodataTest: the blog templates carry no microdata.ProductStructuredDataRenderTest: every theme's card and product page give a fixed-price product aProductwith a pricedOfferand an image, and an open-amount product none.DProductMerchantListingTestcovers the rule.
Check a live page with Google's Rich Results Test or the Schema Markup Validator.