In short
JSON-LD is a script tag containing schema.org-formatted JSON that explicitly describes a page's content type and relationships — pick the schema types that match what's actually on the page (Article, Product, FAQPage, BreadcrumbList, Organization), nest them in one @graph, and validate before publishing.
What JSON-LD actually does
JSON-LD is a block of JSON, wrapped in a <script type="application/ld+json"> tag, that explicitly labels what a page is and how its parts relate — "this is an Article, published on this date, by this author, answering these FAQ questions." Search engines and AI systems can infer a lot from plain HTML, but structured data removes the guesswork entirely, which is why it's rewarded with rich results and easier machine parsing.
The schema types worth knowing
- Article — for blog posts and guides: headline, description, image, dates, author, publisher.
- Product — for anything sold: price, availability, reviews.
- FAQPage — question/answer pairs that are genuinely visible on the page (see how to add FAQ schema).
- BreadcrumbList — the navigational path to the page, which can show as breadcrumbs directly in search results.
- Organization — your company's identity, logo, and social profiles; usually added site-wide, not per-page.
- HowTo — step-by-step instructions, useful for genuinely instructional content.
Use the smallest set that accurately describes the page — adding types that don't match the content is worse than adding none.
Combining multiple types with @graph
A single page often deserves more than one schema type — an article that also has an FAQ section and sits in a breadcrumb hierarchy. Rather than three separate script tags, combine them into one @graph array under a shared @context:
``json { "@context": "https://schema.org", "@graph": [ { "@type": "Article", "headline": "..." }, { "@type": "BreadcrumbList", "itemListElement": [ ... ] }, { "@type": "FAQPage", "mainEntity": [ ... ] } ] } ``
This is cleaner to maintain and avoids any ambiguity about which entity a property belongs to.
The one rule that governs everything
Structured data must accurately describe what's actually visible on the page. Marking up an FAQ that isn't shown, a price that doesn't match what's charged, or a review that doesn't exist violates schema.org guidelines and search engine policies, and can get the markup ignored or the page penalized. Structured data is a machine-readable description of your content, not a separate content channel.
Where to put it
JSON-LD can go anywhere in <head> or <body> — placement doesn't affect whether it's read, unlike some older microdata formats that had to wrap the visible content. This makes JSON-LD easy to inject via a CMS or template system without touching the surrounding markup.
Validating before you ship
Run every page template through Google's Rich Results Test and the Schema.org validator before publishing. Check for: zero errors, correct nesting inside @graph, and that every claim in the JSON-LD matches the visible page content word for word. Re-validate whenever you change a template, since a small change to visible content can silently break the correspondence with the schema.
Common mistakes
- Copy-pasting a schema template without updating the actual values — leaving placeholder text in production JSON-LD.
- Mismatched dates, prices, or facts between the schema and the visible page.
- Over-nesting or duplicating the same entity across multiple script tags instead of one
@graph. - Forgetting
@idreferences when entities need to point at each other (e.g., an Article'sauthorreferencing anOrganizationdefined elsewhere in the same graph).
Common questions
Does adding structured data guarantee rich results?
No — it makes a page eligible, but search engines still decide whether and how to display rich results based on overall page quality and relevance.
Can I add multiple schema types to one page?
Yes, and it's often correct to — combine them in a single @graph array under one @context rather than multiple separate script tags.
How do I validate my structured data?
Google's Rich Results Test and the official Schema.org validator both check syntax and type correctness; always also manually confirm the schema content matches what's visible on the page.