💯Go Struct and Field validation, including Cross Field, Cross Struct, Map, Slice and Array diving
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Dean Karn d2748d5ae5 Merge pull request #103 from bluesuncorp/v5-development 9 years ago
examples add file and README example 10 years ago
.gitignore add file and README example 10 years ago
.travis.yml update travis.ml for overalls, which is giving nothing but problems! 9 years ago
LICENSE Initial commit 10 years ago
README.md add some benchmarks to readme 10 years ago
baked_in.go added many new validator + tests + documentation: 10 years ago
benchmarks_test.go to use new sync pool remove go 1.2 support 9 years ago
doc.go code cleanup 10 years ago
examples_test.go break out benchmarks into separate file 10 years ago
regexes.go added many new validator + tests + documentation: 10 years ago
validator.go change to use native sync.Pool 9 years ago
validator_test.go add test to ensure 100% of the lines of code are called, even in the pool 10 years ago

README.md

Package validator

Build Status Coverage Status GoDoc

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/bluesuncorp/validator.v5

or to update

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

Then import the validator package into your own code.

import "gopkg.in/bluesuncorp/validator.v5"

Usage and documentation

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

Example:
package main

import (
	"fmt"

	"gopkg.in/bluesuncorp/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	       436 ns/op	     192 B/op	       2 allocs/op
BenchmarkValidateStructSimple-4	  	  500000	      2863 ns/op	     784 B/op	      13 allocs/op
BenchmarkTemplateParallelSimple-4	  500000	      3044 ns/op	     784 B/op	      13 allocs/op
BenchmarkValidateStructLarge-4	  	  100000	     15226 ns/op	    4853 B/op	      74 allocs/op
BenchmarkTemplateParallelLarge-4	  100000	     14637 ns/op	    4856 B/op	      74 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.