Guide · Open source
How to use validator: struct tags, install and examples
Updated · written with AI from the project's own documentation and checked against our catalogue data
validator is a Go package that checks data against rules you write as tags on struct fields, such as required, email, or minimum and maximum values. This guide is for Go developers who validate request bodies or form data, and it shows how to install the package, declare rules, run validation and read the errors it returns. You will finish knowing where the tags go, how to compare fields with each other, and where to find the full documentation.
validatorgo-playground/validator · ★ 20.2k · MIT Install options & downloads Quick start
- 1Install the package. Run go get github.com/go-playground/validator/v10 in your Go module.
- 2Import validator. Add the v10 import to the file that holds your structs.
- 3Create a validator instance. Call validator.New with WithRequiredStructEnabled, as the README recommends for new users.
- 4Tag your struct fields. Add tags such as required, email or eqfield to the fields you want to check.
- 5Call Struct on your data. Pass your struct value to validate.Struct and check whether the error is nil.
- 6Read the ValidationErrors. Use errors.As to cast the error and loop over the failing fields.
Install validator with go get
The package is installed with the Go toolchain. The README says to use go get and then import the package in your own code.
The README does not state a minimum Go version, so check the module requirements of your project if you are unsure.
go get github.com/go-playground/validator/v10Import the package and create a validator
Import the v10 package into the file where you validate data. The README's own example starts by creating a validator instance with the WithRequiredStructEnabled option, which it recommends for new users because that behaviour becomes the default in v11 and later.
- Add the import line to your code.
- Create one validator instance and reuse it.
- Use validator.New(validator.WithRequiredStructEnabled()) as shown in the README's special note.
import "github.com/go-playground/validator/v10"
validate := validator.New(validator.WithRequiredStructEnabled())Add validation tags to struct fields
Rules are written as tags on struct fields. The baked-in tags are grouped in the README into fields, network, strings and format categories. Examples include required, email, and comparison tags such as eqfield, gtfield and nefield.
Tags are the main way to declare rules next to the struct definition, which suits teams that want rules visible in one place.
- Fields: eqfield, nefield, gtfield, ltfield and their relative variants ending in csfield.
- Network: ip, ipv4, url, hostname and port, among others.
- Strings: alpha, alphanum, contains, lowercase and uppercase.
- Format: email, base64, credit_card, datetime and many more.
Run validation and read the errors
Call validate.Struct on your value. The README explains that validation functions return type error. It returns nil when the data is valid, and a ValidationErrors value when fields fail. An InvalidValidationError signals bad validation input rather than bad data.
To read field failures, cast the error to ValidationErrors with errors.As, as the README shows.
- Check whether the returned error is nil.
- If it is not nil, use errors.As to see if it is a ValidationErrors value.
- Loop over the field errors to report each failing field.
err := validate.Struct(mystruct)
var validationErrors validator.ValidationErrors
errors.As(err, &validationErrors)Compare fields and validate slices, arrays and maps
Cross-field tags let one field be checked against another, such as a confirm-password field that must match a password field, using eqfield. The README also lists diving support, which lets validation reach into any or all levels of slices, arrays and maps, including both map keys and values.
For custom behaviour, the README points to examples for custom field types, struct-level validation, and translations with custom error messages.
- Use eqfield to require two fields to match.
- Use gtfield or ltfield to compare sizes or dates against another field.
- See the translations example in the README for localised messages.
What people use it for
- Validating JSON request bodies in a Go web API before saving them.
- Checking that a confirm-password field matches the password field in a sign-up form.
- Validating each item in a slice of email addresses or URLs with diving.
- Producing translated or customised error messages for end users.
Frequently asked questions
How do I install go-playground validator?
Run go get github.com/go-playground/validator/v10 and then import github.com/go-playground/validator/v10 in your code. The README gives these two steps as the full installation.
Is go-playground validator free to use?
The package is licensed under the MIT licence, as shown on its repository. Check the LICENSE file in the repository for the full terms.
What do I need to use validator?
You need Go and a project that uses it. The README does not state a specific Go version, so check the package's module requirements.
Which framework uses go-playground validator by default?
The README says it is the default validator for the gin web framework. Gin users get it without a separate setup step.
Can validator compare two fields in the same struct?
Yes. Cross-field tags such as eqfield, nefield, gtfield and ltfield compare one field with another, and relative variants ending in csfield compare against relative fields.
How does validator compare with ozzo-validation or govalidator?
This page does not include a feature comparison. The related projects named for this item are ozzo-validation, govalidator and go-playground/form, so read each project's documentation to compare them for your needs.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use validator if you write Go web APIs or forms and want rules declared as tags next to your structs, including cross-field checks and translated errors. Pick something else if you are not writing Go, or if you need rules loaded from a database or UI without changing code.
Install options & downloads