JSON-LD for SEO: the guide to structured data

Many websites have a JSON-LD implementation that has gradually turned into a patchwork. Organization schema that looks slightly different on every page. Inconsistent @id’s. FAQ markup for questions nobody can see on the page. The result: warnings in Search Console and markup nobody dares to touch any more. On top of that, Google has dropped a series of rich results since 2023, so part of the old advice no longer delivers anything. In this guide we explain how to set up JSON-LD so that it scales, with copy-paste templates, 10 common mistakes and a way to check everything across your site. Structured data is a fixed building block of technical SEO, and that building block has to be right.

What is JSON-LD?

JSON-LD (JavaScript Object Notation for Linked Data) is a format for adding structured data to a web page, so that search engines know exactly what is on the page: an organisation, a product, an article or an event. You place it as a separate <script type="application/ld+json"> block in the HTML, apart from the visible text, using the Schema.org vocabulary.

Google recommends JSON-LD because it is “the easiest solution for website owners to implement and maintain at scale”. The same page states that “all 3 formats are equally fine for Google”, as long as the markup is valid. Microdata and RDFa are therefore just as correct. Google also reads JSON-LD when JavaScript or a CMS widget injects it into the page.

Schema.org manages the vocabulary; the current version is V30.1 of 16 September 2026. More about structured data in general can be found in our guide to structured data for Google. Below we describe one fixed architecture that stays consistent even across hundreds of pages.

Which rich results does Google still show in 2026?

In 2026 Google still shows rich results for articles, products, reviews, recipes, events, job postings, videos, local businesses, organisations and breadcrumbs, among others, the latter only on desktop. FAQ, HowTo and the sitelinks search box have disappeared, as have a series of smaller types. Markup for those types remains valid Schema.org, but no longer produces a visible result in Google.

When the June 2025 phase-out was announced, Henry Hsu, product manager at Google Search, wrote: “This update won’t affect how pages are ranked.” With the removals of 2025 and January 2026, those types also disappeared from the Rich Results Test and Search Console. For webshops, Google added markup for loyalty programmes (10 June 2025) and for shipping policies at merchant level (12 November 2025).

Does JSON-LD help you get cited by AI search engines?

That has not been demonstrated. Google says you do not need any special structured data for AI Overviews and AI Mode. Microsoft Bing says structured content helps AI systems interpret your page. OpenAI’s help article on shopping does not mention JSON-LD at all. And an Ahrefs study of 1,885 pages saw no major rise in AI citations after schema was added.

“Structured data isn’t required for generative AI search, and there’s no special schema.org markup you need to add. However, it’s a good idea to continue using it as part of your overall SEO strategy, as it helps with being eligible for rich results on Google Search.”

— Google Search Central, in the guide to optimizing for generative AI features (July 2026)

Bing is more positive:

“Structured content, like schema-marked product pages, FAQs, and comparison tables, helps AI systems interpret and summarize your content more effectively. This increases the chances of your being cited, clicked, and engaged with in multi-source answers.”

— Fabrice Canel and Krishna Madhavan, Principal Product Managers at Microsoft Bing, on the Bing Webmaster Blog (November 2025)

The help article on shopping with ChatGPT talks about “structured metadata from first-party and third-party providers”, but never mentions Schema.org or JSON-LD. For products, OpenAI works with feeds; more on that in our article on making webshops findable for AI agents.

In the Ahrefs study, citations in AI Overviews fell by 4.6%, statistically significant but small. AI Mode (+2.4%) and ChatGPT (+2.2%) could not be distinguished from zero. Ahrefs itself points out the limits, such as a 30-day measurement window and other changes made at the same time. JSON-LD is therefore technical hygiene. How to become visible in AI answers is covered under GEO and in how SEO is evolving into GEO.

SMEs in Flanders that want to become visible in AI answers can turn to ClickForest for GEO.

Why almost all JSON-LD implementations become messy

JSON-LD implementations usually start well. A developer adds Organization to the homepage. Then product pages and blog articles each get their own copy. Before you know it, the same definition appears on hundreds of pages, with subtle differences because they were added at different times.

