# JSON-LD structured data: the complete guide for web developers - agentmarkup > The complete guide to JSON-LD structured data for web developers. Learn which schema.org types to use, common mistakes to avoid, and how to validate your markup at build time. Source: https://agentmarkup.dev/blog/json-ld-structured-data-guide/ By [Sebastian Cochinescu](/authors/sebastian-cochinescu/) · March 20, 2026 · 10 min read # 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 ` ``` ## 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 `name` or an Article without `headline` is 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 `BlogPost` instead of `BlogPosting`, or `FAQ` instead of `FAQPage`. 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](https://search.google.com/test/rich-results) - checks if your page is eligible for rich results - [Schema Markup Validator](https://validator.schema.org) - 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](https://github.com/agentmarkup/agentmarkup) validate required fields, check for common mistakes, and warn about incomplete schemas during your build. See the [JSON-LD documentation](/docs/json-ld/) 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. ## Make your website machine-readable agentmarkup is an open-source build-time toolkit for Vite, Astro, and Next.js that generates llms.txt, injects JSON-LD structured data, creates optional markdown mirrors from final HTML when raw pages need a cleaner agent-facing fetch path, manages AI crawler robots.txt rules, patches optional Content-Signal and canonical mirror headers, and validates everything at build time. Zero runtime cost. Learn more GitHub ``` pnpm add -D @agentmarkup/vite # or @agentmarkup/astro or @agentmarkup/next ``` Written by [Sebastian Cochinescu](/authors/sebastian-cochinescu/) · Developer of agentmarkup Builder of developer tools for machine-readable websites. Developer of agentmarkup. Founder of Anima Felix. ## More from the blog ### How to add llms.txt, JSON-LD, and AI crawler controls to Next.js Use @agentmarkup/next to generate llms.txt, inject JSON-LD, manage AI crawler rules, and understand the dynamic SSR boundary in Next.js. March 23, 2026 · 8 min read ### When markdown mirrors help, and when they do not A practical guide to when generated markdown mirrors add signal, when HTML is already enough, and how to avoid unnecessary downsides. March 20, 2026 · 7 min read ### Is your website ready for AI? Free LLM discoverability checker Audit your website for llms.txt, JSON-LD, robots.txt, markdown mirrors, and sitemap. Free tool for e-commerce and brand websites. March 20, 2026 · 8 min read ### Build-time markdown mirrors for agent readability: Cloudflare comparison Build-time markdown generation for AI readability, including when it helps and how it compares to Cloudflare runtime extraction. March 20, 2026 · 7 min read ### How to make your brand appear in AI conversations Organization schema, llms.txt, and FAQ markup make your brand visible in ChatGPT, Claude, and Perplexity answers. March 20, 2026 · 7 min read ### Why LLM-optimized e-commerce websites sell more Product JSON-LD, llms.txt, and AI crawler access make your store visible in AI product recommendations. March 20, 2026 · 8 min read ### Every AI crawler indexing your website in 2026 Complete list: GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, and more. What each does and how to control access. March 20, 2026 · 8 min read ### What is GEO? Generative Engine Optimization explained for developers What is real, what is hype, and what you can do today to make your site citeable by AI. March 20, 2026 · 7 min read ### Why llms.txt matters: making your website discoverable by AI LLMs answer questions by synthesizing web content. llms.txt gives them a structured overview of your site. March 20, 2026 · 6 min read