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
```bash
# 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:**
```json
{
  "@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:**
```json
{
  "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:**
```json
{
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "position": 1, "name": "Home", "item": "..." },
    { "position": 2, "name": "Blog", "item": "..." }
  ]
}
```

### Issue: "Publisher logo missing"
**Fix:** Add logo to publisher organization
**Example:**
```json
{
  "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](https://developers.google.com/search/docs/appearance/structured-data/sd-policies)
- [Fix Structured Data Issues](https://support.google.com/webmasters/answer/7445569)
- [Rich Results Status Report](https://support.google.com/webmasters/answer/7552505)

### Schema.org
- [Getting Started](https://schema.org/docs/gs.html)
- [Full Schema Hierarchy](https://schema.org/docs/full.html)
- [Validator](https://validator.schema.org/)

### Social Platforms
- [Facebook Open Graph Docs](https://developers.facebook.com/docs/sharing/webmasters)
- [Twitter Card Docs](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/markup)
- [LinkedIn Share Docs](https://www.linkedin.com/help/linkedin/answer/46687)

---

## Quick Commands

```bash
# 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