Symptoms of drift:

• Organization schema with different values. On page A a logo of 200x200px, on page B one of 400x400px, on page C none at all.
• Inconsistent @id fragments. One page uses #organization, another #company or no @id.
• Mixed types without logic. A contact page with Service, AboutPage and ContactPage at the same time.
• Markup for content that is not there. FAQ questions from a template that cannot be read on the page.
• Self-referencing loops. WebPage.mainEntityOfPage points to itself.

The cause: no separation between what belongs site-wide and what is unique per page. Often there is nothing at all: our research across 200 scanned Belgian websites found no structured data on 119 of the 200 sites. That is why it often surfaces as one of the first technical bottlenecks in an SEO audit.

The core principles that solve everything

Five principles keep JSON-LD consistent: one page-level script per page with a @graph, a fixed @id strategy, a strict separation between site-wide and page-level, URLs that follow your canonical exactly, and during a cleanup only changing what is genuinely wrong. It is an architecture choice of our own that fits within Google’s guidelines, which themselves mention @id as a way to link items on one page.

1. One page-level JSON-LD script per page

Put all page-specific nodes together in one <script type="application/ld+json"> block with a @graph array. You may also merge the site-wide and page-level parts into one @graph via your template.

2. Stable @id strategy

Every node gets an @id based on the canonical URL plus a fragment, such as https://example.com/seo#service or https://example.com/blog/article#blogpost.

3. Strict separation: site-wide vs page-level

You define WebSite, Organization and Person in one place. WebPage, Service, BlogPosting, BreadcrumbList and FAQPage live in the page script and reference the site-wide entities via their @id.

4. Match URLs exactly with canonical

If your canonical is https://example.com/about-us, use exactly that URL in @id and url, including www or non-www and the trailing slash.

5. Preserve unless invalid (when cleaning up existing implementations)

During a cleanup, only change what is factually wrong. Leave a 180-character description or a working image URL alone; that way you avoid unintended side effects.

”(…) Structured data won’t make your site rank better. It’s used for displaying the search features listed in developers.google.com/search/docs/… . Use it if your pages map to & are appropriate for any of those features.”

— John Mueller, Search Advocate at Google, on Bluesky, quoted in Search Engine Journal (April 2025)

What belongs site-wide (and why)

Site-wide is where the data goes that is the same for the whole website: WebSite, Organization and optionally a Person for the founder or regular author. You manage them in one place, in a script that your template loads. That way every page-level node references exactly the same definition, and there is no second version that drifts.

Google itself does not need Organization on every page:

“We recommend placing this information on your home page, or a single page that describes your organization, for example the about us page. You don’t need to include it on every page of your site.”

— Google Search Central, in the documentation on Organization structured data (September 2026)

That does not clash with a site-wide @graph, because the problem lies in copies that differ from each other. Two options are valid: the full Organization only on the homepage or about-us page with @id references elsewhere, or a site-wide include from one source. Pick one.

Which entities belong site-wide:

WebSite: name, url, publisher (the @id of Organization) and inLanguage. You do not need to add a potentialAction for the search box, because Google has not shown the sitelinks search box since 29 November 2024.

Organization: name, url, logo and sameAs, optionally contactPoint and address. Google recommends the most specific subtype that fits your organisation. Webshops also put their return and shipping policies here.

Person (optional): name, url, sameAs (LinkedIn, X) and worksFor (the @id of Organization).

What does NOT belong site-wide: Service, BlogPosting, BreadcrumbList, FAQPage, Product and ProductGroup. These are unique per page.

Start minimal: contactPoint only if you have a real customer service number, address only if you have a relevant physical location.

Overview table: what belongs where

Site-wide JSON-LD template (copy-paste)

