Tags Reference

govalid reads three struct tags. Their default names are configurable via three package-level variables, set them once at startup if you need a different namespace.

Tag	Default name	Variable
Validation rules	valid	govalid.RulesField
Field label	label	govalid.LabelField
Override message	msg	govalid.MessageField

// e.g. coexist with another tag namespace
govalid.RulesField = "validate"
govalid.LabelField = "name"

valid — rule list

valid is a ;-separated list of rules. Each rule is either:

• A bare checker name: required
• A checker with parameters separated by ,: min:0, list:a,b,c

`valid:"required;min:18;max:120"`
`valid:"required;username;minlen:3;maxlen:20"`
`valid:"list:admin,editor,viewer"`

Parser quirks

• Trailing or leading ; are tolerated and ignored.
• Empty rules between ;; are skipped.
• Empty parameter lists like valid:"required:" produce a single empty param, which most checkers reject as a parameter error.
• Anything after the first : is the parameter string verbatim — so url:http://example.com parses to checker url with one param http://example.com.

Rule execution semantics

Rules execute left to right. Each failure produces an *ErrContext, and execution continues to the next rule unless the field has a msg override (see below).

type Form struct {
    Score int `valid:"required;min:0;max:100" label:"得分"`
}
// Score = -1 → "得分应大于0"
// Score = 200 → "得分应小于100"
// Score = 0 → no error

label — human-friendly name

label is prepended to error messages. Without it govalid falls back to the Go field name.

type Form struct {
    Email string `valid:"required" label:"电子邮箱"`
}
// → "电子邮箱不能为空"

Per-locale labels

You can attach localized labels with label-<lang> tags. The lang suffix matches language.Tag.String():

type Form struct {
    Email string `valid:"required" label:"邮箱" label-en:"Email"`
}

govalid.Check(form, language.English)
// → "Email can not be empty"

The lookup order for each Check call is:

1. label-<lang> for the requested locale
2. label (the unsuffixed default)
3. The Go field name

msg — override the message

msg replaces the entire error message for the first failing rule of that field. Subsequent rules are not evaluated.

type Form struct {
    Password string `valid:"required;minlen:8;maxlen:64" label:"密码" msg:"密码长度需在 8-64 之间"`
}
// Empty password → "密码长度需在 8-64 之间"
// 4-character password → "密码长度需在 8-64 之间"

TIP

Use msg when product copy is more important than fine-grained reasons. For multi-message UIs, omit msg and let the locale's templates do the talking.

Tag combination cheat-sheet

type Profile struct {
    // Required + format check, default Chinese label.
    Email string `valid:"required;email" label:"邮箱"`

    // Optional but format-checked when present.
    Backup string `valid:"email"          label:"备用邮箱"`

    // Custom message overrides everything.
    Phone  string `valid:"required;mobile" label:"手机号" msg:"请输入有效的手机号"`

    // Locale-specific labels.
    Name   string `valid:"required" label:"姓名" label-en:"Name"`

    // Cross-field reference uses the Go field name.
    Repeat string `valid:"equal:Password"`
}