What Is JSON-LD and Why Is It the Preferred Schema Format?
Three formats exist and one of them won. This page explains why that matters rather than presenting three equal options, because the choice is settled and the useful question is what to do about whatever your site already has.
One Of These Won
JSON-LD is the recommended format and the dominant one in practice. The other two are not wrong and there is no genuine choice to weigh, so this page explains why rather than laying out options.
Why we open with the answer. Comparisons imply a decision.
Presenting three formats evenly suggests you have something to choose. You do not. A page that built towards the conclusion would waste the time of somebody who arrived to make a decision that was already made for them.
What actually changed. A clear recommendation appeared.
The major search engines now recommend this format specifically. Where a standards body and its main consumers agree on one approach, the others become historical rather than alternative.
Why anybody still asks. Older material and older sites.
A great deal of published writing predates the recommendation. A great many websites were built before it. Both keep the question alive long after it stopped being open.
What this page is actually for. Two things.
Understanding why the winning format wins, which explains the maintenance argument. And recognising the older formats when you find them on a site you inherited, which is the more common situation.
What Makes It Different
The description sits in its own separate block rather than being attached to the page's visible elements. That single difference produces every advantage below it.
What the older approach did. Attached labels to elements.
The description was woven into the page itself, with labels added to the actual heading, the actual address, the actual price. The information and its description occupied the same place.
What this format does instead. Keeps them apart.
The description sits by itself, restating what the page contains without touching how the page is built. The visible page and the machine-readable description are two separate things describing the same subject.
Why that is the whole story. Everything follows.
Easier to add, easier to change, easier to check, harder to break. Each of those is a consequence of the separation rather than a separate feature somebody designed in.
What it costs. Duplication of a kind.
The same information now exists in two places on the page, which means it can disagree with itself. That is the genuine trade. It is why matching the description to the visible content matters.
Why the trade is worth taking. Disagreement is checkable.
Two things that can disagree can be compared. Markup tangled through a page cannot easily be read on its own at all, which makes it harder to audit than to break.
Why Separation Matters
Markup tangled into a page breaks when the design changes. A separate block survives a redesign untouched. That is why the older approaches produced so much maintenance work.
What breaks and why. Rebuilding the page removes the labels.
Where the description is attached to visible elements, replacing those elements removes the description with them. A redesign that touches nothing about the content can silently delete every assertion the site was making.
Why nobody notices. Nothing visible changes.
The page still shows the address and the times. Only the machine-readable description has gone, which produces no error, no warning and no complaint from anybody.
What separation buys. Independence.
A description in its own block is unaffected by changing the layout, the theme or the visible structure. The same block keeps working through a redesign that changes everything a visitor sees.
The other maintenance gain. One place to look.
Checking what a page asserts means reading one block rather than hunting through the page for labels attached to elements. That difference is the reason auditing an older site is slow work.
Where this becomes practical. After any change.
A redesign, a platform update or a template edit can all alter what a site asserts. How to test schema markup covers checking it afterwards.
The Older Formats
Two earlier approaches predate the current recommendation. Neither is wrong and both are simply harder to maintain, which is the entire criticism.
The first approach. Labels on page elements.
The commoner of the two. Descriptions were added directly to the page's own elements, marking which heading was the product name and which figure was the price. Widely used and widely supported.
The second approach. A more formal relative.
Similar in placement and more rigorous in origin, coming from a broader family of standards for describing data. More capable in principle and more demanding to work with.
Why both lost. Not correctness.
Both work and both are still read. They lost on maintenance, since anything woven into a page shares that page's fragility. They also lost on ease of implementation.
What to do if you have one. Nothing urgent.
A site with working older markup is not broken and does not need immediate migration. The time to change is when the site is being rebuilt anyway.
What not to do. Add the new alongside the old.
Implementing the current format on a page that already carries an older one produces two descriptions of the same thing. Block five covers why that is worse than either alone.
Why You Still Meet Them
Inherited sites and older platform themes still carry the earlier formats. Finding both on one site is a common diagnosis. Mixing formats on a single page causes conflicts.
Where they survive. Themes and templates.
A theme written some years ago may include the older approach throughout its templates. Nobody chose it, nobody knows it is there, yet it continues describing every page it built.
How mixing happens. Well meant additions.
Somebody adds current-format markup to a site whose theme already outputs the older kind. Both now describe the page. Where their values differ, the page is asserting two contradictory things.
What the conflict produces. Unpredictable results.
Which description is used is not something you control. A page can behave inconsistently for reasons nobody investigating the visible content would ever find.
Why it is a common diagnosis. It looks like nothing.
Both sets validate individually. Nothing reports an error, because neither is malformed. The problem is that they disagree, which no single check reveals.
Where to take this. The troubleshooting page.
Conflicting sources is the commonest genuine fault in this subject. Why is my schema markup not working covers finding all of them.
It Is Generated More Often Than Written
On most platforms nobody wrote the markup. The platform or an extension produced it, which is why almost no business knows what its own site is asserting.
How it appears. Automatically, from fields.
A platform takes values somebody entered into settings or product fields and builds descriptions from them. The output is created without anybody reviewing what it says.
Why that matters. Nobody checked it.
If nobody wrote it, nobody read it either. The site is still making every one of those claims. The assertion rule applies identically whether a person or a platform produced them.
What goes wrong in practice. Wrong values, repeated.
A field filled in carelessly years ago becomes a false statement on every page that uses it. The error is not visible on the page and it is asserted at scale rather than once.
Why almost nobody looks. There is no prompt.
Nothing tells a business that its platform has been describing it. Without a reason to look, the markup is discovered only when something goes wrong or somebody audits the site.
Where the platform detail sits. Its own page.
What each platform produces by default, plus what that means for you, is covered in schema markup by platform.
What This Means For A Business
The format question is largely settled and it is not the question worth your attention. What matters is what your site is asserting and whether it is true.
Why the format rarely needs a decision. It is chosen for you.
Anybody implementing markup now uses the current format by default. Anything your platform generates will already use it. There is very little left to decide.
What replaces it. Three questions.
What types your site currently asserts, where each of them comes from, then whether the values are accurate. Those are answerable and they are where the actual risk sits.
Why the third question is the important one. The assertion rule.
Format affects maintenance. Accuracy affects whether your site is making false statements. What is schema markup sets out why that distinction carries weight.
When the format does matter. At a rebuild.
If a site is being redesigned, moving to the current format is worth doing as part of that work rather than as a separate exercise.
What we use. The separated format, on everything.
Every page we build carries its description in its own block, which is why a redesign here does not quietly remove it. The full series is on the schema and structured data guide.
Nobody wrote it.
Nobody checked
it.
On most platforms the markup was generated from fields somebody filled in years ago. The site is still making every one of those claims. We will tell you what your site currently asserts, where each part comes from and whether the values are accurate.
On every page we build:
A site with working older markup is not broken. We will say so rather than sell a migration.
Every guide.
One practice.
What structured data is, which types apply to your business, how to test it, where the results features come from and what to do when nothing appears.
