validator

validator is a Go library that implements value validation for structs and individual fields by parsing struct tags at runtime and caching the parsed rules per type. It supports cross-field and cross-struct comparisons, diving into slices, arrays, and maps (including map keys) to validate every element, and pluggable custom type handlers for values like sql.NullString or anything satisfying a Valuer interface.

Beyond roughly a hundred baked-in validation tags covering formats like email, UUID, IP addresses, credit cards, and ISO country/currency codes, it supports internationalized error messages via the go-playground/universal-translator ecosystem, custom struct-level validators, and tag aliasing for reusing common validation combinations. It is the default validator used by the gin web framework and is widely embedded in other Go API frameworks and services.

What You Get

• Reflection-based struct tag validation with per-type caching for high-throughput validation
• Roughly a hundred baked-in validators covering strings, network formats, comparisons, and country/currency/language codes
• Cross-field and cross-struct validation via tags like eqfield, gtfield, and their cross-struct counterparts
• Diving into slices, arrays, and maps (including map keys) to validate nested collections in one pass
• Custom type handlers, custom validators, and struct-level validation hooks for domain-specific rules
• i18n-aware error translation through the go-playground/universal-translator ecosystem

Common Use Cases

• Validating HTTP request bodies and query parameters before they reach business logic
• Enforcing invariants on domain models decoded from JSON, YAML, or database rows
• Providing localized validation error messages to API clients across multiple languages
• Validating nested and collection-typed fields (slices of structs, maps) in a single validation pass

Under The Hood

Architecture

validator’s architecture separates registration/configuration from execution, cleanly divided across three layers: validator_instance.go defines the thread-safe Validate singleton holding registered validations, aliases, custom type handlers, and the tag/struct caches; baked_in.go supplies the built-in validators registered against this singleton at construction time via New(); and validator.go plus cache.go handle execution — parsing validate struct tags into linked cField/cTag structures once per reflect.Type and caching them in structCache/tagCache, then running the mutually recursive validateStruct/traverseField pair against each call’s per-goroutine validate struct drawn from a sync.Pool. This caching is the core invariant: changing how tags are parsed would ripple through every validator function, since cTag.typeof (dive, omitempty, structonly, etc.) drives control flow at execution time rather than registration time.

Tech Stack

Built on Go’s standard reflect package with no web or ORM framework dependency — this is a pure validation library meant to be embedded. Its external dependencies are other go-playground packages — go-playground/locales and go-playground/universal-translator for i18n-aware error messages — plus gabriel-vasile/mimetype for MIME-based file validators and leodido/go-urn for URN tag parsing, with golang.org/x/crypto and golang.org/x/text rounding out cryptographic and unicode-aware string checks. The module targets a recent Go toolchain (module path ends in /v10 to preserve semver-major compatibility), builds via a plain Makefile (make test, make lint, make bench), and CI runs a full matrix across Go versions and ubuntu/macos/windows via GitHub Actions.

Code Quality

Testing is extensive: the test file alone spans close to 17,000 lines covering close to 290 test functions, run with race detection and atomic coverage mode in CI, with coverage reported to Coveralls. A linter runs as a separate CI job. Errors are returned as typed values (ValidationErrors, a slice of FieldError, and InvalidValidationError for misuse) rather than swallowed or logged, matching Go idioms — callers type-assert the returned error per the documented pattern. Exported identifiers are consistently doc-commented, and the repository ships its own contributor-facing architecture notes, indicating an unusually well-documented internal structure for a library this size.

API Design validator’s developer experience centers on a declarative struct-tag syntax that keeps validation rules colocated with the struct definition, with a dive tag letting a single rule descend into nested slices, arrays, and map keys/values without hand-written loops — a capability many peer libraries lack outright. A functional-options pattern enables new default behaviors without breaking existing callers, and tag aliasing lets teams collapse repeated validation combinations into single custom tags. The core validation model (tag-based reflection) follows an established pattern seen across other ecosystems, but the depth of cross-field/cross-struct comparison operators and full collection diving is more complete than most alternatives.