SurfSense/.cursor/skills/schema-markup-generator/references/validation-guide.md

Schema Markup Validation Guide

Complete reference for validating, testing, and troubleshooting structured data.

Validation Tools

Google Rich Results Test

• URL: https://search.google.com/test/rich-results
• Purpose: Check if your schema is eligible for Google rich results
• Tests: Live URL or code snippet
• Output: Errors, warnings, eligible rich result types

Schema.org Validator

• URL: https://validator.schema.org/
• Purpose: Validate against official Schema.org specification
• Tests: URL, code snippet, or microdata
• Output: Technical validation errors

Google Search Console

• Location: Search Console → Enhancements section
• Purpose: Monitor rich results performance and errors at scale
• Reports: Rich results status, coverage, issues over time

---

Common JSON-LD Syntax Errors

Trailing Commas

Error: Invalid JSON syntax

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Title",  ← Trailing comma here
}

Fix: Remove the comma after the last property

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Title"
}

Missing Required Quotes

Error: Property names must be quoted

{
  @context: "https://schema.org"
}

Fix: Quote all property names

{
  "@context": "https://schema.org"
}

Incorrect Date Format

Error: Invalid date format

{
  "datePublished": "01/15/2024"
}

Fix: Use ISO 8601 format

{
  "datePublished": "2024-01-15T08:00:00+00:00"
}

Relative URLs Instead of Absolute

Error: Relative URLs are not allowed

{
  "image": "/images/photo.jpg"
}

Fix: Use absolute URLs

{
  "image": "https://example.com/images/photo.jpg"
}

Incorrect Array Syntax

Error: Multiple values not in array

{
  "image": "url1.jpg", "url2.jpg"
}

Fix: Use array brackets for multiple values

{
  "image": ["url1.jpg", "url2.jpg"]
}

---

Required vs Recommended Properties

FAQPage Schema

Property	Status	Notes
@type	Required	Must be "FAQPage"
mainEntity	Required	Array of Question objects
Question.name	Required	The question text
Answer.text	Required	The answer text

Minimum: 2 Q&A pairs

HowTo Schema

Property	Status	Notes
@type	Required	Must be "HowTo"
name	Required	Title of the how-to
step	Required	Array of HowToStep objects
step.text	Required	Step instructions
image	Recommended	Improves visibility
totalTime	Recommended	Shows duration in results
supply	Recommended	Lists materials needed
tool	Recommended	Lists tools needed

Minimum: 2 steps with text

Article Schema

Property	Status	Notes
@type	Required	Article/BlogPosting/NewsArticle
headline	Required	Max 110 characters
image	Required	Minimum 1200px wide
datePublished	Required	ISO 8601 format
author	Required	Person or Organization
publisher	Required	Organization with logo
publisher.logo	Required	Max 600px wide, 60px high
dateModified	Recommended	Update when content changes
description	Recommended	Improves display

Product Schema

Property	Status	Notes
@type	Required	Must be "Product"
name	Required	Product name
image	Required	Product images
description	Recommended	Product description
offers	Recommended	Required for price display
offers.price	Recommended	Required for price display
offers.priceCurrency	Recommended	Required for price display
offers.availability	Recommended	Stock status
aggregateRating	Recommended	Required for star ratings
review	Recommended	Individual reviews
sku	Recommended	Product identifier
brand	Recommended	Brand information

LocalBusiness Schema

Property	Status	Notes
@type	Required	LocalBusiness or subtype
name	Required	Business name
address	Required	PostalAddress object
address.streetAddress	Required	Street address
address.addressLocality	Required	City
address.addressRegion	Required	State/province
address.postalCode	Required	ZIP/postal code
address.addressCountry	Required	Country code
geo	Recommended	Latitude/longitude
telephone	Recommended	Phone number
openingHoursSpecification	Recommended	Business hours
priceRange	Recommended	Price range indicator
aggregateRating	Recommended	Customer ratings

Organization Schema

Property	Status	Notes
@type	Required	Must be "Organization"
name	Required	Organization name
url	Required	Website URL
logo	Recommended	Brand logo
sameAs	Recommended	Social media profiles
contactPoint	Recommended	Contact information

---

Google Rich Result Eligibility Requirements

FAQ Rich Results

Eligibility checklist:

• Minimum 2 Q&A pairs
• Questions are actual questions (contain "?")
• Answers are complete and comprehensive
• Content matches visible page content exactly
• Not a forum or Q&A page where users can submit answers
• Not advertising or promotional in nature
• Not for medical, legal, or financial advice without proper E-E-A-T

Ineligible content:

• Medical advice without credentials
• Legal advice
• Product/service comparisons that are promotional
• User-generated Q&A (use QAPage instead)

How-To Rich Results

Eligibility checklist:

• Minimum 2 steps with clear instructions
• Complete process from start to finish
• Each step has meaningful text (not just a title)
• Not advertising or promotional
• Not harmful or dangerous content
• Steps are actionable and practical

Ineligible content:

• Single-step processes
• Recipes (use Recipe schema instead)
• Promotional tutorials

Product Rich Results

For price display:

