validator

package module

v1.1.0 Latest Latest Go to latest Published: Jun 5, 2025 License: Apache-2.0 Imports: 27 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/pchchv/validator

Links

Open Source Insights

README ¶

validator

Package validator implements structure and field validation, including cross fields, cross structures, maps, slices and arrays.

Features

Customizable i18n aware error messages.
Handles custom field types such as sql driver Valuer.
Ability to dive into both map keys and values for validation.
Handles type interface by determining it's underlying type prior to validation.
Cross Field and Cross Struct validations by using validation tags or custom validators.
Slice, Array and Map diving, which allows any or all levels of a multidimensional field to be validated.
Alias validation tags, which allows for mapping of several validations to a single tag for easier defining of validations on structs.
Extraction of custom defined Field Name e.g. can specify to extract the JSON name while validating and have it available in the resulting FieldError.

Installation

Use go get

	go get github.com/pchchv/validator

And

	import "github.com/pchchv/validator"

Baked-in Validations

Special Notes:

If new to using validator it is highly recommended to initialize it using the WithRequiredStructEnabled option which is opt-in to new behaviour that will become the default behaviour in v11+. See documentation for more details.

validate := validator.New(validator.WithRequiredStructEnabled())

Fields:

Tag	Description
eqcsfield	Field Equals Another Field (relative)
eqfield	Field Equals Another Field
fieldcontains	Check the indicated characters are present in the Field
fieldexcludes	Check the indicated characters are not present in the field
gtcsfield	Field Greater Than Another Relative Field
gtecsfield	Field Greater Than or Equal To Another Relative Field
gtefield	Field Greater Than or Equal To Another Field
gtfield	Field Greater Than Another Field
ltcsfield	Less Than Another Relative Field
ltecsfield	Less Than or Equal To Another Relative Field
ltefield	Less Than or Equal To Another Field
ltfield	Less Than Another Field
necsfield	Field Does Not Equal Another Field (relative)
nefield	Field Does Not Equal Another Field

Network:

Tag	Description
cidr	Classless Inter-Domain Routing CIDR
cidrv4	Classless Inter-Domain Routing CIDRv4
cidrv6	Classless Inter-Domain Routing CIDRv6
datauri	Data URL
fqdn	Full Qualified Domain Name (FQDN)
hostname	Hostname RFC 952
hostname_port	HostPort
hostname_rfc1123	Hostname RFC 1123
ip	Internet Protocol Address IP
ip4_addr	Internet Protocol Address IPv4
ip6_addr	Internet Protocol Address IPv6
ip_addr	Internet Protocol Address IP
ipv4	Internet Protocol Address IPv4
ipv6	Internet Protocol Address IPv6
mac	Media Access Control Address MAC
tcp4_addr	Transmission Control Protocol Address TCPv4
tcp6_addr	Transmission Control Protocol Address TCPv6
tcp_addr	Transmission Control Protocol Address TCP
udp4_addr	User Datagram Protocol Address UDPv4
udp6_addr	User Datagram Protocol Address UDPv6
udp_addr	User Datagram Protocol Address UDP
unix_addr	Unix domain socket end point Address
uri	URI String
url	URL String
http_url	HTTP URL String
url_encoded	URL Encoded
urn_rfc2141	Urn RFC 2141 String

Strings:

Tag	Description
alpha	Alpha Only
alphanum	Alphanumeric
alphanumunicode	Alphanumeric Unicode
alphaunicode	Alpha Unicode
ascii	ASCII
boolean	Boolean
contains	Contains
containsany	Contains Any
containsrune	Contains Rune
endsnotwith	Ends Not With
endswith	Ends With
excludes	Excludes
excludesall	Excludes All
excludesrune	Excludes Rune
lowercase	Lowercase
multibyte	Multi-Byte Characters
number	Number
numeric	Numeric
printascii	Printable ASCII
startsnotwith	Starts Not With
startswith	Starts With
uppercase	Uppercase

Format:

