JSON-LD in WordPress: how it works, what it does for AI search, and how to implement it properly

What JSON-LD actually is

JSON-LD stands for JavaScript Object Notation for Linked Data. It is a serialisation format for describing things and the relationships between them in a way machines can consume without guessing. On a web page it lives inside a script block of type application/ld+json, separate from the visible HTML — which is the property that makes it maintainable: you can version it, template it and audit it without touching layout.

The vocabulary it carries is schema.org, a shared dictionary maintained since 2011 by Google, Microsoft, Yahoo and Yandex, and still actively released — version 30.0 shipped in March 2026. Google expanded support for JSON-LD in 2015 and has recommended it since. Three formats remain valid; only one is pleasant to maintain across hundreds of WordPress templates.

The distinction worth internalising: schema.org is the vocabulary, JSON-LD is the format, structured data is the practice. Vendors selling "AI schema" are selling ordinary types with a new label on the invoice.

How the entity graph works

A structured data block is not a list of tags. It is a set of nodes and edges — entities and the relationships between them. Four properties do most of the work.

Table scrolls horizontally on mobile.

The identifier is the part most implementations get wrong. When your organisation is declared once with @id ending in #organization, and every article, service and page thereafter references that identifier instead of describing the organisation again, a crawler can merge everything into a single coherent picture of the business. When each template invents its own organisation object, the crawler sees several similar entities and has to decide which one is real. That decision is not made in your favour.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Service",
      "@id": "https://example.com/consulting/#service",
      "name": "Technical SEO consulting",
      "provider": { "@id": "https://example.com/#organization" },
      "areaServed": ["US", "CA", "BR"]
    }
  ]
}

One line — provider pointing at an existing identifier — is the difference between a connected graph and a pile of disconnected fragments.

What changed in 2026

Two shifts reset the strategy this year, and both push in the same direction: away from schema as a display trick, toward schema as a description of what is genuinely on the page.

Rich results narrowed. Google confirmed that FAQ rich results stopped appearing in Search on 7 May 2026, with the Search Console report and Rich Results Test support retired in June and API support ending in August. Google noted the markup can stay in place, since other engines may still process it. This completes a pattern that began in 2023 with the FAQ restriction and the HowTo deprecation: when a feature gets scaled by tooling until it no longer describes the page faithfully, the feature goes away and the vocabulary stays.

AI features arrived, and Google was blunt about requirements. Its guidance for site owners states plainly that there are no additional requirements to appear in AI Overviews or AI Mode, that no machine-readable AI files are needed, and that there is no special schema.org structured data you need to add. Eligibility is the same as for ordinary results: indexed, and eligible to appear with a snippet.

Schema and AI answers: the honest version

Here is where most content on this topic becomes unreliable, so it is worth being precise about what is evidence and what is inference.

What the tests show. In early 2026, a controlled experiment placed a company address exclusively inside an invalid, invented JSON-LD block, with the fact appearing nowhere in the visible copy. Both ChatGPT and Perplexity retrieved the address anyway — which indicates the script content is tokenised as text along with everything else on the page, not parsed as a validated graph. A separate multi-assistant test reached a compatible conclusion for direct page fetches, while noting the obvious limitation: schema may still matter upstream, in the search indexes those assistants query.

What follows from that. Two practical rules, both uncomfortable for anyone selling schema as an AI lever:

• Never put a fact in schema that is not visible on the page. If a model can read your script block as text, an inaccurate block becomes a source of wrong quotes about your business — and Google's general guidelines already prohibit marking up content that is not visible to readers.
• The visible layer does the citing work. Clear definitions near the top of a section, self-contained answers, real tables, unambiguous headings — that is what gets extracted and quoted. Schema is the layer that keeps the entity behind the quote correctly identified.

So the value is a dual layer, not a single lever: JSON-LD for the search infrastructure that feeds AI surfaces; visible structure for the models that read pages as text. Anyone claiming a direct causal line from schema to citations is describing a correlation with an undocumented mechanism. It matters commercially, too — vendor studies through 2026 report AI-referred visitors converting several times better than standard organic on B2B sites, and B2B referral share splitting across four engines rather than concentrating in one. Treat those as directional estimates, not audited numbers; the methodologies vary widely and the panels are small.

The four layers that matter for B2B

A services business does not need forty schema types. It needs four layers, modelled once and referenced everywhere.

1. Identity. Organization plus the people behind it — founder, authors, specialists — with sameAs pointing at the profiles that corroborate them. This is the layer AI systems and knowledge graphs use to decide whether a brand is a known entity or an unverified string.
2. Structure. WebSite, WebPage and BreadcrumbList: how the site is organised and where each page sits. Usually handled by the SEO plugin, and usually best left there.
3. Offer. Service nodes for each thing you sell, connected to the organisation through provider, with areaServed, audience and a service catalogue. This is the layer plugins never generate and B2B sites almost always lack.
4. Content. Article or BlogPosting with author, dates and about entities; FAQPage where genuine Q&A exists. This is what connects your editorial output back to the identity layer instead of leaving it orphaned.

