--- title: "Structured Data with JSON-LD" slug: "structured-data" category: "seo" tags: ["seo", "schema-org", "json-ld"] status: "stable" last_updated: 2026-05-29 summary: "Which schema.org types to ship, how to embed JSON-LD, and how to validate without overclaiming." related: ["[[seo/technical]]", "[[seo/og-images]]", "[[seo/content]]", "[[seo/schema-markup-deep]]", "[[seo/e-e-a-t]]", "[[frontend/html]]", "[[seo/glossary]]", "[[seo/audit-checklist]]"] --- ## Overview Structured data tells search engines what a page is, not just what it says. Ship JSON-LD with schema.org vocabulary on every public page. Done right, it earns rich results (article cards, breadcrumbs, product and review annotations, sitelinks) and feeds knowledge-graph entity resolution. Done wrong, it earns manual penalties. Note that not every schema type still maps to a rich result: Google retired FAQ and HowTo rich results (2023 to 2026), so ship those types for page understanding and AI-agent consumption, not for a SERP feature. See [[seo/schema-markup-deep]]. ## Ship JSON-LD, not Microdata or RDFa Google, Bing, and Yandex all read JSON-LD, and it is the only format the major engines actively recommend. - JSON-LD lives in a ` ``` Generate the block from the page's frontmatter at build time so the structured data and the rendered content cannot drift. Pair it with the `og:image` from [[seo/og-images]] so social and search share the same asset. See [[howto/add-jsonld-to-static-site]] for the end-to-end walkthrough on a static site, and [[cheatsheets/schema-org-types]] for the type-by-type required-field reference. ## Fill required fields, then recommended, then stop Each schema type has a required field set and a recommended field set. Google's docs list both per type. - Required fields must be present and non-empty. Missing a required field disqualifies the page from rich results. - Recommended fields earn the richer treatment. Ship them when the data exists. - Optional fields are noise unless they enable a specific feature. Do not pad the markup. ## Never lie in structured data The cardinal rule. Markup must match what a human sees on the page. - Author in markup matches the byline rendered on the page. Honest author markup is also the load-bearing signal for [[seo/e-e-a-t]]. - `datePublished` matches the published date on the page. - Aggregate ratings come from real reviews on the same page, not from an external source. - Prices in `Product` schema match the price the buyer pays. Mismatches trigger manual actions in Search Console, and the recovery cycle is weeks. ## Validate before every deploy Run two validators on every change. - Google Rich Results Test (`https://search.google.com/test/rich-results`). Confirms eligibility for specific rich result types. - schema.org validator (`https://validator.schema.org`). Confirms the JSON-LD parses and conforms to the vocabulary. Wire both into a pre-deploy smoke test on the sitemap's top 20 URLs. Failures block the deploy. Pair this with the URL hygiene rules in [[seo/technical]] so canonical and JSON-LD never disagree on the URL. ## Related - [[seo/technical]] - [[seo/og-images]] - [[seo/content]] - [[seo/llms-txt]] - [[frontend/html]] - [[howto/add-jsonld-to-static-site]] - [[cheatsheets/schema-org-types]] - [[seo/glossary]] - [[seo/audit-checklist]]