Tag	Description
base64	Base64 String
base64url	Base64URL String
base64rawurl	Base64RawURL String
bic	Business Identifier Code (ISO 9362)
bcp47_language_tag	Language tag (BCP 47)
btc_addr	Bitcoin Address
btc_addr_bech32	Bitcoin Bech32 Address (segwit)
credit_card	Credit Card Number
mongodb	MongoDB ObjectID
mongodb_connection_string	MongoDB Connection String
cron	Cron
spicedb	SpiceDb ObjectID/Permission/Type
datetime	Datetime
e164	e164 formatted phone number
ein	U.S. Employeer Identification Number
email	E-mail String
eth_addr	Ethereum Address
hexadecimal	Hexadecimal String
hexcolor	Hexcolor String
hsl	HSL String
hsla	HSLA String
html	HTML Tags
html_encoded	HTML Encoded
isbn	International Standard Book Number
isbn10	International Standard Book Number 10
isbn13	International Standard Book Number 13
issn	International Standard Serial Number
iso3166_1_alpha2	Two-letter country code (ISO 3166-1 alpha-2)
iso3166_1_alpha3	Three-letter country code (ISO 3166-1 alpha-3)
iso3166_1_alpha_numeric	Numeric country code (ISO 3166-1 numeric)
iso3166_2	Country subdivision code (ISO 3166-2)
iso4217	Currency code (ISO 4217)
json	JSON
jwt	JSON Web Token (JWT)
latitude	Latitude
longitude	Longitude
luhn_checksum	Luhn Algorithm Checksum (for strings and (u)int)
postcode_iso3166_alpha2	Postcode
postcode_iso3166_alpha2_field	Postcode
rgb	RGB String
rgba	RGBA String
ssn	Social Security Number SSN
timezone	Timezone
uuid	Universally Unique Identifier UUID
uuid3	Universally Unique Identifier UUID v3
uuid3_rfc4122	Universally Unique Identifier UUID v3 RFC4122
uuid4	Universally Unique Identifier UUID v4
uuid4_rfc4122	Universally Unique Identifier UUID v4 RFC4122
uuid5	Universally Unique Identifier UUID v5
uuid5_rfc4122	Universally Unique Identifier UUID v5 RFC4122
uuid_rfc4122	Universally Unique Identifier UUID RFC4122
md4	MD4 hash
md5	MD5 hash
sha256	SHA256 hash
sha384	SHA384 hash
sha512	SHA512 hash
ripemd128	RIPEMD-128 hash
ripemd128	RIPEMD-160 hash
tiger128	TIGER128 hash
tiger160	TIGER160 hash
tiger192	TIGER192 hash
semver	Semantic Versioning 2.0.0
ulid	Universally Unique Lexicographically Sortable Identifier ULID
cve	Common Vulnerabilities and Exposures Identifier (CVE id)

Comparisons:

Tag	Description
eq	Equals
eq_ignore_case	Equals ignoring case
gt	Greater than
gte	Greater than or equal
lt	Less Than
lte	Less Than or Equal
ne	Not Equal
ne_ignore_case	Not Equal ignoring case

Other:

Tag	Description
dir	Existing Directory
dirpath	Directory Path
file	Existing File
filepath	File Path
image	Image
isdefault	Is Default
len	Length
max	Maximum
min	Minimum
oneof	One Of
required	Required
required_if	Required If
required_unless	Required Unless
required_with	Required With
required_with_all	Required With All
required_without	Required Without
required_without_all	Required Without All
excluded_if	Excluded If
excluded_unless	Excluded Unless
excluded_with	Excluded With
excluded_with_all	Excluded With All
excluded_without	Excluded Without
excluded_without_all	Excluded Without All
unique	Unique
validateFn	Verify if the method `Validate() error` does not return an error (or any specified method)

Aliases:

Tag	Description
iscolor	hexcolor\|rgb\|rgba\|hsl\|hsla
country_code	iso3166_1_alpha2\|iso3166_1_alpha3\|iso3166_1_alpha_numeric

Error Return Value