JSON-LD in WordPress: three paths and where they collide

WordPress powers a large share of the web precisely because there are always three ways to do anything. Structured data is no exception, and the three paths can coexist — provided someone decides which one owns which entity.

Table scrolls horizontally on mobile.

The collision is predictable. A plugin such as Rank Math or Yoast already emits an organisation node under its own identifier. A developer then adds a custom block that declares an Organization with the same name and a different @id. Now the site publishes two brands. The fix is never to remove the plugin's graph — it is to inspect the identifiers the plugin uses and reference them from every custom node, so provider, publisher and worksFor all point at one canonical entity.

Building the entity model before writing any code

The markup is the last step, not the first. The sequence that works:

1. Inventory the entities. The organisation, the people, each service, each location or market, the recurring content types. Written in plain language before any JSON exists.
2. Assign canonical identifiers. One @id per entity, decided once, documented, never improvised at template level.
3. Map the relationships. Which service belongs to which organisation, which person authors which content, which page describes which service.
4. Check the visible layer. Every claim the schema will make must exist in copy a human can read. This step routinely sends work back to content, and that is a feature.
5. Template it. Implement per page type, not per page, so the model survives the next hundred pages.
6. Validate and document. Both tools, both directions: syntax and eligibility, plus a written record of which identifier means what.

Steps one to four contain most of the value and none of the code. That ordering is what separates structured data as engineering from structured data as a plugin checkbox — and it is the reason this work sits inside our broader approach to SEO, GEO and AEO rather than beside it.

Eight errors we find in almost every audit

• Duplicate entities. Two or more organisation nodes with different identifiers. The most common finding, and the most damaging.
• Schema that contradicts the page. A service described in markup that the copy never mentions, or prices that differ between the block and the front end.
• Orphan nodes. Valid, isolated blocks with no @id and no references — technically correct, semantically useless.
• Relative URLs. Identifiers and image URLs written as paths instead of absolute URLs, which breaks entity merging across the site.
• dateModified theatre. Timestamps bumped automatically on every cache purge, which trains systems to ignore the signal.
• Over-typing. Landing pages declared as Product, blog posts as NewsArticle, agencies as LocalBusiness with no verifiable premises.
• Blocked resources. Structured data behind robots.txt disallow rules or rendered by scripts the crawler cannot execute — Google's guidelines are explicit that markup must remain accessible.
• Set-and-forget. A model built around a service portfolio that changed eighteen months ago, still describing the company that no longer exists.

Validation and measurement

Two tools, two different jobs, and neither is optional. The Rich Results Test answers whether Google sees your markup as eligible for supported features. The Schema Markup Validator answers whether your graph is valid schema.org regardless of what Google chooses to display — which is the relevant question for everything outside Google's rich result gallery.

Measurement is where expectations need calibrating. Structured data has no dedicated success metric, and the things it influences are indirect:

• Search Console enhancement reports for error and eligibility trends by type — remembering that FAQ reporting is being retired through 2026.
• Brand queries and knowledge panel behaviour as a proxy for whether your identity layer is being consolidated correctly.
• AI citation testing: a fixed set of buyer-intent prompts, run monthly across the major assistants, recording whether your brand appears and whether the description is accurate. This is manual, unglamorous, and the only honest read available.
• Referral segmentation in analytics, since AI-sourced sessions land in direct or referral buckets by default and stay invisible until you separate them.

Governance: schema as a maintained asset

Structured data decays. Services get renamed, people leave, markets expand, plugins update their graphs. A model that was accurate at launch describes a fictional company two years later, and the fiction is machine-readable.

Governance means four commitments: a documented entity model that lives outside anyone's head; a review triggered by business events rather than a calendar; validation as part of the deployment routine, not an annual audit; and a single owner who decides what the canonical identifier for each entity is. On a WordPress site this usually means someone who understands both the development layer and the commercial model — which is precisely the seam where most implementations fail.

Working with Flowup from outside Brazil

Flowup Agency has been building digital assets since 2011. We are not a marketing agency: we engineer digital authority — the work of making a brand findable, understandable, verifiable and citable, by people, by search engines and by AI systems. Structured data is one layer of that, and it is the layer where most of our international engagements start, because it is measurable, self-contained and diagnostic of everything else.

What an engagement typically looks like:

• Diagnostic. A map of every entity your site currently declares, the conflicts between them, and the gap between markup and visible content.
• Entity model. A documented set of canonical identifiers and relationships, agreed before implementation.
• Implementation. Versioned JSON-LD by template, coexisting cleanly with your existing SEO plugin instead of fighting it.
• Editorial enablement. Reusable blocks and fields so your team can publish without regenerating the problem.
• Monitoring. Validation, Search Console coverage, and a monthly AI citation test against your own buyer-intent prompts.

We work in English, Portuguese and Spanish, serve clients in Brazil, the United States, Canada and beyond, and operate in a time zone that overlaps the North American and European working day. Everything above is delivered as documentation you own — code, entity model and rationale — not as a black box that requires us to stay.

Frequently asked questions

References