Structured data describes the page it sits on

A web page is written for a person. A machine reading it has to infer everything: that this number is a price, that this string is an author, that this date is when the thing was published rather than when it was updated. Structured data removes the inference. It is a small block of data, attached to the page, that states in an agreed vocabulary what the page is about.

What the format is

JSON-LD is JSON with two extra conventions. @context names the vocabulary the field names come from — for the web that is nearly always schema.org. @type says which kind of thing this is: an Organization, an Article, a Product, a set of questions and answers. Everything after that is ordinary key and value, where the keys are ones the vocabulary defines.

It goes in a script block with a type of application/ld+json. That type matters: a browser will not execute it, because it is not JavaScript. It is a data island, sitting inert in the page, there for anything that goes looking.

A block you can read line by line

This is what the JSON-LD Schema tool emits when you pick the Article type, wrapped exactly as it belongs in the page:

<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "Article", "headline": "How SEO works", "author": { "@type": "Person", "name": "Michael" }, "datePublished": "2026-07-25" } </script>

Five statements, no magic. @context points at schema.org, so every unprefixed name below is a schema.org name. @type is Article, which is the claim that this page is an article rather than a shop listing or a company page. headline is the article's title. author is not a bare string but a nested object with its own @type of Person, because an author is a thing with properties, not a label. datePublished is an ISO date, year then month then day, which is unambiguous in a way that "27/08" is not.

The tool offers five types — Organization, LocalBusiness, Article, Product and FAQPage — and emits a deliberately small set of fields for each: name, url and logo for an Organization; name, telephone and a nested PostalAddress for a LocalBusiness; name plus a nested Offer with price and currency for a Product; one question and answer pair for an FAQPage. That is a starting skeleton, not the full vocabulary. Real schema.org types have dozens of optional properties, and you add the ones that are true of your page.

What it does, and what it does not

Structured data does not raise a page's position by itself. What it does is make a result eligible for a richer presentation — a review line, a price, an expandable set of questions, a recipe card. Eligible is the important word. Meeting the requirements does not mean the richer form appears; whether it does is decided per result, per query, per device, and it can stop appearing without anything on your side changing.

The second half is the part people skip, so here it is bluntly. The markup must describe what is actually on the page. Structured data is a machine-readable restatement of visible content, not a parallel version of your site that only crawlers see. If the page shows no reviews, marking up reviews is a false statement. If the questions and answers are not on the page for a reader, an FAQPage block claiming them is a false statement. Search engines publish this as an explicit requirement and enforce it, and the enforcement is not a gentle correction — the usual outcome is that the rich presentation is withdrawn, sometimes across the whole site. Marking up content nobody can see is the fastest known way to lose the feature you were trying to obtain.

The ordinary ways it goes wrong

• A copied template nobody edited. A placeholder name, a logo URL that returns a 404, someone else's address. A machine reads it exactly as written.
• A price that has drifted. The block is data, so it goes stale silently. If it is generated by hand it will eventually disagree with the page, and disagreement is worse than absence.
• The wrong type. A shop category listing is not a Product. A blog index is not an Article. The type is a claim about what the page is.
• Broken JSON. One trailing comma, one unescaped quote inside a string, and the whole block is ignored. It fails silently — the page renders perfectly and the data is simply not there.

Checking it

Two separate checks, and both are worth doing. The first is that the JSON parses at all, which is what the tool guarantees for the blocks it writes, since it builds them from a JSON writer rather than by pasting strings together. The second is that the claims are true of the page, and no validator can do that one for you. Read the block and the page side by side and ask whether a stranger, given only the block, would recognise the page from it. If not, the block is describing something else.