Validator only returns InvalidValidationError for bad input validation, nil or ValidationErrors as a type error. So all to do is to check if the returned error is nil, and if not, check if the error is InvalidValidationError (if necessary, most of the time it is not), cast it to the ValidationErrors type as shown below:

err := validate.Struct(mystruct)
validationErrors := err.(validator.ValidationErrors)

Examples:

Documentation ¶

Index ¶

type CustomTypeFunc
type FieldError
type FieldLevel
type FilterFunc
type Func
type FuncCtx
type InvalidValidationError
- func (e *InvalidValidationError) Error() string
type Option
- func WithPrivateFieldValidation() Option
- func WithRequiredStructEnabled() Option
type StructLevel
type StructLevelFunc
type StructLevelFuncCtx
type TagNameFunc
type Validate
- func New(options ...Option) *Validate
type ValidationErrors
- func (ve ValidationErrors) Error() string

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type CustomTypeFunc ¶

type CustomTypeFunc func(field reflect.Value) interface{}

CustomTypeFunc overrides or adds custom field type handler functions field = field type value to return a value to validate Valuer example from sql drive see https://golang.org/src/database/sql/driver/types.go?s=1210:1293#L29

type FieldError ¶

type FieldError interface {
	// Tag returns the validation tag that failed.
	// If the validation was an alias,
	// this will return the alias name and not the underlying tag that failed.
	// For example, alias "iscolor": "hexcolor|rgb|rgba|hsl|hsla" will return "iscolor"
	Tag() string
	// ActualTag returns the validation tag that failed,
	// even if an alias the actual tag within the alias will be returned.
	// If an 'or' validation fails the entire or will be returned.
	// For example, alias "iscolor": "hexcolor|rgb|rgba|hsl|hsla" will return "hexcolor|rgb|rgba|hsl|hsla"
	ActualTag() string
	// Namespace returns the namespace for the field error,
	// with the tag name taking precedence over the field's actual name.
	// For example, JSON name "User.fname"
	//
	// See StructNamespace() for a version that returns actual names.
	//
	// NOTE: this field may be empty when validating a single primitive field using validate.Field(...),
	// as there is no way to extract its name.
	Namespace() string
	// StructNamespace returns the namespace for the field error, with the field's actual name.
	// For example, "User.FirstName" see Namespace for comparison
	//
	// NOTE: this field may be empty when validating a single primitive field using validate.Field(...),
	// as there is no way to extract its name.
	StructNamespace() string
	// Field returns the fields name with the tag name taking precedence over the field's actual name.
	//
	// `RegisterTagNameFunc` must be registered to get tag value.
	// For example, JSON name "fname" see StructField for comparison,
	Field() string
	// StructField returns the field's actual name from the struct, when able to determine.
	// For example, "FirstName" see Field for comparison
	StructField() string
	// Value returns the actual field's value in case needed for creating the error message.
	Value() interface{}
	// Param returns the parameter value as a string for comparison.
	// This will also help when generating an error message.
	Param() string
	// Kind returns the Field's reflect Kind.
	// For example, time.Time's kind is a struct
	Kind() reflect.Kind
	// Type returns the Field's reflect Type.
	// For example, time.Time's type is time.Time
	Type() reflect.Type
	// Error returns the FieldError's message.
	Error() string
}

FieldError contains all functions to get error details.

type FieldLevel ¶

