Overview

NLWeb is an emerging protocol for AI agent discovery of web content. This checker validates whether your structured data meets NLWeb requirements at the URL level and site-wide, identifying gaps and providing remediation steps.

How It Works

1. Per-URL check: Validates a single URL against NLWeb requirements
2. Site-wide audit: Scans multiple URLs to assess overall NLWeb readiness
3. Checks include:
– Required schema types present
– Entity relationship graph completeness
– Endpoint discoverability
– Metadata quality
4. Results include pass/fail per criterion and remediation guidance

Tier Availability

| Tier | Per-URL | Site-Wide Audit |
|——|———|—————–|
| Free | No | No |
| Pro | No | No |
| Agency | Yes | Yes |
| Enterprise | Yes | Yes |

Related Features

– AI Discoverability Score: Quantitative score based on readiness
– NLWeb Certificate: Exportable proof of compliance (Enterprise)
– Yoast Schemamap Validator: Complementary schema graph validation

Mini-Tutorial

Checking NLWeb Readiness

1. Check a single URL for NLWeb compliance:

   POST /validgraph/v1/nlweb-readiness

   {
     "url": "https://example.com/article"
   }
   

2. Review the per-URL results:
– ID Coverage: Are entities properly identified?
– sameAs links: Can entities be disambiguated?
– Description Quality: Are descriptions >50 chars?
– Entity Relationships: Do typed references exist?
– Context Correctness: Is @context https://schema.org?
– Graph Structure: Are intra-graph @id links present?

3. Run a site-wide audit:

   GET /validgraph/v1/nlweb-audit?site_id=abc123
   

4. Review aggregate results across all validated pages:
– What percentage of pages pass each criterion?
– Which pages are ready (≥80)?
– Which need work (50-79)?
– Which aren’t ready (<50)?

5. Fix high-impact issues:
– Add missing descriptions to all entities
– Ensure @context is https://schema.org
– Create sameAs links to Wikidata/other sources

6. Re-run the audit to verify improvement.

Technical Details

NLWeb Readiness Rubric (0-100 per page)

1. ID Coverage (25%):
– Entities have proper @id values = +20pts
– All major entities identified = +5pts

2. sameAs (15%):
– sameAs links to external authorities present = +15pts
– Missing sameAs = 0pts

3. Description Quality (20%):
– Descriptions >50 characters = +20pts
– Descriptions ≤50 chars or missing = 0pts

4. Entity Relationships (20%):
– Multiple typed reference properties present = +20pts
– >1 typed reference property = +10pts
– 0-1 references = 0pts

5. Context Correctness (10%):
– @context = “https://schema.org” = +10pts
– Incorrect or missing context = 0pts

6. Graph Structure (10%):
– Intra-graph @id links (entities reference each other via @id) = +10pts
– Missing @id-based linking = 0pts

Status mapping:
– Score ≥80: ready
– Score 50-79: needs_work
– Score <50: not_ready

REST API Examples

Per-URL check:

POST /validgraph/v1/nlweb-readiness

Request body:

{
  "url": "https://example.com/article/ai-trends"
}

Response:

{
  "url": "https://example.com/article/ai-trends",
  "score": 72,
  "status": "needs_work",
  "criteria": [
    {
      "name": "ID Coverage",
      "weight": 0.25,
      "score": 20,
      "max": 25,
      "status": "pass",
      "details": {
        "entities_with_id": 3,
        "total_entities": 4,
        "percentage": 0.75
      }
    },
    {
      "name": "sameAs",
      "weight": 0.15,
      "score": 0,
      "max": 15,
      "status": "fail",
      "details": {
        "sameAs_links": 0,
        "required": "at_least_one"
      }
    },
    {
      "name": "Description Quality",
      "weight": 0.20,
      "score": 20,
      "max": 20,
      "status": "pass",
      "details": {
        "min_description_length": 50,
        "avg_length": 142
      }
    },
    {
      "name": "Entity Relationships",
      "weight": 0.20,
      "score": 10,
      "max": 20,
      "status": "partial",
      "details": {
        "relationship_properties": ["author"],
        "count": 1
      }
    },
    {
      "name": "Context Correctness",
      "weight": 0.10,
      "score": 10,
      "max": 10,
      "status": "pass",
      "details": {
        "context": "https://schema.org"
      }
    },
    {
      "name": "Graph Structure",
      "weight": 0.10,
      "score": 12,
      "max": 10,
      "status": "pass",
      "details": {
        "intra_graph_links": 2
      }
    }
  ],
  "recommendations": [
    {
      "priority": "high",
      "criterion": "sameAs",
      "fix": "Add sameAs links to Wikidata or other authority sources for entity disambiguation"
    },
    {
      "priority": "medium",
      "criterion": "Entity Relationships",
      "fix": "Add publisher reference to Organization"
    }
  ]
}

Site-wide audit:

GET /validgraph/v1/nlweb-audit

Response:

{
  "site_id": "abc123",
  "audit_date": "2026-03-22",
  "pages_analyzed": 42,
  "summary": {
    "ready": 28,
    "needs_work": 10,
    "not_ready": 4
  },
  "status_percentage": {
    "ready": 0.67,
    "needs_work": 0.24,
    "not_ready": 0.09
  },
  "criteria_performance": {
    "ID Coverage": 0.89,
    "sameAs": 0.52,
    "Description Quality": 0.78,
    "Entity Relationships": 0.71,
    "Context Correctness": 0.95,
    "Graph Structure": 0.61
  },
  "common_issues": [
    {
      "criterion": "sameAs",
      "affected_pages": 20,
      "percentage": 0.48
    }
  ]
}

References

– NLWeb Protocol Specification
– JSON-LD Best Practices
– Schema.org Core Vocabulary
– Wikidata Entity Links