JSON-LD

Within this block, a shop or an editorial team describes in machine-readable form what the page is actually about: which product, which price, which brand, which rating. Search engines and increasingly generative AI systems read this information as a reliable factual basis against which they compare the rest of the unstructured text.

The name describes the method precisely. "JSON" is the lean data format of key-value pairs familiar from software development. The appended "LD" (linked data) stands for the idea of linking individual data points with each other and with the outside world via shared vocabularies. The vocabulary used practically everywhere on the web is schema.org, a schema directory supported jointly by Google, Microsoft, Yahoo and Yandex. JSON-LD is therefore the format, schema.org the dictionary. The two terms are often used synonymously but describe different levels of the same thing.

How JSON-LD works

Technically, JSON-LD is a self-contained data block that changes nothing about the visible layout of a page. A crawler reads the script content, recognises from the @type which entity it is (for example Product, Article, FAQPage or Organization) and assigns the following properties to this entity. At its core, a minimal product block looks like this:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Alpine 3000 hiking jacket",
  "brand": { "@type": "Brand", "name": "Example brand" },
  "gtin13": "4012345678901",
  "offers": {
    "@type": "Offer",
    "price": "189.00",
    "priceCurrency": "EUR",
    "availability": "https://schema.org/InStock"
  }
}

The decisive advantage of this separation: the structured data exists independently of the markup that a person sees in the browser. A designer can rebuild the layout without accidentally destroying a markup attribute, and maintenance takes place in a single, clearly defined place. This is exactly what makes JSON-LD so manageable for content management systems and shop software: the system generates the block from the master data that exists anyway and appends it to the page, instead of having to mark up every single price or availability detail in the template.

Why Google prefers JSON-LD

Structured data can basically be delivered in three formats: JSON-LD, Microdata and RDFa. Google supports all three but expressly recommends JSON-LD. The reasons are tangible and match what implementation teams experience in practice:

• Fewer errors. Microdata and RDFa distribute attributes across the entire visible HTML tree. If an element is rebuilt, deleted or replaced via JavaScript, the markup easily breaks, often unnoticed. An isolated JSON-LD block remains unaffected.
• Easier maintenance. The data is in one place, can be versioned and can be generated automatically, instead of being scattered across dozens of template fragments.
• More reliable crawling. A block in the document head is read reliably, whereas dynamically reloaded Microdata attributes can be overlooked depending on the rendering order.
• Protection against accidental changes. Someone who only works on the layout is more likely to delete an itemprop attribute than a script section that is clearly recognisable as a data block.

Microdata is still justified where markup absolutely has to be attached inline to the visible element, and RDFa occupies a shrinking niche. For the majority of today's projects, however, JSON-LD is the sensible standard, an assessment shared by the format overview on Wikipedia.

JSON-LD for e-commerce: the Product schema

In online retail, the Product schema is by far the most important use case. It was one of the first schema types to make structured data popular in the SEO community, because it had directly visible effects: star ratings, price and availability information in the search results, the so-called rich snippets. What matters for the effect is not the presence of any product block but the fields that are filled in. The following are particularly relevant:

The last two fields in particular have gained in importance since generative AI systems began formulating purchase recommendations: an agent making a recommendation reads delivery time and return rights directly from the markup. An iron rule applies here: structured data may only contain information that is also visible to users on the page. Anyone who uses JSON-LD to show prices or ratings that are missing from the visible content risks a manual action by Google.

JSON-LD in Shopware

For Shopware operators, JSON-LD is particularly relevant at the moment because the platform is moving. Newer Shopware 6 versions can output structured data natively as a separate JSON-LD block in the page head, instead of having to embed it via Microdata or a custom plugin as before. This capability partly depends on a feature flag and is not automatically active in every installation. Anyone on an older version or needing more fields than the standard set closes the gap with established extensions from the Shopware Store, such as SEO tool plugins that complete the Product schema.

The often underestimated point: JSON-LD is only as good as the product data behind it. A patchy range with missing GTINs, inconsistent attributes and outdated descriptions cannot be rescued by a schema plugin. Clean markup makes the existing facts unambiguous; it does not invent any. Maintaining the source data, often in the PIM, is therefore the invisible but decisive part of the work.

JSON-LD and AI visibility

