JSON-LD structured data: the complete guide for web developers
JSON-LD is the format Google, Bing, and AI systems use to understand your pages. This guide covers what it is, why it matters, which schema types to use, and how to add it to your site without shipping broken markup.
What is JSON-LD?
JSON-LD (JavaScript Object Notation for Linked Data) is a way to embed structured data in your HTML pages. It lives inside a <script type="application/ld+json"> tag in your page's <head> and describes what the page represents using the schema.org vocabulary.
Unlike microdata or RDFa, JSON-LD does not require changes to your visible HTML. You add a single script tag and search engines read it separately from your page content. This makes it easier to maintain, less error-prone, and the format Google explicitly recommends.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Acme Corp",
"url": "https://acme.com",
"logo": "https://acme.com/logo.png"
}
</script>Why JSON-LD matters
Without structured data, search engines guess what your page is about from HTML content. With JSON-LD, you tell them explicitly. This enables:
- Google rich results - star ratings, FAQ accordions, product cards, recipe cards, event listings. These are powered entirely by structured data.
- Knowledge panels - the info boxes that appear for organizations, people, and products in search results.
- AI understanding - LLMs and AI agents like ChatGPT and Perplexity use structured data to understand page content more accurately.
- Voice assistants - Google Assistant and Siri use structured data to answer spoken queries.
Google's own documentation states that pages with valid structured data are eligible for rich results that pages without it cannot receive.
JSON-LD vs microdata vs RDFa
All three formats encode the same schema.org vocabulary. The difference is where they live:
- JSON-LD - separate script tag in the head. No changes to visible HTML. Google's recommended format.
- Microdata - attributes (
itemscope,itemprop) added directly to HTML elements. Tightly coupled to markup. Harder to maintain. - RDFa - similar to microdata but uses different attributes (
vocab,property). More flexible but more complex.
For new projects, JSON-LD is the clear choice. It is easier to generate programmatically, easier to validate, and easier to maintain because it is decoupled from your HTML structure.
The most important schema types
Schema.org defines hundreds of types. In practice, a handful cover the vast majority of use cases:
WebSite
Add to every page. Tells search engines this is a website with a name, URL, and optional search action (for sitelinks search boxes).
{
"@context": "https://schema.org",
"@type": "WebSite",
"name": "My Shop",
"url": "https://myshop.com"
}Organization
Add to every page or your homepage. Defines your brand with name, logo, URL, and social profiles.
Article / BlogPosting
Add to blog posts and content pages. Include headline, author, publish date, and optionally an image. Powers the article rich result in Google.
Product
Add to product pages. Include name, description, image, price, availability, and reviews. Powers the product card in Google Shopping and search results.
FAQPage
Add to pages with question/answer content. Powers the FAQ accordion that expands directly in search results, giving you significantly more SERP real estate.
BreadcrumbList
Add to pages with hierarchical navigation. Shows the breadcrumb trail in search results (Home > Category > Page).
Common mistakes
Most broken structured data is broken silently. Your pages look fine but search engines ignore the markup. Here are the most common problems:
- Missing required fields. A Product without
nameor an Article withoutheadlineis invalid and will be ignored. - XSS vulnerabilities. If your JSON-LD contains user-generated content (product names, descriptions), unescaped
<or>characters can break your HTML or create security holes. - Wrong @type. Using
BlogPostinstead ofBlogPosting, orFAQinstead ofFAQPage. Schema.org types are specific. - Duplicate schemas. Multiple conflicting schemas of the same type on one page confuse search engines.
- Missing @context. Every JSON-LD block needs
"@context": "https://schema.org". Without it, the data is meaningless.
Validating your structured data
Google provides two tools for checking structured data:
- Rich Results Test - checks if your page is eligible for rich results
- Schema Markup Validator - validates your JSON-LD against the schema.org spec
The problem with both tools: they check after deployment. If your structured data is broken, you do not find out until someone tests a live URL. Build-time validation catches these problems before they reach production.
Tools like agentmarkup validate required fields, check for common mistakes, and warn about incomplete schemas during your build. See the JSON-LD documentation for details.
Adding JSON-LD with agentmarkup
You can add JSON-LD manually by writing script tags in your HTML. For sites with multiple pages and schema types, a build-time approach is more maintainable:
// shared agentmarkup config
const agentmarkupConfig = {
site: 'https://myshop.com',
name: 'My Shop',
globalSchemas: [
{ preset: 'webSite', name: 'My Shop', url: 'https://myshop.com' },
{ preset: 'organization', name: 'My Shop', url: 'https://myshop.com', logo: '/logo.png' },
],
pages: [
{
path: '/faq',
schemas: [{
preset: 'faqPage',
url: 'https://myshop.com/faq',
questions: [
{ question: 'Do you ship internationally?', answer: 'Yes, to 50+ countries.' },
],
}],
},
],
}Global schemas are injected into every page. Per-page schemas are injected only on matching paths. Use this shared config object with the adapter for Vite, Astro, or Next.js. All output is XSS-safe and validated at build time.
The bottom line
JSON-LD is not optional for modern websites. It powers rich results, helps AI systems understand your content, and is the foundation of machine-readable web pages. The format is simple, the tooling is mature, and the upside is measurable. If you are not using it, you are leaving search visibility on the table.