Skip to content

Ch 12 — Structured data

Part V — Site design · The Technical SEO Reference

Playbook coupling: seo-checklist.md covers structured data in Phase 1's "Structured data & brand appearance" block (lines 110–115: Organization placement, site name/favicon, correct type per template, the deprecated-rich-results warning, validation) and Phase 2 line 129 (schema matching visible content). This chapter adds the machinery: the parsing contract, the complete general guidelines, the live 2026 gallery inventory with the full dated deprecation graveyard, report-reading mechanics, the precisely-scoped manual action, and quarantine of the entity-SEO mythology.

Structured data is display-layer infrastructure. It makes pages eligible for enhanced presentation — it does not rank them, and Google's own enforcement mechanism proves the point: the structured-data manual action removes rich-result eligibility while explicitly leaving web ranking untouched. The working discipline is therefore: deploy exactly what a live documented feature consumes, validate that it parses, keep it truthful to the visible page, and treat every display promise as Google's to keep, not yours to sell.

12.1 How Google parses structured data

  • 🟢 Three supported formats "unless documented otherwise": JSON-LD, Microdata, RDFa — and "all 3 formats are equally fine for Google, as long as the markup is valid." JSON-LD is recommended "as it's the easiest solution for website owners to implement and maintain at scale" (intro doc, 2025-12-10).
  • 🟢 ⚠️ Placement is liberal: JSON-LD is "embedded in a <script> tag in the <head> and <body> elements" — body placement is explicitly legal. Head-only rules in audit tools are invented.
  • 🟢 JS injection is fully supported: "Google can read JSON-LD data when it is dynamically injected into the page's contents, such as by JavaScript code or embedded widgets in your content management system" — the parse surface is the rendered DOM: "Google Search can understand and process structured data that's available in the DOM when it renders the page" (generate-with-JS doc; rendering mechanics → Ch 6 §6.7).
  • 🟢 ⚠️ The two documented JS caveats: GTM — "Use variables to extract the structured data from the page instead of duplicating the information in GTM" (duplication "increases the risk of having a mismatch"); and commerce — "Dynamically-generated markup can make Shopping crawls less frequent and less reliable" → Product markup belongs in the initial HTML (best practice added Oct 1, 2024).

12.2 The general guidelines — the rulebook every feature inherits

From sd-policies (revised 2026-07-10), all 🟢:

Technical: "Don't block your structured data pages to Googlebot using robots.txt, noindex, or any other access control methods." ⚠️ "All image URLs specified in structured data must be crawlable and indexable" — a robots-blocked image CDN silently voids eligibility (→ Ch 3, Ch 14).

