zvalidate: zgo.at/zvalidate Index | Files

package zvalidate

import "zgo.at/zvalidate"

Package zvalidate provides simple validation for Go.

Basic usage example:

v := zvalidate.New()
v.Required("firstName", customer.FirstName)
if v.HasErrors() {
    fmt.Println("Had the following validation errors:")
    for key, errors := range v.Errors {
        fmt.Printf("    %s: %s", key, strings.Join(errors))

All validators treat the input's zero type (empty string, 0, nil, etc.) as valid. Use the Required() validator if you want to make a parameter required.

All validators optionally accept a custom message as the last parameter:

v.Required("key", value, "you really need to set this")

The error text only includes a simple human description such as "must be set" or "must be a valid email". When adding new validations, make sure that they can be displayed properly when joined with commas. A text such as "Error: this field must be higher than 42" would look weird:

must be set, Error: this field must be higher than 42

You can set your own errors with v.Append():

if !condition {
    v.Append("key", "must be a valid foo")

Some validators return the parsed value, which makes it easier both validate and get a useful value at the same time:

v := zvalidate.New()
id := v.Integer("id", c.Param("id"))
if v.HasErrors() {
    return v
user := getUserByID(id)


Package Files

messages.go zvalidate.go


var (
    MessageRequired    = "must be set"
    MessageDomain      = "must be a valid domain"
    MessageURL         = "must be a valid url"
    MessageEmail       = "must be a valid email address"
    MessageIPv4        = "must be a valid IPv4 address"
    MessageHexColor    = "must be a valid color code"
    MessageLenLonger   = "must be longer than %d characters"
    MessageLenShorter  = "must be shorter than %d characters"
    MessageExclude     = "cannot be ‘%s’"
    MessageInclude     = "must be one of ‘%s’"
    MessageInteger     = "must be a whole number"
    MessageBool        = "must be a boolean"
    MessageDate        = "must be a date as ‘%s’"
    MessagePhone       = "must be a valid phone number"
    MessageRangeHigher = "must be higher than %d"
    MessageRangeLower  = "must be lower than %d"

Messages for the checkers; this can be changed for i18n.

type Validator Uses

type Validator struct {
    Errors map[string][]string `json:"errors"`

Validator hold the validation errors.

Typically you shouldn't create this directly but use the New() function.

func New Uses

func New() Validator

New makes a new Validator and ensures that it is properly initialized.

func (*Validator) Append Uses

func (v *Validator) Append(key, value string, format ...interface{})

Append a new error to the error list for this key.

func (*Validator) Boolean Uses

func (v *Validator) Boolean(key, value string, message ...string) bool

Boolean checks if this looks like a boolean value.

func (Validator) Code Uses

func (v Validator) Code() int

Code returns the HTTP status code for the error. Satisfies the guru.coder interface in github.com/teamwork/guru.

func (*Validator) Date Uses

func (v *Validator) Date(key, value, layout string, message ...string) time.Time

Date checks if the string looks like a date in the given layout.

func (*Validator) Domain Uses

func (v *Validator) Domain(key, value string, message ...string)

Domain validates that the domain is valid.

A domain must consist of at least two labels. So "com" or "localhost" – while technically valid domain names – are not accepted, whereas "example.com" or "me.localhost" are. For the overwhelming majority of applications this makes the most sense.

This works for internationalized domain names (IDN), either as UTF-8 characters or as punycode.

Limitation: the RFC limits domain labels to 63 bytes, but this validation accepts labels up to 63 *characters*.

TODO: return parsed domain.

func (*Validator) Email Uses

func (v *Validator) Email(key, value string, message ...string) mail.Address

Email validates if this email looks like a valid email address.

func (Validator) Error Uses

func (v Validator) Error() string

Error interface.

func (Validator) ErrorJSON Uses

func (v Validator) ErrorJSON() ([]byte, error)

ErrorJSON for reporting errors as JSON.

func (*Validator) ErrorOrNil Uses

func (v *Validator) ErrorOrNil() error

ErrorOrNil returns nil if there are no errors, or the Validator object if there are.

This makes it a bit more elegant to return from a function:

if v.HasErrors() {
    return v
return nil

Can now be:

return v.ErrorOrNil()

func (*Validator) Exclude Uses

func (v *Validator) Exclude(key, value string, exclude []string, message ...string)

Exclude validates that the value is not in the exclude list.

This list is matched case-insensitive.

func (*Validator) HasErrors Uses

func (v *Validator) HasErrors() bool

HasErrors reports if this validation has any errors.

func (*Validator) HexColor Uses

func (v *Validator) HexColor(key, value string, message ...string) (int, int, int)

HexColor validates if the string looks like a color as a hex triplet (e.g. #ffffff or #fff).

func (*Validator) IPv4 Uses

func (v *Validator) IPv4(key, value string, message ...string) net.IP

IPv4 validates that a string is a valid IPv4 address.

func (*Validator) Include Uses

func (v *Validator) Include(key, value string, include []string, message ...string)

Include validates that the value is in the include list.

This list is matched case-insensitive.

func (*Validator) Integer Uses

func (v *Validator) Integer(key, value string, message ...string) int64

Integer checks if this looks like an integer (i.e. a whole number).

func (*Validator) Len Uses

func (v *Validator) Len(key, value string, min, max int, message ...string) int

Len sets the minimum and maximum length of a string in characters (not bytes).

A maximum of 0 indicates there is no upper limit.

func (*Validator) Merge Uses

func (v *Validator) Merge(other Validator)

Merge errors from another validator in to this one.

func (*Validator) Phone Uses

func (v *Validator) Phone(key, value string, message ...string)

Phone checks if the string looks like a valid phone number.

There are a great amount of writing conventions for phone numbers: https://en.wikipedia.org/wiki/National_conventions_for_writing_telephone_numbers

This merely checks a field contains 5 to 20 characters "0123456789+\-() .", which is not very strict but should cover all conventions.

TODO: return parsed phone number.

func (*Validator) Range Uses

func (v *Validator) Range(key string, value, min, max int64, message ...string)

Range sets the minimum and maximum value of a integer.

A maximum of 0 indicates there is no upper limit.

func (*Validator) Required Uses

func (v *Validator) Required(key string, value interface{}, message ...string)

Required indicates that this value must not be the type's zero value.

Currently supported types are string, int, int64, uint, and uint64. It will panic if the type is not supported.

func (*Validator) String Uses

func (v *Validator) String() string

Strings representation shows either all errors or "<no errors>" if there are no errors.

func (*Validator) Sub Uses

func (v *Validator) Sub(key, subKey string, err error)

Sub allows to specific sub-validations.

Errors from the subvalidation are merged with the top-level one, the keys are added as "top.sub" or "top[n].sub".

If the error is not a Validator the text will be added as just the key name without subkey (i.e. the same as v.Append("key", "msg")).

For example:

v := zvalidate.New()
v.Required("name", customer.Name)

// e.g. "settings.domain"
v.Sub("settings", -1, customer.Settings.Validate())

// e.g. "addresses[1].city"
for i, a := range customer.Addresses {
    a.Sub("addresses", i, c.Validate())

func (*Validator) URL Uses

func (v *Validator) URL(key, value string, message ...string) *url.URL

URL validates that the string contains a valid URL.

The URL may consist of a scheme, host, path, and query parameters. Only the host is required.

The host is validated with the Domain() validation.

If the scheme is not given "http" will be prepended.

Package zvalidate imports 11 packages (graph) and is imported by 6 packages. Updated 2019-12-16. Refresh now. Tools for package owners.