Skip to main content

Google guidelines and the rationale for recommending JSON-LD

What this chapter covers​

Before you start implementing, this chapter summarizes what Google requires and prohibits for structured data. Violations can get you excluded from search results or hit with a manual action, so this is content you must understand before writing markup that technically "works."

The official primary source is General Structured Data Guidelines (checked: 2026-05). This chapter does not rely on quoting URLs; instead it summarizes the spirit of the policy (why the rule exists). Because the page structure of Google's guidelines is reorganized periodically, we prioritize preserving the essence over the URL.

The grand principle: "consistency with content"​

The single most consistent principle throughout Google's guidelines is the following.

The content of structured data must match the content displayed on the page.

This is an ethical rather than a technical requirement; it ensures honesty toward search engines and users.

What counts as a "consistency" violation​

PatternProblem
Claiming information in structured data that is not on the pageBetrays expectations when a user arrives from search results
The value in structured data conflicts with the information on the pageProvides misinformation to the search engine
The type declared in structured data diverges from the actual content (e.g., marking up a product page as Article)Hurts the search engine's classification accuracy
A concrete example

For instance, if the page does not say "★4.8 (250 reviews)," you must not declare ratingValue: 4.8 in AggregateRating. Either match the real values, or display the reviews; it has to be one or the other.

Policy 1: No markup of invisible content​

"Invisible markup" — content hidden from users and declared only in structured data — is prohibited.

  • Referencing elements hidden with display: none or visibility: hidden in structured data
  • Marking up a FAQ that is not on the page with FAQPage
  • Declaring a price that is not displayed with Product.offers

This is a derivative of the earlier "consistency with content" policy. Information shown in search results must be verifiable on the page the user clicks through to.

Policy 2: No spam / misleading markup​

Markup intended to manipulate search rankings is prohibited. Typical prohibited items:

  • Putting a competitor's product name in Product.name (brand impersonation)
  • Stuffing unrelated keywords into description or keywords
  • Marking up every page's subject with the same high-rated Review (review fraud)
  • Combining unrelated types to chase search traffic (e.g., adding Recipe to a regular article)

Policy 3: Matching the page subject to the type​

Structured data must correctly represent the page's subject.

  • A page's subject is basically a single one. Pages with multiple subjects (e.g., a product listing page) should be expressed appropriately (ItemList, etc.)
  • mainEntity is used for the single primary entity of the page. The official schema.org background note clearly states "about can refer to multiple entities/topics, while mainEntity should be used for only the primary one"
  • Writing Product for every product exhaustively on the home page is excessive

This is detailed in Chapter 03, but if you cannot uniquely decide "what the page's subject is," you should first reconsider the structure of the page itself.

Penalties for violations​

When a guideline violation is detected, there are escalating penalties as follows.

  1. No rich result: the page still appears as a regular link in search results, but rich results (images / reviews / breadcrumbs, etc.) no longer appear
  2. Structured data ignored: all structured data on that page is ignored
  3. Manual action: Google manually applies a countermeasure, and a notice arrives in the "Manual Actions" report in Search Console. A manual action for structured data causes the page to lose eligibility for rich result display; it is officially documented that this does not affect web search ranking itself

If you receive a manual action, you must file a reconsideration request after fixing it, and recovery takes time. The risk is not worth the reward, so avoid gray-zone implementations.

The rationale for recommending JSON-LD​

In Chapter 01 we said "there are three formats — JSON-LD / Microdata / RDFa — and JSON-LD is what Google recommends." Here we lay out the detailed rationale.

Official source: Intro to How Structured Data Markup Works (checked: 2026-05) clearly states that Google recommends JSON-LD.

Reason 1: It can be completely separated from the body HTML​

Because Microdata / RDFa are embedded as attributes on HTML elements, you have to touch the body markup every time you change structured data. When a design change alters the element structure, the structured data breaks too.

JSON-LD is fully separated into a <script> block, so it does not depend on the body's DOM structure. The fact that you do not have to distort the body markup to meet SEO requirements is why it has the maintainability advantage.

Reason 2: It is easy to generate dynamically​

JSON-LD is a JSON-serializable object, so it is easy to generate on both the server side and the client side.

// Example: build and return a JSON-LD object on the server side
const jsonLd = {
  "@context": "https://schema.org",
  "@type": "WebPage",
  name: page.title,
  description: page.description,
  // ...
};

return `<script type="application/ld+json">${JSON.stringify(jsonLd).replace(/</g, "\\u003c")}</script>`;

Because JSON.stringify does not sanitize XSS, escaping < is mandatory when you embed dynamic values (Google's official guide also recommends the same replacement).

Microdata / RDFa require assembling attributes on the HTML template side, which tightly couples the data source and the markup.

Reason 3: It pairs well with component design​

In component-oriented UIs like React / Vue / Nuxt / Next.js, the component tree takes a nested structure. Writing Microdata's itemscope / itemtype along component boundaries hurts UI reusability.

Because JSON-LD is independent as page metadata, UI components can focus solely on UI responsibilities, and structured data can be managed in a separate layer.

Cases where other formats are chosen​

JSON-LD is recommended, but the other formats remain options in the following cases.

  • Migrating existing Microdata markup incrementally: avoid running both in parallel; it causes less confusion to move everything to JSON-LD at once
  • An environment that is static HTML only and cannot use any JavaScript: even then, <script type="application/ld+json"> does not involve running JS, so JSON-LD can still be used

In practice, for new implementations you can basically treat JSON-LD as the first choice.

Anti-pattern: over-markup​

Although not a guideline violation, excessive markup is not recommended.

The approach of "let's add all of WebPage / Article / BlogPosting / Product / Review / FAQPage" is counterproductive. The page's subject becomes ambiguous, and Google's classification accuracy drops.

Principle: write the minimum necessary types, at the appropriate hierarchy

Anti-pattern 2: Filling in unnecessary properties​

schema.org has dozens of properties per type, but you do not need to fill them all in. Omit properties that do not apply to the page's content (do not pad them with empty strings or placeholder values).

Anti-pattern 3: One giant single JSON-LD block​

Rather than cramming all information into a single <script>, listing multiple objects in parallel with @graph is more readable and maintainable.

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Organization", "@id": "...", ... },
    { "@type": "WebSite", "@id": "...", ... },
    { "@type": "WebPage", "@id": "...", "isPartOf": { "@id": "..." }, ... }
  ]
}

Using @graph lets you declare each object as an independent entity and cross-reference them with @id, which makes the structure clear.

A checklist before starting implementation​

For guideline compliance, confirm the following before implementing.

Pre-implementation checklist
  • Does the content of the structured data match the information displayed on the page?
  • Are you referencing invisible elements in structured data?
  • Is the page's subject narrowed down to one?
  • Can you settle mainEntity on a single one?
  • Are you adding loosely related types "just in case"?
  • Are you padding properties with empty strings or dummy values?

What's next​

We have covered the guideline policies and the rationale for recommending JSON-LD. The next chapter, 03. Type-selection process, presents — as the core of this guide — the decision flow for deciding "which type to choose for your own site," complete with a generalized decision tree.