gozod CLAUDE.md

GoZod

GoZod is a TypeScript Zod v4-inspired validation library for Go 1.26.5. The root package is a user-facing facade over concrete schemas in types/, shared contracts in core/, runtime machinery in internal/, struct-tag helpers in pkg/tagparser, and JSON Schema conversion in jsonschema/.

• Reference implementations: .reference/zod/ for Zod v4 semantics, .reference/valibot/ for validation composition and issue propagation, and .reference/validator/ for Go reflection and declared-type handling.
• User-facing usage: see README.md, docs/, and examples/.

Commands

Run these from the repository root.

task test                           # Run go test -race ./...
task test:race                      # Run race tests for core and lightweight utility packages
task lint                           # Run golangci-lint and tidy-lint
task golangci-lint                  # Run golangci-lint v2 only
task tidy-lint                      # Verify go.mod and go.sum stay tidy
task contractcheck                  # Run go test -tags=contractcheck ./types
task docs:integrity                 # Run public documentation stale-claim checks
task bench:smoke                    # Compile and smoke-run benchmarks with tiny benchtime
task fmt                            # Run golangci-lint fmt ./...
task vet                            # Run go vet ./...
task vuln                           # Run govulncheck ./...
task verify:ci                      # Run lint, contractcheck, docs, race tests, benchmark smoke, and vuln
task verify                         # Run deps, fmt, vet, lint, contracts, docs, tests, benchmark smoke, and vuln
go build ./...                      # Verify all packages compile

Architecture

gozod/
├── constructors_*.go # Root facade constructor functions
├── core.go           # Root aliases for shared contracts
├── errors.go         # Root error presentation functions and sentinels
├── jsonschema.go     # Root JSON Schema conversion functions and protocol aliases
├── metadata.go       # Root registry and metadata aliases
├── structs.go        # Root FromStruct helpers
├── cmd/gozodgen/     # Code generator for struct-tag schemas
├── coerce/           # z.coerce-style constructors for automatic input conversion
├── core/             # Public contracts, config, issue codes, shared types
├── docs/             # User documentation
├── examples/         # Runnable examples
├── internal/         # Engine, checks, issues, and runtime helpers
├── jsonschema/       # To/From JSON Schema conversion
├── locales/          # Localized validation messages
├── pkg/              # Shared helpers for clone, coercion, maps, regex, reflection, tags, transforms
├── types/            # Concrete schema implementations and fluent APIs
├── .agents/rules/    # Project rules for schemas, checks, naming, tests, performance, and structure
└── .agents/skills/   # Local agent skills available in this repository