GitHub - go-playground/validator: :100:Go Struct and Field validation, including Cross Field, Cross Struct, Map, Slice and Array diving · GitHub

Author: go-playground | Published: Unknown | Generated: 2025-02-11 | Domain: github.com
Tags: ‘#golang’ ‘#validation’ ‘#struct-tags’ ‘#api-development’ ‘#i18n’

---

TLDR

go-playground/validator is a Go validation package that applies rules through struct tags or custom validators, covering fields, cross-field and cross-struct comparisons, and recursively nested slices, arrays, and maps—including map keys. It provides a large catalog of format, network, conditional, and comparison validators; customizable aliases, field names, and translated errors; and integrations such as Gin. The project recommends enabling WithRequiredStructEnabled() now because that behavior is planned as the v11 default, while guaranteeing support for the two most recent Go major versions.

Key Takeaways

• Rich traversal and rule model: Supports standard field validation, relative and absolute cross-field comparisons, struct-level validation, and dive-style traversal of multidimensional slices, arrays, maps, keys, and values.
• Extensible type handling: Can validate underlying interface values, SQL driver Valuer types, custom types, and generic wrapper types through the ValidatorValuer interface; aliases consolidate multiple validation rules under one tag.
• Built-in validation breadth: Includes network, URL, identifier, ISO country/currency, cryptographic hash, JSON/JWT, postal code, image/MIME type, cron, UUID, semantic-version, conditional-required, uniqueness, and string-format validators.
• Error handling and localization: Struct returns nil, InvalidValidationError, or ValidationErrors; callers can use errors.As to extract typed field failures. Custom field-name extraction—such as JSON names—and i18n-aware error messages are supported.
• Performance profile: On an Apple M3 Max with Go 1.23.3, a successful single-field validation measures 27.88 ns/op with 0 allocations, and parallel success measures 2.289 ns/op with 0 allocations. A simple successful struct validation measures 109.5 ns/op, or 8.932 ns/op in the reported parallel benchmark.
• Versioning note: Initialize with validator.New(validator.WithRequiredStructEnabled()); this opt-in behavior is intended to become the default in v11+. The package follows Go’s release policy by guaranteeing support for the two latest Go major versions.

Images & Media

• Package validator logo — Repository logo displayed at the top of the README.

Referenced Links

• Package documentation on pkg.go.dev — Detailed API reference and usage documentation.
• Gin web framework — validator is Gin’s default validation engine.
• Gin upgrade/override example — Example for upgrading Gin validation from validator v8 to v9 or overriding the validator.
• Simple usage example — Basic struct and field validation example.
• Custom field types example — Custom type validation patterns.
• Struct-level validation example — Cross-field and struct-level validation example.
• Translations and custom errors example — Localized validation-error setup.
• ValidatorValuer example — Validating values exposed by custom wrapper types.
• Maintainer call discussion — Project request for additional maintainers.
• Go release policy — Upstream policy referenced for supported Go versions.