Documentation
¶
Overview ¶
Package validate validates Go structs and types recursively based on tags. It provides powerful syntax to perform validation for substructs, maps, slices, arrays, and pointers. Package also allows to run custom validation methods.
Use this package to make sure that the content of the struct is in the format you need. For example, **validate** package is useful when unmarshalling YAML or JSON.
This package supports most of the built-in types: int8, uint8, int16, uint16, int32, uint32, int64, uint64, int, uint, uintptr, float32, float64 and aliased types: time.Duration, byte (uint8), rune (int32).
Following validators are available: gt, lt, gte, lte, empty, nil, one_of, format.
Basic usage ¶
Use validate tag to specify validators for fields of a struct. If any of validators fail, validate.Validate returns an error.
type S struct {
i int `validate:"gte=0"` // Should be greater than or equal to 0
s string `validate:"format=email"` // Should be in the email format
b *bool `validate:"nil=false"` // Should not be nil
}
err := validate.Validate(S{
i: -1,
s: "",
b: nil,
})
// err contains an error because n is less than 0, s is empty, and b is nil
Multiple validators ¶
It is possible to specify multiple validators using & (ampersand) or | (vertical bar) operator. & operator is used for logical AND, while | is used for logical OR. & operator has a priority over | operator.
type S struct {
// Check that the value is in the range of -20...-10 or 10...20
field int `validate:"gte=-20 & lte=-10 | gte=10 & lte=20"`
}
Slice and array validation ¶
You can use a regular syntax to validate a slice/array. To validate slice/array values, specify validators after an arrow character.
type S struct {
// Check that the slice is not empty and slice values are either 1 or -1
field []int `validate:"empty=false > one_of=1,-1"`
}
Map validation ¶
You can use a regular syntax to validate a map. To validate map keys, specify validators inside brackets. To validate map values, specify validators after an arrow character.
type S struct {
// Check that the map contains at least two elements, map keys are not empty, and map values are between 0 and 10
field map[string]int `validate:"gte=2 [empty=false] > gte=0 & lte=10"`
}
Pointer validation ¶
You can use a regular syntax to validate a pointer. To dereference a pointer, specify validators after an arrow character.
type S struct {
// Check that the pointer is not nil and the number is between 0 and 10
field *int `validate:"nil=false > gte=0 & lte=10"`
}
Nested struct validation ¶
You can validate a nested struct with regular syntax.
type A struct {
// Check that the number is greater than or equal to 0
a int `validate:"gte=0"`
}
type B struct {
A
// Check that the number is greater than or equal to 0
b int `validate:"gte=0"`
}
Substruct validation ¶
You can validate a substruct with regular syntax.
type A struct {
// Check that the number is greater than or equal to 0
field int `validate:"gte=0"`
}
type B struct {
a A
// Check that the number is greater than or equal to 0
field int `validate:"gte=0"`
}
Deep validation ¶
You can use brackets and arrow syntax to deep to as many levels as you need.
type A struct {
field int `validate:"gte=0 & lte=10"`
}
type B struct {
field []map[*string]*A `validate:"gte=1 & lte=2 | eq=4 > empty=false [nil=false > empty=false] > nil=false"`
}
// gte=1 & lte=2 | eq=4 will be applied to the array
// empty=false will be applied to the map
// nil=false > empty=false will be applied to the map key (pointer and string)
// nil=false will be applied to the map value
// gte=0 & lte=10 will be applied to the A.field
Custom validation ¶
You can specify custom validation method. Custom validation also works for a substuct, if a substruct is defined in an exported field.
type S struct {
field int
}
func (s S) Validate() error {
if s.field <= 0 {
return errors.New("field should be positive")
}
return nil
}
Handling errors ¶
Validate method returns two types of errors: ErrorSyntax and ErrorValidation. You can handle an error type using switch syntax.
type S struct {
field *string `validate:"empty=false"`
}
var err error
if err = validate.Validate(S{nil}); err != nil {
switch err.(type) {
case validate.ErrorSyntax:
// Handle syntax error
case validate.ErrorValidation:
// Handle validation error
default:
// Handle other errors
}
}
Index ¶
Constants ¶
const MasterTag = "validate"
MasterTag is the main validation tag.
Variables ¶
This section is empty.
Functions ¶
func Validate ¶
func Validate(element interface{}) error
Validate validates fields of a struct. It accepts a struct or a struct pointer as a parameter. It returns an error if a struct does not validate or nil if there are no validation errors.
err := validate.Validate(struct {
field time.Duration `validate:"gte=0s"`
}{
field: -time.Second,
})
// err contains an error
func ValidateVariable ¶
Types ¶
type CustomValidator ¶
type CustomValidator interface {
// Validate is a custom validation function.
// Validate does not work when the receiver is a reference.
// Validate does not work for nested types obtained from unexported field.
Validate() error
}
CustomValidator is an interface for a validated struct.
type ErrorField ¶
ErrorField is an error interface for field/value error.
type ErrorSyntax ¶
type ErrorSyntax struct {
// contains filtered or unexported fields
}
ErrorSyntax occurs when there is a syntax error.
type ErrorValidation ¶
type ErrorValidation struct {
// contains filtered or unexported fields
}
ErrorValidation occurs when validator does not validate.
func (ErrorValidation) FieldName ¶
func (e ErrorValidation) FieldName() string
FieldName gets a field name.
type FormatType ¶
type FormatType string
FormatType is used for format validator type definitions.
const ( FormatDate FormatType = "date" FormatAlpha FormatType = "alpha" FormatAlnum FormatType = "alnum" FormatAlphaUnicode FormatType = "alpha_unicode" FormatAlnumUnicode FormatType = "alnum_unicode" FormatSlug FormatType = "slug" FormatText FormatType = "text" FormatStrictHtml FormatType = "strict_html" FormatUsername FormatType = "username" FormatNumeric FormatType = "numeric" FormatNumber FormatType = "number" FormatHexadecimal FormatType = "hexadecimal" FormatHEXColor FormatType = "hexcolor" FormatRGB FormatType = "rgb" FormatRGBA FormatType = "rgba" FormatHSL FormatType = "hsl" FormatHSLA FormatType = "hsla" FormatEmail FormatType = "email" FormatURL FormatType = "url" FormatURI FormatType = "uri" FormatUrnRFC2141 FormatType = "urn_rfc2141" // RFC 2141 FormatFile FormatType = "file" FormatBase64 FormatType = "base64" FormatBase64URL FormatType = "base64url" FormatISBN FormatType = "isbn" FormatISBN10 FormatType = "isbn10" FormatISBN13 FormatType = "isbn13" FormatEthereumAddress FormatType = "eth_addr" FormatBitcoinAddress FormatType = "btc_addr" FormatBitcoinBech32Address FormatType = "btc_addr_bech32" FormatUUID FormatType = "uuid" FormatUUID3 FormatType = "uuid3" FormatUUID4 FormatType = "uuid4" FormatUUID5 FormatType = "uuid5" FormatASCII FormatType = "ascii" FormatPrintableASCII FormatType = "ascii_print" FormatDataURI FormatType = "datauri" FormatLatitude FormatType = "latitude" FormatLongitude FormatType = "longitude" FormatSSN FormatType = "ssn" FormatIPv4 FormatType = "ipv4" FormatIPv6 FormatType = "ipv6" FormatIP FormatType = "ip" FormatCIDRv4 FormatType = "cidrv4" FormatCIDRv6 FormatType = "cidrv6" FormatCIDR FormatType = "cidr" FormatMAC FormatType = "mac" FormatHostnameRFC952 FormatType = "hostname" // RFC 952 FormatHostnameRFC1123 FormatType = "hostname_rfc1123" // RFC 1123 FormatFQDN FormatType = "fqdn" FormatURLEncoded FormatType = "url_encoded" FormatDir FormatType = "dir" FormatPostcode FormatType = "postcode" )
Following string formats are available. E.g. `validate:"format=email"`
type ValidatorType ¶
type ValidatorType string
ValidatorType is used for validator type definitions.
const ( // ValidatorEq (equals) compares a numeric value of a number or compares a count of elements in a string, a map, a slice, or an array. // E.g. `validate:"eq=1"` ValidatorEq ValidatorType = "eq" // ValidatorNe (not equals) compares a numeric value of a number or compares a count of elements in a string, a map, a slice, or an array. // E.g. `validate:"ne=0"` ValidatorNe ValidatorType = "ne" // ValidatorGt (greater than) compares a numeric value of a number or compares a count of elements in a string, a map, a slice, or an array. // E.g. `validate:"gt=-1"` ValidatorGt ValidatorType = "gt" // ValidatorLt (less than) compares a numeric value of a number or compares a count of elements in a string, a map, a slice, or an array. // E.g. `validate:"lt=11"` ValidatorLt ValidatorType = "lt" // ValidatorGte (greater than or equal to) compares a numeric value of a number or compares a count of elements in a string, a map, a slice, or an array. // E.g. `validate:"gte=0"` ValidatorGte ValidatorType = "gte" // ValidatorLte (less than or equal to) compares a numeric value of a number or compares a count of elements in a string, a map, a slice, or an array. // E.g. `validate:"lte=10"` ValidatorLte ValidatorType = "lte" // ValidatorEmpty checks if a string, a map, a slice, or an array is (not) empty. // E.g. `validate:"empty=false"` ValidatorEmpty ValidatorType = "empty" // ValidatorNil checks if a pointer is (not) nil. // E.g. `validate:"nil=false"` ValidatorNil ValidatorType = "nil" // ValidatorOneOf checks if a number or a string contains any of the given elements. // E.g. `validate:"one_of=1,2,3"` ValidatorOneOf ValidatorType = "one_of" // ValidatorFormat checks if a string of a given format. // E.g. `validate:"format=email"` ValidatorFormat ValidatorType = "format" )
Following validators are available.
Source Files