Understand Anything Knowledge Graph Schema: Complete Node and Edge Type Reference

The Understand Anything knowledge graph schema defines 21 distinct node types and 35 edge types across nine functional categories, implemented as Zod enums in packages/core/src/schema.ts.

The Egonex-AI/Understand-Anything repository provides a structured ontology for representing software systems, infrastructure, and domain knowledge as an interconnected graph. At the core of this system lies the schema definition that dictates how entities and relationships are modeled, validated, and normalized throughout the engine.

Node Types in the Understand Anything Knowledge Graph

The node types are enumerated in the GraphNodeSchema.type field within understand-anything-plugin/packages/core/src/schema.ts (lines 69-76). These canonical categories cover source code, infrastructure, documentation, and business concepts:

• file – A source-code file
• function – A function or method
• class – A class or interface
• module – A package or module
• concept – An abstract concept or idea
• config – Configuration value
• document – Documentation file (README, etc.)
• service – Deployable service (container, pod, etc.)
• table – Database table
• endpoint – API endpoint (route, query, mutation)
• pipeline – CI/CD or data-pipeline job
• schema – Data schema (protobuf, JSON schema, etc.)
• resource – Cloud resource (Terraform, infrastructure)
• domain – Business domain
• flow – Business flow
• step – Individual step in a flow
• article – Knowledge article
• entity – Real-world entity (person, organization)
• topic – Subject tag or category
• claim – Assertion or decision
• source – External source reference (paper, link)

These types enable the graph to represent everything from microservice architectures to research citations within a unified structure.

Edge Types and Relationship Taxonomy

The edge types are defined in EdgeTypeSchema (lines 4-14 of schema.ts), providing 35 relationship verbs organized into nine functional categories that describe how nodes interact:

Structural Relationships

These edges define code organization and inheritance:

• imports – Module import dependencies
• exports – Public API surface exposure
• contains – Hierarchical composition
• inherits – Class inheritance
• implements – Interface implementation

Behavioral and Data Flow

These capture runtime interactions and data movement:

• calls – Function invocations
• subscribes – Event subscription patterns
• publishes – Event publication
• middleware – Middleware chain relationships
• reads_from – Data read operations
• writes_to – Data write operations
• transforms – Data transformation pipelines
• validates – Validation relationships

Infrastructure and Deployment Edges

Model DevOps and cloud infrastructure:

• deploys – Deployment relationships
• serves – Service provision
• provisions – Resource provisioning
• triggers – Automation triggers
• migrates – Database or schema migrations

Domain and Knowledge Relationships

Capture business logic and semantic connections:

• contains_flow – Flow composition
• flow_step – Step sequencing within flows
• cross_domain – Inter-domain boundaries
• cites – Academic or source citations
• contradicts – Conflicting claims
• builds_on – Incremental knowledge building
• exemplifies – Example relationships
• categorized_under – Taxonomic classification
• authored_by – Attribution

Additional Edge Categories

The schema also includes depends_on, tested_by, configures for dependency management; related and similar_to for semantic similarity; documents for documentation linkage; and routes for API routing definitions.

Working with the Schema in Code

The schema is implemented using Zod for runtime validation and TypeScript inference. You can construct nodes and edges using the GraphNodeSchema and GraphEdgeSchema parsers:

import { GraphNodeSchema, GraphEdgeSchema } from '@understand-anything/core';

// Create a function node
const fnNode = GraphNodeSchema.parse({
  id: 'node-123',
  type: 'function',
  name: 'calculateSum',
  filePath: 'src/math.ts',
  summary: 'Adds two numbers',
  tags: ['math', 'utility'],
  complexity: 'simple',
});

// Define a behavioral relationship
const callEdge = GraphEdgeSchema.parse({
  source: 'node-123',
  target: 'node-456',
  type: 'calls',
  direction: 'forward',
  weight: 0.8,
});

The engine automatically normalizes aliases to canonical values. When processing raw graph data, use the normalization utilities to ensure type safety:

import { normalizeGraph, validateGraph } from '@understand-anything/core';

const raw = {
  nodes: [{ 
    id: 'n1', 
    type: 'func',  // Alias automatically normalized to 'function'
    name: 'doWork', 
    summary: '', 
    tags: [], 
    complexity: 'easy' 
  }],
  edges: [{ 
    source: 'n1', 
    target: 'n2', 
    type: 'invoke',  // Normalized to 'calls'
    direction: 'to', // Normalized to 'forward'
    weight: 1 
  }],
};

const { data, issues } = validateGraph(normalizeGraph(raw));

Key Implementation Files

The following files define and enforce the Understand Anything knowledge graph schema:

• packages/core/src/schema.ts – Defines the full Zod schema for nodes, edges, layers, tours, and the complete knowledge graph (including the 21 node types and 35 edge types).
• packages/core/src/types.ts – Exports TypeScript types derived from the Zod schemas for consumption by other packages.
• packages/core/src/validateGraph.ts – Contains functions for sanitizing, normalizing, auto-fixing, and validating graph data against the schema constraints.
• packages/core/__tests__/schema.test.ts – Unit tests verifying that node and edge enums behave as expected during parsing and validation.

Summary

• The Understand Anything knowledge graph schema defines 21 node types spanning code, infrastructure, documentation, and business domains.
• 35 edge types are organized into nine categories: Structural, Behavioral, Data Flow, Dependencies, Semantic, Infrastructure, Schema/Data, Domain, and Knowledge.
• Schema validation is implemented in packages/core/src/schema.ts using Zod, with automatic normalization of aliases to canonical values.
• The GraphNodeSchema and GraphEdgeSchema parsers enforce type safety while allowing flexible graph construction.

Frequently Asked Questions

How does the Understand Anything schema handle type aliases?

The schema normalization layer automatically maps common aliases to canonical values. For example, type: 'func' normalizes to 'function', and type: 'invoke' normalizes to 'calls'. This occurs within the normalizeGraph() function in packages/core/src/schema.ts before validation.

Can I extend the schema with custom node or edge types?

The current implementation uses strict Zod enums defined in schema.ts. While the base types cover software systems (files, functions, services) and knowledge domains (concepts, claims, sources), extending the schema would require modifying the GraphNodeSchema.type or EdgeTypeSchema enums and rebuilding the core package.

What is the difference between flow and step node types?

A flow node represents a complete business process or workflow (such as a user registration flow), while a step node represents an individual stage within that process. These are connected via contains_flow and flow_step edges to model hierarchical business logic separately from code-level function calls.

How are edge weights utilized in the knowledge graph?

The weight field (ranging 0.0 to 1.0) in GraphEdgeSchema indicates relationship strength or confidence. For example, a calls edge might have weight 0.9 for direct synchronous invocations versus 0.3 for potential conditional calls, enabling graph algorithms to prioritize high-confidence paths during analysis.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}