type FieldLevel interface {
	// Top returns the top level struct, if any
	Top() reflect.Value
	// Parent returns the current fields parent struct,
	// if any or the comparison value if called 'VarWithValue'
	Parent() reflect.Value
	// Field returns current field for validation
	Field() reflect.Value
	// FieldName returns the field's name with the tag
	// name taking precedence over the fields actual name.
	FieldName() string
	// StructFieldName returns the struct field's name
	StructFieldName() string
	// Param returns param for validation against current field
	Param() string
	// GetTag returns the current validations tag name
	GetTag() string
	// ExtractType gets the actual underlying type of field value.
	// It will dive into pointers,
	// customTypes and return you the underlying value and it's kind.
	ExtractType(field reflect.Value) (value reflect.Value, kind reflect.Kind, nullable bool)
	// GetStructFieldOK traverses the parent struct to retrieve a specific field denoted by the provided namespace
	// in the param and returns the field, field kind,
	// if it's a nullable type and whether is was successful in retrieving the field at all.
	//
	// NOTE: when not successful ok will be false,
	// this can happen when a nested struct is nil and so the field could not be retrieved because it didn't exist.
	GetStructFieldOK() (reflect.Value, reflect.Kind, bool, bool)
	// GetStructFieldOKAdvanced is the same as GetStructFieldOK except that it accepts the
	// parent struct to start looking for the field and namespace allowing more extensibility for validators.
	GetStructFieldOKAdvanced(val reflect.Value, namespace string) (reflect.Value, reflect.Kind, bool, bool)
}

FieldLevel contains all the information and helper functions to validate a field.

type FilterFunc ¶

type FilterFunc func(ns []byte) bool

FilterFunc is the type used to filter fields using the StructFiltered(...) function. Return true causes the field to be filtered/skipped on validation.

type Func ¶

type Func func(fl FieldLevel) bool

Func accepts a FieldLevel interface for all validation needs. Return value should be true when validation succeeds.

type FuncCtx ¶

type FuncCtx func(ctx context.Context, fl FieldLevel) bool

FuncCtx accepts a context.Context and FieldLevel interface for all validation needs. The return value should be true when validation succeeds.

type InvalidValidationError ¶

type InvalidValidationError struct {
	Type reflect.Type
}