• Valid Product schema
• offers with price property
• priceCurrency specified
• availability status

For review stars:

• Valid aggregateRating OR individual review
• Minimum 1 review for individual review display
• Honest, unbiased reviews (not paid/incentivized)

For product markup:

• name property present
• At least one image
• Valid product type (not person, organization, etc.)

Article Rich Results

Eligibility checklist:

• Valid Article/BlogPosting/NewsArticle schema
• High-quality, original content
• Proper publisher with valid logo
• Valid author information
• Images meet size requirements (1200px wide)
• Not short-form content (minimum ~300 words)

---

Testing Workflow

Initial Implementation

1. Add schema to development/staging environment
2. Validate syntax at validator.schema.org
   • Paste code or test URL
   • Fix all errors before proceeding
3. Test at Google Rich Results Test
   • Check for Google-specific issues
   • Verify eligible rich result types
4. Visual inspection
   • View page source to confirm schema is present
   • Check JSON formatting in browser

Pre-Launch Testing

1. Test on staging URL with Rich Results Test
2. Verify all required properties present
3. Confirm content matches visible page content
4. Check for policy violations
5. Test multiple schema types if combining
6. Validate images are accessible and meet size requirements

Post-Launch Monitoring

1. Submit sitemap to Google Search Console
2. Monitor Enhancements reports
   • Check for validation errors
   • Watch for policy violations
   • Track rich result impressions
3. Re-test pages if content changes
4. Update dateModified when updating content
5. Fix errors within 30 days to avoid rich result removal

---

Common Policy Violations

Content Mismatch

Violation: Schema content doesn't match visible page content

Example: FAQ schema includes Q&A pairs not visible on page

Fix: Ensure all structured data reflects actual page content exactly

Deceptive Content

Violation: Schema contains misleading information

Example: Product reviews that are fake or incentivized

Fix: Only include genuine, verifiable information

Spammy Markup

Violation: Excessive or irrelevant schema

Example: Adding Product schema to every blog post

Fix: Only use schema types relevant to page content

Hidden Content

Violation: Schema references content hidden from users

Example: FAQ answers only in schema, not visible on page

Fix: Make all schema content visible to users

Promotional Content in FAQ

Violation: Using FAQ schema for promotional purposes

Example: Questions like "Why is [Brand] the best?"

Fix: Use neutral, informational questions

---

Debugging Common Issues

Schema Not Appearing in Rich Results Test

Possible causes:

• JSON syntax error (validate at validator.schema.org)
• Schema in incorrect location (should be in <head> or <body>)
• Script tag missing type="application/ld+json"
• Content served dynamically after page load (bot can't see it)

Debug steps:

1. View page source (not inspect element)
2. Search for "@type"
3. Copy JSON to validator.schema.org
4. Fix syntax errors

Rich Results Not Showing in Search

Possible causes:

• Schema is new (can take days/weeks to appear)
• Page not indexed by Google
• Schema has errors in Search Console
• Content doesn't meet quality guidelines
• Competition for rich results is high

Debug steps:

1. Check Search Console → Enhancements
2. Use URL Inspection tool to request indexing
3. Verify schema passes Rich Results Test
4. Check for manual actions

Warnings vs Errors

Errors (must fix):

• Invalid syntax
• Missing required properties
• Invalid property values
• Schema type doesn't exist

Warnings (should fix when possible):

• Missing recommended properties
• Suboptimal property values
• Non-standard extensions
• Property not recognized for this type

---

Schema Maintenance Checklist

Monthly

• Check Search Console for new errors
• Verify rich results are still appearing
• Update dateModified on changed content

Quarterly

• Audit all schema implementations
• Test key pages with Rich Results Test
• Update any outdated information (prices, dates, etc.)
• Check for new schema types relevant to your content

After Content Changes

• Update schema to match new content
• Update dateModified timestamp
• Re-validate with Rich Results Test
• Request re-indexing in Search Console if major changes

After Site Migration

• Verify schema preserved on new URLs
• Update all absolute URLs in schema
• Submit new sitemap
• Monitor for errors in new domain's Search Console

---

Quick Reference: Error Messages and Fixes

Error Message	Cause	Fix
"Missing required field"	Required property not included	Add the required property
"Invalid date format"	Date not in ISO 8601	Use format: 2024-01-15T08:00:00+00:00
"URL is not absolute"	Relative URL used	Add full URL with https://
"Unexpected token"	JSON syntax error	Check for missing quotes, brackets, commas
"This markup is not eligible for rich results"	Schema type or content doesn't qualify	Review eligibility requirements
"Image too small"	Image doesn't meet size requirements	Use image at least 1200px wide
"The attribute price is required"	Product missing price	Add offers.price property
"Logo must be 600x60 or smaller"	Publisher logo too large	Resize logo to meet requirements

---

Resources

• Schema.org Documentation: https://schema.org/
• Google Search Central: https://developers.google.com/search/docs/appearance/structured-data
• Rich Results Test: https://search.google.com/test/rich-results
• Schema Validator: https://validator.schema.org/
• JSON-LD Playground: https://json-ld.org/playground/