CompanySite/.agents/seo-specialist/VALIDATION_GUIDE.md

Structured Data Validation Guide

Quick reference for testing and validating structured data implementation.

---

Automated Validation

Run Local Validation Script

# Build the site first
npm run build

# Run validation
npm run validate:schema

What it checks:

• ✅ JSON-LD syntax validity
• ✅ Required schema properties
• ✅ Open Graph tags completeness
• ✅ Twitter Card tags completeness
• ⚠️ Recommended optional properties

---

Manual Testing Tools

1. Google Rich Results Test

URL: https://search.google.com/test/rich-results

How to use:

1. Enter your page URL (or paste HTML)
2. Click "Test URL"
3. Review detected structured data
4. Check for errors and warnings

Pages to test:

• Homepage: https://workroot.in/
• Blog post: https://workroot.in/blog/[any-post]
• Services: https://workroot.in/services
• About: https://workroot.in/about
• Contact: https://workroot.in/contact

Expected results:

• ✅ No errors
• ✅ All schemas detected
• ✅ Valid for rich results

---

2. Schema Markup Validator

URL: https://validator.schema.org/

How to use:

1. Go to validator
2. Paste page HTML or URL
3. Click "Run test"
4. Review validation results

What to check:

• ✅ All schemas are valid
• ✅ No syntax errors
• ✅ Required properties present
• ⚠️ Fix any warnings

---

3. Facebook Sharing Debugger

URL: https://developers.facebook.com/tools/debug/

How to use:

1. Enter your page URL
2. Click "Debug"
3. Review Open Graph tags
4. Check preview image

What to verify:

• ✅ Title displays correctly
• ✅ Description is accurate
• ✅ Image loads (1200x630px)
• ✅ URL is correct
• ✅ Preview looks good

Troubleshooting:

• If changes don't appear, click "Scrape Again"
• Clear Facebook cache for updated content

---

4. Twitter Card Validator

URL: https://cards-dev.twitter.com/validator

How to use:

1. Enter your page URL
2. Click "Preview card"
3. Review card preview

What to verify:

• ✅ Card type: summary_large_image
• ✅ Title displays correctly
• ✅ Description is accurate
• ✅ Image loads and looks good
• ✅ Domain is correct

---

5. LinkedIn Post Inspector

URL: https://www.linkedin.com/post-inspector/

How to use:

1. Enter your page URL
2. Click "Inspect"
3. Review preview

What to verify:

• ✅ Uses Open Graph tags
• ✅ Preview displays correctly
• ✅ Image renders properly

---

6. Google Search Console

How to use:

1. Go to Search Console
2. Navigate to "Enhancements"
3. Check each enhancement report

What to monitor:

• Rich Results: Track eligible pages
• Breadcrumbs: Verify detection
• Organization: Check knowledge graph
• FAQs: Monitor FAQ rich snippets
• Errors: Fix any structured data errors

Setup:

1. Add property: https://workroot.in
2. Verify ownership
3. Submit sitemap.xml
4. Wait 24-48 hours for data

---

Testing Checklist

Homepage (/)

• Organization schema valid
• WebSite schema valid
• FAQPage schema valid
• Open Graph tags complete
• Twitter Card tags complete
• FAQ rich snippet preview

Blog Post (/blog/[slug])

• BlogPosting schema valid
• BreadcrumbList schema valid
• Author information present
• Image with dimensions
• Published/modified dates
• Keywords and category
• Open Graph article type
• Twitter large image card

Services (/services)

• Service schema valid
• BreadcrumbList schema valid
• WebPage schema valid
• Service descriptions complete
• Open Graph tags
• Twitter Card tags

About (/about)

• AboutPage schema valid
• BreadcrumbList schema valid
• Organization reference
• Team member info
• Open Graph tags
• Twitter Card tags

Contact (/contact)

• ContactPage schema valid
• BreadcrumbList schema valid
• Contact info accurate
• Open Graph tags
• Twitter Card tags

---

Common Issues & Fixes

Issue: "Missing required property"

Fix: Add the required property to the schema Example:

{
  "@type": "BlogPosting",
  "headline": "Required - add this",
  "author": "Required - add this",
  "datePublished": "Required - add this"
}

Issue: "Invalid URL"

Fix: Ensure all URLs are absolute (start with https://) Example:

{
  "image": "https://workroot.in/image.jpg",  // ✅ Absolute
  "image": "/image.jpg"  // ❌ Relative
}

Issue: "Image too small"

Fix: Use images at least 1200x630px for social sharing Optimal sizes:

• Open Graph: 1200x630px
• Twitter Card: 1200x675px (or 1200x630px)

Issue: "Missing breadcrumb position"

Fix: Ensure positions start at 1 and increment Example:

{
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "position": 1, "name": "Home", "item": "..." },
    { "position": 2, "name": "Blog", "item": "..." }
  ]
}

Issue: "Publisher logo missing"

Fix: Add logo to publisher organization Example:

{
  "publisher": {
    "@type": "Organization",
    "name": "WorkRoot IT Solutions",
    "logo": {
      "@type": "ImageObject",
      "url": "https://workroot.in/logo.png",
      "width": 512,
      "height": 512
    }
  }
}

Issue: "Open Graph image not loading"

Fixes:

1. Verify image URL is accessible
2. Ensure image is publicly accessible (not behind auth)
3. Check image format (JPG, PNG recommended)
4. Clear Facebook cache using Sharing Debugger
5. Verify image dimensions (min 200x200, recommended 1200x630)

Issue: "Twitter Card not showing"

Fixes:

1. Ensure twitter:card is set to summary_large_image
2. Verify image URL is absolute
3. Check image size (min 300x157, max 4096x4096)
4. Image must be under 5MB
5. Use Twitter Card Validator to debug

---

Monitoring & Maintenance

Weekly Checks

• Check Search Console for new structured data errors
• Monitor rich results impressions
• Review CTR for pages with rich snippets

Monthly Checks

• Re-validate all pages with Google Rich Results Test
• Update aggregate rating if new reviews received
• Check for broken image URLs
• Verify social sharing previews

Quarterly Checks

• Full schema audit with validator.schema.org
• Review and update FAQ content
• Update team member information
• Refresh service descriptions
• Check for new schema types to implement

---

Performance Tracking

Key Metrics to Monitor

Google Search Console:

• Rich results impressions
• Rich results clicks
• Average CTR (should increase with rich snippets)
• Top performing rich result types

Analytics:

• Organic search traffic
• Bounce rate from search (should decrease)
• Pages/session from organic search
• Social referral traffic

Social Sharing:

• Click-through rate on social shares
• Engagement on shared links
• Share conversion rate

---

Troubleshooting Resources

Google Support

• Structured Data Guidelines
• Fix Structured Data Issues
• Rich Results Status Report

Schema.org

• Getting Started
• Full Schema Hierarchy
• Validator

Social Platforms

• Facebook Open Graph Docs
• Twitter Card Docs
• LinkedIn Share Docs

---

Quick Commands

# Build site
npm run build

# Validate schemas
npm run validate:schema

# Start dev server
npm run dev

# Preview build
npm run preview

# Deploy
npm run deploy:build
npm run deploy:start

---

Last Updated: 2026-03-21 Need Help? Check .agents/seo-specialist/STRUCTURED_DATA.md for detailed documentation