validate

README

validate

Package validate validates Go struct 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.

Installation

1. Use go get to download validate package.

   go get gopkg.in/dealancer/validate.v2
   

2. Import validate package into your project.

   import "gopkg.in/dealancer/validate.v2"
   

Types

This package supports a wide variety of types.

• Most of the built-in types:
  • int, int8 int16, int32, int64
  • uint, uint8, uint16, uint32, uint64
  • float32, float64
  • uintptr
  • string
• Aliased types:
  • time.Duration
  • byte (uint8)
  • rune (int32)
  • e.g. type Enum string
• Complex types:
  • Struct
  • Map
  • Slice
  • Array
  • Pointer

Validators

This package provides the following validators.

• eq (equals), ne (not equals), gt (greater than), lt (less than), gte (greater than or equal to), lte (less than or equal to) validators compare a numeric value of a number or compare a count of elements in a string, a map, a slice, or an array.
• empty validator checks if a string, a map, a slice, or an array is (not) empty.
• nil validator checks if a pointer is (not) nil.
• one_of validator checks if a number or a string contains any of the given elements.
• format validator checks if a string in one of the following formats: alpha, alnum, alpha_unicode, alnum_unicode, numeric, number, hexadecimal, hexcolor, rgb, rgba, hsl, hsla, email, url, uri, urn_rfc2141, file, base64, base64url, isbn, isbn10, isbn13, eth_addr, btc_addr, btc_addr_bech32, uuid, uuid3, uuid4, uuid5, ascii, ascii_print, datauri, latitude, longitude, ssn, ipv4, ipv6, ip, cidrv4, cidrv6, cidr, mac, hostname, hostname_rfc1123, fqdn, url_encoded, dir.

Operators

Following operators are used. There are listed in the descending order of their precedence.

• [] (brackets) are used to validate map keys.
• > (greater-than sign) is used to validate values of maps, slices, arrays or to dereference a pointer.
• & (ampersand) is used to perform multiple validators using AND logic.
• | (vertical bar) is used to perform multiple validators using OR logic.
• = (equal sign) is used to separate validator type from value.
• , (comma) is used to specify multiple tokens for a validator (e.g. one_of).

Usage

type Registration struct {
    // Username should be between 3 and 25 characters and in alphanumeric unicode format
    Username string `validate:"gte=3 & lte=25 & format=alnum_unicode"`

    // Email should be empty or in the email format
    Email string `validate:"empty=true | format=email"`

    // Password is validated using a custom validation method
    Password string

    // Role should be one of "admin", "publisher", or "author"
    Role string `validate:"one_of=admin,publisher,author"`

    // URLs should not be empty, URLs values should be in the url format
    URLs []string `validate:"empty=false > format=url"`

    // Retired (pointer) should not be nil
    Retired *bool `validate:"nil=false"`

    // Some complex field with validation
    Complex []map[*string]int `validate:"gte=1 & lte=2 | eq=4 > empty=false [nil=false > empty=false] > ne=0"`
}

// Custom validation
func (r Registration) Validate() error {
    if !StrongPass(c.Password) {
        return errors.New("Password should be strong!")
    }

    return nil
}

type Registrations struct {
	r []Registration `validate:"gte=2"` // There should be at least two registrations
}

registrations := Registrations{
	r: []Registration{
		Registration{
			Username: "admin",
		},
	},
}

if err := validate.Validate(&registrations); err != nil {
	panic(err)
}

See GoDoc for the complete reference.

Credits

This project is written by Vadym Myrgorod. Insipred by go-playground/validator.

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
• func Validate(element interface{}) error
• type CustomValidator
• type ErrorField
• type ErrorSyntax
  • func (e ErrorSyntax) Error() string
  • func (e ErrorSyntax) FieldName() string
• type ErrorValidation
  • func (e ErrorValidation) Error() string
  • func (e ErrorValidation) FieldName() string
• type FormatType
• type ValidatorType

Constants

const MasterTag = "validate"

MasterTag is the main validation tag.

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

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 validation .

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 (
	FormatAlpha                FormatType = "alpha"
	FormatAlnum                FormatType = "alnum"
	FormatAlphaUnicode         FormatType = "alpha_unicode"
	FormatAlnumUnicode         FormatType = "alnum_unicode"
	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"
)

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.