InvalidValidationError describes an invalid argument passed to `Struct`, `StructExcept`, StructPartial` or `Field`.

func (*InvalidValidationError) Error ¶

func (e *InvalidValidationError) Error() string

Error returns InvalidValidationError message.

type Option ¶

type Option func(*Validate)

Option represents a configurations option to be applied to validator during initialization.

func WithPrivateFieldValidation ¶

func WithPrivateFieldValidation() Option

WithPrivateFieldValidation activates validation for unexported fields using of the `unsafe` package.

WARNING: By using this feature, you acknowledge that you are aware of the risks and accept any current or future consequences of using this feature.

func WithRequiredStructEnabled ¶

func WithRequiredStructEnabled() Option

WithRequiredStructEnabled enables required tag on non-pointer structs to be applied instead of ignored.

This was made opt-in behaviour in order to maintain backward compatibility with the behaviour previous to being able to apply struct level validations on struct fields directly.

NOTE: It is recommended to enabled this.

type StructLevel ¶

type StructLevel interface {
	// Validator returns the main validation object, in case one wants to call validations internally.
	// this is so you don't have to use anonymous functions to get access to the validate instance.
	Validator() *Validate
	// Top returns the top level struct, if any.
	Top() reflect.Value
	// Parent returns the current fields parent struct, if any.
	Parent() reflect.Value
	// Current returns the current struct.
	Current() reflect.Value
	// ExtractType gets the actual underlying type of field value.
	// It will dive into pointers,
	// customTypes and return you the underlying value and its kind.
	ExtractType(field reflect.Value) (value reflect.Value, kind reflect.Kind, nullable bool)
	// ReportError reports an error by simply passing field and tag information.
	//
	// fieldName and structFieldName are appended to the existing namespace that the validator resides on.
	// For example, could pass 'FirstName' or 'Names[0]' depending on the nesting.
	//
	// tag can be an existing validation tag or an arbitrary tag (needs handling).
	ReportError(field interface{}, fieldName, structFieldName string, tag, param string)
	// ReportValidationErrors reports an error just by passing ValidationErrors.
	//
	// relativeNamespace and relativeActualNamespace get appended to the existing namespace that validator is on.
	// For example, could pass 'User.FirstName' or 'Users[0].FirstName' depending on the nesting.
	// Most of the time they will be blank, unless you validate at a level lower the current field depth.
	ReportValidationErrors(relativeNamespace, relativeActualNamespace string, errs ValidationErrors)
}

StructLevel contains all the information and helper functions to validate the structure.

type StructLevelFunc ¶

type StructLevelFunc func(sl StructLevel)

StructLevelFunc accepts all values needed for struct level validation.

type StructLevelFuncCtx ¶

type StructLevelFuncCtx func(ctx context.Context, sl StructLevel)

StructLevelFuncCtx accepts all values needed for struct level validation but also allows passing of contextual validation information via context.Context.

type TagNameFunc ¶

type TagNameFunc func(field reflect.StructField) string

TagNameFunc allows for adding of a custom tag name parser.

type Validate ¶

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

Validate contains the validator settings and cache.

func New ¶

func New(options ...Option) *Validate

New returns a new instance of 'validate' with sane defaults. Validate is designed to be thread-safe and used as a singleton instance. It caches information about your struct and validations, in essence only parsing your validation tags once per struct type. Using multiple instances neglects the benefit of caching.

func (*Validate) RegisterAlias ¶

func (v *Validate) RegisterAlias(alias, tags string)

RegisterAlias registers a mapping of a single validation tag that defines a common or complex set of validation(s) to simplify adding validations to structures.

NOTE: this method is not thread-safe it is intended that these all be registered prior to any validation.

func (*Validate) RegisterCustomTypeFunc ¶

func (v *Validate) RegisterCustomTypeFunc(fn CustomTypeFunc, types ...interface{})

RegisterCustomTypeFunc registers a CustomTypeFunc against a number of types.

NOTE: this method is not thread-safe it is intended that these all be registered prior to any validation.

func (*Validate) RegisterStructValidation ¶

func (v *Validate) RegisterStructValidation(fn StructLevelFunc, types ...interface{})

RegisterStructValidation registers a StructLevelFunc against a number of types.

NOTE: this method is not thread-safe it is intended that these all be registered prior to any validation.

func (*Validate) RegisterStructValidationCtx ¶

func (v *Validate) RegisterStructValidationCtx(fn StructLevelFuncCtx, types ...interface{})

RegisterStructValidationCtx registers a StructLevelFuncCtx against a number of types and allows passing of contextual validation information vis context.Context.

NOTE: this method is not thread-safe it is intended that these all be registered prior to any validation.

func (*Validate) RegisterStructValidationMapRules ¶

func (v *Validate) RegisterStructValidationMapRules(rules map[string]string, types ...interface{})

RegisterStructValidationMapRules registers validate map rules. Be aware that map validation rules supersede those defined on a/the struct if present.

NOTE: this method is not thread-safe it is intended that these all be registered prior to any validation

func (*Validate) RegisterTagNameFunc ¶

func (v *Validate) RegisterTagNameFunc(fn TagNameFunc)

RegisterTagNameFunc registers a function to get alternate names for StructFields. For example, to use the names which have been specified for JSON representations of structs, rather than normal Go field names:

validate.RegisterTagNameFunc(func(fld reflect.StructField) string {
    name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
    // skip if tag key says it should be ignored
    if name == "-" {
        return ""
    }
    return name
})

func (*Validate) RegisterValidation ¶

func (v *Validate) RegisterValidation(tag string, fn Func, callValidationEvenIfNull ...bool) error

RegisterValidation adds a validation with the given tag.

NOTES: If the key already exists, the previous validation function will be replaced. This method is not thread-safe it is intended that these all be registered prior to any validation.

func (*Validate) RegisterValidationCtx ¶

func (v *Validate) RegisterValidationCtx(tag string, fn FuncCtx, callValidationEvenIfNull ...bool) error

RegisterValidationCtx does the same as RegisterValidation on accepts a FuncCtx validation allowing context.Context validation support.

func (*Validate) SetTagName ¶

func (v *Validate) SetTagName(name string)

SetTagName allows for changing of the default tag name of 'validate'.

func (*Validate) Struct ¶

func (v *Validate) Struct(s interface{}) error

Struct validates a structs exposed fields, and automatically validates nested structs, unless otherwise specified.