# colinhacks/zod architecture

> Architecture diagram of the GitHub repository colinhacks/zod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/colinhacks/zod
- Repository: https://github.com/colinhacks/zod

## Overview

Zod is a TypeScript-first schema-validation library. The principal workflow is that a developer defines a schema, supplies input to its parse API, and receives validated, typed output or structured issues; async parsing is also supported. The v4 core provides schema construction, checks and parsing, with separate classic and mini APIs, JSON Schema conversion, and optional compilation. The repository also retains a v3 implementation. Edges for documented user-facing behavior cite the README; internal links rely on the supplied source excerpts or SOURCE INDEX references, so unsampled internals are not expanded into speculative call chains.

Main entry points: [`packages/zod/src/v4/core/schemas.ts`](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/schemas.ts) (Schema Types), [`packages/zod/src/v4/core/checks.ts`](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/checks.ts) (Validation Checks), [`packages/zod/src/v4/core/api.ts`](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/api.ts) (Schema Builders), [`packages/zod/src/v4/core/compile.ts`](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/compile.ts) (AOT Compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Schema APIs"]
  node_v4classic["Classic API<br/>[index.ts]"]
  node_v4mini["Mini API<br/>[schemas.ts]"]
  node_coreapi["Schema Builders<br/>[api.ts]"]
end

subgraph group_engine["Validation Core"]
  node_schemas["Schema Types<br/>[schemas.ts]"]
  node_checks["Validation Checks<br/>[checks.ts]"]
  node_parse["Parser<br/>[parse.ts]"]
  node_errors["Issue Handling<br/>[errors.ts]"]
  node_regexes["Format Patterns<br/>[regexes.ts]"]
  node_util["Core Utilities<br/>[util.ts]"]
  node_memoizer["Schema Memoizer<br/>[memoizer.ts]"]
  node_registries["Schema Registry<br/>[registries.ts]"]
end

subgraph group_extensions["Output Extensions"]
  node_standard["Standard Schema<br/>[standard-schema.ts]"]
  node_jsonschema["JSON Schema<br/>[to-json-schema.ts]"]
  node_jsonprocess["JSON Schema Processing"]
  node_compile["AOT Compiler<br/>[compile.ts]"]
  node_compileentry["Compile Entry<br/>[compile.ts]"]
end

subgraph group_compat["Compatibility"]
  node_v3types["V3 Schemas<br/>[types.ts]"]
  node_v3errors["V3 Errors<br/>[ZodError.ts]"]
end

node_developer(("Developer"))

node_developer -->|"defines schema"| node_v4classic
node_developer -->|"submits input"| node_v4classic
node_v4classic -.->|"builds schemas"| node_coreapi
node_v4mini -->|"builds schemas"| node_schemas
node_coreapi -->|"constructs"| node_schemas
node_coreapi -->|"constructs checks"| node_checks
node_schemas -->|"invokes parser"| node_parse
node_checks -->|"checks schema values"| node_schemas
node_checks -->|"uses patterns"| node_regexes
node_checks -->|"uses helpers"| node_util
node_schemas -->|"uses issue types"| node_errors
node_schemas -->|"uses helpers"| node_util
node_compileentry -->|"exposes compilation"| node_compile
node_compile -->|"detects recursion"| node_memoizer
node_compile -->|"compiles schemas"| node_schemas
node_jsonschema -->|"converts schemas"| node_schemas
node_jsonprocess -->|"processes schemas"| node_schemas
node_registries -->|"registers metadata"| node_schemas
node_developer -.->|"uses legacy API"| node_v3types
node_v3types -.->|"reports validation issues"| node_v3errors

click node_v4classic "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/classic/index.ts"
click node_v4mini "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/mini/schemas.ts"
click node_coreapi "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/api.ts"
click node_schemas "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/schemas.ts"
click node_checks "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/checks.ts"
click node_parse "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/parse.ts"
click node_errors "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/errors.ts"
click node_regexes "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/regexes.ts"
click node_util "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/util.ts"
click node_memoizer "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/memoizer.ts"
click node_registries "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/registries.ts"
click node_standard "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/standard-schema.ts"
click node_jsonschema "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/to-json-schema.ts"
click node_jsonprocess "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/json-schema-processors.ts"
click node_compile "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/compile.ts"
click node_compileentry "https://github.com/colinhacks/zod/blob/main/packages/zod/src/compile.ts"
click node_v3types "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v3/types.ts"
click node_v3errors "https://github.com/colinhacks/zod/blob/main/packages/zod/src/v3/ZodError.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_v4classic,node_v4mini,node_coreapi toneBlue
class node_schemas,node_checks,node_parse,node_errors,node_regexes,node_util,node_memoizer,node_registries toneAmber
class node_standard,node_jsonschema,node_jsonprocess,node_compile,node_compileentry toneMint
class node_v3types,node_v3errors toneRose
class node_developer toneIndigo
```

## Components

### Schema APIs

- [Classic API](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/classic/index.ts): `packages/zod/src/v4/classic/index.ts`
- [Mini API](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/mini/schemas.ts): `packages/zod/src/v4/mini/schemas.ts`
- [Schema Builders](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/api.ts): `packages/zod/src/v4/core/api.ts`

### Validation Core

- [Schema Types](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/schemas.ts): `packages/zod/src/v4/core/schemas.ts`
- [Validation Checks](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/checks.ts): `packages/zod/src/v4/core/checks.ts`
- [Parser](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/parse.ts): `packages/zod/src/v4/core/parse.ts`
- [Issue Handling](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/errors.ts): `packages/zod/src/v4/core/errors.ts`
- [Format Patterns](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/regexes.ts): `packages/zod/src/v4/core/regexes.ts`
- [Core Utilities](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/util.ts): `packages/zod/src/v4/core/util.ts`
- [Schema Memoizer](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/memoizer.ts): `packages/zod/src/v4/core/memoizer.ts`
- [Schema Registry](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/registries.ts): `packages/zod/src/v4/core/registries.ts`

### Output Extensions

- [Standard Schema](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/standard-schema.ts): `packages/zod/src/v4/core/standard-schema.ts`
- [JSON Schema](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/to-json-schema.ts): `packages/zod/src/v4/core/to-json-schema.ts`
- [JSON Schema Processing](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/json-schema-processors.ts): `packages/zod/src/v4/core/json-schema-processors.ts`
- [AOT Compiler](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v4/core/compile.ts): `packages/zod/src/v4/core/compile.ts`
- [Compile Entry](https://github.com/colinhacks/zod/blob/main/packages/zod/src/compile.ts): `packages/zod/src/compile.ts`

### Compatibility

- [V3 Schemas](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v3/types.ts): `packages/zod/src/v3/types.ts`
- [V3 Errors](https://github.com/colinhacks/zod/blob/main/packages/zod/src/v3/ZodError.ts): `packages/zod/src/v3/ZodError.ts`

### Other components

- **Developer**

## Connections

- Developer → Classic API: defines schema (evidence: `README.md`)
- Developer → Classic API: submits input (evidence: `README.md`)
- Classic API → Schema Builders: builds schemas
- Mini API → Schema Types: builds schemas (evidence: `packages/zod/src/v4/mini/schemas.ts`)
- Schema Builders → Schema Types: constructs (evidence: `packages/zod/src/v4/core/api.ts`)
- Schema Builders → Validation Checks: constructs checks (evidence: `packages/zod/src/v4/core/api.ts`)
- Schema Types → Parser: invokes parser (evidence: `packages/zod/src/v4/core/schemas.ts`)
- Validation Checks → Schema Types: checks schema values (evidence: `packages/zod/src/v4/core/checks.ts`)
- Validation Checks → Format Patterns: uses patterns (evidence: `packages/zod/src/v4/core/checks.ts`)
- Validation Checks → Core Utilities: uses helpers (evidence: `packages/zod/src/v4/core/checks.ts`)
- Schema Types → Issue Handling: uses issue types (evidence: `packages/zod/src/v4/core/schemas.ts`)
- Schema Types → Core Utilities: uses helpers (evidence: `packages/zod/src/v4/core/schemas.ts`)
- Compile Entry → AOT Compiler: exposes compilation (evidence: `packages/zod/src/compile.ts`)
- AOT Compiler → Schema Memoizer: detects recursion (evidence: `packages/zod/src/v4/core/compile.ts`)
- AOT Compiler → Schema Types: compiles schemas (evidence: `packages/zod/src/v4/core/compile.ts`)
- JSON Schema → Schema Types: converts schemas (evidence: `packages/zod/src/v4/core/schemas.ts`)
- JSON Schema Processing → Schema Types: processes schemas (evidence: `packages/zod/src/v4/core/schemas.ts`)
- Schema Registry → Schema Types: registers metadata (evidence: `packages/zod/src/v4/core/registries.ts`)
- Developer → V3 Schemas: uses legacy API
- V3 Schemas → V3 Errors: reports validation issues
