Structured Data JSON-LD for Magento 2

What you get

Admin Preview

Stores → Configuration → Panth Extensions → Structured Data carries the full configuration surface — Social Profiles (Organization sameAs), Organization Details, Structured Data toggles (JSON-LD), and Breadcrumbs. Every field is [store view]-scoped so a multi-store install can ship a different schema per storefront.

Key Features

One Block, One Graph, Zero Duplicates

• Single <script type="application/ld+json" data-panth-seo="jsonld"> per page. Everything the module knows about the current entity lives inside one @graph.
• Aggregator deduplicates by @id and deep-merges so the Product node emitted by ProductProvider and the AggregateOffer from ConfigurableOfferProvider become one coherent Product with one Offer, no collisions.
• Native-markup strip plugin removes Magento's built-in application/ld+json from product.info.main, breadcrumbs, product.price.final plus all itemprop / itemscope / itemtype microdata attributes on those blocks — so you never ship two Product schemas.
• Own blocks are explicitly skipped — scripts carrying data-panth-seo are preserved.

Full Product Type Coverage

• Simple → Product + scalar Offer (price / availability / itemCondition / seller / priceValidUntil / shippingDetails).
• Configurable → Product + AggregateOffer (lowPrice / highPrice / offerCount) with one child Offer per visible variant, each carrying its own price / sku / availability / url.
• Bundle → Product + AggregateOffer with lowPrice / highPrice pulled from the bundle option price range. Fixed-price bundles get a single Offer with the fixed final price.
• Grouped → Product + AggregateOffer with one child Offer per grouped SKU (name / price / availability / sku / url).
• Virtual / Downloadable → treated like simple products — Product + Offer.
• ProductGroup + hasVariant (optional, opt-in) → richer variant modelling via ProductGroup + variesBy on color / size / material.

Identity Nodes

• Organization — name / url / logo / legalName / contactPoint (phone + email) / PostalAddress / sameAs array merging the 7 dedicated social-profile fields (Facebook, Twitter/X, Instagram, LinkedIn, YouTube, Pinterest, TikTok) with a free-form textarea for anything else.
• WebSite — with SearchAction for Google Sitelinks Search Box eligibility.
• Seller — auto-merged into #organization by default (since business_type = Organization); switches the @type to LocalBusiness / Store / OnlineStore when configured.

Content-Rich Nodes

