JSON Schema for the Knowledge Graph in Understand-Anything: Node and Edge Types

The knowledge graph in Understand-Anything relies on a strict Zod-based JSON schema that defines 21 node types and 35 edge types, centralized in schema.ts to enforce type safety across project metadata, code entities, and their relationships.

The Understand-Anything repository generates structured knowledge graphs that map codebase architecture, domain concepts, and documentation into a machine-readable format. At the heart of this system lies a comprehensive JSON schema for the knowledge graph that ensures every emitted graph conforms to a versioned contract. Using Zod for runtime validation, the schema is defined in understand-anything-plugin/packages/core/src/schema.ts and governs everything from file-level imports to abstract knowledge relationships.

Core Node Types in the JSON Schema

Available Node Classifications

The GraphNodeSchema captures atomic entities ranging from source code artifacts to semantic knowledge nodes. According to the Zod definition in schema.ts, the type field accepts 21 distinct string literals:

• Code artifacts: file, function, class, module
• Configuration & docs: config, document
• System components: service, table, endpoint, pipeline, schema, resource
• Process modeling: domain, flow, step
• Knowledge representation: concept, article, entity, topic, claim, source

Node Schema Structure

Each node must satisfy the GraphNodeSchema object, which requires an id, type, name, summary, tags array, and complexity rating (simple, moderate, or complex). Optional fields include filePath, lineRange as a tuple of [start, end], languageNotes, and extension schemas for domain or knowledge metadata.

export const GraphNodeSchema = z.object({
  id: z.string(),
  type: z.enum([
    "file", "function", "class", "module", "concept",
    "config", "document", "service", "table", "endpoint",
    "pipeline", "schema", "resource",
    "domain", "flow", "step",
    "article", "entity", "topic", "claim", "source",
  ]),
  name: z.string(),
  filePath: z.string().optional(),
  lineRange: z.tuple([z.number(), z.number()]).optional(),
  summary: z.string(),
  tags: z.array(z.string()),
  complexity: z.enum(["simple", "moderate", "complex"]),
  languageNotes: z.string().optional(),
  domainMeta: DomainMetaSchema.optional(),
  knowledgeMeta: KnowledgeMetaSchema.optional(),
}).passthrough();

The .passthrough() method allows additional custom properties while strictly enforcing the core fields required by the knowledge graph JSON schema.

Edge Types and Relationships

The 35 Canonical Edge Types

Relationships are strictly typed through the EdgeTypeSchema enum, which defines 35 directed edge identifiers organized into nine functional categories:

• Structural: imports, exports, contains, inherits, implements
• Behavioral: calls, subscribes, publishes, middleware
• Data flow: reads_from, writes_to, transforms, validates
• Dependencies: depends_on, tested_by, configures
• Semantic: related, similar_to
• Infrastructure: deploys, serves, provisions, triggers
• Schema/Data: migrates, documents, routes, defines_schema
• Domain: contains_flow, flow_step, cross_domain
• Knowledge: cites, contradicts, builds_on, exemplifies, categorized_under, authored_by

Edge Schema Structure

The GraphEdgeSchema defines directed relationships connecting two nodes by their id values. Every edge specifies a source, target, type from the canonical enum above, direction (forward, backward, or bidirectional), and a weight between 0 and 1 representing confidence or strength. An optional description field captures human-readable context.

export const GraphEdgeSchema = z.object({
  source: z.string(),
  target: z.string(),
  type: EdgeTypeSchema,
  direction: z.enum(["forward", "backward", "bidirectional"]),
  description: z.string().optional(),
  weight: z.number().min(0).max(1),
});

Top-Level Schema Structure

Project Metadata and Graph Container

The root KnowledgeGraphSchema wraps all entities into a single document. It includes a version string, optional kind discriminator (codebase or knowledge), and a project field adhering to ProjectMetaSchema containing the repository name, languages, frameworks, description, analyzedAt timestamp, and gitCommitHash.

export const KnowledgeGraphSchema = z.object({
  version: z.string(),
  kind: z.enum(["codebase", "knowledge"]).optional(),
  project: ProjectMetaSchema,
  nodes: z.array(GraphNodeSchema),
  edges: z.array(GraphEdgeSchema),
  layers: z.array(LayerSchema),
  tour: z.array(TourStepSchema),
});

Layers and Tour Steps

The schema supports architectural grouping via LayerSchema, which maps a name and description to an array of nodeIds. For interactive exploration, TourStepSchema defines guided walkthroughs with order, title, description, optional languageLesson, and the nodeIds included in each step.

