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

The knowledge graph node schema in Understand Anything is defined as the GraphNodeSchema Zod object in 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. 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) 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) 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. 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:

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:

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:

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 consumes GraphNodeSchema to validate entire knowledge graphs before they are persisted or rendered. Meanwhile, 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 (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.

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

What node types are supported by GraphNodeSchema?

GraphNodeSchema supports 20 canonical types enumerated in 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.

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