Validate structured data before shipping in Technical SEO

Validate structured data before shipping

I've seen production sites rank well for years, then suddenly lose rich snippets overnight—not because the content changed, but because someone pushed malformed JSON-LD without testing it first. Broken structured data fails silently; Google won't show an error, it just ignores your markup and moves on. Today I'm walking you through the validation tools and CI practices that catch these issues before they cost you visibility.

Why structured data validation matters

Structured data is how you tell search engines what your content is about. A broken schema doesn't trigger 404s or obvious errors—it simply doesn't work. Your rich results disappear, your FAQ snippets vanish, your product ratings stop showing in search. For e-commerce platforms I've built, a single syntax error in product JSON-LD can flatten CTR by 20–30% because users see a plain blue link instead of a card with price, rating, and availability.

The cost of validation is near zero. The cost of not validating is high and invisible until someone pulls a report three weeks later.

Rich Results Test for Google features

Google's Rich Results Test is the first place I check before and after shipping schema markup. It's the official validator for features that generate rich results: products, recipes, articles, FAQs, job postings, events, and more.

Here's what I do in practice:

1. Build your page with structured data locally or in staging.
2. Copy the entire HTML source (not just the JSON-LD block—Google crawls the full page).
3. Paste it into https://search.google.com/test/rich-results.
4. Look for green checkmarks next to detected rich result types. Red warnings or errors mean your markup won't generate rich results.
5. Click each error to see exactly which field is missing or malformed.

Example: I once built a product listing page with this JSON-LD:

{
  "@context": "https://schema.org/",
  "@type": "Product",
  "name": "Wireless Headphones",
  "image": "https://example.com/headphones.jpg",
  "description": "High-quality wireless headphones",
  "offers": {
    "@type": "Offer",
    "price": "99.99",
    "priceCurrency": "USD"
  }
}

Rich Results Test flagged that availability was missing from the Offer. Without it, Google wouldn't render the "In Stock" badge. Adding "availability": "https://schema.org/InStock" fixed it instantly and the badge appeared in test results.

Run this test every time you ship new schema markup, even if it's just copying an existing template. A typo in a field name or a missing required property breaks everything silently.

Schema Markup Validator for general schema

Rich Results Test is specific to Google's rich features, but you might also use schema.org properties that don't generate rich results—like datePublished, author, or inLanguage. These still matter for knowledge panels, voice search, and AI indexing, even if they don't show up as visual snippets.

For comprehensive validation, I use the Schema.org Markup Validator (https://validator.schema.org/). It checks your JSON-LD against the full schema.org specification, not just Google's rich result requirements.

The validator will catch:

• Properties that don't exist in the schema (typos like descrition instead of description).
• Wrong data types (e.g., passing a string where an object is required).
• Missing required properties for that schema type.
• Deprecated properties you should stop using.

Example from a CRM integration I worked on: I had a Person schema with "jobTitle": "Sales Manager" but never included "name". The Rich Results Test didn't complain (Person doesn't require name for rich results), but the Schema.org validator flagged it as a best practice violation. Adding "name": "John Doe" made the schema semantically complete.

I run both validators—Rich Results Test for Google's features, Schema.org Validator for semantic correctness. Different tools, complementary coverage.

Search Console enhancement reports after launch

Validators are great for staging, but the real test is production. Google Search Console's Enhancement reports show you exactly which pages have schema issues in the wild.

After shipping structured data, wait 24–48 hours and check Enhancements → [Rich result type] in Search Console. You'll see:

• Valid: pages where Google parsed your schema successfully.
• Valid with warnings: schema works, but missing optional fields or recommended practices.
• Errors: schema is broken and won't generate rich results.

The error list is filterable and shows you exactly which pages are affected. This is your production safety net.

Real example: After launching a recipe aggregation feature on a travel platform, Search Console showed 200 Recipe schemas valid, but 45 had warnings. Clicking into the warning details revealed that prepTime was missing from all 45. I added a fallback value in the template, redeployed, and within a week all warnings cleared.

Set up a monthly reminder to check these reports. If errors suddenly spike, you've got a bug in your template logic.

Add validation to your CI for templates

Manual testing catches mistakes on day one. CI catches regressions on day 100. I always add schema validation to my build pipeline.

Here's a practical approach for Next.js and Node.js:

1. Extract schema from rendered HTML: Use a library like cheerio to parse the HTML and pull out all <script type="application/ld+json"> blocks.
2. Validate against schema.org: Use a validator library or call an API.
3. Fail the build if validation fails: Treat schema errors like linting errors.

Here's a minimal example:

// validate-schema.js
import fs from 'fs';
import * as cheerio from 'cheerio';
import fetch from 'node-fetch';

async function validateSchema(htmlFile) {
  const html = fs.readFileSync(htmlFile, 'utf-8');
  const $ = cheerio.load(html);
  const schemaScripts = $('script[type="application/ld+json"]');

  if (schemaScripts.length === 0) {
    console.warn('No structured data found');
    return;
  }

  for (const script of schemaScripts) {
    const jsonld = JSON.parse($(script).html());
    
    // Basic validation: required fields for Product
    if (jsonld['@type'] === 'Product') {
      if (!jsonld.name || !jsonld.image || !jsonld.offers) {
        throw new Error(`Product schema missing required fields: ${JSON.stringify(jsonld)}`);
      }
    }
  }

  console.log('Schema validation passed');
}

// Run on all HTML files in output directory
const files = fs.readdirSync('./out').filter(f => f.endsWith('.html'));
for (const file of files) {
  await validateSchema(`./out/${file}`);
}

This is a lightweight check you can run in your CI/CD pipeline. For more robust validation, integrate with the Schema.org validator API or use a tool like schema-validator npm package.

I also add a pre-commit hook that validates schema in my template files before they even get pushed:

// .husky/pre-commit
#!/bin/sh
node scripts/validate-schema.js || exit 1

Catch errors locally. Never let broken schema reach staging or production.

Common mistakes

Assuming JSON syntax is enough. Valid JSON is necessary but not sufficient. You can have perfectly valid JSON that violates schema.org constraints. A Rich Results Test pass doesn't guarantee a Schema.org Validator pass and vice versa.

Validating only one page. Validate a representative page from each template type. Your product schema might be solid, but your article schema could be broken. I've seen platforms where home page schema is fine but category pages have errors in 50% of cases.

Validating once and forgetting. Schema breaks when you refactor templates, update dependencies, or change data sources. Add validation to CI so regressions are caught immediately, not weeks later when you notice rich results vanishing.

Ignoring warnings. "Valid with warnings" from Search Console isn't a pass. Those warnings often point to missing fields that will matter for future features. A recipe missing prepTime might not hurt you today, but Google could require it for the recipe rich result in six months.

Testing only in staging. Staging data is often sanitized or incomplete. Production real data might expose schema issues (null fields, unexpected data types, edge cases). Validate in Search Console after launch, not just before.

Key takeaways

• Broken JSON-LD fails silently—use Rich Results Test before shipping any schema for Google rich result types.
• Rich Results Test is Google-specific; use Schema.org Markup Validator for semantic correctness across all schema properties.
• Check Search Console Enhancement reports 24–48 hours after launch to catch real-world validation errors in production data.
• Add schema validation to your CI pipeline so regressions are caught immediately, not weeks later.
• Validate representative pages for each template type, not just one page—different schemas have different requirements.
• Treat schema warnings seriously, even if they don't block rich results today—they often predict future requirements.