• BreadcrumbList — full category hierarchy for products (Home → Gear → Bags → Product), not just Home + Product. Respects admin-configured category priority weights when enabled.
• ItemList — on category pages, listing products with position for rich carousel results.
• Review + AggregateRating — top-N approved reviews with ISO 8601 datePublished, scaled 1-5 rating from Magento's 0-100 percent votes.
• FAQPage — auto-extracted Question / acceptedAnswer pairs from product / category / CMS descriptions. Recognises <h2>…?</h2><p>…</p> and <h3>…?</h3><p>…</p> patterns.
• Article — for CMS pages under blog/*, news/*, articles/* or carrying article in their meta keywords.
• VideoObject — for product media gallery entries of type external-video (YouTube / Vimeo).

Merchant / Pricing Extras

• MerchantReturnPolicy — applicableCountry (ISO 3166-1), merchantReturnDays (int), returnMethod, returnFees (properly mapped to the schema.org ReturnFeesEnumeration URL).
• Product pricing: priceValidUntil from product special_to_date → admin default → auto +1 year fallback; availability from isSalable() / StockRegistry with LimitedAvailability / BackOrder / PreOrder / Discontinued beyond InStock / OutOfStock.
• Sale Event (opt-in) — priceSpecification with validFrom / validThrough on products with active special prices.
• Delivery Methods — structured shipping details from admin-listed methods.
• Payment Methods — acceptedPaymentMethod in Offer from admin list.
• Multi-Region Shipping (auto-detect) — reads Magento's table-rate / flat-rate config and emits shippingDetails per region. Only when admin hasn't configured manual delivery_methods.

Specialist Nodes

• Brand — standalone Brand node using the configured product attribute (default manufacturer) + admin-configurable default fallback brand.
• Certifications — hasCertification from a textarea attribute in Authority | Name | ID format.
• Energy Efficiency Label (EU) — hasEnergyConsumptionDetails with grades A–G.
• Pros / Cons — positiveNotes / negativeNotes ItemLists from textarea attributes.
• Custom Properties — admin-configurable JSON object deep-merged into the Product node for anything beyond the built-in schemas (e.g. material, audience, custom-vocabulary facets).

Production-Grade Implementation

• Theme-agnostic — head block attached to head.additional via view/frontend/layout/default.xml. No JS, no RequireJS, no x-magento-init. Identical output on Hyva, Luma, Breeze, and every custom theme.
• Fully cacheable — the head block is cacheable="true", so FPC bakes the JSON-LD alongside the rest of the <head> and the providers only run on uncached renders.
• ISO 8601 dates everywhere — product dateModified / datePublished, review datePublished, article dates, sale validFrom/validThrough all go through DateTimeImmutable::format(ATOM) for strict schema.org compliance.
• Attribute-text coerced — getAttributeText() return values (string | array | false | null from multi-select attributes) are normalised before use, preventing a single multi-select attribute from silently killing the entire Product node.
• XSS-safe JSON payload — every </ inside the JSON is escaped to <\/ so browsers can't be tricked into closing the <script> tag early.

How It Works

The module is a pipeline: admin config → providers → aggregator → head block → <script> tag.

┌─────────────────────────────────────────────────────────────────────┐
│ Admin → Stores → Configuration → Panth Extensions → Structured Data│
│ (toggles, attribute codes, social URLs, organization fields) │
└────────────────────────────────────┬────────────────────────────────┘
 │
 Helper\Config reads every field
 ▼
┌─────────────────────────────────────────────────────────────────────┐
│ Aggregator (di.xml-registered pipeline of 24 providers) │
│ │
│ OrganizationProvider → Organization #organization │
│ WebsiteProvider → WebSite #website (+ SearchAction) │
│ BreadcrumbProvider → BreadcrumbList │
│ ProductProvider → Product #product + scalar Offer extras │
│ FaqExtractor → FAQPage (if Q&A pairs detected) │
│ ReviewProvider → Review[] (top 5 approved) │
│ VideoProvider → VideoObject[] (external-video entries) │
│ CmsArticleProvider → Article (blog-like CMS pages) │
│ ReturnPolicyProvider → MerchantReturnPolicy │
│ BrandProvider → Brand │
│ ProductListProvider → ItemList (category pages) │
│ PaymentMethodProvider → Offer (acceptedPaymentMethod) │
│ DeliveryMethodProvider→ Offer (shippingDetails) │
│ MultiRegionShipping → Offer (multi-region shippingDetails) │
│ ConfigurableOffer → Product #product → AggregateOffer │
│ GroupedOffer → Product #product → AggregateOffer (group) │
│ BundleOffer → Product #product → AggregateOffer (bundle) │
│ CustomProperties → Product #product + merchant-defined JSON │
│ EnergyLabel → Product #product + hasEnergyConsumption │
│ Certification → Product #product + hasCertification │
│ SaleEvent → Product #product + priceSpecification │
│ ProductGroup → ProductGroup + hasVariant │
│ ProsCons → Product #product + positiveNotes/negative │
│ SellerProvider → Organization #organization (merged) │
└────────────────────────────────────┬────────────────────────────────┘
 │
 Deep-merge by @id, deduplicate, validate
 ▼
┌─────────────────────────────────────────────────────────────────────┐
│ {"@context":"https://schema.org","@graph":[ ...merged nodes... ]} │
│ JSON_UNESCAPED_SLASHES + JSON_UNESCAPED_UNICODE + `</` → `<\/` │
└────────────────────────────────────┬────────────────────────────────┘
 │
 Block\Head\StructuredData echoes inside:
 ▼
┌─────────────────────────────────────────────────────────────────────┐
│ <script type="application/ld+json" data-panth-seo="jsonld"> │
│ { ...full @graph... } │
│ </script> │
│ │
│ RemoveNativeMarkupPlugin also runs on AbstractBlock::afterToHtml │
│ and strips Magento's native ld+json + microdata from three blocks: │
│ product.info.main, breadcrumbs, product.price.final │
│ (own blocks carrying data-panth-seo are explicitly preserved) │
└─────────────────────────────────────────────────────────────────────┘

Six things the Aggregator does

1. Applicability check — every provider exposes isApplicable(). Product-scoped providers return false on CMS pages, ReturnPolicyProvider returns false when return_policy_days = 0, FaqExtractor defers to Panth_Faq when that module owns the current page. Providers that return false are skipped entirely.
2. Config gate — Config::isStructuredDataEnabled($provider->getCode()) reads panth_structured_data/structured_data/{code}. Admin disables any provider with a single Yes/No toggle.
3. Node collection — applicable + enabled providers' getJsonLd() returns are collected. Single-node returns and list-of-nodes returns both work.
4. Dedup + deep-merge — two nodes with the same @id get merged key-by-key. Scalars from later providers win, arrays recurse, new keys get appended. Two providers contributing to the same Product, Organization, or Offer always produce one coherent node.
5. Document shape — one node in @graph → inline the node under @context. Multiple nodes → wrap in @graph.
6. XSS safety — every </ in the serialised JSON is replaced with <\/ so the <script> tag can never be closed early by a malicious product name.

The deep-merge, concretely

Before merge (two separate provider outputs on a configurable PDP):

// ProductProvider
{
 "@type": "Product",
 "@id": "https://example.com/hoodie.html#product",
 "name": "Chaz Kangeroo Hoodie",
 "offers": {
 "@type": "Offer",
 "itemCondition": "https://schema.org/NewCondition",
 "seller": {"@id": "https://example.com/#organization"},
 "priceValidUntil": "2027-04-23",
 "shippingDetails": { ... }
 }
}

// ConfigurableOfferProvider
{
 "@type": "Product",
 "@id": "https://example.com/hoodie.html#product",
 "offers": {
 "@type": "AggregateOffer",
 "lowPrice": "52.00",
 "highPrice": "52.00",
 "offerCount": 15,
 "priceCurrency": "USD",
 "offers": [ {...15 child offers...} ]
 }
}

After merge in @graph:

{
 "@type": "Product",
 "@id": "https://example.com/hoodie.html#product",
 "name": "Chaz Kangeroo Hoodie",
 "offers": {
 "@type": "AggregateOffer",
 "lowPrice": "52.00",
 "highPrice": "52.00",
 "offerCount": 15,
 "priceCurrency": "USD",
 "itemCondition": "https://schema.org/NewCondition",
 "seller": {"@id": "https://example.com/#organization"},
 "priceValidUntil": "2027-04-23",
 "shippingDetails": { ... },
 "offers": [ {...15 child offers...} ]
 }
}

Scalar @type is overridden by the later ConfigurableOfferProvider ("AggregateOffer" wins). Every scalar key unique to one side is preserved. shippingDetails (nested array) comes through untouched from ProductProvider. offers (the child-offer array from ConfigurableOfferProvider) is added without conflict.

Schema.org Nodes Emitted

All URL-valued attributes (og:url, url, image, logo, sameAs) preserve : and / (no entity-encoding). All dates are ISO 8601 (YYYY-MM-DDTHH:MM:SS+00:00). All enumerations (availability, itemCondition, returnFees, returnPolicyCategory, returnMethod) are full schema.org URLs.

Product Type Coverage

Tested end-to-end across Magento's sample catalogue on both Hyva and Luma:

Across all variant types the shared offer-level extras (itemCondition, seller @id, priceValidUntil, shippingDetails) merge into the AggregateOffer via the deep-merge path, so a bundle / grouped / configurable product still carries its return policy and product condition on the Offer node.

Quick Test — URLs You Can Hit Right Now

Every URL below returns HTML with exactly one <script type="application/ld+json" data-panth-seo="jsonld">…</script> block. Substitute your own host for the domain.

1. View the JSON-LD in a browser

Open any URL → right-click → View Page Source → Ctrl-F for application/ld+json. The block carries the full @graph.

Product types — Hyva + Luma test stores

Other page types

2. Pretty-print from the terminal

curl -ks https://your-store.test/chaz-kangeroo-hoodie.html \
 | perl -ne 'BEGIN{$/=undef} while (/<script type="application\/ld\+json"[^>]*>(.*?)<\/script>/gs) { print "$1\n" }' \
 | python3 -m json.tool

3. One-shot type summary across every page

for url in / /compete-track-tote.html /chaz-kangeroo-hoodie.html \
 /sprite-yoga-companion-kit.html /set-of-sprite-yoga-straps.html \
 /gear/bags.html /about-us /no-route; do
 types=$(curl -ks "https://your-store.test$url" \
 | perl -ne 'BEGIN{$/=undef} while (/<script type="application\/ld\+json"[^>]*>(.*?)<\/script>/gs) { print "$1\n" }' \
 | python3 -c 'import json,sys; d=json.loads(sys.stdin.read()); print(",".join(n.get("@type","?") for n in d.get("@graph",[d])))')
 printf " %-40s %s\n" "$url" "$types"
done

Expected output on a stock sample-data install:

 / Organization,WebSite
 /compete-track-tote.html Organization,WebSite,BreadcrumbList,Product,Review,MerchantReturnPolicy
 /chaz-kangeroo-hoodie.html Organization,WebSite,BreadcrumbList,Product,MerchantReturnPolicy
 /sprite-yoga-companion-kit.html Organization,WebSite,BreadcrumbList,Product,MerchantReturnPolicy
 /set-of-sprite-yoga-straps.html Organization,WebSite,BreadcrumbList,Product,MerchantReturnPolicy
 /gear/bags.html Organization,WebSite,BreadcrumbList,ItemList
 /about-us Organization,WebSite
 /no-route Organization

4. Browser DevTools one-liner

Paste in Chrome / Firefox / Safari DevTools console on any page:

JSON.parse(document.querySelector('script[data-panth-seo="jsonld"]').textContent)
 ['@graph'].forEach(n => console.log(n['@type'], '→', n.name || n.headline || n['@id']))

How to Validate with Google Search Console (Step by Step)

Google's Rich Results Test is the authoritative validator — it's what determines whether your pages get rich cards in SERPs. Here's the full flow.

Prerequisite: your site must be publicly reachable

Google's crawler can't reach localhost, *.test, VPN-internal, or intranet URLs. If you're testing locally, expose the site through a tunnel first:

# Option A: Cloudflare Tunnel (free, no signup for temporary tunnels)
cloudflared tunnel --url https://your-store.test

# Option B: ngrok (free tier fine for testing)
ngrok http https://your-store.test

Either gives you a public https://xxxx.trycloudflare.com/ or https://xxxx.ngrok.io/ URL. Use that in every validator below.

Step 1 — Google Rich Results Test

1. Open search.google.com/test/rich-results.
2. Paste your full product URL (e.g. https://xxxx.trycloudflare.com/compete-track-tote.html).
3. Click Test URL. Google fetches the page.
4. Once it finishes, you'll see one or more "Detected items" — Products, Breadcrumbs, Reviews, Merchant listings, etc.
5. Click each item to expand. The left pane shows a live SERP preview card with your product image, price, rating stars, and availability.
6. Any errors or warnings show at the top of each item panel. Errors block rich results; warnings are suggestions.

What to expect on a working product page:

• Products — 1 item detected (valid)
• Breadcrumbs — 1 item detected (valid)
• Merchant listings — 1 item detected (valid) [if MerchantReturnPolicy enabled]
• Reviews — N items detected [if product has reviews]

Step 2 — Submit your domain to Google Search Console

To track rich-result performance over time, add the whole site:

1. Open search.google.com/search-console.
2. Click Add property.
3. Choose Domain (covers all subdomains + http/https) or URL prefix (for a specific scheme + host).
4. Follow the verification flow — DNS TXT record for a domain property, or HTML file upload / meta tag / Google Analytics / Google Tag Manager for URL prefix.
5. Once verified you'll see the Overview dashboard within 24 hours.

Step 3 — Submit your sitemap

If you have Panth_HtmlSitemap or any other sitemap generator, submit it:

1. In Search Console → Sitemaps (left sidebar).
2. Paste the sitemap URL (e.g. https://your-store.com/sitemap.xml).
3. Click Submit. Google will crawl every URL in the sitemap and start detecting structured data.

Step 4 — Monitor rich-result eligibility

After Google re-crawls (typically 1–7 days):

1. In Search Console → Enhancements (left sidebar).
2. You'll see separate reports for every rich-result type your site emits:

• Products (from Product schema)
• Breadcrumbs (from BreadcrumbList schema)
• Review snippets (from Review + AggregateRating)
• Merchant listings (from Product + Offer with price + availability + merchant return policy)
• Sitelinks searchbox (from WebSite + SearchAction)
• FAQ (from FAQPage schema)
• Logo (from Organization + logo)

3. Each report shows Valid / Valid with warnings / Invalid URLs. Invalid URLs are the ones to fix first.

Step 5 — Fix any invalid items

For each invalid URL:

1. Click the error type (e.g. "Missing field 'priceValidUntil'").
2. Review the list of affected URLs.
3. Open the URL in the Rich Results Test (Step 1) to see the exact problem.
4. Fix the admin config — e.g. populate Default Price Valid Until or the missing brand attribute.
5. Flush caches (bin/magento cache:flush config full_page).
6. In Search Console, click Validate fix on the error. Google will re-crawl within days.

Step 6 — Request indexing (optional, speeds things up)

For a single URL:

1. In Search Console → URL Inspection (top search bar).
2. Paste a product URL.
3. Click Request Indexing.
4. Google will prioritize crawling that URL. Repeat for 10-20 of your most important pages.

Step 7 — Confirm rich results in SERP

After Google re-indexes, search for your product in site:your-store.com mode:

site:your-store.com compete track tote

Rich snippets (price, stars, availability badges, breadcrumb path above the title) should appear. Full rollout across all indexed pages takes 2-8 weeks.

Other Validators

Complement Google's Rich Results Test with these before shipping:

Per-Provider Deep Dive

ProductProvider

• Runs on: product pages (current_product in registry).
• Emits: Product with @id = {product_url}#product, full image list (from Magento Image helper + media gallery), description (meta_description → short_description → description, ≤5000 chars), brand (via Brand), audience (via PeopleAudience.audienceType from gender attribute), scalar Offer for simple products or offer-level extras (itemCondition, seller, priceValidUntil, shippingDetails, hasMerchantReturnPolicy) for variant types, AggregateRating from Magento's review summary, ISO 8601 dateModified / datePublished.
• Availability logic: Discontinued (status=disabled or visibility=not_visible) → PreOrder (news_from_date in future) → BackOrder (backorders > 0) → OutOfStock → LimitedAvailability (qty < threshold) → InStock.
• Variant types (configurable / bundle / grouped) skip scalar price / priceCurrency / availability / url — the specialised provider contributes those via deep-merge.

ConfigurableOfferProvider, BundleOfferProvider, GroupedOfferProvider

• Run on: configurable, bundle, grouped products respectively.
• Emit: a Product #product contribution containing an AggregateOffer with lowPrice / highPrice / offerCount and for Configurable / Grouped a child offers array of per-variant Offer nodes.
• Bundle dynamic pricing pulls min/max from the bundle option price range. Bundle fixed pricing emits a scalar Offer.
• All three merge into the same #product @id so the result is one coherent Product node.

OrganizationProvider + SellerProvider

• Run on: every page (Organization) / product pages (Seller).
• Emit: Organization #organization with full identity details.
• SellerProvider uses the same @id = #organization by default; when business_type = LocalBusiness / Store / OnlineStore the merged @type is promoted to the more specific class.
• sameAs combines 7 dedicated social-profile fields with a free-form textarea.

BreadcrumbProvider

• Runs on: any page with a clear entity (product / category / CMS).
• For products: picks the primary category from the product's category set, honoring admin-configured priority weights when enable_breadcrumb_priority = Yes, else tiebreaker on depth (longest / shortest).
• Builds full hierarchy: Home → Category → Subcategory → Product (4 levels on most PDPs).

ProductListProvider

• Runs on: category pages only.
• Emits: ItemList with one ListItem per visible product in the current category view, preserving pagination order.

ReviewProvider

• Runs on: product pages with reviews enabled (catalog/review/active).
• Emits: up to 5 most-recent approved Review nodes with ISO 8601 datePublished, scaled 1-5 rating from Magento's 0-100 percent vote aggregate.
• Defers to Panth_Testimonials on its own routes.

WebsiteProvider

• Runs on: every page.
• Emits: WebSite #website with SearchAction pointing at {store_url}catalogsearch/result/?q={search_term_string} — enables Google Sitelinks Search Box.

FaqExtractor

• Runs on: any page with a description containing heading/paragraph Q&A pairs.
• Parser: <h2>…?</h2><p>…</p> and <h3>…?</h3><p>…</p>.
• Needs ≥2 Q&A pairs; defers to Panth_Faq on its routes.

CmsArticleProvider

• Runs on: CMS pages whose identifier starts with blog/, news/, articles/ or whose meta keywords contain article.
• Emits: Article with headline / description / mainEntityOfPage / url / author / publisher refs + ISO 8601 datePublished / dateModified + up to 5000 chars of articleBody.

ReturnPolicyProvider

• Runs on: product pages when return_policy_days > 0.
• Emits: MerchantReturnPolicy with applicableCountry from store config, merchantReturnDays (int), returnMethod, returnFees (mapped to ReturnFeesEnumeration URL).

VideoProvider

• Runs on: product pages with media gallery entries of type external-video.
• Emits: VideoObject for each video (YouTube / Vimeo).

Specialist providers

• CertificationProvider — hasCertification from a textarea attribute.
• EnergyLabelProvider — hasEnergyConsumptionDetails with grade A–G.
• ProsConsProvider — positiveNotes / negativeNotes ItemLists.
• SaleEventProvider — priceSpecification (UnitPriceSpecification) with validFrom/validThrough when special price is active.
• DeliveryMethodProvider / PaymentMethodProvider / MultiRegionShippingProvider — Offer extensions for shipping + payment.
• ProductGroupProvider — ProductGroup + hasVariant + variesBy (opt-in; richer variant modelling).
• CustomPropertiesProvider — admin-editable JSON object deep-merged into the Product node for anything outside the built-in schemas.
• BrandProvider — standalone Brand node alongside the inline Product.brand.

Troubleshooting

Compatibility

Works standalone (no other Panth module needed) and composes cleanly with Panth_AdvancedSEO, Panth_Faq, Panth_Testimonials when any of those are installed (specialist providers defer to those modules on their own routes).

Installation

Composer Installation (Recommended)

composer require mage2kishan/module-structured-data
bin/magento module:enable Panth_Core Panth_StructuredData
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Manual Installation via ZIP

1. Download the latest release ZIP from Packagist or the Adobe Commerce Marketplace.
2. Extract the contents to app/code/Panth/StructuredData/ in your Magento installation.
3. Ensure Panth_Core is installed (required dependency).
4. Run the same commands as above starting from bin/magento module:enable.

Verify Installation

bin/magento module:status Panth_StructuredData
# Expected output: Module is enabled

# Every page now carries one JSON-LD block:
curl -ks https://your-store.test/ | grep -c 'application/ld+json'
# Expected output: 1

Configuration

Navigate to Admin → Stores → Configuration → Panth Extensions → Structured Data. Four fieldsets:

Social Profiles (Organization sameAs)

All URLs validated against validate-url and the module's internal HTTPS-only allowlist before being emitted.

Organization Details

Leave empty to fall back to core Magento Store Information.

Structured Data (JSON-LD)

Master toggles + attribute codes + defaults. Every toggle is Yes/No, every attribute code is a plain Magento attribute identifier.

Breadcrumbs

Every field is [store view]-scoped.

After any change, flush caches:

bin/magento cache:flush config full_page

License

Panth Structured Data is licensed under a proprietary license — see LICENSE.txt. One license per Magento installation.