This template defines WebSite, Organization and Person in one @graph. Place it via a global include in the <head> of every page, so that every @id reference on that page resolves, or limit it to the homepage and the about-us page if you choose that option. Replace the placeholders and remove anything you do not actually have.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com",
      "name": "[WEBSITE_NAME]",
      "inLanguage": "en-GB",
      "publisher": {
        "@id": "https://example.com/#organization"
      }
    },
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "[ORGANIZATION_NAME]",
      "url": "https://example.com",
      "logo": {
        "@type": "ImageObject",
        "url": "[LOGO_URL]"
      },
      "sameAs": [
        "[SOCIAL_URL_1]",
        "[SOCIAL_URL_2]",
        "[SOCIAL_URL_3]"
      ]
    },
    {
      "@type": "Person",
      "@id": "https://example.com/#founder",
      "name": "[FOUNDER_NAME]",
      "url": "https://example.com/about-us",
      "sameAs": [
        "[LINKEDIN_URL]"
      ],
      "worksFor": {
        "@id": "https://example.com/#organization"
      }
    }
  ]
}

Replace the placeholders:

• [WEBSITE_NAME] and [ORGANIZATION_NAME]: your website name and formal company name
• [LOGO_URL]: full URL to your logo, at least 112x112px according to Google
• [SOCIAL_URL_1/2/3]: official profiles such as LinkedIn, Facebook, Instagram or X
• [FOUNDER_NAME] and [LINKEDIN_URL]: the founder’s name and LinkedIn

Replace “Organization” with a more specific subtype if one fits. Only include the Person block if your company is founder-led or relies on thought leadership.

Page-level JSON-LD for regular pages (services, locations, etc.)

For regular pages such as services, about us, contact and locations, a small set of nodes is enough: always a WebPage, a Service if it is genuinely a service page, and optionally a BreadcrumbList and an FAQPage. Every node references the site-wide WebSite and Organization via @id, so your company data is never repeated anywhere.

Linking cheatsheet per page type

Canonical template for service page:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebPage",
      "@id": "https://example.com/seo#webpage",
      "url": "https://example.com/seo",
      "name": "SEO services",
      "description": "SEO optimisation for businesses in Belgium.",
      "isPartOf": {
        "@id": "https://example.com/#website"
      },
      "mainEntity": {
        "@id": "https://example.com/seo#service"
      }
    },
    {
      "@type": "Service",
      "@id": "https://example.com/seo#service",
      "serviceType": "SEO optimisation",
      "name": "SEO services",
      "description": "Technical SEO, content optimisation and link building.",
      "provider": {
        "@id": "https://example.com/#organization"
      },
      "areaServed": {
        "@type": "Country",
        "name": "Belgium"
      },
      "mainEntityOfPage": {
        "@id": "https://example.com/seo#webpage"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://example.com/seo#breadcrumbs",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://example.com"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "SEO",
          "item": "https://example.com/seo"
        }
      ]
    }
  ]
}

Note on BreadcrumbList: only include breadcrumbs if you show them or maintain a hierarchy consistently. Since 22 January 2025 Google only shows them in desktop results. Product pages need their own markup, which we discuss further on under webshops.

Page-level JSON-LD for blog articles

A blog article gets a WebPage and a BlogPosting, optionally with a BreadcrumbList and an FAQPage if the questions are visible on the page. The BlogPosting references the WebPage via mainEntityOfPage, the author via author and your company via publisher. That keeps every article linked to the same site-wide entities.

Canonical template for blog post:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebPage",
      "@id": "https://example.com/blog/seo-tips#webpage",
      "url": "https://example.com/blog/seo-tips",
      "name": "SEO tips for 2026",
      "description": "Overview of practical SEO tips.",
      "isPartOf": {
        "@id": "https://example.com/#website"
      },
      "mainEntity": {
        "@id": "https://example.com/blog/seo-tips#blogpost"
      }
    },
    {
      "@type": "BlogPosting",
      "@id": "https://example.com/blog/seo-tips#blogpost",
      "headline": "SEO tips for 2026",
      "description": "Overview of practical SEO tips.",
      "image": "https://example.com/images/seo-tips-header.jpg",
      "datePublished": "2026-01-15T10:00:00+01:00",
      "dateModified": "2026-01-20T14:30:00+01:00",
      "author": {
        "@type": "Person",
        "@id": "https://example.com/#founder",
        "name": "[FOUNDER_NAME]",
        "url": "https://example.com/about-us"
      },
      "publisher": {
        "@id": "https://example.com/#organization"
      },
      "mainEntityOfPage": {
        "@id": "https://example.com/blog/seo-tips#webpage"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://example.com/blog/seo-tips#breadcrumbs",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://example.com"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Blog",
          "item": "https://example.com/blog"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "SEO tips for 2026",
          "item": "https://example.com/blog/seo-tips"
        }
      ]
    }
  ]
}

