JSON-LD Basics: The Merchant's Guide to Structured Data That AI Actually Reads

JSON-LD is the structured data format that powers how search engines and AI systems understand your ecommerce store. It holds 89.4% market share among structured data formats, Google explicitly recommends it, and every major AI engine -- ChatGPT, Perplexity, Google AI Overviews, Claude -- parses it natively. If you are running an online store and not using JSON-LD, you are invisible to the fastest-growing discovery channels in ecommerce. This guide covers everything merchants need to know: what JSON-LD is, how it works, where to put it, and why it dominates every alternative.

What JSON-LD Actually Is

JSON-LD stands for JavaScript Object Notation for Linked Data. In plain terms, it is a way to describe facts about your business, products, and content in a format that machines can read without guessing. Instead of forcing a search engine or AI to scan your page and hope it correctly identifies that "$49.99" is a price and "4.8 stars" is a rating, JSON-LD hands them a structured block of labeled data.

The "Linked Data" part means each piece of information connects to a globally defined vocabulary at Schema.org. When you mark something as "@type": "Product", every search engine and AI system on the planet knows you are describing a product -- not a blog post, not a recipe, not an event.

Here is the simplest possible JSON-LD block:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Organic Cotton T-Shirt",
  "offers": {
    "@type": "Offer",
    "price": "29.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}

That block tells any machine reading your page: "This page sells an Organic Cotton T-Shirt for $29.99 USD, and it is in stock." No ambiguity, no parsing errors, no guesswork.

JSON-LD Syntax: The Five Things You Need to Know

JSON-LD follows standard JSON syntax with a few structured data conventions on top. Here is what matters for merchants:

1. The @context Declaration

Every JSON-LD block starts with "@context": "https://schema.org". This tells the parser which vocabulary you are using. Schema.org is the universal standard -- over 62 million domains use it as of 2025, representing 37% year-over-year growth.

2. The @type Property

The @type property declares what kind of thing you are describing. For ecommerce, the types you will use most are Product, Offer, Organization, BreadcrumbList, FAQPage, Review, AggregateRating, Article, and HowTo.

3. Nesting Objects

JSON-LD represents relationships by nesting objects. A Product contains an Offer. An Offer contains a ShippingDetails object. A Product contains an AggregateRating. Each nested object gets its own @type:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Merino Wool Socks",
  "brand": {
    "@type": "Brand",
    "name": "TrailWear"
  },
  "offers": {
    "@type": "Offer",
    "price": "18.00",
    "priceCurrency": "USD"
  }
}

4. Arrays for Multiple Items

When you have multiple values -- like multiple images or multiple reviews -- use JSON arrays (square brackets):

{
  "image": [
    "https://example.com/sock-front.jpg",
    "https://example.com/sock-side.jpg",
    "https://example.com/sock-detail.jpg"
  ]
}

5. The @id Property for Cross-Referencing

The @id property gives an entity a unique identifier so you can reference it from other schema blocks on the same page or across your site. This is critical for connecting your Organization schema to your Product schema:

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "TrailWear Co."
}

Now your Product schema can reference this organization without repeating all the details:

{
  "manufacturer": {
    "@id": "https://example.com/#organization"
  }
}

Where to Place JSON-LD on Your Pages

JSON-LD blocks go inside <script type="application/ld+json"> tags. You can place them in the <head> or <body> of your HTML. Google supports both placements, and both are equally valid.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Organic Cotton T-Shirt",
  "offers": {
    "@type": "Offer",
    "price": "29.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock"
  }
}
</script>

Critical for ecommerce platforms: Google Merchant Center's automated crawl requires that structured data be present in the initial HTML response from the server. Markup generated by client-side JavaScript after page load may not be read by Merchant Center's crawler. If you are using a JavaScript framework (React, Vue, Next.js), ensure server-side rendering for your JSON-LD blocks.

Multiple blocks per page are fine. You can have separate script tags for Product, BreadcrumbList, Organization, and FAQPage schema on the same page. Google handles this correctly.

Why JSON-LD Beats Microdata and RDFa

