Structured data and JSON-LD: a beginner’s guide
Structured data is a machine-readable description of what a page contains: this is an article, this is its headline, this is who published it. Search engines use it to understand pages and, sometimes, to show richer results.
Three formats, one clear favourite
Structured data can be written as Microdata or RDFa, which are attributes scattered through your HTML, or as JSON-LD, which is a single block of JSON inside a <script type="application/ld+json"> tag. JSON-LD is the easiest to write, read and maintain, because it sits apart from your layout. Major search engines accept it, and it is the format the builder below produces.
How a JSON-LD block is shaped
{
"@context": "(the schema.org vocabulary address)",
"@type": "Article",
"headline": "How to repot a cactus",
"datePublished": "2024-03-18",
"author": {"@type": "Person", "name": "Sam Example"}
}
@contextnames the vocabulary, almost always schema.org.@typesays what kind of thing is described.- The other keys are properties of that type. Values can be text, numbers, dates in ISO format, or nested objects with their own
@type.
JSON-LD builder
The builder runs in your browser and only arranges what you type. Wrap the output in a JSON-LD script tag in your page head, then test it with a structured data validator.
Which type for which page
| Page | Type to consider |
|---|---|
| Blog post, news story, guide | Article or BlogPosting |
| Questions and answers visible on the page | FAQPage |
| Home or about page of a company or project | Organization |
| Step-by-step instructions | HowTo |
| Trail of parent pages above the title | BreadcrumbList |
The honesty rule
Markup must describe what a visitor can actually see on the page. Marking up questions that are not on the page, inventing dates, or describing things the page does not offer goes against search engine guidelines and can lead to the markup being ignored or a manual action. Never add markup for opinions, scores or reviews you did not genuinely collect.
Common mistakes
- Trailing commas or single quotes, which make the whole block invalid JSON.
- Dates in local formats like 18/03/2024 instead of 2024-03-18.
- Copying one block onto every page so every page claims the same headline.
Questions
Will structured data make my page rank higher?
It helps search engines understand the page. It does not guarantee better rankings, and showing a rich result is always the search engine’s choice.
Can a page have more than one block?
Yes. A guide can carry an Article block and a BreadcrumbList block side by side.