export const LayerSchema = z.object({
  id: z.string(),
  name: z.string(),
  description: z.string(),
  nodeIds: z.array(z.string()),
});

export const TourStepSchema = z.object({
  order: z.number(),
  title: z.string(),
  description: z.string(),
  nodeIds: z.array(z.string()),
  languageLesson: z.string().optional(),
});

Validation and Implementation

Schema Validation with Zod

The validateGraph function—located at line 499 of schema.ts—serves as the gatekeeper for data integrity. It sanitizes raw payloads, auto-fixes common structural issues, and validates the entire graph against the Zod schemas before passing data to the dashboard UI. This ensures that node and edge types strictly conform to the enums defined in the JSON schema for the knowledge graph.

Key Source Files

• understand-anything-plugin/packages/core/src/schema.ts: Central Zod definitions for GraphNodeSchema, GraphEdgeSchema, and validation logic.
• understand-anything-plugin/packages/core/src/types.ts: Runtime TypeScript interfaces that mirror the Zod schemas for use throughout the core package.
• understand-anything-plugin/packages/core/src/analyzer/graph-builder.ts: Logic that instantiates nodes and edges during analysis, ensuring output conforms to the schema before serialization.

Practical JSON Example

Below is a conformant knowledge graph payload illustrating required fields, optional metadata, and typed relationships:

{
  "version": "1.0.0",
  "kind": "codebase",
  "project": {
    "name": "my-app",
    "languages": ["typescript", "python"],
    "frameworks": ["react", "fastapi"],
    "description": "Sample monorepo",
    "analyzedAt": "2026-06-02T12:00:00Z",
    "gitCommitHash": "abc123def"
  },
  "nodes": [
    {
      "id": "node-1",
      "type": "file",
      "name": "src/index.ts",
      "filePath": "src/index.ts",
      "summary": "Entry point",
      "tags": ["entry"],
      "complexity": "simple"
    },
    {
      "id": "node-2",
      "type": "function",
      "name": "handleRequest",
      "filePath": "src/api.ts",
      "lineRange": [12, 34],
      "summary": "Handles HTTP request",
      "tags": ["api", "handler"],
      "complexity": "moderate"
    }
  ],
  "edges": [
    {
      "source": "node-2",
      "target": "node-1",
      "type": "contains",
      "direction": "forward",
      "weight": 0.8
    },
    {
      "source": "node-2",
      "target": "node-3",
      "type": "calls",
      "direction": "forward",
      "weight": 0.6,
      "description": "Invokes utility function"
    }
  ],
  "layers": [
    {
      "id": "layer-frontend",
      "name": "Frontend",
      "description": "UI code",
      "nodeIds": ["node-1"]
    }
  ],
  "tour": [
    {
      "order": 1,
      "title": "Entry Point Tour",
      "description": "Explore the main entry file",
      "nodeIds": ["node-1"]
    }
  ]
}

Summary

• The JSON schema for the knowledge graph defines 21 node types and 35 edge types using Zod in understand-anything-plugin/packages/core/src/schema.ts.
• Node schema requires core fields (id, type, name, summary) and supports optional metadata (lineRange, complexity, domainMeta).
• Edge schema enforces typed relationships via the EdgeTypeSchema enum, with directional flow (forward, backward, bidirectional) and weighted confidence scores.
• The top-level KnowledgeGraphSchema container includes ProjectMetaSchema, arrays of nodes and edges, plus LayerSchema and TourStepSchema for organization and interaction.
• The validateGraph function ensures strict schema conformance before consumption by downstream UI components.

Frequently Asked Questions

What file contains the knowledge graph JSON schema definition?

The schema is defined in understand-anything-plugin/packages/core/src/schema.ts. This file exports the Zod schemas for nodes, edges, project metadata, and the top-level graph container, alongside the validateGraph validation utility.

How many edge types are supported in the Understand-Anything schema?

The schema supports 35 canonical edge types organized into categories including structural (e.g., imports, inherits), behavioral (e.g., calls, publishes), data-flow (e.g., reads_from, transforms), and knowledge relationships (e.g., cites, contradicts).

Can I extend nodes with custom properties beyond the standard fields?

Yes, the GraphNodeSchema uses Zod's .passthrough() method, which allows additional properties beyond the standard id, type, name, and summary fields while still enforcing that all required core fields are present and correctly typed.

How does the system ensure JSON outputs conform to the schema?

The validateGraph function (located around line 499 in schema.ts) sanitizes and validates raw graph data against the Zod schemas. It auto-fixes common structural issues and throws validation errors for type mismatches, ensuring only conformant graphs reach the dashboard UI.

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