What is JSON-LD?

It is embedded in the page as a separate block and is independent of the HTML structure. That independence is its greatest advantage over the other two structured data formats: even if the page’s visual layout changes completely, the block stays the same and does not break.

This is the format Google explicitly recommends. The other formats scatter the markup through HTML elements; they are hard to maintain and break easily when the layout changes.

A block opens with a field declaring the context and contains nodes. Every node has a type, and the fields defined for that type in schema.org are filled in. The real value lies in nodes being linked to one another by identity — unlinked nodes form a scattered heap, linked ones form a graph.

The most dangerous way to use it is to declare information that is not on screen. That is both a plain violation of search engine guidelines and something that puts the page at odds with itself. The correct pattern: schema adds no new information, it translates existing information into machine language.

It breaks silently: when a block is malformed the page goes on looking normal and no error message appears. That is why validation belongs to the deployment process.

Maintenance matters too: hand-written schema diverges from reality within months. The page changes, the schema stays. That is why the schema should be derived by the generator from the page’s own data — divergence then becomes structurally impossible.

And validation has two layers: syntax is checked by automated tools, meaning by human judgement. A graph that is free of errors but meaningless is technically valid and of no use at all.

• One block, many nodes — gather all the page’s nodes into a single graph.
• Stable identities — define the organisation, the person and the site once, and refer to them from everywhere.
• The page’s own node — every page should carry its own identity.
• Breadcrumb trail — the page’s place in the hierarchy.
• Content node — article, service or definition, depending on the page type.

This order can be skipped, but when it is the upper layers work in vain: an article node without an identity node cannot show its author, and a page without a site node cannot say which site it belongs to.

Example: two nodes linked by identity

The block below describes an organisation and a page it publishes; the page node links to the organisation by identity (@id), not by name. The organisation is defined once, and every page on the site refers to the same identity.

1. <script type="application/ld+json">
2. { "@context": "https://schema.org", "@graph": [
3. { "@type": "Organization", "@id": "https://www.example.com/#org", "name": "Example Ltd." },
4. { "@type": "WebPage", "@id": "https://www.example.com/about/#webpage",
5. "publisher": { "@id": "https://www.example.com/#org" } } ] }
6. </script>

How to test the block for validity and compliance with Google’s rules is covered under structured data.

If you want to know how your brand is cited in ChatGPT, Google AI Overviews and Perplexity, our GEO consulting records which questions and engines cite you and builds the prerequisites.