Besides the @id, the author also carries a name and url, with exactly the same values as your site-wide Person, so that the author is recognisable on its own as well. Only set dateModified after a genuine change to the content.

ID and URL strategy that is bulk-proof

An @id is a fixed name for a node: your canonical URL plus a fragment such as #webpage or #service. Generate it with the same logic that builds your canonical URL, and the references stay correct even on sites with hundreds of product or blog pages. One stray slash or an extra www breaks the link between two nodes.

Strict pattern for @id fragments:

• WebPage: [CANONICAL_URL]#webpage
• Service: [CANONICAL_URL]#service
• BlogPosting: [CANONICAL_URL]#blogpost
• BreadcrumbList: [CANONICAL_URL]#breadcrumbs
• FAQPage: [CANONICAL_URL]#faq
• ImageObject (primary): [CANONICAL_URL]#primaryimage

Write fragments in lowercase (#webpage) and use the same fragment for the same type everywhere, for example #service on every service page. With 200 product pages, you generate the @id’s in your template. Shopify has the Liquid filter structured_data for this, which turns a product or article into Schema.org markup.

What JSON-LD does a webshop need?

A webshop needs Product markup, and for products in several sizes or colours a ProductGroup with the variants as Product. Google distinguishes product snippets for pages where you cannot buy from merchant listings for pages where you can; the latter carry more detail, such as shipping and return policy. Reviews and aggregateRating are not required.

Google recommends combining markup with a product feed: “Providing both structured data on web pages and a Merchant Center feed maximizes your eligibility to experiences and helps Google correctly understand and verify your data.”

For Shopify webshops, the structured_data filter turns a product without variants into a Product and a product with variants into a ProductGroup. You put return, shipping and loyalty policies at merchant level under Organization, with hasMerchantReturnPolicy, hasShippingService and hasMemberProgram; a shipping policy can also be set in Search Console. According to OpenAI, the product data of Shopify merchants is already in ChatGPT via Shopify Catalog, without any extra work.

With a Shopify webshop, first check what the theme already generates before you add markup: two Product nodes for the same product are a classic symptom of drift. More in our SEO checklist for Shopify and e-commerce SEO tips.

For Shopify webshops in Flanders, ClickForest includes the structured data in an SEO audit.

Common mistakes (with fixes)

Most JSON-LD mistakes come down to duplicate definitions, references that do not resolve and markup that does not match the visible page. Syntax errors break the whole script; the other mistakes blur your signals or cost you rich results. Below are the 10 mistakes that occur most often, first as an overview and then with an explanation and a fix.

Quick reference: 10 mistakes overview

Detailed explanation per mistake

1. Duplicating Organization schema on every page. Every page gets its own Organization, and those copies drift apart. Fix: one source, with page-level nodes referencing it via {"@id": "https://example.com/#organization"}.

2. Mixing BlogPosting and Service on the same URL. Choose one primary type: an article about a service is a BlogPosting, a service page is a Service with a WebPage.

3. WebPage.mainEntityOfPage pointing to itself.

{
  "@type": "WebPage",
  "@id": "https://example.com/seo#webpage",
  "mainEntityOfPage": {
    "@id": "https://example.com/seo#webpage"
  }
}

mainEntityOfPage points from a Service or BlogPosting to the WebPage it lives on. Fix: remove it from the WebPage node.

4. Markup for content that is not on the page. Google prohibits markup for content that readers cannot see, such as FAQ questions from a template or reviews that appear nowhere. The consequence is spelled out in the same guidelines: “A structured data manual action means that a page loses eligibility for appearance as a rich result; it doesn’t affect how the page ranks in Google web search.”

5. Description with claims you cannot substantiate. “500+ satisfied clients” without those clients is misleading markup. Only use facts you can prove.

6. Changing URL formats mid-site. The homepage uses https://example.com, the subpages https://www.example.com/. That breaks the references between entities. Choose one format, identical to your canonical.

7. Over-filled sameAs with arbitrary sources. Only use official profiles and possibly Wikipedia. Our rule of thumb: 3 to 5 URLs that you manage yourself.

8. Multiple JSON-LD scripts without reason. Four separate blocks increase the risk of duplication. Stick to one site-wide and one page-level script, or one merged @graph.

9. Broken JSON due to syntax errors. JSON is strict. Three errors occur most often.

A. Trailing commas: JSON does not allow a comma after the last property.

{
  "name": "Test",
  "url": "https://example.com",
}

B. Smart quotes: JSON requires straight double quotation marks around keys and strings. The typographic version that Word and Google Docs create automatically breaks parsing. A typographic apostrophe inside a string is fine.

{
  “name”: “Test Service”
}

C. Escaping quotes within strings: a quote inside a string gets a backslash in front of it.

{
  "name": "Test "Premium" Service"
}

{
  "name": "Test \"Premium\" Service"
}

A validator such as JSONLint catches all of these syntax errors before publication.

10. Modifying other scripts on the page during a JSON-LD edit. Whoever adds JSON-LD sometimes touches the Google Analytics script by accident. After deployment, test whether tracking still works.

How do you check JSON-LD across your whole site?

You check JSON-LD across your site in two layers. The rich result reports in Google Search Console show, for free, what Google finds across your whole site. A crawler with built-in validation checks every URL against Schema.org and Google’s requirements. Keep the Rich Results Test and the Schema Markup Validator for individual pages.

The reports in Search Console have their limits. Google writes that they “aren’t a comprehensive list of all detected items”, the detail table stops at 1,000 rows, and you only see types that Google supports, so no FAQ or HowTo any more. Keep following them after launch too, because templates can break markup.

A crawler fills that gap: Screaming Frog SEO Spider, for example, can “audit and validate structured data against Schema.org specifications and Google’s rich result feature requirements” and bundles the errors of the whole site into one report, with a paid licence. Their documentation dates from 2024, so check which validations still count. Bing Webmaster Tools shows, per URL, the markup that Bing finds.

If your SEO plugin only shows schema per page, you do not have to switch: combine Search Console with a crawl. For the AI side, a GEO audit is the logical next step.

Pre-publication checklist

Before JSON-LD goes live, check the syntax, whether each type fits the page, whether every @id reference resolves and whether everything in the markup is visible. Then roll out in phases. Google says so in its own feature guides, such as the one on software apps: “Deploy a few pages that include your structured data and use the URL Inspection tool to test how Google sees the page.”

• JSON syntax validated with JSONLint
• Schema type fits the page (Service for a service, BlogPosting for an article)
• All @id references resolve
• Tested with the Rich Results Test and the Schema Markup Validator, without errors
• Markup matches the visible content
• URLs exactly as in the canonical (www/non-www and trailing slash)
• dateModified updated after a content change
• No more markup for retired features such as the sitelinks search box
• Phased rollout; our rule of thumb is 5 pages first, monitor for 48 hours and then continue

Where do you start cleaning up your JSON-LD?

Start with the site-wide entities: one Organization, one WebSite and optionally one Person, managed in one place. Then define a template per page type, validate it and roll it out in phases. Stop spending time on markup for features that Google no longer shows, and keep an eye on the reports in Search Console after the rollout.

Structured data works best alongside solid keyword research, conversion optimisation, GEO strategies and the approach from our article on combining SEO and AI. ClickForest checks the structured data of SMEs and webshops in Flanders as part of an SEO audit or a full website audit. Want to know where your JSON-LD stands? Get in touch.