Structured data: what JSON-LD does and what it can't promise

Structured data is a block of code that describes a page in terms a search engine understands without reading the prose: this is an article, published on this date, written by this person. The format Google recommends is JSON-LD, because it’s the easiest to maintain (Google Search Central, introduction to structured data). Markup makes a page eligible for a rich result, but it doesn’t guarantee one. And it only counts when it describes what people actually see on the screen.

Vocabulary and format aren’t the same thing

There are two pieces here. The vocabulary says which types and properties exist, such as Article, Offer and datePublished. Almost all the structured data Google Search uses comes from schema.org, a vocabulary founded by Google, Microsoft, Yahoo and Yandex and now kept up by an open community.

The format says how that vocabulary gets into the HTML. Google accepts three (Google Search Central):

JSON-LD, a <script type="application/ld+json"> block kept apart from the visible text. This is the recommended one.
Microdata, attributes spread across the tags in the body.
RDFa, also attribute based, tied to the visible content.

To Google, all three are equal as long as the markup is valid. JSON-LD’s edge is practical: since it doesn’t mix with the text, nesting one item inside another is easier, and editing the page is less likely to break the markup. Google also reads JSON-LD when JavaScript injects it into the page (Google Search Central).

What it can get you

The direct payoff is the rich result: a search result with more than the blue link, such as a rating, a price, a breadcrumb trail or a bigger image. The Search Gallery lists which types get their own display.

Google publishes cases from sites that added markup. Rotten Tomatoes marked up 100,000 pages and measured a 25% higher click-through rate on them than on pages without it. Nestlé measured an 82% higher click-through rate on pages that showed up as rich results (Google Search Central, introduction to structured data). These are numbers the companies reported to Google, with no test design alongside them. Read them as a sign it’s worth trying, not as a forecast for another site.

NN/g, the Nielsen Norman Group, helps explain why, even though it doesn’t measure structured data itself. It studies the special elements on a results page, the ones that break from the plain blue link. In an analysis of 471 queries run between 2017 and 2019, those elements got looked at in 74% of the cases where they appeared (Kate Moran and Cami Goray, NN/g). Eyes stopped moving down the list in order and started jumping between whatever stood out.

Moran and Goray describe four roles for these elements (NN/g, three key results page features). They work as signposts, since an image quickly confirms the result is about the right thing. They pull attention, reshape the question and sometimes hand over the answer outright.

There’s a less visible payoff too. Google uses markup to understand the page and to gather information about the people, companies and books mentioned in it (Google Search Central). According to that page, schema.org properties Google doesn’t require may still be useful to other search engines and tools.

What it doesn’t guarantee

Google’s general guidelines are blunt: correct markup, even when it passes the test, doesn’t guarantee a rich result. Markup makes the feature available, and the algorithm decides whether to show it. It weighs the searcher’s history, location and device, and sometimes it prefers a plain text result.

A feature can also go away. In June 2025, Google announced it would stop showing seven little-used types in Search, including Course Info, Claim Review and Vehicle Listing (Google Search Central Blog). The same post says the change doesn’t affect how pages rank, and that using these types outside Google Search isn’t affected. The post on FAQ pages covers a similar cut, the one to FAQPage.

Bad markup has a cost, but a limited one. A structured data issue can lead to a manual action, and the page loses eligibility for rich results. According to Google, that doesn’t change where the page ranks in regular search (general guidelines).

The rules Google enforces

Some rules are technical, and an automated test catches them. Others are about quality, and no tool checks them for you. The main ones, from the general structured data guidelines:

Only what’s on the screen. If the JSON-LD describes a performer, the page body has to talk about that performer. Hidden information stays out, even when it’s accurate.
A true picture of the page. Google’s example is a woodworking site that marks up instructions as recipes. The code can be valid, and the data is still irrelevant.
Every required property. An item missing a property its type requires won’t make it into a rich result.
The most specific type. When two schema.org types fit, use the more precise one.
On the page it describes. Markup lives on the page itself, not on a blank page made just to hold it.
Open access. If robots.txt or noindex blocks a page, its markup doesn’t get read.

More properties aren’t always better. Google’s introduction prefers fewer recommended properties that are complete and accurate over every one filled in with badly formed data.

When a page holds more than one item, like an article and its breadcrumb trail, they can be nested or listed separately. If two separate items refer to the same thing, @id links one to the other (Google Search Central).

Dates with a time zone

Article dates are a detail that often goes wrong. Google’s article documentation expects datePublished and dateModified in ISO 8601 format and recommends including the time zone. Without it, Google falls back to Googlebot’s own time zone, and the recorded time may not be the one the site meant.

How to check before and after you publish

Google lays out a path in three stages (introduction to structured data):

During development, the Rich Results Test validates the markup and, in some cases, shows a preview.
After publishing, the rich result status reports track your pages in Search Console, Google’s dashboard for site owners. Markup can break later because of a problem in the page template.
To measure the effect, compare pages before and after for a few months in the Performance report. Pick stable pages that don’t depend on the time of year.

To check markup against the schema.org vocabulary in general, without looking at Google features, there’s the Schema Markup Validator.

How it shows up in my work

On kahue.net, every blog post ships with a BlogPosting block built from its own frontmatter. The dates carry the time and the Brasília time zone, as in this post’s markup:

"datePublished": "2026-10-20T19:00:00-03:00",
"dateModified": "2026-10-20T19:00:00-03:00"

When a post has no revision date, dateModified repeats the publish date. I wrote that down in the code itself: repeating the publish date is honest, and a made-up modification date isn’t. The same page carries a BreadcrumbList with the path from home to blog to post, which is what readers see at the top.

On Vexor, my product for AI assistants on WhatsApp, the Brazilian site (in Portuguese) declares the offer and the price in structured data. The values match the visible table: a R$ 1,500 setup fee on the monthly plan and a monthly fee of R$ 400, R$ 650 or R$ 1,200. R$ is the symbol for the Brazilian real. That’s the point of the rule: a price that only existed in the code would be exactly the hidden information Google forbids.

None of these sites has published measurements of what the markup did in search. The examples show how I applied the rules, not a result.

Where the documentation seems to contradict itself

Google says to follow its own documentation, not schema.org’s, to know how Google Search behaves (Google Search Central). schema.org has plenty of types and properties Google doesn’t use, though other search engines and tools might. That suggests a practical split: if you want the rich result, follow Google. If you want to describe the page well for any machine reader, you can go further, as long as everything stays visible.

The bigger split is about the click. Google’s cases show more clicks on marked-up pages. NN/g points to the other side: when the answer already shows up on the results page, people settle their question there and click nothing (Kate Moran and Cami Goray, NN/g). That’s good for the searcher. For the site that wrote the information, not so much. Moran and Goray see this mostly with simple needs, like an address, a phone number or a definition (NN/g). When the decision means opening the page, like comparing plans or reading the whole piece, the click is still the way through.

The common mistake: marking up what the page doesn’t show

The costliest mistake is treating structured data as a second shop window. A rating that never appears in the text, a sale price that only exists in the code, an author the page never names. The automated test passes, because the syntax is right. Google asks for something else: the markup has to be a true picture of the page, and fake reviews can lead to a manual action (general guidelines). The check that fixes it is simple: for every property in the block, point to where it is on the screen.