How to Validate Schema Markup: A 15-Step Audit Checklist
How to validate schema markup in 15 steps: syntax, required properties, matching visible content, template duplicates and Rich Results Test vs validator.
Kazi Khalid Hasan Tamim · BugViso Team
16 min read
To validate schema markup, check it at four tiers: valid JSON syntax, the required and recommended properties for each type, markup that matches the visible page, and linked entities.
Run the 15 checks below on every template before release. One unparsable block can stop Google reading that markup and cost you rich results.
If you are new to the format, read what schema markup is first.
Syntax errors, missing required fields and markup that contradicts the page are the usual reasons Google reports "Unparsable structured data" or drops rich results.
The four tiers, in order:
- Syntax and container integrity: valid JSON per RFC 8259, no trailing commas.
- Entity and attribute compliance: the mandatory and recommended Schema.org properties.
- Truthfulness and page parity: the schema matches the visible text.
- Knowledge graph architecture: consistent
@idlinking and mobile parity.
This schema audit checklist provides a 15-point technical inspection framework, complete with command-line testing tools, before-and-after code solutions, and an automated verification script to audit structured data at scale.
1. How to Validate Schema Markup: The 15-Step Matrix
The matrix below organizes the 15 validation checkpoints into four logical priority tiers (P0 Critical, P1 Major, P2 Moderate), defining the technical failure mode and pass criteria for each step:
| Priority Tier | Step # | Audit Checkpoint | Impact of Failure | Validation Pass Criteria |
|---|---|---|---|---|
| Tier 1 (P0) | 1 | RFC 8259 JSON Syntax | Fatal GSC unparsable error | jq . parses payload with zero syntax errors |
| Tier 1 (P0) | 2 | Script Container Tagging | Schema ignored by search bots | Encapsulated in <script type="application/ld+json"> |
| Tier 1 (P0) | 3 | HTML Entity Sanitation | Unescaped quotes break parse | No raw " inside script; valid UTF-8 quotes |
| Tier 1 (P0) | 4 | Server-Side Render Parity | Client-side only missed by bots | Schema present in raw initial HTTP response |
| Tier 2 (P0) | 5 | Mandatory Property Check | Ineligible for Rich Results | All required fields present (e.g., offers.price) |
| Tier 2 (P1) | 6 | Recommended Property Check | Degraded snippet display | Maximum recommended fields populated |
| Tier 2 (P1) | 7 | ISO 8601 Date Formatting | Timestamps rejected by parser | Strict YYYY-MM-DDTHH:MM:SSZ formatting |
| Tier 2 (P1) | 8 | Numeric Type Enforcement | Price / coordinates fail parse | Prices and lat/lng serialized as floats, not strings |
| Tier 3 (P0) | 9 | Visible DOM Data Parity | Deceptive Structured Data manual action | 100% of schema values match visible page text |
| Tier 3 (P0) | 10 | Self-Serving Review Ban | Review stars stripped in SERP | Zero aggregateRating on LocalBusiness/Org |
| Tier 3 (P1) | 11 | Canonical URL Alignment | Conflicting entity signals | Schema @id and url match <link rel="canonical"> |
| Tier 4 (P1) | 12 | Connected @graph Topology | Fragmented entity understanding | Interlinked entities via unique @id URI nodes |
| Tier 4 (P1) | 13 | Mobile Viewport Parity | Mobile-first indexing dropped | Schema matches identically on mobile & desktop |
| Tier 4 (P2) | 14 | Duplicate Syntax Purge | Conflicting data parsing errors | Legacy Microdata/RDFa stripped in favor of JSON-LD |
| Tier 4 (P2) | 15 | AI Search Citability (GEO) | Machines read a different answer than visitors see | Markup states the same facts as the visible text |
Rich Results Test vs Schema Markup Validator: Which Schema Validator to Use
Use both. Google's Rich Results Test checks whether a page is eligible for a Google rich result and which required properties are missing. Our comparison of the best structured data testing tools covers which tester answers which question.
The Schema Markup Validator checks any schema.org markup for syntax and vocabulary errors, whether or not Google has a feature for it. Structured data testing is not one tool's job.
2. Tier 1: Syntax, Parsing & Container Integrity (Steps 1–4)
A failure in Tier 1 is a catastrophic defect that prevents search engine crawlers from extracting any structured data from the document.
Step 1: Validate Strict RFC 8259 JSON Syntax
Verify that the JSON payload is free of trailing commas, unquoted property keys, single-quoted strings, or JavaScript-style comments (// or /* */):
# Verify JSON syntax via cURL and jq
curl -sL https://example.com/product | sed -n '/<script type="application\/ld+json">/,/<\/script>/p' | sed 's/<script type="application\/ld+json">//g' | sed 's/<\/script>//g' | jq .If jq outputs parse error, you have a fatal syntax bug. To explore specific syntax debugging techniques, review our guide on fixing unparsable structured data errors in GSC.
Step 2: Validate the Script Container MIME Type
The structured data payload must be encapsulated within a standard HTML <script> tag declaring the exact MIME type:
<!-- ✅ Valid Container Declaration -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "WebPage"
}
</script>Omitting type="application/ld+json" or declaring type="text/javascript" causes crawlers to treat the block as executable application code rather than semantic metadata.
Step 3: Prevent HTML Double-Escaping
Ensure your backend templating engine (Blade, Jinja, ERB) does not sanitize JSON quotes into HTML entities:
- ❌ Broken:
{"@context": "https://schema.org"} - ✅ Fixed:
{"@context": "https://schema.org"}
Step 4: Confirm Server-Side Rendering (SSR) Delivery
Do not inject critical JSON-LD purely client-side inside a React useEffect or Vue mounted hook. Inspect the initial server response via curl -I and curl -s to confirm that the script block is present in the initial HTML byte stream before client hydration.
3. Tier 2: Entity & Attribute Compliance (Steps 5–8)
Tier 2 ensures your schema satisfies Schema.org vocabularies and Google's Rich Results specifications.
Step 5: Audit Required Properties per Entity Type
Google publishes explicit documentation defining mandatory properties for each rich snippet feature:
Product: Requiresname,image, andoffers(withoffers.priceandoffers.priceCurrency).Article: Requiresheadline,image,datePublished, andauthor.BreadcrumbList: RequiresitemListElement(withposition,name, anditem).
Missing even one mandatory property completely revokes rich snippet eligibility.
Step 6: Populate Recommended Properties for Visual Richness
Recommended properties do not cause validation failures if omitted, but their presence dramatically improves snippet appearance:
- For
Product: AddingaggregateRating,brand,sku,gtin13, andhasMerchantReturnPolicy. - For
VideoObject: AddingdurationandhasPart(Key Moments).
Step 7: Enforce ISO 8601 Date & Duration Standards
All dates and durations must adhere strictly to international standards:
- Publication Date:
"2026-09-22T08:00:00+00:00"(Full UTC timestamp). - Video Duration:
"PT4M30S"(ISO 8601 duration notation: 4 minutes, 30 seconds).
Step 8: Strict Numeric Type Enforcement
Ensure numeric metrics are serialized as raw floats or integers rather than string literals:
- Latitude / Longitude:
37.7909,-122.4018(Numeric floats). - Product Pricing:
149.00(Numeric float, without currency symbols).
4. Tier 3: Quality, Parity & Anti-Spam Compliance (Steps 9–11)
Technical validity means nothing if your schema violates Google's Webmaster Content Policies.
Step 9: Verify 100% Data Parity with Visible Text
Every claim made in your JSON-LD must be visible to human users reading the page. If your schema declares:
price: "49.00"-> The visible page must display$49.00.ratingValue: "4.8"-> The page must visibly show4.8stars and authentic customer reviews.
Discrepancies trigger manual action penalties for deceptive structured data.
Step 10: Enforce the Ban on Self-Serving Reviews
Never attach aggregateRating to LocalBusiness or Organization schema on your own domain:
// ❌ CRITICAL POLICY VIOLATION: Self-serving review penalty risk
{
"@context": "https://schema.org",
"@type": "LocalBusiness",
"name": "Apex Law Firm",
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5.0",
"reviewCount": "42" // Prohibited by Google since 2019!
}
}Review markup is permitted only on discrete items evaluated by third-party customers (Product, SoftwareApplication, Book, Recipe). For detailed rules, see our technical breakdown of Product and AggregateRating schema review stars.
Step 11: Align Schema with the Canonical URL
The @id and url properties inside your schema must match the page's <link rel="canonical"> tag exactly:
- Check trailing slashes (
/product/vs/product). - Check protocols (
httpsvshttp). - Check subdomain consistency (
example.comvswww.example.com).
5. Tier 4: Knowledge Graph Linking & Mobile Parity (Steps 12–15)
Tier 4 elevates your structured data into a cohesive enterprise knowledge graph optimized for search engines and generative AI answer engines.
Step 12: Connect Entities via @graph and @id
Avoid isolated, disconnected JSON-LD blocks. Combine multiple entities on a single page into a unified @graph array, connecting them via explicit URI pointers:
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Apex Corporation"
},
{
"@type": "TechArticle",
"@id": "https://example.com/blog/sample/#article",
"headline": "Engineering Scalable Web Systems",
"publisher": { "@id": "https://example.com/#organization" }
}
]
}To review the architectural advantages of the @graph array, see our comparison on JSON-LD vs Microdata vs RDFa.
Step 13: Guarantee Mobile Viewport Parity
Google uses Mobile-First Indexing exclusively. If your mobile layout hides customer reviews or removes product specifications via CSS (display: none or conditional component rendering), Googlebot-Smartphone will not index those properties. Ensure schema and content parity across all device viewports.
Step 14: Purge Legacy Microdata and RDFa
If your codebase still contains legacy HTML5 Microdata (itemscope, itemprop) alongside new JSON-LD scripts, search engine parsers may encounter conflicting values. Remove all legacy inline attributes to establish JSON-LD as the single source of truth.
Step 15: Optimize for Generative Engine Citations (GEO)
Keep entity facts (names, prices, dates, authors) identical in the markup and in the visible, answer-first text. AI engines have not published how much weight they give JSON-LD, so the goal is consistency, not a citation boost. If you use FAQ markup, remember Google stopped showing FAQ rich results on May 7, 2026; the FAQPage schema guide explains what it is still good for.
6. Python Automation: 15-Point Automated Schema Audit Script
This automated Python script executes a comprehensive inspection against any production URL, testing all 15 checkpoints and returning a clear pass/fail report:
# scripts/schema_15_point_audit.py
import sys
import json
import httpx
from bs4 import BeautifulSoup
def audit_schema_checklist(url: str):
print(f"[*] Starting 15-Point Schema Audit on: {url}")
headers = {"User-Agent": "BugVisoSchemaAuditor/1.0 (+https://bugviso.com)"}
try:
res = httpx.get(url, headers=headers, timeout=12.0, follow_redirects=True)
except Exception as e:
print(f"[X] HTTP Fetch Failed: {e}")
return False
soup = BeautifulSoup(res.text, "html.parser")
page_text = soup.get_text()
canonical_tag = soup.find("link", rel="canonical")
canonical_url = canonical_tag.get("href", "").strip() if canonical_tag else None
scripts = soup.find_all("script", type="application/ld+json")
# Checkpoint 2: Container Tagging
if not scripts:
print("[X] Checkpoint #2 FAILED: Zero <script type='application/ld+json'> tags detected.")
return False
else:
print(f"[✓] Checkpoint #2 PASSED: Found {len(scripts)} JSON-LD script container(s).")
total_errors = 0
for idx, script in enumerate(scripts, start=1):
raw = script.string
if not raw:
print(f"[X] Checkpoint #1 FAILED in Block #{idx}: Empty script container.")
total_errors += 1
continue
# Checkpoint 3: HTML Entities
if """ in raw or "'" in raw:
print(f"[X] Checkpoint #3 FAILED in Block #{idx}: Raw HTML entities detected. Disable auto-escaping.")
total_errors += 1
else:
print(f"[✓] Checkpoint #3 PASSED in Block #{idx}: No HTML entity double-escaping.")
# Checkpoint 1: RFC 8259 Syntax
try:
payload = json.loads(raw)
print(f"[✓] Checkpoint #1 PASSED in Block #{idx}: Valid RFC 8259 JSON syntax.")
except json.JSONDecodeError as exc:
print(f"[X] Checkpoint #1 FAILED in Block #{idx}: Syntax Error -> {exc}")
total_errors += 1
continue
nodes = payload.get("@graph", [payload]) if isinstance(payload, dict) else payload
for node in nodes:
ntype = node.get("@type", "Unknown")
print(f"\n--- Evaluating Entity: {ntype} ---")
# Checkpoint 10: Self-Serving Review Ban
if ntype in ["LocalBusiness", "Organization"] and "aggregateRating" in node:
print(f"[X] Checkpoint #10 FAILED: Self-serving 'aggregateRating' on {ntype}!")
total_errors += 1
else:
print("[✓] Checkpoint #10 PASSED: No self-serving review violations.")
# Checkpoint 11: Canonical Alignment
node_url = node.get("url") or node.get("@id")
if canonical_url and node_url and canonical_url in str(node_url):
print(f"[✓] Checkpoint #11 PASSED: Entity aligns with canonical URL ({canonical_url}).")
elif canonical_url:
print(f"[!] Checkpoint #11 Warning: Entity URI '{node_url}' does not match canonical '{canonical_url}'.")
# Checkpoint 5: Mandatory Fields Check
if ntype == "Product":
if not node.get("name") or not node.get("offers"):
print("[X] Checkpoint #5 FAILED: Product missing required 'name' or 'offers'.")
total_errors += 1
else:
print("[✓] Checkpoint #5 PASSED: Product mandatory fields confirmed.")
if ntype == "Article" or ntype == "BlogPosting":
if not node.get("headline") or not node.get("author"):
print("[X] Checkpoint #5 FAILED: Article missing required 'headline' or 'author'.")
total_errors += 1
else:
print("[✓] Checkpoint #5 PASSED: Article mandatory fields confirmed.")
print("\n" + "=" * 65)
if total_errors == 0:
print("[✓] AUDIT SUCCESS: All critical structured data checkpoints passed!")
return True
else:
print(f"[X] AUDIT FAILURE: Encountered {total_errors} critical schema error(s).")
return False
if __name__ == "__main__":
target = sys.argv[1] if len(sys.argv) > 1 else "https://example.com"
audit_schema_checklist(target)7. How BugViso Automates Site-Wide Schema Checks
Checking single URLs by hand does not scale to thousands of templated pages.
A BugViso scan runs the structured data checks across every crawled URL. When you sign in and run a scan:
- Parsing and validation: the crawler reads the JSON-LD on each page and validates it against the required and recommended properties for each Schema.org type, flagging unparsable blocks and missing fields.
- Rich results readiness: it flags a missing property such as
offers.priceon aProduct, which Google needs for a rich result. - Whole-site coverage: one crawl covers all page templates, so a defect in a shared template shows up on every page that uses it.
- Fix list: every finding comes with an AI-written JSON-LD fix in the report and the branded PDF.
BugViso does not compare schema values with the rendered page text, so keep the parity checkpoints in the script above for that.
You pay $1.49 per full branded PDF report or use a monthly plan. More detail is on the structured data and duplicate content checks feature page.
8. Frequently Asked Questions
What is the most common reason schema fails in Google Search Console?
The single most common defect is invalid JSON syntax, specifically trailing commas after the final element in an array or object, which breaks RFC 8259 compliance and makes the block unparsable. If Search Console reports it, follow how to fix unparsable structured data errors.
How often should I audit my website's structured data?
Run the schema script on staging before each release. In addition, run a full site-wide crawl monthly to ensure dynamic database content, pricing updates, and third-party plugins have not corrupted your schema markup.
Can structured data trigger a manual penalty from Google?
Yes. Google issues manual actions for "Spammy structured markup" if schema declarations do not match visible page content, if reviews are marked up deceptively on local businesses, or if structured data is added to pages with hidden, manipulative intent.
Does valid schema guarantee rich snippets in Google search?
No. Valid schema is a strict technical prerequisite, but display in search results is Google's decision per query, and some types, such as FAQ, no longer show at all.
What should I do if Google Search Console shows schema warnings?
Warnings (yellow markers) indicate that recommended properties are missing. Unlike errors (red markers), warnings do not invalidate your schema, and rich snippets can still be awarded. However, resolving warnings improves snippet visual richness and search visibility.
9. Conclusion
Following these schema validation steps transforms structured data from a fragile technical risk into a reliable competitive advantage.
Verify JSON syntax, enforce entity completeness, keep data parity with visible text, and connect your entities into one graph.
Your markup then stays accurate and eligible for the rich results Google still offers. An automated BugViso scan runs these checks across every page on your domain.
Written by
Kazi Khalid Hasan Tamim · BugViso Team
Kazi writes BugViso’s guides on website audits, Core Web Vitals, technical SEO, accessibility and AI search. The data in them comes from audits BugViso runs in a real Chromium browser, including our 219-site study of website health.
Summarise with AI
Open this guide in your assistant.
Follow BugViso
New guides and audit data as we publish them.
AI visibility tracker
Is your brand in AI answers?
See how often AI assistants mention you, cite your site and rank you against your competitors.
- ChatGPT
- Gemini
- Perplexity
- Claude
- AI Overviews
See where your site stands
Run a free BugViso audit for SEO, speed, accessibility and AI search readiness — with fixes you can ship today.