SpunkArt
Websites, APIs and search

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"}
}
  • @context names the vocabulary, almost always schema.org.
  • @type says 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

PageType to consider
Blog post, news story, guideArticle or BlogPosting
Questions and answers visible on the pageFAQPage
Home or about page of a company or projectOrganization
Step-by-step instructionsHowTo
Trail of parent pages above the titleBreadcrumbList

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.