Skip to content

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, and publisher pointing at the Organization. When search is available it also has a potentialAction SearchAction, 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:
    • logo
    • sameAs: the social profiles
    • legalName, address, identifier (company number) and vatID

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.

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 use th: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:replace line 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 to sameAs, 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 real fragment/head and checks the script is inside <head>, exactly once, and that a blog post's BlogPosting follows 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. EventInterceptorsTest covers 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 a Product with a priced Offer and an image, and an open-amount product none. DProductMerchantListingTest covers the rule.

Check a live page with Google's Rich Results Test or the Schema Markup Validator.