Overview

Analyzes your site’s entity graph specifically from an AI consumption perspective. Evaluates how well entities interconnect, whether the knowledge graph is coherent, and how effectively AI agents can traverse and understand your structured data.

How It Works

1. Aggregates all validated schemas across the site
2. Builds an entity relationship graph
3. Analyzes from an AI perspective:
– Graph connectivity (orphan entities, dead ends)
– Entity disambiguation quality
– Cross-page entity consistency
– Relationship completeness
4. Provides AI-specific improvement recommendations

Tier Availability

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

Related Features

– AI Discoverability Score: Quantitative measure of AI readiness
– Entity Relationship Graph: Visual D3.js graph representation
– Entity Consistency Checker: Cross-page entity validation

Mini-Tutorial

Analyzing Your Knowledge Graph for AI Consumption

1. Request the AI graph analysis:

   GET /validgraph/v1/ai-entity-graph?site_id=abc123
   

2. Review the graph structure assessment:
– Is the graph a single connected component or fragmented?
– Which entities are hubs (Organization, WebSite)?
– What’s the average relationship density?
– Are relationships bidirectional (high-quality)?

3. Identify graph issues:
– Disconnected islands: Article nodes not linked to Organization
– Missing hubs: No central WebSite entity
– Low density: Entities exist but few relationships
– Unidirectional: author references exist but not reciprocal

4. Improve graph coherence:
– Add WebSite entity if missing
– Create author/publisher relationships from all content
– Ensure Organization appears on multiple pages
– Add breadcrumb links to establish hierarchy

5. Example fix: Add missing relationships:

   {
     "@context": "https://schema.org",
     "@type": "Article",
     "author": { "@id": "https://example.com/org" },
     "publisher": { "@id": "https://example.com/org" },
     "isPartOf": { "@id": "https://example.com/website" }
   }
   

Technical Details

Graph Analysis Algorithm

1. Graph Construction:
– BFS traversal from each entity’s @id, url, or normalized name
– Edges built from reference properties: author, publisher, brand, offers, location, creator, mainEntity, parentOrganization
– Bidirectional edges tracked separately

2. Scoring Components:
– Single Component Bonus (+30pts): Graph is fully connected (rare)
– Hub Entity Detection (+20pts): Organization/WebSite with 3+ connections acts as knowledge center
– Relationship Density (+20pts): Average degree ≥2.0 indicates robust linking
– Bidirectional Edges (+15pts): >50% of edges are reciprocal (quality indicator)
– Relationship Patterns (+15pts): No missing expected relationships for entity types

3. Island Detection:
– Identifies disconnected components (orphan clusters)
– Flags entities with zero in-degree or out-degree
– Suggests bridge relationships to connect islands

4. Hub Entity Recognition:
– Organization or WebSite entities with 3+ incoming/outgoing relationships
– Indicates effective knowledge graph anchoring
– Multiple hubs = better distributed knowledge

REST API Example

Request:

GET /validgraph/v1/ai-entity-graph

Response:

{
  "graph_score": 82,
  "graph_status": "coherent",
  "structure": {
    "total_entities": 47,
    "total_relationships": 54,
    "connected_components": 1,
    "avg_degree": 2.3,
    "density": 0.049
  },
  "scoring_breakdown": {
    "single_component": {
      "score": 30,
      "achieved": true,
      "description": "All entities form a single connected graph"
    },
    "hub_entities": {
      "score": 20,
      "achieved": true,
      "hubs": [
        {
          "entity": "Organization#acme-corp",
          "type": "Organization",
          "connections": 8,
          "role": "primary_hub"
        }
      ]
    },
    "relationship_density": {
      "score": 20,
      "achieved": true,
      "avg_degree": 2.3,
      "threshold": 2.0
    },
    "bidirectional_edges": {
      "score": 12,
      "max": 15,
      "percentage": 0.59,
      "threshold": 0.5
    },
    "relationship_patterns": {
      "score": 0,
      "max": 15,
      "missing_patterns": [
        {
          "from_type": "Article",
          "property": "mainEntity",
          "coverage": 0.4
        }
      ]
    }
  },
  "islands": [],
  "recommendations": [
    {
      "priority": "medium",
      "type": "missing_relationship",
      "from_entity": "Product#widget-x",
      "property": "brand",
      "to_entity": "Organization#acme-corp",
      "impact": "Improves AI understanding of product ownership"
    }
  ]
}

References

– Graph Theory and Knowledge Representation
– Semantic Web Best Practices
– Entity Linking and Disambiguation
– Schema.org Reference Properties