What Is JSON-LD?
JSON-LD (JavaScript Object Notation for Linked Data) is a lightweight format for adding structured data to a web page so search engines can understand its content. It uses standard JSON syntax wrapped in a script tag and follows schema.org vocabulary to describe entities like a business, product, article, or FAQ. Google recommends JSON-LD as the preferred method for structured data because it sits in the page's code without altering visible HTML, making it easier to add, test, and maintain.
- Full name
- JSON-LD stands for JavaScript Object Notation for Linked Data, a W3C standard first published in 2014 (W3C).
- Google's preference
- Google explicitly recommends JSON-LD over Microdata and RDFa for structured data (Google Search Central documentation).
- Where it lives
- JSON-LD is placed inside a script type="application/ld+json" tag, typically in the page head or body (schema.org).
- Vocabulary
- JSON-LD for SEO uses schema.org types such as LocalBusiness, FAQPage, Product, and Article (schema.org).
What is JSON-LD in plain terms? #
JSON-LD is a way to describe what a web page is about in a language machines can read reliably. Humans look at a dentist's homepage and instantly understand the name, address, hours, and services. Search engines see mostly unlabeled text and have to guess. JSON-LD removes the guessing by attaching a small, structured block of data that explicitly states 'this is a dental practice, here is its address, here are its hours' using an agreed vocabulary. The 'JSON' part means it uses the same simple key-value format developers already use to exchange data. The 'LD', or Linked Data, part means the data references shared definitions so different systems interpret it the same way. Crucially, JSON-LD lives in the page's source code and is invisible to visitors; it changes nothing about how the page looks. It exists purely to communicate meaning to search engines, AI systems, and other software. For local businesses, that clarity is the difference between being understood and being overlooked, which is why our /wiki/schema-markup-guide treats it as essential.
How is JSON-LD different from Microdata and RDFa? #
Structured data can be expressed three ways: JSON-LD, Microdata, and RDFa. Microdata and RDFa embed their markup directly into your visible HTML, wrapping and tagging elements inline with extra attributes throughout the page. That means the structured data is tangled up with your content and layout, so editing one risks breaking the other. JSON-LD takes a completely different approach: it keeps all the structured data in a single self-contained block, separate from the HTML that renders your page. You can add, update, or remove it without touching your design or copy. This separation is the main reason JSON-LD has become dominant. It is easier to generate programmatically, simpler to inject through a tag manager, and far less error-prone to maintain because there is one place to look. All three formats can produce the same rich-result eligibility when done correctly, so the choice is about maintainability rather than capability. For nearly every modern site, and certainly the ones our /services/web-design team builds, JSON-LD is the sensible default, and legacy Microdata is usually migrated to it during a rebuild.
Why does Google recommend JSON-LD? #
Google publicly states that JSON-LD is its preferred structured-data format, and that endorsement carries real weight. The recommendation comes down to practicality. Because JSON-LD sits in a discrete script block, Google can parse it cleanly without wading through your presentational markup. It is also compatible with dynamic rendering: JavaScript frameworks and tag managers can inject or update JSON-LD after the page loads, which suits modern sites where content is assembled on the fly. Google can even read JSON-LD that is inserted via Google Tag Manager, giving non-developers a path to add structured data without editing templates. The format's separation of concerns means marketers can update schema without risking site stability, and developers can maintain it in one location. None of this means Microdata or RDFa are ignored, since Google supports all three, but when the search engine that dictates rich-result eligibility names a preferred method, following it removes friction and reduces the chance of parsing problems. That is why nearly every structured-data guide, including ours, defaults to JSON-LD examples.
What does JSON-LD actually look like? #
Here is a real example for a local plumbing company. The block declares its type as Plumber, a specific kind of LocalBusiness, then fills in properties like name, address, phone, hours, and geographic coordinates using schema.org vocabulary. Notice that everything lives inside a single script tag with the type application/ld+json, and that the syntax is ordinary JSON: keys in quotes, values in quotes or numbers, and nested objects for structured fields like the postal address. The '@context' line points to schema.org so search engines know which vocabulary is in use, and '@type' names the specific entity being described. A browser renders none of this; it exists solely for machines. You would paste this into the page's HTML, ideally in the head or just before the closing body tag. Every local business type, whether Dentist, Restaurant, Roofer, or HVACBusiness, follows the same pattern with different type names and properties. Once in place, you can confirm it with the /tools/schema-validator to catch typos or missing required fields before search engines ever see it.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Plumber",
"name": "Rivertown Plumbing Co.",
"image": "https://www.rivertownplumbing.com/logo.jpg",
"telephone": "+1-512-555-0142",
"email": "[email protected]",
"url": "https://www.rivertownplumbing.com",
"address": {
"@type": "PostalAddress",
"streetAddress": "1420 Cedar Street",
"addressLocality": "Austin",
"addressRegion": "TX",
"postalCode": "78701",
"addressCountry": "US"
},
"geo": {
"@type": "GeoCoordinates",
"latitude": 30.2711,
"longitude": -97.7437
},
"openingHours": "Mo-Fr 07:00-18:00",
"priceRange": "$$"
}
</script>How does JSON-LD connect to schema.org? #
JSON-LD is the format; schema.org is the vocabulary it speaks. Schema.org is a collaborative standard, backed by Google, Microsoft, Yahoo, and Yandex, that defines thousands of types and properties for describing things on the web, from LocalBusiness and Product to Event, Recipe, and JobPosting. When you write JSON-LD, the '@context' field points to schema.org, and each '@type' you choose must be a valid type from that vocabulary with properties spelled exactly as defined. Using the wrong property name, or inventing one, means search engines silently ignore it. This is why picking the most specific applicable type matters: a dental office should use Dentist rather than the generic LocalBusiness, because the more precise type carries properties and meaning tuned to that entity. Schema.org also defines which properties Google requires or recommends for each rich-result type, and those requirements are documented separately in Google's guidelines. In practice you consult both: schema.org for the vocabulary and Google's documentation for what a given rich result needs. Our /wiki/schema-markup-guide walks through choosing the right types for common trades.
How do you add JSON-LD to a website? #
There are three common ways to add JSON-LD. First, directly in your templates: paste the script block into the page's HTML, usually in the head or before the closing body tag, and populate it with the correct data for that page. On a CMS this often means editing a theme file or using a custom-fields block. Second, through a plugin or platform feature: WordPress SEO plugins, Shopify apps, and many site builders generate JSON-LD automatically from fields you fill in, which is the easiest route for non-developers. Third, through a tag manager: Google Tag Manager can inject JSON-LD across many pages from one place, useful for large or frequently changing sites. Whichever method you use, the data must be accurate and match the visible content on the page, because Google penalizes structured data that describes things not present to users. Dynamic pages should generate JSON-LD from the same source as the visible content so the two never drift apart. Our /services/wordpress-development team typically wires schema into templates so every new page is marked up automatically, without manual effort per page.
How do you test JSON-LD? #
Never publish structured data without testing it. Google's Rich Results Test and the Schema Markup Validator both parse your JSON-LD and report errors, warnings, and which rich-result types the page qualifies for. Errors, like a missing required property or a malformed value, can disqualify you from rich results entirely, while warnings flag recommended fields you have omitted. Paste your code or a live URL, and the tools show exactly what search engines see. Our own /tools/schema-validator does the same quickly for any page. Below is a second common example, an FAQPage, which powers the expandable question-and-answer rich results you see in search. Each question is a 'Question' object with an 'acceptedAnswer'. The FAQ content in the markup must match the FAQs actually visible on the page. After launch, Google Search Console's rich-result reports monitor your structured data over time and alert you to new errors, so testing is not a one-time step but an ongoing habit as pages and templates change.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "Do you offer emergency plumbing service?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes. We provide 24/7 emergency plumbing across the Austin metro, including nights, weekends, and holidays."
}
},
{
"@type": "Question",
"name": "Are your estimates free?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes. We provide free, no-obligation written estimates for all standard residential plumbing work before any job begins."
}
}
]
}
</script>Does JSON-LD help with rich results and AI Overviews? #
JSON-LD earns two related benefits. The first is rich results: enhanced search listings with star ratings, FAQs, prices, event dates, or business details pulled straight from your markup. These make your listing larger and more informative, which can lift click-through even without moving your ranking position. The second, increasingly important benefit is machine comprehension. AI systems that power search summaries and assistants rely heavily on clean, explicit data to understand and cite sources accurately. When your page states its facts in structured form, an AI is far more likely to represent your business correctly rather than guessing or omitting you. For local businesses, that can mean the difference between being named in an /wiki/what-are-ai-overviews answer and being invisible in it. JSON-LD does not guarantee a rich result, since Google decides when to show them, and it is not a direct ranking factor by itself. But it removes ambiguity, and in a search landscape where both traditional engines and AI models reward clarity, unambiguous structured data is one of the highest-leverage technical investments a local site can make.
What are the most common JSON-LD mistakes to avoid? #
A few recurring mistakes undermine JSON-LD. The most serious is marking up content that is not visible on the page, such as inventing reviews, adding FAQs that appear nowhere, or listing services the page never mentions, which violates Google's guidelines and can trigger manual penalties. Another is choosing the wrong or overly generic type, such as tagging a restaurant as a plain LocalBusiness and missing the properties that unlock richer results. Syntax errors are common too: a missing comma, an unquoted key, or a stray bracket breaks the entire block, since JSON is unforgiving. Mismatched data, like an address in the markup that differs from the visible NAP or your Google Business Profile, sends conflicting signals and can hurt local trust. Finally, many sites add JSON-LD once and never revisit it, letting it drift out of sync as prices, hours, and content change. Treat structured data as living code: validate it on launch, keep it matched to visible content, and re-check it whenever templates change. Done well, JSON-LD is quietly one of the most reliable SEO investments available.
FAQ
Is JSON-LD hard to learn?
Not particularly. If you can read a basic JSON file, with keys and values in braces, you can read JSON-LD. The vocabulary from schema.org takes some familiarization, but generators and SEO plugins produce valid markup from simple form fields, so many site owners add it without writing code by hand. Testing tools then catch mistakes before publishing.
Does JSON-LD improve my Google rankings directly?
Not on its own. JSON-LD is not a direct ranking factor. It works indirectly by making your content eligible for rich results and easier for search engines and AI systems to understand accurately. Better comprehension and more prominent listings can raise click-through and visibility, but the markup itself does not move your position in the results.
Where should JSON-LD go on the page?
Inside a script tag with the type application/ld+json. Google accepts it in either the head or the body, so placement flexibility is one of the format's advantages. Many developers place it in the head for consistency, but injecting it via a tag manager into the body works equally well and is fully supported by search engines.
Can I have multiple JSON-LD blocks on one page?
Yes. You can include several separate script blocks, one for LocalBusiness, another for FAQPage, another for BreadcrumbList, and Google reads them all. Alternatively you can combine them into a single block using an array. Both approaches are valid, so choose whichever is easier to generate and maintain for your particular site and setup.
What happens if my JSON-LD has an error?
It depends on the error. A minor issue like a missing recommended property usually just forfeits some rich-result features. A syntax error, such as a missing comma or bracket, can invalidate the entire block so search engines ignore it completely. Validation tools flag both types, which is why testing before publishing is essential every time.
Do I need JSON-LD if I use a website builder or WordPress?
Often the platform adds basic JSON-LD for you, but the default is rarely complete or optimized for your business type. Plugins and apps help, yet they still need correct configuration and the right schema types. For competitive local markets, custom or reviewed markup usually outperforms out-of-the-box defaults by a meaningful margin.
Was this helpful?