What is JSON-LD? The Beginner-to-Expert Guide
Last Updated: February 25, 2026 · 12 min read
JSON-LD stands for JavaScript Object Notation for Linked Data. It is a lightweight format for adding structured data to web pages — metadata that search engines, browsers, and AI systems read to understand what your content is actually about. If you have ever seen star ratings, recipe cards, or FAQ dropdowns in Google search results, they were powered by JSON-LD.
💡 The 30-second explanation
Your HTML tells browsers how to display your content. JSON-LD tells search engines what your content means. A price tag in HTML is just text. Wrapped in JSON-LD Product schema, it becomes structured data that Google can display as a rich result.
1. How JSON-LD Actually Works
JSON-LD is added to a page inside a special <script> tag with the type application/ld+json. It does not change anything visible to users. It is purely for machines.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "What is JSON-LD?",
"datePublished": "2026-02-25",
"author": {
"@type": "Person",
"name": "Jane Doe"
}
}
</script>The three key pieces:
- @contextAlways
https://schema.org— the shared vocabulary that defines what every type and property means. - @typeWhat kind of thing this is:
Article,Product,LocalBusiness,Recipe, etc. - PropertiesKey-value pairs like
headline,datePublished,price— all defined by Schema.org.
2. JSON-LD vs Microdata vs RDFa
There are three ways to add structured data to HTML. Google supports all three but officially recommends JSON-LD.
| Format | Where it lives | Ease of use | Google recommendation |
|---|---|---|---|
| JSON-LD | Separate <script> tag | ⭐⭐⭐ Easiest | ✅ Recommended |
| Microdata | Mixed into HTML attributes | ⭐⭐ Moderate | Supported |
| RDFa | Mixed into HTML attributes | ⭐ Complex | Supported |
JSON-LD wins because: (1) it is completely separate from your HTML so it cannot break your layout, (2) it is easy to update without touching the DOM, (3) JavaScript frameworks can inject it dynamically, and (4) it is the easiest to validate and debug.
3. Which Schema Types Get Rich Results?
RecipeRecipe card with image, cooking time, ratingsProductPrice, availability, star ratings in SERPFAQPageExpandable FAQ directly in search resultsHowToStep-by-step carousel on mobileEventEvent listing with date, location, ticket priceJobPostingJob listing in Google JobsArticleTop Stories eligibility, author displayLocalBusinessKnowledge Panel, Maps integration4. How to Add JSON-LD to Any Website
Plain HTML
Paste inside <head> or just before </body>:
<head>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "WebSite",
"name": "My Website",
"url": "https://example.com"
}
</script>
</head>Next.js / React
// In your page component or layout.tsx
const jsonLd = {
"@context": "https://schema.org",
"@type": "Article",
"headline": "My Article Title",
"datePublished": "2026-02-25",
};
return (
<>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>
{/* ... rest of page */}
</>
);WordPress (without a plugin)
Add to your theme's functions.php:
function add_json_ld() {
if (is_singular('post')) {
echo '<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BlogPosting",
"headline": "' . get_the_title() . '",
"datePublished": "' . get_the_date('c') . '"
}
</script>';
}
}
add_action('wp_head', 'add_json_ld');5. The 5 Most Common JSON-LD Mistakes
Missing @context
Always include "@context": "https://schema.org" — without it, search engines cannot resolve the vocabulary.
Invalid JSON syntax
A single missing comma or unclosed brace breaks the entire block. Validate at schemavalidator.org before deploying.
Content mismatch
The structured data must reflect actual visible page content. Do not mark up content that is not on the page — Google will penalise this.
Wrong property names
Schema.org property names are case-sensitive. "datePublished" works; "DatePublished" does not.
Missing required properties
Most schema types have required properties for rich results. Check Google's documentation for the specific type you are implementing.
Frequently Asked Questions
Does JSON-LD guarantee rich results in Google? ▼
No. Valid JSON-LD makes you eligible for rich results, but Google decides whether to display them based on content quality, page authority, query relevance, and whether the schema accurately reflects the page. A zero-error validation report is a necessary condition, not a sufficient one.
Can I add multiple JSON-LD blocks on one page? ▼
Yes — you can have as many script type="application/ld+json" blocks as you need. Each one is parsed independently. This is actually better practice than combining everything into one large block, because it keeps each schema type isolated and easier to maintain. Common pattern: one block for Organization in the layout + one block per page type (Article, Product, etc.).
Does JSON-LD need to be in the head tag? ▼
No. Google can read JSON-LD from anywhere in the document — head or body. Best practice is head so it is available as early as possible during parsing, and so it does not affect visible page rendering. In Next.js, placing it in the server component means it is always in the initial HTML response, which is ideal.
How long does it take for JSON-LD to appear in Google rich results? ▼
Typically 2–4 weeks after Google re-crawls and processes the page. You can speed this up by submitting the URL in Google Search Console under URL Inspection → Request Indexing. After crawling, the rich result still takes 1–2 weeks to appear in active SERPs as Google processes and validates the structured data.
Is JSON-LD different from Schema.org? ▼
JSON-LD is the format (how you write structured data). Schema.org is the vocabulary (what the properties and types mean). Think of Schema.org as a dictionary and JSON-LD as the language you write it in. You can also express Schema.org using Microdata or RDFa format, but JSON-LD is the recommended choice because it is clean, separate from HTML, and easiest to validate.
Can I use JSON-LD with Next.js App Router? ▼
Yes — add a script tag with type="application/ld+json" and dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} directly in your page.tsx or layout.tsx server components. Since these are server-rendered, the JSON-LD will be in the initial HTML response, which is exactly what Googlebot needs. Do not use useEffect to inject JSON-LD — that makes it client-side only and invisible to bots that do not execute JavaScript.
What happens if my JSON-LD has a syntax error? ▼
A JSON syntax error (missing comma, unclosed bracket, unescaped quote) causes the entire JSON-LD block to fail silently. Google ignores the malformed block completely — no error in GSC, no rich result, no feedback. This is why validating before deployment is critical. Always run your schema through a validator that checks JSON syntax first, then schema.org property validation.
Can I generate JSON-LD dynamically from my CMS data? ▼
Yes — and this is the recommended approach at scale. In Next.js, fetch your CMS data in the server component and use JSON.stringify() to generate the JSON-LD from real data. In WordPress, use a filter hook to generate schema from post meta. Never hardcode values like price, availability, or rating — these change and stale schema causes rich result removal.
Validate Your JSON-LD Instantly
Paste your JSON-LD and get errors, warnings, and rich-result eligibility in seconds.
Open Free Validator →Related Guides
→ What is Structured Data?
The broader context of structured data, schema, and rich results
→ Microdata vs JSON-LD
Deep dive comparison of all three structured data formats
→ JavaScript SEO & Schema
Server rendering vs client-side JSON-LD injection explained
→ Schema Markup Checker
How to check and validate your JSON-LD on any page
→ Schema Markup Generator
Generate correctly formatted JSON-LD without writing code
→ Google Rich Results Guide
Which JSON-LD types unlock which Google rich results