project-structure

GoZod Project Structure & File Organization Guide

---

1. Design Goals & Philosophy

GoZod follows a type-safe, layered architecture that mirrors the API surface of Zod v4 while embracing Go idioms:

1. Input-Output Symmetry – every schema returns the same type it accepts after validation/coercion.
2. Unified Wrapper Pattern – optional / nilable / default / prefault wrappers share the same internal contract.
3. Strict Separation of Concerns – parsing, checking, issue creation, error formatting and i18n each live in their own packages.
4. Composable Validation Pipeline – checks are first-class citizens that can be merged, cloned and reused.
5. Compatibility First – public API names and ergonomics track Zod whenever practical.

---

2. Layered Architecture

go module gozod
├── bin/         # Build outputs and tools
├── coerce/      # Root-level coercion utilities
├── core/        # Foundation contracts (no concrete logic)
├── docs/        # Documentation and guides
├── examples/    # Example implementations and usage
├── internal/    # Private runtime (engine, checks, issues, utils)
├── jsonschema/  # JSON Schema conversion (to/from)
├── locales/     # Built-in i18n bundles
├── pkg/         # Re-usable, reflection-free helpers (zero deps)
└── types/       # Public schema implementations (String, Array, …)

2.1 One-Way Dependency Rule

graph TD;
  core --> internal;
  core --> pkg;
  pkg  --> internal;
  internal --> types;
  core --> types;
  internal --> locales;
  types --> locales;
  coerce --> types;
  coerce --> internal;

types never import each other; all cross-type logic lives in internal, pkg, or coerce.

---

3. Directory Reference

3.1 Root Level Files

File	Purpose
gozod.go	Main entry point re-exporting all types, constructors, and JSON Schema conversion from subpackages
gozod_test.go	Integration tests for the main API
gozod_tags_test.go	Tests for struct tag validation
gozod_circular_test.go	Tests for circular reference handling
metadata_test.go	Tests for metadata/registry functionality
CLAUDE.md	Project instructions for Claude Code AI assistant
Makefile	Build automation and common tasks