There are three formats for structured data on the web. JSON-LD won decisively, and the numbers tell the story.

The Market Share Numbers

According to W3Techs and the HTTP Archive Web Almanac 2024, JSON-LD now holds 89.4% market share among structured data formats when measured by actively adopting domains. The Web Data Commons 2024 corpus found 11.5 million websites using JSON-LD, compared to 7.6 million using Microdata and just 400,000 using RDFa. On a per-page basis, JSON-LD grew from 34% in 2022 to 41% in 2024, while Microdata peaked in 2019-2021 and has declined since.

The data richness gap is even more telling. The average number of triples (individual data facts) per JSON-LD webpage has grown from 10 in 2015 to 57 in 2024. JSON-LD pages carry nearly six times more structured information than they did a decade ago.

Why Microdata Fails for Merchants

Microdata embeds structured data directly into your HTML using attributes like itemprop, itemscope, and itemtype. The problem: your schema markup is tangled with your visual markup. When a designer changes a template, the schema breaks. When a developer refactors a component, the schema breaks. When you switch themes, the schema breaks.

Here is what Microdata looks like in practice:

<div itemscope itemtype="https://schema.org/Product">
  <h1 itemprop="name">Organic Cotton T-Shirt</h1>
  <span itemprop="offers" itemscope itemtype="https://schema.org/Offer">
    <span itemprop="price" content="29.99">$29.99</span>
    <meta itemprop="priceCurrency" content="USD">
  </span>
</div>

Every HTML element now serves double duty -- presentation and data. That coupling is why Microdata adoption peaked and declined.

Why RDFa Lost

RDFa uses a similar inline approach with different attributes (typeof, property, vocab). It suffers from the same coupling problem as Microdata, with the added complexity of namespace management. At just 400,000 websites, RDFa is effectively a legacy format.

The JSON-LD Advantage in Six Points

  1. Separation of concerns. Your structured data lives independently from your templates. Redesign your site without breaking your schema.
  2. Google's explicitly recommended format. Google documentation states JSON-LD as the preferred format for structured data.
  3. AI-native parsing. Large language models parse JSON natively. JSON-LD is the easiest format for AI crawlers to consume during indexing.
  4. Dynamic generation. Your backend can inject JSON-LD from your product database without touching templates. Pull price from your inventory system, availability from your warehouse API, ratings from your review platform -- all into a clean JSON block.
  5. Easy to validate. JSON is simple to lint, test, and debug. Paste it into any validator and get instant feedback.
  6. Faster indexing. Pages with properly structured JSON-LD see up to 4.2x faster indexing for certain schema types, according to industry analysis.

Essential JSON-LD Tools for Merchants

You do not need to hand-write JSON-LD. Here are the tools that matter:

Google Rich Results Test

URL: https://search.google.com/test/rich-results

This is your primary testing tool. It renders your page through the same system Googlebot uses -- executing JavaScript, loading external resources, building the complete DOM -- then parses the structured data from the rendered output. It tells you which rich results your page is eligible for and flags any errors.

Schema Markup Validator

URL: https://validator.schema.org

This validates your markup against the full Schema.org vocabulary, not just Google's supported types. Use it to catch issues that the Rich Results Test might miss because they relate to schema types Google does not currently use for rich results but that AI engines do consume.

Google Search Console Enhancement Reports

After your schema is live, Search Console's Enhancement reports show you how Google is reading your structured data across your entire site. You will see counts of valid items, items with warnings, and items with errors -- broken down by schema type.

JSON-LD Playground

URL: https://json-ld.org/playground/

The official JSON-LD playground lets you paste any JSON-LD block and see how it expands, compacts, and resolves. Useful for debugging @id references and understanding how nested objects relate.

Browser Extensions

The "Structured Data Testing Tool" Chrome extension by Google and third-party tools like "Schema Builder" let you inspect any page's structured data without leaving the browser.

A Complete JSON-LD Template for a Product Page