Quality/content: - "Your structured data must be a true representation of the page content." - "Don't mark up content that is not visible to readers of the page." - "Don't mark up irrelevant or misleading content, such as fake reviews or content unrelated to the focus of a page"; "Don't use structured data to deceive or mislead users." - "Provide up-to-date information. We won't show a rich result for time-sensitive content that is no longer relevant." - Location: "Put the structured data on the page that it describes"; duplicates: "we recommend placing the same structured data on all page duplicates" (→ Ch 8 — markup follows the page; you don't deduplicate it). - Specificity: "Try to use the most specific applicable type and property names defined by schema.org." - Eligibility gate: markup "shouldn't violate the Content policies for Google Search (which include our spam policies)."

12.3 Eligibility vs display — the guarantee gap

  • 🟢 "Google does not guarantee that your structured data will show up in search results, even if your page is marked up correctly according to the Rich Results Test." And: "Using structured data enables a feature to be present, it does not guarantee that it will be present."
  • 🟢 Documented non-display reasons: algorithmic tailoring ("the best search experience"), markup "not representative of the main content of the page, or is potentially misleading," marked-up content "hidden from the user."
  • ⚠️ Client-communication rule (house standard, anchored on the above): sell eligibility work, never display guarantees — the RRT preview itself disclaims: "Google does not guarantee that your page will appear exactly as shown here."

🟢 The search gallery (revision 2026-06-15) lists 25 features: Article, Breadcrumb, Carousel, Course List, Dataset, Discussion Forum, Education Q&A, Employer Aggregate Rating, Event, Image Metadata, Job Posting, Local Business, Math Solver, Movie, Organization, Product, Profile Page, Q&A, Recipe, Review Snippet, Software App, Speakable, Subscription/Paywalled Content, Vacation Rental, Video.

Availability quirks worth knowing: - ⚠️ Breadcrumb: desktop-only since Jan 2025 (→ Ch 10 §10.5). - ⚠️ Dataset is not a Search feature — Nov 5, 2025 clarification: "only used by Dataset Search, and not Google Search." Audits flagging it as a Search opportunity are wrong. - Discussion Forum / Profile Page / expanded Q&A are the newest general-web additions (Nov 2023; SocialMediaPosting support Jun 2024). - Product keeps absorbing merchant sub-features: variants via isVariantOf (Feb 2024), 3D models (Mar 2024), org-level return policies (Jun 2024), loyalty programs (Jun 2025), merchant-level shipping policies (Nov 2025), hasAdultConsideration (May 2026), Product.category + sale-duration validFrom/validThrough (Jul 2026). (→ playbook Phase 2 Ecommerce module; Merchant Center pairing.)

12.5 The deprecation graveyard — dated

The kill-list for stale templates and stale pitches (all 🟢 from the changelog unless noted):

Feature Dead date Notes
HowTo Sept 2023 "no longer shown in search results," desktop and mobile; docs removed Sept 14, 2023
FAQ (gov/health-only) Aug 2023 Phase 1: restricted to "well-known, authoritative government and health websites"
FAQ (fully retired) May 7, 2026 Deprecation notice logged May 8: "This feature will no longer appear in Google Search starting May 7, 2026"; docs removed Jun 15, 2026. 🟢 GSC API FAQ deprecation "in August 2026" (live API-reference banner, V0-verified); 🟡 the GSC-report June 2026 sunset date is industry-reported
Sitelinks search box Nov 21, 2024 Announced Oct 21 ("Farewell, Sitelinks Search Box"); docs removed + nositelinkssearchbox archived Nov 29. ⚠️ Keep WebSite markup — it still powers site names (→ Ch 13)
Video carousel guidance Apr 17, 2024 Test concluded, guidance removed (V0-verified)
Home activity Jun 11, 2024 COVID-era leftover
Special announcement Jul 31, 2025 COVID-era; notice Apr 23, 2025
Course info, estimated salary, learning video, vehicle listing Sept 9, 2025 The mass removal (banners added Jun 12, 2025)
Practice problems Jan 6, 2026 Notice Nov 5, 2025
Fact check (ClaimReview) phasing out (no date) Live doc: "We're phasing out support for ClaimReview markup in Google Search"; still feeds Fact Check Explorer
Book actions not deprecated Live doc (2025-12-10, checked 2026-08-04) carries no deprecation notice; feature remains gated to "book providers with a wide selection" via registration. The reported Jun 12, 2025 banner did not become a removal

🟡 Leftover markup is harmless — Google's "Farewell, Sitelinks Search Box" post (Oct 2024): "Unsupported structured data like this won't cause issues in Search, and won't trigger errors in Search Console reports," and site names use "a variation of WebSite structured data, which continues to be supported" (verbatim per Search Engine Land's relay, confirmed 2026-08-04; the primary blog URL is live but would not render body text — stays 🟡 under the live-fetch rule). Strip it for hygiene and client honesty, not risk. This is the doctrinal basis for the playbook's line 114 and the bk8mypro FAQ-stripping fix.

  • 🟢 "You must include all the required properties for an object to be eligible for appearance in Google Search with enhanced display."
  • 🟢 ⚠️ Quality beats coverage, officially: "it is more important to supply fewer but complete and accurate recommended properties rather than trying to provide every possible recommended property with less complete, badly-formed, or inaccurate data" — the anti-checklist rule most schema plugins violate by design. More recommended properties "can make it more likely" your information appears enhanced — a quality dial, not a stuffing target.
  • ⚠️ Requirement tables drift. Video description: required → recommended (May 2023). Online-event properties removed (Jun 2025). Review snippet tightened against "fake and undisclosed incentivized reviews" (Jul 24, 2026 — directly relevant to the gambling vertical's self-rating temptations; → Ch 18). Re-read the feature doc on every build; never code from memory.

12.7 Entity linking: @id, sameAs, nesting — and the @graph reality check

  • 🟢 Nesting doctrine: both patterns are documented as valid — nested items (Recipe containing aggregateRating and video) and separate top-level items in an array. "Multiple items on a page means that there is more than one kind of thing on a page." Choose for maintainability.
  • 🟢 @id is documented where a feature needs stable identity — e.g., Book actions: "A globally unique ID… It must be stable and not change over time." It is not a general-purpose requirement.
  • 🟢 sameAs, in full: "The URL of a page on another website with additional information about your organization… For example, a URL to your organization's profile page on a social media or review site" (Organization doc, 2026-04-15). No authority, ranking, or knowledge-panel promise is attached. Organization markup's documented purpose: "help Google better understand your organization's administrative details and disambiguate your organization" — placed "on your home page, or a single page that describes your organization." Identifier properties exist for real-world disambiguation: iso6523Code, naics, duns, leiCode, vatID, taxID.
  • ⚪ ⚠️ @graph is not a Google feature. Google's docs nowhere require or document @graph; it is a legal JSON-LD 1.1 serialization choice (📘 W3C). The industry's "entity SEO architecture" — elaborate @graph webs with @id cross-links "building entity authority" — has no documented mechanism behind it. (The bk8mypro 21-profile sameAs stack was this lore weaponized; disambiguation only works when profiles corroborate a real entity.)

12.8 schema.org vs Google's subset

  • 📘 schema.org defines the vocabulary; 🟢 Google consumes a documented profile of it: "Most Search structured data uses schema.org vocabulary, but you should rely on the Google Search Central documentation as definitive for Google Search behavior."
  • 🟡 Undocumented types neither hurt nor help: Mueller — "It's fine to use it for other things in schema.org, that won't cause problems, but you're unlikely to see any visible change from it in Google Search" (Bluesky, Apr 2025, verified verbatim per SEJ writeup 2026-08-04; thread at bsky.app/profile/hboon.com/post/3lmmibjlrcg2v).
  • 🟢 Google sometimes narrows schema.org further — e.g., "we only support standard schema.org enumeration values for local business opening hours" (Aug 2023).

12.9 Validation tooling — two tools, two jobs

Tool Job Limits
Rich Results Test 🟢 "The official Google tool for testing your structured data to see which Google rich results can be generated" — Google-eligibility + a render-pipeline check (evaluates the rendered page; smartphone UA default) Covers only Google-supported types; preview is disclaimed; ⚠️ for JS-generated markup "use the URL input instead of the code input because there are JavaScript limitations… (for example, CORS restrictions)"
Schema Markup Validator (validator.schema.org) 🟢 "Validate all Schema.org-based structured data… without Google feature specific warnings" — generic vocabulary validation No eligibility signal at all; the successor to the retired Structured Data Testing Tool (⚪ Aug 2021, industry-dated)

Workflow: RRT for anything you want displayed in Google; SMV for vocabulary correctness of types Google doesn't consume. A page can pass one and fail the other — that's the design, not a bug.

12.10 Reading the GSC rich result reports

🟢 From the report help: reports appear only when "Google finds valid markup in your property, and the markup is a supported rich result type." - ⚠️ Items, not pages: "A valid item… doesn't have any critical issues"; "An invalid item has at least one critical issue preventing it from appearing as a rich result." One item with multiple issues appears in multiple issue tables but once in totals — report totals will never reconcile with page counts. - ⚠️ Sampled: "The reports aren't a comprehensive list of all detected items. They show a sample." - Fix loop: "Fixes must be applied to your site's source code" → Validate Fix → per-URL confirmation via URL Inspection Enhancements. - ⚠️ A vanished report is usually a deprecation, not a bug — sitelinks-searchbox report gone after Nov 2024, FAQ report gone 2026. Check the graveyard (§12.5) before filing support threads.

12.11 The manual action and the spam boundary

  • 🟢 Trigger (Manual Actions report): "markup… using techniques that are outside our structured data guidelines, for example: marking up content that is invisible to users, marking up irrelevant or misleading content, or other manipulative behavior."
  • 🟢 ⚠️ The penalty's exact scope (stated in sd-policies, not the Manual Actions help page): "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." Practitioners routinely misdescribe this as a ranking penalty — it is not (though fake-review content can separately violate spam policies → Ch 18).
  • Recovery: fix against §12.2, then Request Review. Canonical vertical example: self-serving aggregateRating on the brand you promote — the maxim88-my.com pattern from reviews/96m-vs-maxim88-2026-08-03.md — is precisely "marking up irrelevant or misleading content."

12.12 Carousels (beta) — the regulatory-era rich result

  • 🟢 An ItemList "host carousel" — "a list-like rich result that people can scroll horizontally to see more entities from a given site" (carousels-beta doc, 2026-01-21; launched Feb 29, 2024, DMA-era). Markup: summary page carries ItemList → ≥3 ListItems with position + an item of type LocalBusiness/Product/Event, each pointing to detail pages.
  • ⚠️ Geography-gated: EEA (hotels, vacation rentals, transport, flights, local businesses, things-to-do, shopping); Turkey (May 2025: hotels, vacation rentals, local businesses); South Africa (Aug 2025: broader). Not available elsewhere — do not promise carousel treatment globally, and note the name collision with the classic gallery Carousel (Recipe/Course/Restaurant/Movie).

12.13 Structured data and AI surfaces

  • 🟢 The position, verbatim (AI features doc): "You don't need to create new machine readable files, AI text files, or markup to appear in these features. There's also no special schema.org structured data that you need to add." Eligibility = "indexed and eligible to be shown in Google Search with a snippet."
  • 🟢 The AI optimization guide (2026-07-10): "Structured data isn't required for generative AI search… 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."
  • ⚪ Whether markup helps non-Google LLMs/answer engines is an open third-party question — never present it as a Google claim. (→ Ch 5; playbook Phase 6.)

12.14 Paywalled and gated content — the sanctioned pattern

The gallery lists Subscription/Paywalled Content (§12.4); the mechanics matter because they are the cloaking exemption done right (→ Ch 6 §6.7's JS-paywall warning for how it's done wrong):

  • 🟢 The documented pattern (paywalled-content doc, 2025-12-10; property list verified live 2026-08-04): serve the full content to Googlebot server-side; isAccessibleForFree (Boolean) is the required property, with recommended hasPart of @type: WebPageElement carrying isAccessibleForFree: false and a cssSelector "that references the class name" of the gated section. The point, verbatim: "This structured data helps Google differentiate paywalled content from the practice of cloaking, which violates spam policies." The doc scopes access restriction as "subscription or registration" — it does not use the phrase "lead generation."
  • 🟢 What is also verified: JS-hiding of fully-served content "isn't a reliable way to limit access" (Ch 6); and Subscription/Paywalled Content is a live gallery feature.
  • 🟢 Flexible sampling (metering vs. lead-in sampling for paywalled publishers) remains a live documented framework — Flexible Sampling Guidelines confirmed live 2026-08-04 (recommends monthly over daily metering; the 2017 launch post suggested ~10 clicks/month as a starting point).

Symptoms & diagnosis

Symptom Likely cause Where
Perfect markup, no rich result The guarantee gap — eligibility ≠ display §12.3
Rich results vanished sitewide on one feature Check the graveyard — feature likely retired §12.5
GSC enhancement report disappeared Same — deprecation, not data loss §12.10, §12.5
Report totals don't match page counts Items-not-pages counting + sampling §12.10
"Structured data issue" manual action Invisible/misleading/self-serving markup — fix + Request Review; ranking unaffected §12.11
Product rich results flaky on JS site Dynamically-generated Product markup degrading Shopping crawls §12.1, Ch 6
Markup valid in SMV, invisible to Google Type outside Google's documented subset §12.8, §12.9
Images missing from rich results SD image URLs blocked from crawling §12.2
Agency pitching FAQ/HowTo schema Both dead (2023 / May 2026) — see graveyard §12.5
Elaborate @graph "entity stack" proposed No documented mechanism; sameAs is disambiguation only §12.7

Sources

All fetched 2026-08-04 (V2 audit 2026-08-04 re-verified live: intro, sd-policies, search-gallery, manual-actions trigger, paywalled-content, book, and the V2-item relays listed below): - Intro to structured data (2025-12-10) - General structured data guidelines (sd-policies) (2026-07-10) - Search gallery (2026-06-15) - Generate structured data with JavaScript (2025-12-10) - Documentation changelog (deprecation entries 2023–2026 as dated in §12.5) - Carousels (beta) (2026-01-21) - Fact check / ClaimReview (2025-12-10) - AI features and your website (2025-12-10) · AI optimization guide (2026-07-10) - Organization (2026-04-15) · LocalBusiness (2025-12-10) · Book actions (2025-12-10) - Paywalled content structured data (2025-12-10) · Flexible sampling guidelines - Rich Results Test help · Rich result status reports · Manual Actions report - V2 audit 2026-08-04: resolved — leftover-markup reassurance (verbatim via SEL relay; primary blog body would not render, stays 🟡), Mueller Bluesky (Apr 2025, verbatim via SEJ, thread URL recorded), Book-actions status (no deprecation notice on live doc), paywalled-content properties (verified verbatim, §12.14 upgraded 🟢), flexible-sampling doc (live). Still open: FAQ GSC-report June-2026 sunset date remains industry-reported (🟡)