What is JSON-LD? Ecommerce structured data, explained
JSON-LD is a JSON-based format for writing linked data: information that describes entities, facts, and relationships in a way software can parse.
On ecommerce sites, JSON-LD is most often used to add schema markup to pages without wrapping the visible HTML in extra code. A product page can use JSON-LD to state that the page contains a product, an offer, a price, availability, a brand, a SKU, a GTIN, images, reviews, shipping details, and other product facts.
The short version: JSON-LD is a common way to turn product-page information into machine-readable structured data for search engines, shopping systems, and AI commerce.
What JSON-LD means in ecommerce
JSON is a way to write data objects. JSON-LD uses that familiar JSON shape, then adds linked-data context so software can understand what the values mean. The extra layer matters because a plain JSON object might say price, while JSON-LD can connect that price to a Product and Offer vocabulary that search engines and other systems recognize.
For ecommerce teams, JSON-LD usually shows up as a script block on a webpage. It does not change what a shopper sees directly. Instead, it gives crawlers and machine readers a clearer description of the page.
A product detail page might show a hoodie title, image, variant picker, price, sale badge, star rating, shipping copy, and availability message. JSON-LD labels those facts so software does not have to guess which number is the price, which text is the product name, which image belongs to the product, or whether the item is in stock.
That makes JSON-LD useful, but it also makes weak product data more obvious. If the product page says one price, the product feed sends another price, and the JSON-LD says a third price, downstream systems receive conflicting signals. JSON-LD is only as trustworthy as the product facts it exposes.
How JSON-LD works
Most ecommerce JSON-LD uses a small set of repeatable building blocks.
| Part | What it does | Ecommerce example |
|---|---|---|
@context | Tells software which vocabulary gives meaning to the properties | "https://schema.org" |
@type | Names the kind of thing being described | Product, Offer, Brand, FAQPage, or BreadcrumbList |
@id | Gives the entity a stable identifier within the page or site data graph | A product entity ID that stays consistent across markup updates |
Properties | Describe facts about the entity | name, description, image, sku, brand, offers |
Nested objects | Describe related entities inside the main entity | A Product with a nested Offer and Brand |
Arrays | Store multiple values for one property | Multiple product images, breadcrumbs, reviews, or accepted variants |
Script tag | Places the JSON-LD in the page HTML | <script type="application/ld+json"> |
Using a fictional product, a simplified Product JSON-LD block might look like this:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Product",
"@id": "https://northstar-supply.test/products/merino-wool-hoodie#product",
"name": "Merino Wool Hoodie",
"description": "A navy merino wool hoodie made for everyday layering.",
"sku": "MWH-NAVY",
"gtin13": "0123456789012",
"brand": {
"@type": "Brand",
"name": "Northstar Supply"
},
"image": [
"https://northstar-supply.test/images/merino-wool-hoodie-navy.jpg"
],
"offers": {
"@type": "Offer",
"url": "https://northstar-supply.test/products/merino-wool-hoodie",
"priceCurrency": "USD",
"price": "129.00",
"availability": "https://schema.org/InStock",
"itemCondition": "https://schema.org/NewCondition"
}
}
</script>The exact fields depend on the page and product type. A product with variants may need variant-level offers. A page with reviews may need supported review and rating data. A page with shipping and return policies may need those details only when they are accurate and visible enough to support.
The important rule is simple: JSON-LD should describe the real page and the real product data. It should not invent facts that are missing from the page or paper over data problems upstream.
JSON-LD vs related terms
JSON-LD overlaps with several SEO, data, and product-catalog terms. The differences matter because teams often use the words interchangeably even though they belong to different layers.
| Term | What it means | How it relates to JSON-LD |
|---|---|---|
| JSON | A lightweight data format made of objects, arrays, keys, and values | JSON-LD uses JSON syntax, but not every JSON object is JSON-LD |
| Structured data | Information organized into predictable fields, values, and relationships | JSON-LD is one format for expressing structured data |
| Schema markup | Structured data added to a webpage so search engines and machine readers can understand page content | JSON-LD is a common way to write schema markup |
| Schema.org | A shared vocabulary of entity types and properties | Ecommerce JSON-LD often uses Schema.org vocabulary |
| Product schema | The product-specific structure that labels product facts for software | Product schema markup is often written in JSON-LD |
| Metadata | Page-level information such as title tags and meta descriptions | Metadata describes the page; JSON-LD can describe entities and facts inside the page |
| Product feed | A structured product-data file, stream, or transfer sent to commerce destinations | Feeds move product records to channels; JSON-LD labels facts on a webpage |
| API response | Structured data returned by a software request | API responses may use JSON, but they are delivery mechanisms rather than page markup |
| Microdata or RDFa | Alternative structured-data formats embedded in visible HTML | JSON-LD is usually easier to maintain because it can sit separately from the visible markup |
A simple way to remember the stack: structured data is the broad concept, Schema.org is a common vocabulary, schema markup is the webpage implementation, product schema is the product-specific structure, and JSON-LD is a common format for writing that structure on the page.
Practical JSON-LD examples
Product page markup
A product detail page is the most common ecommerce use case. JSON-LD can identify the product, brand, SKU, GTIN, image, description, category, offers, price, currency, availability, condition, ratings, reviews, shipping details, and return policy.
This helps search engines and other machine readers connect visible page content to explicit product facts. It also helps teams check whether the product page, product schema, product feed, and channel listings are telling the same story.
Variant and offer markup
Variants create one of the easiest places to make JSON-LD mistakes. A sweater sold in five colors and six sizes may look like one product family to shoppers, but each purchasable variant can have its own SKU, GTIN, image, price, and availability.
JSON-LD should reflect the way the page actually works. If the page represents one selected variant, the markup should not accidentally describe a different color or size. If the page represents a product group, the data model needs a clean way to connect the parent product, child variants, and offers.
Merchant Center and shopping surfaces
JSON-LD is not a replacement for Google Merchant Center or a product feed. Merchant Center receives product data through account-level sources such as feeds, integrations, website data, or product updates. JSON-LD labels product facts on the website itself.
The two layers should agree. If Merchant Center sees one price, the landing page shows another price, and the JSON-LD exposes a third price, the product data is not channel-ready. The fix is usually upstream: define the trusted product record, then make sure the page, feed, and markup are generated from current data.
FAQ, breadcrumb, and organization markup
JSON-LD is not only for products. Ecommerce sites also use it to describe FAQs, breadcrumbs, articles, organizations, local business information, and site search. These page-level structures can help machines understand the site and the relationships between pages.
For glossary pages, JSON-LD can describe the defined term and supporting FAQ questions. For product catalogs, it can describe navigation paths and entity relationships. The same principle applies: mark up what the page actually supports.
AI commerce and product understanding
AI-shopping systems need more than a title and price. They often need attributes, compatibility, use cases, constraints, policies, variants, freshness, and enough context to answer buyer questions accurately.
JSON-LD can expose some of that structure on a page. It is not the whole AI-commerce layer, though. AI systems are more likely to use product information correctly when the underlying product catalog, attributes, identifiers, variants, and availability data are already complete and consistent.
Why JSON-LD matters
Product data quality
JSON-LD gives product facts a clear shape. That makes gaps easier to spot: missing images, weak descriptions, incomplete identifiers, unsupported ratings, stale prices, inconsistent availability, or variant data that does not match the selected product.
Good JSON-LD starts with good source data. If merchandising teams do not know which product name, image, color value, material, SKU, or availability state is trusted, the markup will inherit that uncertainty. Catalog's guide to product data quality goes deeper on the data-quality dimensions behind this work.
Channel readiness
Modern commerce data moves across product pages, feeds, marketplaces, search engines, shopping surfaces, retailer portals, recommendations, and AI-shopping systems. JSON-LD is one output in that broader channel-readiness workflow.
When product records are complete and normalized, teams can map those facts into product pages, Merchant Center, feeds, product schema, and other destinations with less manual cleanup. When records are thin or inconsistent, every destination becomes a separate cleanup project.
Search and discovery
JSON-LD can help search engines understand page entities and product facts more explicitly. For product pages, that can support eligibility for enhanced search displays such as product snippets or merchant listing experiences when the page and markup meet the required conditions.
Eligibility is not a guarantee. JSON-LD does not automatically create rankings, rich results, AI mentions, or better conversion rates. It gives machines cleaner facts to interpret. The page still needs useful content, accurate product data, crawlability, technical health, and a reason to be trusted.
AI commerce
AI commerce raises the bar for product data. A shopper may ask whether a product works for a specific use case, fits a certain constraint, compares well against another item, ships to a region, or is compatible with something they already own.
JSON-LD can help expose structured facts, but the facts have to exist first. Richer attributes, normalized values, trusted identifiers, variant relationships, and current offers make product information easier for AI systems to retrieve and reason over. Catalog's guide to product data enrichment for AI commerce covers the enrichment side of that workflow.
Template and engineering maintainability
JSON-LD is usually easier to maintain than structured-data formats that require attributes throughout the visible HTML. Developers can generate a JSON-LD object from the same product data that powers the page, then place it in one script block.
That separation helps at scale. A small shop can hand-edit markup for a few pages. A large catalog with thousands of products, variants, prices, inventory changes, and regional rules needs structured data generated from reliable product records.
Common JSON-LD mistakes
Treating JSON-LD as a magic SEO tactic
JSON-LD can help machines understand a page and may support rich-result eligibility. It is not a guaranteed ranking boost. If the page is thin, slow, uncrawlable, untrustworthy, or irrelevant, valid JSON-LD will not fix the larger problem.
Marking up facts that are not visible or supported
Structured data should match the page. Do not add a rating, review count, price, return policy, shipping promise, FAQ, or availability state that shoppers cannot verify from the page or supporting commerce flow.
Letting price and availability drift
Price and stock status change often. If JSON-LD is generated from stale data while the storefront or feed has already changed, search and shopping systems can receive inaccurate offer information.
Copying the same Product markup across variants
Variant pages need precise product data. Reusing one JSON-LD block across every color, size, region, bundle, or configuration can create wrong SKUs, wrong images, wrong identifiers, or wrong availability.
Confusing JSON with JSON-LD
A product object in JSON is not automatically JSON-LD. JSON-LD needs context and entity typing so software can understand how the properties should be interpreted.
Using Product markup on broad category pages
A category page that lists many different products should not pretend the whole page is one Product. It may need a different structure, such as breadcrumbs, item lists, or collection-level markup, depending on the page and supported data.
Hiding important facts only in JSON-LD
JSON-LD should clarify page facts, not replace them. If a product attribute matters to shoppers, the product page, filters, comparison tools, feeds, and support content may need that fact too.
Forgetting validation after template changes
Valid JSON-LD can break when templates change, apps inject conflicting markup, required fields disappear, or product data stops syncing. Validation should happen before launch and continue through monitoring after launch.
Fixing the markup while the source data stays messy
A markup fix is often just a symptom fix. If product names, identifiers, variants, images, prices, or availability are wrong upstream, the next export or template render can reintroduce the same problem.
Where Catalog fits with JSON-LD
Catalog does not replace JSON-LD, schema markup, Schema.org, Search Console, Merchant Center, a PIM, an ecommerce platform, or a feed tool. JSON-LD is an output format. Catalog fits at the product-data layer that makes those outputs stronger.
| Layer | Job |
|---|---|
| Source systems | Store or expose product information from ecommerce platforms, PIMs, ERPs, supplier files, DAMs, spreadsheets, product pages, and internal databases. |
| Catalog | Normalize, enrich, structure, and expose product facts as machine-readable product objects. |
| Page and schema layer | Generate product pages and JSON-LD markup from the same current product facts. |
| Channel outputs | Power product feeds, Merchant Center, marketplace listings, search indexes, recommendations, and AI-shopping systems. |
| Monitoring and governance | Check whether product data stays accurate, complete, current, and consistent across destinations. |
For merchants and merchandising teams, that distinction matters because JSON-LD is only as good as the data behind it. A page can have clean syntax and still expose thin product facts. Catalog helps create richer structured product data so pages, feeds, schema markup, and AI-shopping systems can all work from a better foundation.
For adjacent concepts, read the glossary entries for structured data, schema markup, product schema, product feeds, and Google Merchant Center. For AI-search context, read Catalog's guide to making products show up in ChatGPT.
Related terms
FAQ
What does JSON-LD stand for?
JSON-LD stands for JavaScript Object Notation for Linked Data. In practice, it means linked data written with JSON syntax.
What is JSON-LD in simple terms?
JSON-LD is a way to write facts in a format machines can understand. For ecommerce, it can tell software which text is the product name, which value is the price, which image belongs to the product, whether the item is in stock, and how those facts relate to each other.
Is JSON-LD the same as schema markup?
No. Schema markup is structured data added to a webpage. JSON-LD is one common format for writing that markup. Many ecommerce pages use Schema.org vocabulary written as JSON-LD.
Is JSON-LD the same as structured data?
No. Structured data is the broad concept of organized, machine-readable information. JSON-LD is one way to express structured data, especially on webpages.
Is JSON-LD better than microdata?
For many modern websites, JSON-LD is easier to maintain because it can sit in one script block instead of being woven through the visible HTML. Microdata can still be valid, but it is often harder to keep clean across templates and dynamic commerce pages.
Does JSON-LD help SEO?
JSON-LD can help search engines understand page content more explicitly and can make eligible pages qualify for certain enhanced search displays. It is not a guaranteed ranking improvement. SEO performance still depends on content quality, relevance, authority, crawlability, technical health, and accurate product data.
What JSON-LD should ecommerce sites use?
Most ecommerce sites start with Product, Offer, Brand, BreadcrumbList, Organization, WebSite, Article, and FAQPage markup where those structures match the page. Product pages usually need product-specific fields such as name, image, description, SKU, GTIN, brand, offer, price, currency, availability, reviews, ratings, shipping, returns, and variant details when supported.
Where do you put JSON-LD on a page?
JSON-LD is usually placed in a script block in the page HTML. The exact location depends on the site framework, but the data should be available in the rendered page for crawlers that need to read it.
How do you validate JSON-LD?
Use structured-data testing tools before launch, then monitor search and merchant diagnostics after launch. For ecommerce, validation should check both syntax and business accuracy: the product name, image, SKU, GTIN, price, currency, availability, reviews, shipping, returns, variants, and URLs should match the real page and current product data.
Does JSON-LD need to match the visible page?
Yes. JSON-LD should describe facts that the page and supporting commerce flow actually support. Marking up hidden, stale, fake, or unsupported product facts can create trust, eligibility, and data-quality problems.
Does Catalog replace JSON-LD?
No. Catalog does not replace JSON-LD. Catalog helps create the normalized, enriched product data that JSON-LD, product pages, product feeds, search systems, recommendations, and AI-shopping tools can use.