While JSON-LD was originally a pure display signal for attractive snippets, it has developed into a comprehension signal. Language models do not interpret structured data like running text that they first have to make sense of, but take it as an ordered factual basis. Product data that is cleanly marked up can be assigned unambiguously to an entity instead of being guessed from prose. However, the industry overestimates how strong the direct effect on AI citations is: individual studies find only slight movement in citations after markup is added. The solid reason for taking JSON-LD seriously is therefore not a promised citation multiplier but the basic prerequisite that your own product facts are available unambiguously and without room for interpretation at all.

JSON-LD in combination with other schema types

In practice, it rarely stops at the pure Product block. A well-marked-up page combines several schema types, each describing a different aspect and supporting the others. On a shop page, three or four entities can quickly come together without the code having to feel cluttered, because each type stands in its own clearly named object.

• Organization or Store. Describes the company itself: name, logo, contact channels, social profiles. This block helps AI systems and search engines to recognise the brand as an entity in its own right and to attribute statements about it correctly.
• BreadcrumbList. Maps the navigation hierarchy and makes it traceable for crawlers where a page sits in the catalogue.
• FAQPage. Marks up question-and-answer pairs. For generative engines in particular, which often want to answer a question directly, cleanly structured FAQ content is a rewarding, easily extractable building block.
• Review and AggregateRating. Deliver ratings as separate, verifiable data points instead of running text.

It is important not to stack the blocks arbitrarily but to mark up only what really appears on the page and is relevant to the search intent. Excessive, irrelevant markup improves nothing and merely increases the risk of errors during maintenance.

Typical mistakes in implementing JSON-LD

Most problems with JSON-LD arise not from missing markup but from faulty or dishonest markup. The recurring pitfalls:

• Markup without a visible counterpart. Marking up ratings or prices that do not appear on the page: the classic reason for a manual action.
• Outdated values. A statically maintained block carrying yesterday's price while the page has long been showing a new one. JSON-LD should be fed from the same source as the visible content.
• Incorrect or missing required fields. An Offer without price or priceCurrency is incomplete and is sometimes ignored by Google.
• Invalid syntax. A missing comma or an unclosed bracket makes the entire block unusable. Validation before deployment is therefore mandatory, not a nice-to-have.

A practical workflow looks like this: generate the markup automatically from the master data, run it through the Rich Results Test and a schema validator before every release and spot-check it on live pages. That way the markup stays correct permanently, instead of being set up cleanly once and then quietly becoming outdated.

The history: from microformats to the preferred standard

JSON-LD did not appear out of nowhere but is the provisional result of a longer development towards a machine-readable web. The first attempts to embed meaning in HTML ran via microformats and later via Microdata and RDFa, all methods that attached markup directly to the visible HTML elements. This worked but was error-prone and closely intertwined with the layout. Every design change carried the risk of damaging the semantics.

JSON-LD was developed as a specification in its own right and published as a recommendation of the World Wide Web Consortium in 2014. The decisive conceptual break: meaning is decoupled from layout and moved into a separate data block. When Google increasingly preferred JSON-LD in the following years and finally recommended it openly, practice tipped over: today it is the norm in professional environments, while Microdata and RDFa survive mainly in legacy inventories or special cases. Anyone setting up a new project has hardly any reason to decide against JSON-LD.

This development also explains why JSON-LD fits the current AI era so well. A web whose content is available in clearly separated, machine-readable data blocks is exactly what both search engine crawlers and the retrieval layers of generative systems can evaluate reliably. What began as an SEO tool for attractive snippets has thus become a building block of machine knowledge processing, and its importance is growing rather than shrinking.

Frequently asked questions about JSON-LD

Is JSON-LD a ranking factor? Not directly. JSON-LD does not improve the position as such but enables rich snippets and unambiguous entity matching. The better presentation in the results can increase the click-through rate, but the effect is indirect.

Where does the JSON-LD block go? The document head is recommended; technically, the body also works. More important than the position is that the block is valid and only describes visible content.

How do I check my JSON-LD? With Google's Rich Results Test and the Schema Markup Validator. Both report syntax errors and missing required fields before they go live.

Do I need JSON-LD and a Merchant Center feed? For Google, yes: both sources feed the Shopping Graph. The feed is the canonical data channel, and the page markup supplements it. They do not replace each other.

Does incorrect JSON-LD do harm? Yes. Markup that describes content not visible on the page, or that makes misleading statements, can lead to a manual action. Correctness comes before completeness.