Here is a production-ready JSON-LD block that covers everything AI engines and Google look for on a product page:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Organic Cotton Crew Neck T-Shirt",
  "description": "100% GOTS-certified organic cotton. Pre-shrunk, 180 GSM midweight fabric. Available in 8 colors.",
  "image": [
    "https://example.com/images/tshirt-white-front.jpg",
    "https://example.com/images/tshirt-white-back.jpg",
    "https://example.com/images/tshirt-white-detail.jpg"
  ],
  "brand": {
    "@type": "Brand",
    "name": "EcoWear"
  },
  "sku": "ECW-CREW-WHT-M",
  "gtin13": "0012345678905",
  "color": "White",
  "size": "M",
  "material": "Organic Cotton",
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/products/organic-cotton-tshirt-white",
    "priceCurrency": "USD",
    "price": "34.00",
    "priceValidUntil": "2027-12-31",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition",
    "seller": {
      "@type": "Organization",
      "name": "EcoWear Store"
    },
    "shippingDetails": {
      "@type": "OfferShippingDetails",
      "shippingRate": {
        "@type": "MonetaryAmount",
        "value": "0",
        "currency": "USD"
      },
      "shippingDestination": {
        "@type": "DefinedRegion",
        "addressCountry": "US"
      },
      "deliveryTime": {
        "@type": "ShippingDeliveryTime",
        "handlingTime": {
          "@type": "QuantitativeValue",
          "minValue": "1",
          "maxValue": "2",
          "unitCode": "DAY"
        },
        "transitTime": {
          "@type": "QuantitativeValue",
          "minValue": "3",
          "maxValue": "5",
          "unitCode": "DAY"
        }
      }
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.7",
    "bestRating": "5",
    "worstRating": "1",
    "reviewCount": "189",
    "ratingCount": "234"
  },
  "review": [
    {
      "@type": "Review",
      "author": {
        "@type": "Person",
        "name": "Alex T."
      },
      "datePublished": "2026-02-10",
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": "5",
        "bestRating": "5"
      },
      "reviewBody": "Softest cotton tee I have ever worn. True to size, holds shape after washing."
    }
  ]
}

JSON-LD and AI Visibility: The Connection

The reason JSON-LD matters for AI goes beyond traditional rich results. Research shows that 71% of pages cited by ChatGPT and 65% of pages cited by Google AI Mode include structured data markup. Schema-compliant pages are cited 3.1 times more frequently in Google AI Overviews compared to pages without structured data.

AI engines do not parse your JSON-LD in real time when a user asks a question. Instead, during the indexing phase, search engine crawlers (Googlebot, Bingbot) extract your JSON-LD data and store it in their indexes. When AI systems like ChatGPT, Perplexity, or Google AI Overviews generate answers, they query these indexes. Your JSON-LD reaches AI through this indirect but critical path.

This means two things for merchants:

  1. Your JSON-LD must be in the server-rendered HTML. If it only appears after client-side JavaScript executes, Googlebot's crawler may miss it, and it will never reach the AI systems that query Google's and Bing's indexes.
  2. Your JSON-LD must be accurate and current. Stale prices, wrong availability, outdated ratings -- these do not just hurt your rich results. They feed incorrect information into AI systems that millions of people use to make purchase decisions.

Getting Started: Your First JSON-LD Implementation

If you have never added JSON-LD to your store, start with these three schema types in order:

  1. Product schema on every product page. Include name, description, image, brand, SKU, price, currency, availability, and condition at minimum.
  2. Organization schema on your homepage. Include name, URL, logo, contact information, and sameAs links to your social profiles.
  3. BreadcrumbList schema on every page. Map your site's navigation hierarchy so AI understands your catalog structure.

After those three, add FAQPage schema to product pages with common questions, Review/AggregateRating schema if you have customer reviews, and Article schema to your blog posts.

The investment is modest -- a few hours of implementation for a permanent improvement in how every AI system and search engine understands your store. With structured data now appearing on 51.25% of all crawled web pages and JSON-LD commanding 89.4% of the format market, this is not early-adopter territory. It is baseline ecommerce infrastructure.

Up next

Product Schema

The definitive guide to Product schema markup for ecommerce.