status-go/vendor/gopkg.in/go-playground/validator.v9/README.md

12 KiB

Package validator

Join the chat at https://gitter.im/go-playground/validator Project status Build Status Coverage Status Go Report Card GoDoc License

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 by using validation tags or custom validators.
  • Slice, Array and Map diving, which allows any or all levels of a multidimensional field to be validated.
  • Ability to dive into both map keys and values for validation
  • Handles type interface by determining it's underlying type prior to validation.
  • Handles custom field types such as sql driver Valuer see Valuer
  • Alias validation tags, which allows for mapping of several validations to a single tag for easier defining of validations on structs
  • Extraction of custom defined Field Name e.g. can specify to extract the JSON name while validating and have it available in the resulting FieldError
  • Customizable i18n aware error messages.
  • Default validator for the gin web framework; upgrading from v8 to v9 in gin see here

Installation

Use go get.

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

Then import the validator package into your own code.

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

Error Return Value

Validation functions return type error

They return type error to avoid the issue discussed in the following, where err is always != nil:

Validator only InvalidValidationError for bad validation input, nil or ValidationErrors as type error; so, in your code all you need to do is check if the error returned is not nil, and if it's not check if error is InvalidValidationError ( if necessary, most of the time it isn't ) type cast it to type ValidationErrors like so:

err := validate.Struct(mystruct)
validationErrors := err.(validator.ValidationErrors)

Usage and documentation

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

Examples:

Benchmarks

