validator/README.md

Package validator

Package validator implements value validations for structs and individual fields based on tags.

It has the following unique features:

• Cross Field and Cross Struct validations.
• Slice, Array and Map diving, which allows any or all levels of a multidimensional field to be validated.
• Handles type interface by determining it's underlying type prior to validation.

Installation

Use go get.

go get gopkg.in/go-playground/validator.v5

or to update

go get -u gopkg.in/go-playground/validator.v5

Then import the validator package into your own code.

import "gopkg.in/go-playground/validator.v5"

Usage and documentation

Please see http://godoc.org/gopkg.in/go-playground/validator.v5 for detailed usage docs.

Example:

package main

import (
	"fmt"

	"gopkg.in/go-playground/validator.v5"
)

// User contains user information
type User struct {
	FirstName      string     `validate:"required"`
	LastName       string     `validate:"required"`
	Age            uint8      `validate:"gte=0,lte=130"`
	Email          string     `validate:"required,email"`
	FavouriteColor string     `validate:"hexcolor|rgb|rgba"`
	Addresses      []*Address `validate:"required,dive,required"` // a person can have a home and cottage...
}

// Address houses a users address information
type Address struct {
	Street string `validate:"required"`
	City   string `validate:"required"`
	Planet string `validate:"required"`
	Phone  string `validate:"required"`
}

var validate *validator.Validate

func main() {

	validate = validator.New("validate", validator.BakedInValidators)

	address := &Address{
		Street: "Eavesdown Docks",
		Planet: "Persphone",
		Phone:  "none",
	}

	user := &User{
		FirstName:      "Badger",
		LastName:       "Smith",
		Age:            135,
		Email:          "Badger.Smith@gmail.com",
		FavouriteColor: "#000",
		Addresses:      []*Address{address},
	}

	// returns nil or *StructErrors
	errs := validate.Struct(user)

	if errs != nil {

		// err will be of type *FieldError
		err := errs.Errors["Age"]
		fmt.Println(err.Error()) // output: Field validation for "Age" failed on the "lte" tag
		fmt.Println(err.Field)   // output: Age
		fmt.Println(err.Tag)     // output: lte
		fmt.Println(err.Kind)    // output: uint8
		fmt.Println(err.Type)    // output: uint8
		fmt.Println(err.Param)   // output: 130
		fmt.Println(err.Value)   // output: 135

		// or if you prefer you can use the Flatten function
		// NOTE: I find this usefull when using a more hard static approach of checking field errors.
		// The above, is best for passing to some generic code to say parse the errors. i.e. I pass errs
		// to a routine which loops through the errors, creates and translates the error message into the
		// users locale and returns a map of map[string]string // field and error which I then use
		// within the HTML rendering.

		flat := errs.Flatten()
		fmt.Println(flat) // output: map[Age:Field validation for "Age" failed on the "lte" tag Addresses[0].Address.City:Field validation for "City" failed on the "required" tag]
		err = flat["Addresses[0].Address.City"]
		fmt.Println(err.Field) // output: City
		fmt.Println(err.Tag)   // output: required
		fmt.Println(err.Kind)  // output: string
		fmt.Println(err.Type)  // output: string
		fmt.Println(err.Param) // output:
		fmt.Println(err.Value) // output:

		// from here you can create your own error messages in whatever language you wish
		return
	}

	// save user to database
}

Benchmarks

Run on MacBook Pro (Retina, 15-inch, Late 2013) 2.6 GHz Intel Core i7 16 GB 1600 MHz DDR3

$ go test -cpu=4 -bench=. -benchmem=true
PASS
BenchmarkValidateField-4	 		 3000000	       429 ns/op	     192 B/op	       2 allocs/op
BenchmarkValidateStructSimple-4	  	  500000	      2877 ns/op	     657 B/op	      10 allocs/op
BenchmarkTemplateParallelSimple-4	  500000	      3097 ns/op	     657 B/op	      10 allocs/op
BenchmarkValidateStructLarge-4	  	  100000	     15228 ns/op	    4350 B/op	      62 allocs/op
BenchmarkTemplateParallelLarge-4	  100000	     14257 ns/op	    4354 B/op	      62 allocs/op

How to Contribute

There will always be a development branch for each version i.e. v1-development. In order to contribute, please make your pull requests against those branches.

If the changes being proposed or requested are breaking changes, please create an issue, for discussion or create a pull request against the highest development branch for example this package has a v1 and v1-development branch however, there will also be a v2-development brach even though v2 doesn't exist yet.

I strongly encourage everyone whom creates a custom validation function to contribute them and help make this package even better.

License

Distributed under MIT License, please see license file in code for more details.