Overview

Sites using Yoast SEO expose a /schemamap endpoint that aggregates schema data. This validator checks that endpoint for completeness, consistency, and proper structure — ensuring the schema graph accurately represents the site’s content.

How It Works

1. User provides the site URL (schemamap endpoint is auto-detected)
2. ValidGraph fetches and parses the schemamap
3. Validates:
– Endpoint availability and response format
– Schema type coverage
– Entity relationship completeness
– Per-URL schema consistency with the schemamap
4. Reports gaps and inconsistencies

Tier Availability

| Tier | Available |
|——|———–|
| Free | No |
| Pro | No |
| Agency | Yes |
| Enterprise | Yes |

Related Features

– Schemamap Cross-Validation: Compare schemamap vs individual pages (Enterprise)
– NLWeb Readiness Checker: Broader AI readiness assessment

Mini-Tutorial

Validating Your Yoast Schemamap Endpoint

1. Trigger a schemamap validation:

   POST /validgraph/v1/schemamap-validate

   {
     "site_url": "https://example.com"
   }
   

2. Review the validation report:
– Endpoint availability: Is /schemamap reachable?
– Response format: Valid JSON?
– Schema type coverage: How many types are declared?
– Entity relationship completeness: Are entities linked?

3. Identify issues:
– Endpoint missing: Add
– Format errors: Fix JSON syntax in Yoast settings
– Incomplete coverage: Some pages not in schemamap
– Weak relationships: Entities listed but not connected

4. Fix schemamap issues:
– Re-run Yoast schema generation
– Ensure all pages are indexed
– Verify schema completeness in Yoast plugin settings

5. Re-validate to track improvement.

Technical Details

Schemamap Validation Process

1. Endpoint Discovery:
– Attempts standard locations: /.well-known/schema, /schemamap
– Checks for tag in homepage
– Fallback: Uses Yoast’s documented endpoint path

2. Health Check:
– Verifies endpoint responds (HTTP 200)
– Validates JSON format
– Checks response structure compatibility

3. Schema Analysis:
– Extracts all declared schema types
– Counts entity occurrences
– Identifies relationship patterns
– Validates @context = “https://schema.org”

4. Entity Scoring:
– Per-entity assessment of completeness
– Checks for required properties (name, @type, @id)
– Evaluates relationship quality
– Generates improvement recommendations

5. Pagination Handling:
– Follows “next” links in schemamap
– Crawls up to 10 pages per validation (Agency tier)
– Tracks coverage across pages

6. Partner Plugin Detection:
– Identifies WordPress plugins extending schema
– The Events Calendar (EventPosting)
– WP Recipe Maker (Recipe)
– Flags compatibility concerns

REST API Example

Request:

POST /validgraph/v1/schemamap-validate

Request body:

{
  "site_url": "https://example.com"
}

Response:

{
  "site_url": "https://example.com",
  "schemamap_endpoint": "https://example.com/schemamap",
  "validation_date": "2026-03-22",
  "health": {
    "endpoint_accessible": true,
    "http_status": 200,
    "valid_json": true,
    "correct_context": true
  },
  "coverage": {
    "pages_in_schemamap": 52,
    "unique_schema_types": 8,
    "total_entities": 156
  },
  "schema_types": [
    {
      "type": "Organization",
      "count": 1,
      "coverage": "complete",
      "properties_present": [
        "name",
        "url",
        "@id",
        "logo",
        "sameAs"
      ],
      "missing_properties": []
    },
    {
      "type": "Article",
      "count": 42,
      "coverage": "mostly_complete",
      "avg_properties": 12,
      "min_properties": 8,
      "max_properties": 18,
      "common_missing": [
        "articleBody",
        "keywords"
      ]
    },
    {
      "type": "Product",
      "count": 35,
      "coverage": "partial",
      "issues": [
        {
          "severity": "medium",
          "issue": "missing_offers",
          "affected_count": 15,
          "percentage": 0.43
        }
      ]
    }
  ],
  "relationship_analysis": {
    "entities_with_relationships": 89,
    "avg_relationships_per_entity": 1.8,
    "relationship_types": {
      "author": 42,
      "publisher": 40,
      "mainEntity": 8
    }
  },
  "partner_plugins": [
    {
      "name": "The Events Calendar",
      "schema_types": ["EventPosting"],
      "detected_on_pages": 5,
      "compatibility": "compatible"
    }
  ],
  "overall_score": 78,
  "status": "needs_work",
  "issues": [
    {
      "severity": "medium",
      "type": "incomplete_coverage",
      "message": "Product entities missing offer details",
      "affected_count": 15
    },
    {
      "severity": "low",
      "type": "weak_relationships",
      "message": "Some entities could benefit from additional linking",
      "affected_count": 23
    }
  ],
  "recommendations": [
    {
      "priority": "high",
      "action": "Add offer details to Product schema",
      "impact": "Improves e-commerce schema completeness"
    },
    {
      "priority": "medium",
      "action": "Increase relationship density",
      "impact": "Better AI entity comprehension"
    }
  ]
}

Entity-level detail example:

{
  "entity": {
    "@type": "Article",
    "@id": "https://example.com/article/widget-guide",
    "completeness_score": 0.82
  },
  "properties": [
    {
      "name": "name",
      "present": true,
      "quality": "good",
      "value_length": 45
    },
    {
      "name": "description",
      "present": true,
      "quality": "good",
      "value_length": 158
    },
    {
      "name": "datePublished",
      "present": true,
      "quality": "good",
      "format": "ISO8601"
    },
    {
      "name": "articleBody",
      "present": false,
      "quality": "missing",
      "recommendation": "Add for better content understanding"
    }
  ]
}

References

– Yoast SEO Schema Documentation
– Schema.org Type Definitions
– JSON-LD Best Practices
– Google Search Central: Structured Data
– WordPress SEO Plugins