JSON-LD: structured data written where there is none

That gap is the whole subject. Everything else on a page describes it to a reader; structured data describes it to a program, in a shape the program does not have to infer. A machine reading prose has to decide what the page is about. A machine reading a declaration only has to believe it or not.

What it is, in one paragraph

A block of JSON in the page's markup, conventionally in the head, naming a type from a shared vocabulary and filling in its fields. It says the same kind of thing as the title and description, in a form that does not have to be read as prose first. An Organization says who publishes the site. A WebSite names the site itself. A BreadcrumbList says where the page sits. A WebPage or BlogPosting says what this particular page is.

None of it is a promise about how a result will look. It is a statement of fact in a form that can be read without parsing prose.

What is written where none exists

The organisation and the site come from the brand profile, so they are the same on every page and correct by construction rather than by luck. The breadcrumb comes from the path. The page type comes from what the page is.

A home page is not given a breadcrumb, because it has nowhere to come from. That kind of small correctness is the whole reason to generate this rather than paste it.

The type is the part most often got wrong by hand. A tool page is not an article and a listing is not a blog post, and declaring the wrong one is worse than declaring nothing: it invites the reader to expect fields the page will never have, such as an author or a publication date on something that has neither. Deriving the type from what the page is avoids the question rather than answering it badly.

Why a broken block is worse than none

Absence costs a page the chance to say something. Invalidity can cost it more than that.

A parser meets one malformed block and has no obliging way to recover half of it. The usual outcome is that the block is discarded whole, and where your own markup sat in the same block, it goes with it. A page that described itself correctly until a stray comma arrived now describes itself not at all, and nothing on the page looks different.

This is the reason a record is checked before it is stored rather than after it is injected. A record that fails the check is dropped, and the page keeps its gap. Given the choice between saying nothing and saying something a parser will reject, the first is plainly the safer of the two, and it is the one that leaves your existing markup untouched.

How the blocks refer to each other

Several blocks on one page are not several unrelated statements. They form a graph, and @id is what stitches it together.

An Organization is defined once, with a name and a logo, and every page that needs a publisher points at that identifier rather than restating it. The alternative, which is common enough on sites that pasted their markup in by hand, is a publisher block repeated on every page and drifting out of step with itself: a name updated here, a logo path stale there, and a reader with no way to know which copy to believe.

References are worth checking in the same breath as validity. A pointer to an identifier that nothing defines parses cleanly and says nothing, which is the quietest failure in the set.

What must not be marked up

Structured data is supposed to describe what the page actually contains. A review the page does not show, a price it does not state, a rating nobody gave: marking those up is not an optimisation but a misrepresentation, and engines treat it as one.

Generation stays on the right side of that line by construction rather than by good intentions. The record is written from the page in front of it, so it can only describe what is there. Where the page does not claim something, there is nothing for the block to say about it.

What happens to markup you already have

It stays. Structured data already on the page is left alone, and nothing is merged into it. Two blocks describing different things are normal and expected; a generated block never edits a written one.

That includes markup a plugin put there and nobody has looked at since. Whether it is good is not the question being asked. The question is only whether the page declares a given thing at all, and where it does, the answer is to leave it be.

FAQ