Model Diagrams

Zog can render model schemas and validated references as ASCII or Mermaid diagrams. This is useful for documenting MongoDB collections without turning Zog into an ORM or requiring a CLI to understand your TypeScript project.

If your models declare references, diagrams include those references as annotations or relationship edges.

Use the pure renderers when you want to print or compose the output yourself:

import { renderDbDiagram } from "@mp-lb/zog";
import { postModel, userModel } from "./models";

const models = [userModel, postModel] as const;

console.log(renderDbDiagram(models));
console.log(renderDbDiagram(models, { format: "mermaid" }));

The default ASCII view combines schema shape and references:

posts collection (posts)
├── _id <- id: string [primary]
├── authorId: string -> users.id
└── comments: object[]
    ├── authorId: string -> users.id
    └── body: string

Mermaid output uses a flowchart so embedded documents and cross-model references can appear in one diagram.

renderDbDiagram(models, { format: "mermaid" });

Use view when you only want one part of the model map:

renderDbDiagram(models, { view: "schema" });
renderDbDiagram(models, { view: "relationships" });
renderDbDiagram(models, { format: "mermaid", view: "relationships" });

Write Diagram Files

Most applications should call the writer from an app-owned script. This avoids requiring a Zog CLI to understand every TypeScript loader, bundler, path alias, and environment setup.

// scripts/write-model-diagram.ts
import { writeDbDiagramFile } from "@mp-lb/zog";
import { models } from "../src/models";

await writeDbDiagramFile("docs/data-models.md", models, {
  format: "mermaid",
  title: "Data Models",
});

Run it with the TypeScript runner your project already uses:

tsx scripts/write-model-diagram.ts

Markdown files (.md and .mdx) are written with fenced code blocks. Other file extensions are written as raw diagram text.

await writeDbDiagramFile("docs/data-models.md", models);
await writeDbDiagramFile("docs/data-models.txt", models);
await writeDbDiagramFile("docs/data-models.mmd", models, {
  format: "mermaid",
});

For one model, use renderModelDiagram or writeModelDiagramFile.

Diagram rendering requires Zod 4 schemas because it introspects schema internals for this feature.