Run on MacBook Pro (15-inch, 2017) Go version go1.9.2 darwin/amd64
go test -bench=. -benchmem=true
BenchmarkFieldSuccess-8                                       	20000000	        79.9 ns/op	       0 B/op	       0 allocs/op
BenchmarkFieldSuccessParallel-8                               	50000000	        25.0 ns/op	       0 B/op	       0 allocs/op
BenchmarkFieldFailure-8                                       	 5000000	       281 ns/op	     208 B/op	       4 allocs/op
BenchmarkFieldFailureParallel-8                               	20000000	        97.0 ns/op	     208 B/op	       4 allocs/op
BenchmarkFieldArrayDiveSuccess-8                              	 3000000	       591 ns/op	     201 B/op	      11 allocs/op
BenchmarkFieldArrayDiveSuccessParallel-8                      	10000000	       195 ns/op	     201 B/op	      11 allocs/op
BenchmarkFieldArrayDiveFailure-8                              	 2000000	       878 ns/op	     412 B/op	      16 allocs/op
BenchmarkFieldArrayDiveFailureParallel-8                      	 5000000	       274 ns/op	     413 B/op	      16 allocs/op
BenchmarkFieldMapDiveSuccess-8                                	 1000000	      1279 ns/op	     432 B/op	      18 allocs/op
BenchmarkFieldMapDiveSuccessParallel-8                        	 5000000	       401 ns/op	     432 B/op	      18 allocs/op
BenchmarkFieldMapDiveFailure-8                                	 1000000	      1060 ns/op	     512 B/op	      16 allocs/op
BenchmarkFieldMapDiveFailureParallel-8                        	 5000000	       334 ns/op	     512 B/op	      16 allocs/op
BenchmarkFieldMapDiveWithKeysSuccess-8                        	 1000000	      1462 ns/op	     480 B/op	      21 allocs/op
BenchmarkFieldMapDiveWithKeysSuccessParallel-8                	 3000000	       463 ns/op	     480 B/op	      21 allocs/op
BenchmarkFieldMapDiveWithKeysFailure-8                        	 1000000	      1414 ns/op	     721 B/op	      21 allocs/op
BenchmarkFieldMapDiveWithKeysFailureParallel-8                	 3000000	       446 ns/op	     721 B/op	      21 allocs/op
BenchmarkFieldCustomTypeSuccess-8                             	10000000	       211 ns/op	      32 B/op	       2 allocs/op
BenchmarkFieldCustomTypeSuccessParallel-8                     	20000000	        65.9 ns/op	      32 B/op	       2 allocs/op
BenchmarkFieldCustomTypeFailure-8                             	 5000000	       270 ns/op	     208 B/op	       4 allocs/op
BenchmarkFieldCustomTypeFailureParallel-8                     	20000000	        93.3 ns/op	     208 B/op	       4 allocs/op
BenchmarkFieldOrTagSuccess-8                                  	 2000000	       729 ns/op	      16 B/op	       1 allocs/op
BenchmarkFieldOrTagSuccessParallel-8                          	 5000000	       367 ns/op	      16 B/op	       1 allocs/op
BenchmarkFieldOrTagFailure-8                                  	 3000000	       472 ns/op	     224 B/op	       5 allocs/op
BenchmarkFieldOrTagFailureParallel-8                          	 5000000	       373 ns/op	     224 B/op	       5 allocs/op
BenchmarkStructLevelValidationSuccess-8                       	10000000	       201 ns/op	      32 B/op	       2 allocs/op
BenchmarkStructLevelValidationSuccessParallel-8               	20000000	        66.3 ns/op	      32 B/op	       2 allocs/op
BenchmarkStructLevelValidationFailure-8                       	 3000000	       468 ns/op	     304 B/op	       8 allocs/op
BenchmarkStructLevelValidationFailureParallel-8               	10000000	       172 ns/op	     304 B/op	       8 allocs/op
BenchmarkStructSimpleCustomTypeSuccess-8                      	 5000000	       376 ns/op	      32 B/op	       2 allocs/op
BenchmarkStructSimpleCustomTypeSuccessParallel-8              	20000000	       126 ns/op	      32 B/op	       2 allocs/op
BenchmarkStructSimpleCustomTypeFailure-8                      	 2000000	       646 ns/op	     424 B/op	       9 allocs/op
BenchmarkStructSimpleCustomTypeFailureParallel-8              	10000000	       240 ns/op	     440 B/op	      10 allocs/op
BenchmarkStructFilteredSuccess-8                              	 3000000	       582 ns/op	     288 B/op	       9 allocs/op
BenchmarkStructFilteredSuccessParallel-8                      	10000000	       198 ns/op	     288 B/op	       9 allocs/op
BenchmarkStructFilteredFailure-8                              	 3000000	       447 ns/op	     256 B/op	       7 allocs/op
BenchmarkStructFilteredFailureParallel-8                      	10000000	       156 ns/op	     256 B/op	       7 allocs/op
BenchmarkStructPartialSuccess-8                               	 3000000	       536 ns/op	     256 B/op	       6 allocs/op
BenchmarkStructPartialSuccessParallel-8                       	10000000	       175 ns/op	     256 B/op	       6 allocs/op
BenchmarkStructPartialFailure-8                               	 2000000	       738 ns/op	     480 B/op	      11 allocs/op
BenchmarkStructPartialFailureParallel-8                       	 5000000	       256 ns/op	     480 B/op	      11 allocs/op
BenchmarkStructExceptSuccess-8                                	 2000000	       835 ns/op	     496 B/op	      12 allocs/op
BenchmarkStructExceptSuccessParallel-8                        	10000000	       163 ns/op	     240 B/op	       5 allocs/op
BenchmarkStructExceptFailure-8                                	 2000000	       682 ns/op	     464 B/op	      10 allocs/op
BenchmarkStructExceptFailureParallel-8                        	10000000	       244 ns/op	     464 B/op	      10 allocs/op
BenchmarkStructSimpleCrossFieldSuccess-8                      	 5000000	       392 ns/op	      72 B/op	       3 allocs/op
BenchmarkStructSimpleCrossFieldSuccessParallel-8              	20000000	       126 ns/op	      72 B/op	       3 allocs/op
BenchmarkStructSimpleCrossFieldFailure-8                      	 2000000	       611 ns/op	     304 B/op	       8 allocs/op
BenchmarkStructSimpleCrossFieldFailureParallel-8              	10000000	       214 ns/op	     304 B/op	       8 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccess-8           	 3000000	       567 ns/op	      80 B/op	       4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-8   	10000000	       177 ns/op	      80 B/op	       4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailure-8           	 2000000	       807 ns/op	     320 B/op	       9 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-8   	 5000000	       268 ns/op	     320 B/op	       9 allocs/op
BenchmarkStructSimpleSuccess-8                                	 5000000	       256 ns/op	       0 B/op	       0 allocs/op
BenchmarkStructSimpleSuccessParallel-8                        	20000000	        76.3 ns/op	       0 B/op	       0 allocs/op
BenchmarkStructSimpleFailure-8                                	 2000000	       625 ns/op	     424 B/op	       9 allocs/op
BenchmarkStructSimpleFailureParallel-8                        	10000000	       219 ns/op	     424 B/op	       9 allocs/op
BenchmarkStructComplexSuccess-8                               	 1000000	      1431 ns/op	     128 B/op	       8 allocs/op
BenchmarkStructComplexSuccessParallel-8                       	 3000000	       427 ns/op	     128 B/op	       8 allocs/op
BenchmarkStructComplexFailure-8                               	  300000	      4065 ns/op	    3041 B/op	      53 allocs/op
BenchmarkStructComplexFailureParallel-8                       	 1000000	      1478 ns/op	    3041 B/op	      53 allocs/op

Complementary Software

Here is a list of software that complements using this library either pre or post validation.

  • form - Decodes url.Values into Go value(s) and Encodes Go value(s) into url.Values. Dual Array and Full map support.
  • mold - A general library to help modify or set data within data structures and other objects

How to Contribute

Make a pull request...

License

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