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

> Explore the JSON schema for the Understand-Anything knowledge graph, detailing 21 node and 35 edge types. Ensure type safety and understand entity relationships with this Zod-based schema.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: api-reference
- Published: 2026-06-02

---

**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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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.

```typescript
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.

```typescript
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`.

```typescript
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.

```typescript
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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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:

```json
{
  "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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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.