JSON-LD and structured data

JSON-LD is a block of JSON inside a <script type="application/ld+json"> element that describes what a page is about in a vocabulary machines already know, usually schema.org. It does not change how the page looks and it does not rank a page. It makes claims about the page legible without parsing prose, and every claim must be one the visible page also makes.

Status: Reference What this means
Audience: both, developer
Last verified: 2026-09-10
Product version: 6.3.2

Why the linked-data form won#

Three syntaxes express the same vocabulary. Microdata and RDFa attach attributes to the HTML elements that already display the values; JSON-LD puts a separate object in a script element and leaves the markup alone.

Syntax	Where it lives	Practical consequence
Microdata	`itemprop` attributes on visible elements	Cannot drift from the text, because it is the text. Breaks whenever the markup is restyled.
RDFa Lite	`property` attributes, same idea	Same coupling, a richer vocabulary model, rarely used outside publishing.
JSON-LD	One script block, usually in the head	Independent of layout, generated from the same record the page renders from. Free to drift, which is the risk.

The freedom to drift is the whole trade. A template that emits JSON-LD from a different source than the one that renders the page will eventually describe a page that no longer exists — a price that changed, an author who was removed, a date nobody updated. Generate both from one record and the problem cannot occur.

The rule that decides everything else#

Structured data must describe content that is visible on the page to the person who loads it. This is not a style preference; it is the condition every major search engine attaches to using the markup at all, and breaking it is the fastest route to having your markup ignored or penalised across the whole site.

Do not mark up a rating, review or FAQ the page does not display.
Do not mark up content behind a tab, an accordion or a modal unless it is genuinely present in the served HTML.
Do not describe a product, offer or availability the page does not state.
Do not mark up something that is true of a different page. Article on a category listing describes nothing.

Does Connect use JSON-LD?#

Used, on the public documentation pages, and generated by the build rather than written by hand. The corpus is built from page records: each record carries a canonical URL, a description, a status, an answer-first paragraph, its FAQ pairs and its sources. The HTML and the structured data are rendered from that one record, so the markup cannot describe a page different from the one it sits in.

The types that carry information a machine can act on are the ones worth emitting here: the page itself, its position in the documentation hierarchy, and its question-and-answer pairs where the page actually shows them. The organisation behind the site is JBRH Digital Solutions, and that is stated in the same place a reader would find it.

What is deliberately absent matters as much. There is no review or rating markup, because this corpus publishes none. There is no offer or price markup, because no page states a price. There is no Person author markup, because these pages are not written by a named human and inventing one to satisfy a schema field would be a fabrication with a validator's blessing.

{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "JSON-LD and structured data",
  "url": "https://connectbyjbrh.com/docs/technology/json-ld/",
  "description": "…the same string the meta description carries…",
  "isPartOf": {"@type": "WebSite", "name": "Connect by JBRH"}
}

Validation, and what validation does not tell you#

Parse the block as JSON before anything else. A trailing comma or an unescaped quote makes the whole thing invisible.
Result You have eliminated the failure that produces no error message anywhere — a malformed block is simply skipped.
Check the required properties for each type you claim.
Result A type missing its required properties is usually discarded rather than partially used.
Compare every emitted value against the rendered page, field by field.
Result This is the check no validator performs, and the one that decides whether the markup is honest.

A validator confirms the shape. It cannot confirm the truth, and a green result on markup that describes content the page does not contain is a false pass in the most literal sense.

Questions#

Does adding JSON-LD improve rankings?

No search engine has said that it does, and treating it as a ranking input leads to marking up things the page does not show. What structured data can change is *presentation* — whether a result is eligible for a richer format — and eligibility is not entitlement. Add it because it makes the page legible to programs, and accept the presentation as a side effect.

Should FAQ markup be added to every page that has questions on it?

Only where the questions and answers are genuinely on the page and written for a reader. Manufacturing a question so that a page qualifies for a format is the exact behaviour the visible-content rule exists to stop, and the eligibility rules for FAQ presentation have narrowed more than once.

Where should the script block go?

The head is conventional and the body is permitted; what matters more is that it is in the served HTML rather than injected later by a script. A page whose structured data only exists after client-side execution is relying on every consumer running that script, and many do not.