Built-in Checkers

govalid ships 17 checkers registered in the global Checkers map. Every checker accepts the same CheckerContext and returns *ErrContext on failure.

Empty string short-circuit

Format-style checkers (alpha, alphanumeric, alphadash, username, email, ipv4, mobile, tel, phone, idcard) treat the empty string as valid. Combine them with required to reject empty inputs. This makes optional fields trivial to model.

Presence

required

Field must not be its zero / empty form.

Kind	Failure condition
string, slice, array, map, chan	length is 0
pointer, interface, func	value is nil
Other comparable kinds	value equals the zero value
Incomparable struct types	rule is skipped (no panic)

type Form struct {
    Name string            `valid:"required"`
    Tags []string          `valid:"required"`
    Cfg  *Config           `valid:"required"`
    Meta map[string]string `valid:"required"`
}

Numeric range

min:N

Field must be >= N. Works on signed ints, unsigned ints and floats.

type Form struct {
    Age   uint    `valid:"min:18"`
    Score float64 `valid:"min:0"`
}

max:N

Field must be <= N. Works on signed ints, unsigned ints and floats.

type Form struct {
    Age uint `valid:"min:18;max:120"`
}

WARNING

NaN values neither fail min nor max because IEEE 754 NaN comparisons are always false. Reject them explicitly with a custom checker if it matters for your domain.

Length

minlen:N

Length is >= N. Strings are counted in runes (so "中文" has length 2). Works on string, slice, array, map.

maxlen:N

Length is <= N.

type Comment struct {
    Body string   `valid:"minlen:1;maxlen:280"`
    Tags []string `valid:"maxlen:5"`
}

Strings

alpha

ASCII letters only (a-z, A-Z).

alphanumeric

ASCII letters or digits.

alphadash

Letters, digits, or underscores (\w+). Note that - is not included.

username

alphadash plus two extra rules:

1. The first character (rune) must be an ASCII letter.
2. The last character must not be _.

type Form struct {
    Username string `valid:"required;username;minlen:3;maxlen:20"`
}

Format

email

Email address. Allows +tag addressing, dotted local parts, multi-level domains.

ipv4

Dotted-quad IPv4 address (0.0.0.0 to 255.255.255.255).

mobile

Chinese mobile phone number. Optional +86 or 86 country prefix. Pattern is exposed as MobilePattern if you want to swap it.

tel

Chinese landline number. Optional area code with optional -.

phone

Either mobile or tel. Returns the dedicated phone error template — not the underlying mobile/tel ones — when both fail.

idcard

Chinese resident ID card: 15 digits, or 17 digits + final check character (0-9, X, x).

type Profile struct {
    Email   string `valid:"email"`
    HomeIP  string `valid:"ipv4"`
    Mobile  string `valid:"required;mobile"`
    IDCard  string `valid:"idcard"`
}

Cross-field

equal:OtherField

Stringified value must match another field of the surrounding struct. The compared field is referenced by its Go name, not its label.

type Form struct {
    Password       string `valid:"required;minlen:8" label:"密码"`
    RepeatPassword string `valid:"equal:Password"   label:"重复密码"`
}

If the referenced field doesn't exist, the rule fails with a field not found error rather than silently passing.

Enumeration

list:a,b,c

Stringified field value must be one of the comma-separated allowed values. Works on any kind because fmt.Sprintf("%v", value) is used for comparison.

type User struct {
    Role string `valid:"list:admin,editor,viewer"`
}

TIP

Because list stringifies the value, you can use it on numbers, bools or even custom types whose %v representation is stable:

type Settings struct {
    Verbosity int `valid:"list:0,1,2,3"`
}

Reference table

Rule	Parameters	Applies to	Empty string short-circuit
required	—	any	no
min:N	one number	int / uint / float	—
max:N	one number	int / uint / float	—
minlen:N	one int	string / slice / array / map	yes
maxlen:N	one int	string / slice / array / map	yes
alpha	—	string	yes
alphanumeric	—	string	yes
alphadash	—	string	yes
username	—	string	yes
email	—	string	yes
ipv4	—	string	yes
mobile	—	string	yes
tel	—	string	yes
phone	—	string	yes
idcard	—	string	yes
equal:Field	one field name	any	no
list:a,b,c	one or more values	any (stringified)	no

Need something else? See Custom Checkers.