What JSON-LD does — and does not do

A lot of site owners hear the same advice: add schema.

That sounds simple until you open a plugin, a generator, or a technical audit and see words like JSON-LD, microdata, RDFa, @context, @type, @graph, Organization, Article, FAQPage, BreadcrumbList, Product, WebSite, and twenty other things nobody asked for.

Here is the practical version.

JSON-LD is a way to describe the content of a page in a machine-readable format. It can help Google and other systems understand what the page is about, who published it, what entity it represents, and whether it matches a specific search feature.

It does not guarantee rankings. It does not force a rich result. It does not make thin content useful. It does not turn a weak page into a strong page.

Used well, JSON-LD removes ambiguity. Used badly, it adds noise.

JSON-LD is structured clarification, not an SEO trick

Google describes structured data as a standardized format for providing information about a page and classifying the page content. That sentence matters because it puts JSON-LD in the right box.

It is classification and clarification.

It is not a ranking lever you pull in isolation.

For example, an article page may visibly show a headline, author, publish date, and body content. JSON-LD can repeat those facts in a format that search systems can parse reliably. A product page may show price, availability, review information, and images. Product structured data can help search systems interpret those details.

The important part is that the markup describes the same thing users can see on the page. If the page says one thing and the JSON-LD says another, the markup is not helping. It may be ignored, or worse, it may create eligibility problems for search features.

JSON-LD is the most common format because it can sit in a <script type="application/ld+json"> block without wrapping every visible HTML element. That makes it easier to manage in a CMS, easier to generate consistently, and easier to debug.

Google supports three formats for structured data eligibility: JSON-LD, microdata, and RDFa. Google recommends JSON-LD. For most modern websites, that is the sensible default.

JSON-LD vs microdata vs RDFa

Microdata and RDFa are inline approaches. They attach structured data attributes directly to visible HTML elements.

That can work, but it also makes templates harder to read and maintain. If a CMS changes the layout, moves a heading, or rebuilds a block, the structured data may break with it. Developers then have to debug both the page layout and the markup at the same time.

JSON-LD is different. It usually lives as a separate script block on the page. The page still shows normal HTML to users. The JSON-LD block gives machines a clean summary of the same content.

That separation is why JSON-LD is often easier for WordPress, Shopify, Webflow, SaaS sites, and custom CMS setups. A plugin, theme, or internal tool can generate it without injecting extra attributes through every visible field.

There is a catch: because JSON-LD is separate from the visible HTML, it is also easier to lie with it. You can mark up reviews that are not visible. You can add an author that is not shown. You can say a homepage is a product page. You can describe a business address that users cannot find anywhere else.

That is not clever. It is just fragile.

Callout: Treat JSON-LD as a receipt for what the page already says. If the visible page does not support the markup, fix the page before expanding the schema.

What `@context`, `@type`, and `@graph` mean

Most JSON-LD examples start with @context and @type.

@context tells parsers which vocabulary you are using. For SEO work, that is usually https://schema.org.

@type tells parsers what kind of thing you are describing. Common examples include Organization, WebSite, Article, BlogPosting, FAQPage, Product, BreadcrumbList, and Person.

@graph is used when you want to describe multiple related things in one block. For example, a homepage might include an Organization node and a WebSite node. An article page might include an Article node, a Person author node, and an Organization publisher node.

A simple Organization example can look like this:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Example Company",
  "url": "https://www.example.com/",
  "logo": "https://www.example.com/logo.png",
  "sameAs": [
    "https://www.linkedin.com/company/example-company"
  ]
}
</script>

That is enough to show the concept. It identifies the organization, its canonical website, its logo, and one external profile that helps disambiguate the entity.

You do not need to turn every page into a giant entity graph. Start with the page’s main purpose and mark up the primary thing accurately.

What JSON-LD can help with

JSON-LD can help machines understand a page more consistently.

That can matter in several ways.

First, it can make a page eligible for certain Google rich results when Google still supports that feature and the page follows the relevant guidelines. The important word is eligible. Eligibility is not a promise.

Second, it can reduce entity ambiguity. Organization schema on a homepage, for example, can help clarify the brand behind the site. Article schema can clarify the headline, author, publisher, and date information for editorial pages.

Third, it can make audits easier. A crawler can detect which structured data types exist, where they are missing, whether the wrong type is used on a URL, and whether key fields are incomplete.

Fourth, it can support AI discoverability indirectly. AI systems and search engines still need clean, crawlable, text-based content. Structured data can help clarify entities, relationships, and page purpose, but it is not a magic AI visibility switch.

What JSON-LD does not do

JSON-LD does not guarantee a ranking boost.

It does not guarantee a rich result.

It does not override weak content, bad internal linking, blocked crawling, thin pages, duplicated pages, poor product data, or a missing business identity.

It does not mean every schema.org type is useful for Google Search. schema.org is a large vocabulary. Google Search supports specific structured data features, and those supported features change over time.

It also does not mean more types are better. A page with five conflicting structured data blocks is usually worse than a page with one clean, accurate block.

The worst pattern is kitchen-sink schema: every plugin adds its own Organization, WebSite, WebPage, Article, Breadcrumb, FAQ, Product, Review, and LocalBusiness markup until no single entity is clearly authoritative.

That is not optimization. That is clutter.

When to skip structured data

Skip JSON-LD when the page is thin, temporary, or unclear.

A low-value tag archive does not need Article schema. A homepage does not need FAQPage schema just because there is a support question in the footer. A product category page is not the same thing as a single Product. A service page should not claim fake reviews unless those reviews are visible and legitimate.

Also skip schema when you cannot maintain it. Stale dateModified values, broken image URLs, old prices, missing authors, and dead social profile links can all create unnecessary quality problems.

The order should be simple:

Make the visible page clear.
Make the page crawlable.
Add JSON-LD that matches the page.
Test it.
Watch Search Console over time.

The practical approach

For most sites, the sensible starting point is not every schema type. It is a small set of accurate blocks:

Organization on the homepage when the brand identity is known.
WebSite on the homepage for site name clarity.
Article or BlogPosting on real editorial content.
BreadcrumbList where breadcrumbs are visible and useful.
FAQPage only when the page contains visible questions and answers that are genuinely useful.
Product or local business markup only where the page actually represents that thing.

If you are using SEO Perception, this is the mindset behind structured data possibilities. The point is not to shout “schema missing” on every URL. The point is to find the places where markup would clarify a real page and avoid guessing fields that the crawler cannot verify.

You can use the free JSON-LD generator to create a clean starting block, then use the JSON-LD basics docs to understand what the fields mean before adding it to a live site.

Structured data is useful. It is just not magic.

And that is a good thing. Magic is hard to debug.

Frequently asked questions

Does JSON-LD improve rankings?

Not by itself. JSON-LD helps search systems understand page content and can make pages eligible for supported rich result features, but it does not guarantee higher rankings.

Is JSON-LD better than microdata?

For most modern websites, yes. Google recommends JSON-LD, and it is usually easier to maintain because it does not require structured data attributes throughout the visible HTML.

Should every page have schema markup?

No. Add structured data when it accurately describes the main content of the page and can be maintained. Thin or unclear pages should be improved first.

Can I use multiple schema types on one page?

Yes, when they describe visible, relevant entities on the page. Use clear IDs and avoid duplicate or conflicting entities.

For implementation detail, see JSON-LD basics, Organization schema, and the free JSON-LD generator.