# Egonex Knowledge Graph JSON Structure: Node and Edge Schemas Explained

> Discover the Egonex knowledge graph JSON structure. Understand node and edge schemas, UUID identifiers, and semantic relationships like contains and calls.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: api-reference
- Published: 2026-06-21

---

**The Egonex knowledge graph persists as a JSON file containing three top-level keys—`nodes`, `edges`, and `metadata`—where nodes represent repository entities with UUID-v4 identifiers and edges define semantic relationships like "contains" and "calls" using source/target references.**

The **Understand-Anything** toolchain from Egonex-AI constructs this graph to model source code repositories. According to the Egonex knowledge graph JSON structure defined in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts), the format uses strict Zod validation to ensure interoperability between the CLI, web dashboard, and third-party integrations.

## Top-Level JSON Structure

The knowledge graph serializes to a single file at [`./.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/./.understand-anything/knowledge-graph.json) by default. The root object contains three mandatory sections that work together to represent the complete codebase topology.

### Nodes Array

The `nodes` field is an array of **Node** objects, each representing a logical entity such as a file, class, function, or variable. Every node adheres to the schema defined in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts) and includes the following fields:

- **`id`** – A globally unique UUID-v4 string identifying the node.
- **`type`** – The entity classification: `"file"`, `"module"`, `"class"`, `"function"`, `"variable"`, or additional plugin-defined types.
- **`name`** – The human-readable identifier (e.g., `UserService`).
- **`path`** – A relative path from the repository root, populated for file-type nodes.
- **`range`** – An object with `start` and `end` Position objects marking the source-code location using line and column coordinates.
- **`language`** – The detected programming language (e.g., `js`, `ts`, `py`).
- **`attributes`** – An open-ended `Record<string, any>` map for arbitrary metadata like JSDoc comments or test status flags.
- **`children`** – An array of node IDs representing direct descendants in the hierarchy.
- **`parents`** – An array of node IDs enabling reverse navigation to ancestor nodes.

### Edges Array

The `edges` field defines relationships between nodes through an array of **Edge** objects. Each edge specifies directional semantics connecting the source repository entities:

- **`source`** – The UUID of the originating node.
- **`target`** – The UUID of the destination node.
- **`type`** – The relationship classification: `"contains"`, `"calls"`, `"imports"`, `"extends"`, or `"references"`.
- **`label`** – An optional human-readable string clarifying the relationship (e.g., `"uses"`).
- **`metadata`** – An optional `Record<string, any>` for edge-specific information.

### Metadata Object

The `metadata` section tracks provenance and configuration used during graph generation:

- **`generatedAt`** – ISO-8601 timestamp recording when the graph was created.
- **`toolVersion`** – The Understand-Anything version string that produced the file.
- **`repoRoot`** – The absolute path of the analyzed repository.
- **`settings`** – A key-value map of options affecting generation, such as ignore patterns and active plugin lists.

## Schema Validation and Implementation

The [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts) file implements the JSON shape using **Zod** for runtime validation. This guarantees that every [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) file conforms to the expected structure before consumption by the dashboard or CLI tools.

The validation step occurs in the graph construction pipeline after [`packages/core/src/analyzer/graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/analyzer/graph-builder.ts) consolidates raw nodes. By enforcing strict typing through Zod, the system detects breaking changes early and prevents malformed graphs from propagating to downstream consumers.

TypeScript interfaces mirroring the Zod schema are exported from [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts), providing compile-time safety for developers building plugins or custom scripts against the graph.

## Graph Construction Pipeline

The Egonex knowledge graph JSON structure emerges through a four-stage pipeline:

1. **File Discovery** – The tree-sitter plugin traverses the filesystem and parses source files.
2. **Extraction** – Language-specific extractors in `packages/core/src/plugins/extractors/*.ts` emit raw node data with preliminary attributes.
3. **Normalization** – The [`graph-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-builder.ts) module resolves hierarchical relationships, populates `children` and `parents` arrays, and generates edges based on symbol references.
4. **Validation** – The final object passes through the Zod schema in [`schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/schema.ts) before serialization to disk.

## Working with the Knowledge Graph

### Loading and Validating the Graph

You can load the JSON in a Node.js script while enforcing schema compliance using the exported Zod validator:

```typescript
import { readFileSync } from "node:fs";
import { z } from "zod";
import { knowledgeGraphSchema } from "@understand-anything/core/schema";

const raw = readFileSync("./.understand-anything/knowledge-graph.json", "utf-8");
const graph = knowledgeGraphSchema.parse(JSON.parse(raw));

console.log(`Loaded ${graph.nodes.length} nodes and ${graph.edges.length} edges`);

```

### Traversing from Files to Exports

Navigate hierarchical relationships using the `children` array to find exported functions or classes within a specific file:

```typescript
function getExports(filePath: string) {
  const fileNode = graph.nodes.find(n => n.type === "file" && n.path === filePath);
  if (!fileNode) return [];

  return fileNode.children
    .map(id => graph.nodes.find(n => n.id === id))
    .filter(n => n && (n.type === "function" || n.type === "class"));
}

```

### Extending Nodes with Custom Attributes

Plugins can attach domain-specific data without breaking the core schema by writing to the `attributes` map:

```typescript
// Inside a custom extractor
node.attributes = {
  ...node.attributes,
  myPluginScore: computeScore(node)
};

```

The open-ended `attributes` field accepts new keys automatically during Zod validation, enabling safe extensibility.

## Summary

- The **Egonex knowledge graph JSON structure** comprises three top-level sections: `nodes`, `edges`, and `metadata`.
- **Nodes** use UUID-v4 identifiers and include hierarchical `children`/`parents` arrays, source `range` data, and extensible `attributes`.
- **Edges** define directional relationships via `source` and `target` IDs, with standardized `type` values like `"calls"` and `"imports"`.
- The schema is enforced by **Zod** in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts), ensuring version safety and interoperability.
- Plugins can safely extend the graph through the `attributes` and `metadata` maps without modifying core type definitions.

## Frequently Asked Questions

### What file types and entities does the Egonex knowledge graph represent?

The graph supports nodes of type `"file"`, `"module"`, `"class"`, `"function"`, `"variable"`, and additional custom types defined by plugins. Each node captures language-specific metadata including the detected programming language and precise source-code location through the `range` field.

### How does the schema accommodate custom plugin data?

The `attributes` field on nodes and the `metadata` field on edges are open-ended `Record<string, any>` maps. According to the implementation in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts), these fields accept arbitrary keys during Zod validation, allowing plugins to attach custom scores, flags, or documentation without breaking the core JSON structure.

### What validation ensures the knowledge graph JSON conforms to the schema?

The `knowledgeGraphSchema` Zod object in [`packages/core/src/schema.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/schema.ts) runtime-validates the entire graph object before serialization. This validation checks that all nodes contain required UUIDs, that edges reference valid node IDs, and that metadata fields match expected types, preventing malformed graphs from reaching the output file.

### Where is the knowledge graph JSON file stored by default?

By default, Understand-Anything writes the structured output to [`./.understand-anything/knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/./.understand-anything/knowledge-graph.json) relative to the analyzed repository root. The `repoRoot` field in the `metadata` section records the absolute path of the source repository for verification purposes.