JSON-LD: structured data for rich results and understanding

JSON-LD (JavaScript Object Notation for Linked Data) is a way to mark up your content so search engines understand it better.

Google supports JSON-LD, Microdata, and RDFa for Search features and generally recommends JSON-LD when a site’s setup allows it. The format is separate from the visible HTML, which makes templates easier to maintain, but it also makes mismatches easier to introduce.

What JSON-LD does

• Describes content: tells search engines what your content represents (article, product, FAQ, etc.)
• Creates eligibility: supported markup can make a page eligible for a relevant rich-result feature; it does not guarantee display
• Clarifies ambiguity: helps search engines understand entities and relationships

JSON-LD lives in a <script type="application/ld+json"> block in your page head (or body).

Choose a Type from the Page, Not the Keyword

• Article: for blog posts and news content
• Product: for ecommerce products with prices and availability
• QAPage: for a page where users can submit answers to one question; it is not a generic FAQ substitute
• Organization: for company info and branding
• LocalBusiness: for local businesses with address and hours
• BreadcrumbList: for breadcrumb navigation

You don’t need to use every type. Pick what matches your content.

Start with the page’s primary visible purpose. A product detail page may use Product; an editorial review needs the appropriate review properties and visible evidence; a category page should not copy the Product markup from every card into one fictional item. Check Google’s current feature documentation as well as Schema.org because a valid Schema.org type is not automatically supported as a Google rich result.

Build a Stable Entity Graph

Multiple JSON-LD blocks are valid, but related entities should use stable @id values so they can be connected instead of repeated as slightly different objects. A typical article graph can link:

• the Article to its canonical URL
• author to a Person profile
• publisher to one Organization
• isPartOf to the website
• BreadcrumbList to the visible breadcrumb trail

Use absolute URLs for identity fields and keep the same organization and author identifiers across templates. Do not invent ratings, prices, dates, credentials, or relationships that users cannot verify on the page.

A Minimal QA Sequence

1. Parse every JSON-LD block as JSON; syntax errors stop deeper validation.
2. Confirm the type matches the page’s visible main content.
3. Compare required and recommended properties with the current Google feature documentation.
4. Check canonical URLs, @id references, dates, currencies, availability, and image URLs against the rendered page.
5. Run the Rich Results Test for Google-supported features and a Schema.org validator for vocabulary-level checks.
6. Inspect the deployed URL, not only local markup, because templates, hydration, caching, and edge rewrites can change the response.

Testing structured data

Use Google’s Rich Results Test or our Schema Markup Tool to validate your JSON-LD. Google’s structured data policies are the final reference for Search eligibility.

Common mistakes to avoid:

• marking up content that isn’t visible to users
• misleading or inaccurate markup
• overusing schema just to hope for rich results

Use structured data to clarify, not trick.

Passing a test is not the end of QA. Monitor Search Console enhancement reports and compare changes after template releases. If valid items fall suddenly across many URLs, investigate shared templates, deployment output, canonical changes, and data feeds before editing pages one by one.

Link back to the glossary

Quick definition: JSON-LD.

Related wiki terms

• Schema markup
• Rich snippets
• Meta tags