validate

package
v1.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2022 License: MIT Imports: 13 Imported by: 1

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

View Source
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

func ValidateVariable(fieldName, validator string, value interface{}) error

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

type ErrorField interface {
	error
	FieldName() string
}

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.

func (ErrorSyntax) Error

func (e ErrorSyntax) Error() string

Error returns an error.

func (ErrorSyntax) FieldName

func (e ErrorSyntax) FieldName() string

FieldName gets a field name.

type ErrorValidation

type ErrorValidation struct {
	// contains filtered or unexported fields
}

ErrorValidation occurs when validator does not validate.

func (ErrorValidation) Error

func (e ErrorValidation) Error() string

Error returns an error.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL