JSON-LD fundamentals.
JSON-LD is the structured data format that declares a page’s meaning in a machine-readable form without changing a single pixel of the page.
A human reading a page infers what is what from the headings and the text: this is a service description, that is a price, this is an author’s name. For a machine the same inference is guesswork, and error-prone. Structured data removes the guesswork: a block embedded in the page says “this is an organization, its name is X, its founder is Y, this is the service it offers.” The block is invisible on screen, yet it is the layer machines read most carefully.
There are three formats, but in practice one is preferred. The other two scatter the markup through the HTML; that approach is hard to maintain and breaks easily when the layout changes. JSON-LD stands as a separate block, independent of the HTML, and stays the same even if the page’s visual structure changes completely. It is also the format Google explicitly recommends.
The basic structure
A JSON-LD block starts with a field declaring the context, and the nodes follow. Every node has a type — organization, person, article, service — and the fields defined for that type on schema.org are filled in. A single page can hold several nodes, and it is expected to; the real value is in connecting the nodes to each other.
Connecting is done with identifiers. Each node receives a stable identifier, and other nodes reference it. The organization is defined once, the person is defined once, and the page node points to both. Without this pattern the graph is a scattered pile: ten separate organization declarations, or ten repetitions of the same one — impossible to tell.
- One block, many nodes — all the nodes on a page gather into a single graph.
- Stable identifiers — organization, person and website are defined once and referenced from everywhere.
- The page’s own node — every page carries its own identity and connects to the site.
- Breadcrumb trail — the page’s place in the hierarchy, visible in search results too.
- Content node — article, service, product or definition, depending on the page type.
The most common mistake
The most dangerous use of structured data is declaring something that is not on screen. A rating that does not appear on the page, an unlisted question and answer, or an unwritten price placed in the schema creates two problems at once: it is an explicit violation of search engine rules and can be penalized, and it puts the page in contradiction with itself. When a model cannot find in the text what the schema says, trust does not rise — it falls.
The correct pattern is simple: the schema translates into machine language what already stands on screen. It adds no new information; it structures what exists. On this site the rule is enforced in code — the FAQ questions on the service pages live both in the schema and on screen, and the verification suite measures on every run that the two match.
The schema adds no new information; it translates existing information into machine language.
Where to start
Building a graph from scratch can look daunting, but the order is clear and every step leans on the previous one. First the identity: the organization or person node, with a stable identifier. Then the website node and each page’s own node. Then the breadcrumb trail — it feeds both the navigation structure and the appearance in search results. Last, the nodes specific to the page type: article, service, definition, question-and-answer.
The order can be skipped, but then the upper layers run on empty. An article node without an identity node cannot show its author; a page node without a website node cannot say which site it belongs to. The graph’s value is in its connections, and connections are built from the center outward.
Do not forget the maintenance side: hand-written schemas drift from reality within a few months. The page changes; the schema stays. That is why the schema should be produced by the build, derived from the page’s own data — making drift structurally impossible.
Validation and the common breakages
Rather than assuming a written schema can actually be read, verify it — and there are two layers. The first is syntax: is the block a valid data structure, can it be parsed? A single missing comma invalidates the whole block, and all structured data on that page is ignored. The second is meaning: does the resulting node list describe what the site actually is? An error-free but meaningless graph is technically valid and useful for nothing.
The usual breaking points are well known. Dates written in loose form — a machine-readable date demands a standard format; free text is not accepted. References pointing into the void — if a node references an identifier that does not exist, no connection is made. And required fields left empty — some types produce no rich results without specific fields.
Doing these checks by hand works once; the lasting solution is automation. A short check that parses every page’s schema blocks on each deploy and reports the node types makes breakage instantly visible. On this site that check lives inside the verification suite and measures on every route that the schema graph carries the expected nodes.
Finally, there is the matter of schema and content aging together. When a page’s text is updated, the date field in its schema must update too; otherwise the machine-readable layer and the visible layer drift apart and the freshness signal turns false. On this site the date fields are tied to a ledger, and the ledger advances only when the page’s OUTPUT changes — a date reset to today on every build would soon become a signal nobody heeds. The honest freshness declaration is the one that points at a page that really changed.
Which types actually pay off
Schema.org defines hundreds of types, and trying to use them all is a mistake; most types receive no special treatment from any search or answer engine. The types that make a difference in practice are few and depend on the kind of site. For a consulting site, the organization, person, service, article and question-answer types deliver nearly all the value; the rest is noise.
The selection criterion should be: does this type describe something that really exists on the page? Using the product type requires a real product; a product schema requires a real price. Choosing a type to declare something that does not exist is taking the wrong road from the first step. This site declares no prices because it publishes none — and the verification suite checks that no fabricated price field has been added.
There is also the question of scope: instead of putting every type on every page, one main node fitting the page type, surrounded by the identity nodes, is enough. On an article page the article node is the main node; on a service page, the service node. Putting both on the same page blurs the structure.