# Understand Anything Knowledge Graph Node Schema: Zod Definition and Validation Guide

> Explore the Understand Anything knowledge graph node schema. Learn about the Zod definition and validation for 20 canonical node types plus custom metadata extensions. Ensure data integrity.

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

---

**The knowledge graph node schema in Understand Anything is defined as the `GraphNodeSchema` Zod object in [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts), enforcing strict typing for 20 canonical node types while allowing optional domain and knowledge metadata extensions.**

In the Understand Anything open-source project, the knowledge graph node schema serves as the foundational contract for every entity extracted from codebases, documentation, and domain models. Implemented with Zod in the core package, `GraphNodeSchema` validates required fields such as `id`, `type`, and `complexity` alongside optional source-location and metadata properties. This schema ensures that downstream graph operations—search, visualization, and analysis—operate on uniform, predictable data structures.

## GraphNodeSchema Core Definition

The canonical definition of `GraphNodeSchema` resides at lines 68–86 of [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts). It is a Zod object schema that describes every field a node must contain and validates its values.

`GraphNodeSchema` is composed of the following fields:

- **`id`** (`string`): Unique identifier for the node.
- **`type`** (`enum`): One of 20 canonical node types, including `file`, `function`, `class`, `module`, `concept`, `config`, `document`, `service`, `table`, `endpoint`, `pipeline`, `schema`, `resource`, `domain`, `flow`, `step`, `article`, `entity`, `topic`, `claim`, and `source`.
- **`name`** (`string`): Human-readable name of the node.
- **`filePath?`** (`string`, optional): Path to the source file when the node originates from code.
- **`lineRange?`** (`[number, number]`, optional): Start and end line numbers in the source file.
- **`summary`** (`string`): Short description of the node’s purpose or content.
- **`tags`** (`string[]`): Arbitrary tags for categorisation and search.
- **`complexity`** (`enum`): A coarse-grained complexity rating—`simple`, `moderate`, or `complex`.
- **`languageNotes?`** (`string`, optional): Language-specific notes, such as TypeScript quirks.
- **`domainMeta?`** (`DomainMetaSchema`, optional): Metadata for domain-level entities, including business rules and cross-domain interactions.
- **`knowledgeMeta?`** (`KnowledgeMetaSchema`, optional): Metadata for knowledge-type nodes, including wikilinks, backlinks, category, and content.
- **`.passthrough()`**: Allows additional undocumented keys without validation errors.

## Optional Metadata Schemas

The knowledge graph node schema references two auxiliary Zod objects defined in the same file.

`DomainMetaSchema` (lines 53–58 of [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts)) provides the shape for the optional `domainMeta` field. It captures metadata for domain-level entities such as business rules, cross-domain interactions, and entry points.

`KnowledgeMetaSchema` (lines 61–66 of [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts)) defines the optional `knowledgeMeta` field. It stores wikilinks, backlinks, category, and content for knowledge-type nodes such as articles and documentation.

## Supported Node Types

The `type` field accepts one of 20 canonical values enumerated in [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts). These include:

- **Code entities**: `file`, `function`, `class`, `module`
- **System components**: `service`, `table`, `endpoint`, `pipeline`, `schema`, `resource`, `config`
- **Domain concepts**: `concept`, `domain`, `flow`, `step`, `entity`
- **Knowledge assets**: `document`, `article`, `topic`, `claim`, `source`

This taxonomy allows the knowledge graph to represent both static source code and dynamic business logic within a single schema.

## Validating Knowledge Graph Nodes

You can validate node objects at runtime by importing `GraphNodeSchema` from `@understand-anything/core` and calling `safeParse()`. Below are three practical examples drawn directly from the source architecture.

### Simple File Node

This example demonstrates a minimal valid node representing a source file:

```ts
import { GraphNodeSchema } from "@understand-anything/core";

// Example 1 – a simple file node
const fileNode = {
  id: "file-123",
  type: "file",
  name: "src/index.ts",
  filePath: "src/index.ts",
  summary: "Entry point of the application",
  tags: ["entry", "typescript"],
  complexity: "simple",
};

const fileParse = GraphNodeSchema.safeParse(fileNode);
console.log(fileParse.success); // true

```

### Function Node with Source Location

Function nodes can include the optional `lineRange` and `languageNotes` fields to anchor the entity to a specific code location:

```ts
const fnNode = {
  id: "func-42",
  type: "function",
  name: "calculate",
  filePath: "src/utils/math.ts",
  lineRange: [10, 20],
  summary: "Calculates the result",
  tags: ["math", "utility"],
  complexity: "moderate",
  languageNotes: "Uses async/await",
};

const fnParse = GraphNodeSchema.safeParse(fnNode);
console.log(fnParse.success); // true

```

### Knowledge Article with knowledgeMeta

Nodes representing documentation leverage the `knowledgeMeta` field for linked references and categorical data:

```ts
const articleNode = {
  id: "article-7",
  type: "article",
  name: "Understanding Zod",
  summary: "An overview of Zod validation library",
  tags: ["zod", "validation"],
  complexity: "simple",
  knowledgeMeta: {
    wikilinks: ["https://github.com/colinhacks/zod"],
    category: "documentation",
    content: "Zod provides a TypeScript-first schema validation...",
  },
};

const articleParse = GraphNodeSchema.safeParse(articleNode);
console.log(articleParse.success); // true

```

## Schema Enforcement Across the Core Package

The `GraphNodeSchema` definition is not merely descriptive; it is actively enforced by the Understand Anything pipeline.

[`packages/core/src/validateGraph.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/validateGraph.ts) consumes `GraphNodeSchema` to validate entire knowledge graphs before they are persisted or rendered. Meanwhile, [`packages/core/src/__tests__/schema.test.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/__tests__/schema.test.ts) contains unit tests that verify node validation rules, including edge cases for optional fields and the `.passthrough()` behavior.

Together, these files define, enforce, and test the structure of every node that can appear in the Understand Anything knowledge graph.

## Summary

- The **knowledge graph node schema** is implemented as the `GraphNodeSchema` Zod object in [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts) (lines 68–86).
- **Required fields** include `id`, `type`, `name`, `summary`, `tags`, and `complexity`; optional fields cover file paths, line ranges, language notes, `domainMeta`, and `knowledgeMeta`.
- **Twenty canonical node types** are supported, ranging from code entities like `function` and `class` to knowledge assets like `article` and `claim`.
- The schema uses **`.passthrough()`** to permit extra keys without validation failures.
- **Auxiliary schemas** `DomainMetaSchema` (lines 53–58) and `KnowledgeMetaSchema` (lines 61–66) provide structured metadata extensions.
- Runtime validation is handled by `GraphNodeSchema.safeParse()` and enforced graph-wide via [`validateGraph.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/validateGraph.ts).

## Frequently Asked Questions

### What file defines the knowledge graph node schema in Understand Anything?

The knowledge graph node schema is defined in [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts). According to the Understand Anything source code, this file contains the `GraphNodeSchema` Zod object at lines 68–86, along with the supporting `DomainMetaSchema` and `KnowledgeMetaSchema` definitions.

### What are the required fields for every knowledge graph node?

Every node must provide `id` (string), `type` (enum), `name` (string), `summary` (string), `tags` (string array), and `complexity` (one of `simple`, `moderate`, or `complex`). These fields are enforced by `GraphNodeSchema` during `safeParse()` validation.

### How does the schema handle optional metadata like domain or knowledge properties?

The schema includes optional `domainMeta` and `knowledgeMeta` fields. `domainMeta` conforms to `DomainMetaSchema` for business rules and cross-domain interactions, while `knowledgeMeta` conforms to `KnowledgeMetaSchema` for wikilinks, backlinks, and categorical content. Both auxiliary schemas are defined in [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts).

### What node types are supported by GraphNodeSchema?

`GraphNodeSchema` supports 20 canonical types enumerated in [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts). These include `file`, `function`, `class`, `module`, `concept`, `config`, `document`, `service`, `table`, `endpoint`, `pipeline`, `schema`, `resource`, `domain`, `flow`, `step`, `article`, `entity`, `topic`, `claim`, and `source`.