💯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.
validator/README.md

137 lines
10 KiB

10 years ago
Package validator
10 years ago
================
8 years ago
<img align="right" src="https://raw.githubusercontent.com/go-playground/validator/v9/logo.png">
[![Join the chat at https://gitter.im/go-playground/validator](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/go-playground/validator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
![Project status](https://img.shields.io/badge/version-9.1.0-green.svg)
[![Build Status](https://semaphoreci.com/api/v1/joeybloggs/validator/branches/v9/badge.svg)](https://semaphoreci.com/joeybloggs/validator)
8 years ago
[![Coverage Status](https://coveralls.io/repos/go-playground/validator/badge.svg?branch=v9&service=github)](https://coveralls.io/github/go-playground/validator?branch=v9)
[![Go Report Card](https://goreportcard.com/badge/github.com/go-playground/validator)](https://goreportcard.com/report/github.com/go-playground/validator)
8 years ago
[![GoDoc](https://godoc.org/gopkg.in/go-playground/validator.v9?status.svg)](https://godoc.org/gopkg.in/go-playground/validator.v9)
9 years ago
![License](https://img.shields.io/dub/l/vibe-d.svg)
10 years ago
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.
- Handles type interface by determining it's underlying type prior to validation.
- Handles custom field types such as sql driver Valuer see [Valuer](https://golang.org/src/database/sql/driver/types.go?s=1210:1293#L29)
- Alias validation tags, which allows for mapping of several validations to a single tag for easier defining of validations on structs
9 years ago
- 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
8 years ago
- Customizable i18n aware error messages.
- Default validator for the [gin](https://github.com/gin-gonic/gin) web framework; upgrading from v8 to v9 in gin see [here](https://github.com/go-playground/validator/tree/v9/examples/gin-upgrading-overriding)
10 years ago
Installation
------------
10 years ago
Use go get.
10 years ago
8 years ago
go get gopkg.in/go-playground/validator.v9
10 years ago
Then import the validator package into your own code.
10 years ago
8 years ago
import "gopkg.in/go-playground/validator.v9"
10 years ago
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:
* http://stackoverflow.com/a/29138676/3158232
* https://github.com/go-playground/validator/issues/134
8 years ago
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:
```go
err := validate.Struct(mystruct)
validationErrors := err.(validator.ValidationErrors)
```
Usage and documentation
------
10 years ago
8 years ago
Please see http://godoc.org/gopkg.in/go-playground/validator.v9 for detailed usage docs.
##### Examples:
- [Simple](https://github.com/go-playground/validator/blob/v9/examples/simple/main.go)
- [Custom Field Types](https://github.com/go-playground/validator/blob/v9/examples/custom/main.go)
- [Struct Level](https://github.com/go-playground/validator/blob/v9/examples/struct-level/main.go)
- [Translations & Custom Errors](https://github.com/go-playground/validator/blob/v9/examples/translations/main.go)
- [Gin upgrade and/or override validator](https://github.com/go-playground/validator/tree/v9/examples/gin-upgrading-overriding)
- [wash - an example application putting it all together](https://github.com/bluesuncorp/wash)
Benchmarks
------
Update benchmarks run against Go 1.7 Go 1.7 some nice boosts, for nothing! ``` benchmark old ns/op new ns/op delta BenchmarkFieldSuccess-8 147 108 -26.53% BenchmarkFieldSuccessParallel-8 42.5 35.7 -16.00% BenchmarkFieldFailure-8 417 320 -23.26% BenchmarkFieldFailureParallel-8 140 113 -19.29% BenchmarkFieldDiveSuccess-8 876 726 -17.12% BenchmarkFieldDiveSuccessParallel-8 277 263 -5.05% BenchmarkFieldDiveFailure-8 1185 939 -20.76% BenchmarkFieldDiveFailureParallel-8 402 382 -4.98% BenchmarkFieldCustomTypeSuccess-8 321 268 -16.51% BenchmarkFieldCustomTypeSuccessParallel-8 104 87.8 -15.58% BenchmarkFieldCustomTypeFailure-8 416 310 -25.48% BenchmarkFieldCustomTypeFailureParallel-8 150 131 -12.67% BenchmarkFieldOrTagSuccess-8 1119 889 -20.55% BenchmarkFieldOrTagSuccessParallel-8 462 418 -9.52% BenchmarkFieldOrTagFailure-8 715 546 -23.64% BenchmarkFieldOrTagFailureParallel-8 436 450 +3.21% BenchmarkStructLevelValidationSuccess-8 399 336 -15.79% BenchmarkStructLevelValidationSuccessParallel-8 140 123 -12.14% BenchmarkStructLevelValidationFailure-8 749 611 -18.42% BenchmarkStructLevelValidationFailureParallel-8 296 298 +0.68% BenchmarkStructSimpleCustomTypeSuccess-8 673 555 -17.53% BenchmarkStructSimpleCustomTypeSuccessParallel-8 213 197 -7.51% BenchmarkStructSimpleCustomTypeFailure-8 1056 811 -23.20% BenchmarkStructSimpleCustomTypeFailureParallel-8 450 370 -17.78% BenchmarkStructPartialSuccess-8 789 676 -14.32% BenchmarkStructPartialSuccessParallel-8 307 301 -1.95% BenchmarkStructPartialFailure-8 1105 1001 -9.41% BenchmarkStructPartialFailureParallel-8 493 436 -11.56% BenchmarkStructExceptSuccess-8 1212 1038 -14.36% BenchmarkStructExceptSuccessParallel-8 282 281 -0.35% BenchmarkStructExceptFailure-8 1004 863 -14.04% BenchmarkStructExceptFailureParallel-8 452 379 -16.15% BenchmarkStructSimpleCrossFieldSuccess-8 656 549 -16.31% BenchmarkStructSimpleCrossFieldSuccessParallel-8 211 192 -9.00% BenchmarkStructSimpleCrossFieldFailure-8 968 783 -19.11% BenchmarkStructSimpleCrossFieldFailureParallel-8 406 296 -27.09% BenchmarkStructSimpleCrossStructCrossFieldSuccess-8 1000 837 -16.30% BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-8 334 284 -14.97% BenchmarkStructSimpleCrossStructCrossFieldFailure-8 1324 1110 -16.16% BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-8 520 416 -20.00% BenchmarkStructSimpleSuccess-8 534 380 -28.84% BenchmarkStructSimpleSuccessParallel-8 144 114 -20.83% BenchmarkStructSimpleFailure-8 1039 760 -26.85% BenchmarkStructSimpleFailureParallel-8 419 353 -15.75% BenchmarkStructComplexSuccess-8 2678 2100 -21.58% BenchmarkStructComplexSuccessParallel-8 874 662 -24.26% BenchmarkStructComplexFailure-8 6342 5080 -19.90% BenchmarkStructComplexFailureParallel-8 2875 2159 -24.90% benchmark old allocs new allocs delta BenchmarkFieldSuccess-8 0 0 +0.00% BenchmarkFieldSuccessParallel-8 0 0 +0.00% BenchmarkFieldFailure-8 4 4 +0.00% BenchmarkFieldFailureParallel-8 4 4 +0.00% BenchmarkFieldDiveSuccess-8 11 11 +0.00% BenchmarkFieldDiveSuccessParallel-8 11 11 +0.00% BenchmarkFieldDiveFailure-8 16 16 +0.00% BenchmarkFieldDiveFailureParallel-8 16 16 +0.00% BenchmarkFieldCustomTypeSuccess-8 2 2 +0.00% BenchmarkFieldCustomTypeSuccessParallel-8 2 2 +0.00% BenchmarkFieldCustomTypeFailure-8 4 4 +0.00% BenchmarkFieldCustomTypeFailureParallel-8 4 4 +0.00% BenchmarkFieldOrTagSuccess-8 1 1 +0.00% BenchmarkFieldOrTagSuccessParallel-8 1 1 +0.00% BenchmarkFieldOrTagFailure-8 5 5 +0.00% BenchmarkFieldOrTagFailureParallel-8 5 5 +0.00% BenchmarkStructLevelValidationSuccess-8 2 2 +0.00% BenchmarkStructLevelValidationSuccessParallel-8 2 2 +0.00% BenchmarkStructLevelValidationFailure-8 8 8 +0.00% BenchmarkStructLevelValidationFailureParallel-8 8 8 +0.00% BenchmarkStructSimpleCustomTypeSuccess-8 2 2 +0.00% BenchmarkStructSimpleCustomTypeSuccessParallel-8 2 2 +0.00% BenchmarkStructSimpleCustomTypeFailure-8 9 9 +0.00% BenchmarkStructSimpleCustomTypeFailureParallel-8 10 10 +0.00% BenchmarkStructPartialSuccess-8 6 6 +0.00% BenchmarkStructPartialSuccessParallel-8 6 6 +0.00% BenchmarkStructPartialFailure-8 11 11 +0.00% BenchmarkStructPartialFailureParallel-8 11 11 +0.00% BenchmarkStructExceptSuccess-8 12 12 +0.00% BenchmarkStructExceptSuccessParallel-8 5 5 +0.00% BenchmarkStructExceptFailure-8 10 10 +0.00% BenchmarkStructExceptFailureParallel-8 10 10 +0.00% BenchmarkStructSimpleCrossFieldSuccess-8 3 3 +0.00% BenchmarkStructSimpleCrossFieldSuccessParallel-8 3 3 +0.00% BenchmarkStructSimpleCrossFieldFailure-8 8 8 +0.00% BenchmarkStructSimpleCrossFieldFailureParallel-8 8 8 +0.00% BenchmarkStructSimpleCrossStructCrossFieldSuccess-8 4 4 +0.00% BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-8 4 4 +0.00% BenchmarkStructSimpleCrossStructCrossFieldFailure-8 9 9 +0.00% BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-8 9 9 +0.00% BenchmarkStructSimpleSuccess-8 0 0 +0.00% BenchmarkStructSimpleSuccessParallel-8 0 0 +0.00% BenchmarkStructSimpleFailure-8 9 9 +0.00% BenchmarkStructSimpleFailureParallel-8 9 9 +0.00% BenchmarkStructComplexSuccess-8 8 8 +0.00% BenchmarkStructComplexSuccessParallel-8 8 8 +0.00% BenchmarkStructComplexFailure-8 53 53 +0.00% BenchmarkStructComplexFailureParallel-8 53 53 +0.00% benchmark old bytes new bytes delta BenchmarkFieldSuccess-8 0 0 +0.00% BenchmarkFieldSuccessParallel-8 0 0 +0.00% BenchmarkFieldFailure-8 192 192 +0.00% BenchmarkFieldFailureParallel-8 192 192 +0.00% BenchmarkFieldDiveSuccess-8 201 201 +0.00% BenchmarkFieldDiveSuccessParallel-8 201 201 +0.00% BenchmarkFieldDiveFailure-8 396 396 +0.00% BenchmarkFieldDiveFailureParallel-8 397 397 +0.00% BenchmarkFieldCustomTypeSuccess-8 32 32 +0.00% BenchmarkFieldCustomTypeSuccessParallel-8 32 32 +0.00% BenchmarkFieldCustomTypeFailure-8 192 192 +0.00% BenchmarkFieldCustomTypeFailureParallel-8 192 192 +0.00% BenchmarkFieldOrTagSuccess-8 16 16 +0.00% BenchmarkFieldOrTagSuccessParallel-8 16 16 +0.00% BenchmarkFieldOrTagFailure-8 208 208 +0.00% BenchmarkFieldOrTagFailureParallel-8 208 208 +0.00% BenchmarkStructLevelValidationSuccess-8 32 32 +0.00% BenchmarkStructLevelValidationSuccessParallel-8 32 32 +0.00% BenchmarkStructLevelValidationFailure-8 288 288 +0.00% BenchmarkStructLevelValidationFailureParallel-8 288 288 +0.00% BenchmarkStructSimpleCustomTypeSuccess-8 32 32 +0.00% BenchmarkStructSimpleCustomTypeSuccessParallel-8 32 32 +0.00% BenchmarkStructSimpleCustomTypeFailure-8 392 392 +0.00% BenchmarkStructSimpleCustomTypeFailureParallel-8 408 408 +0.00% BenchmarkStructPartialSuccess-8 256 256 +0.00% BenchmarkStructPartialSuccessParallel-8 256 256 +0.00% BenchmarkStructPartialFailure-8 464 464 +0.00% BenchmarkStructPartialFailureParallel-8 464 464 +0.00% BenchmarkStructExceptSuccess-8 480 480 +0.00% BenchmarkStructExceptSuccessParallel-8 240 240 +0.00% BenchmarkStructExceptFailure-8 448 448 +0.00% BenchmarkStructExceptFailureParallel-8 448 448 +0.00% BenchmarkStructSimpleCrossFieldSuccess-8 72 72 +0.00% BenchmarkStructSimpleCrossFieldSuccessParallel-8 72 72 +0.00% BenchmarkStructSimpleCrossFieldFailure-8 288 288 +0.00% BenchmarkStructSimpleCrossFieldFailureParallel-8 288 288 +0.00% BenchmarkStructSimpleCrossStructCrossFieldSuccess-8 80 80 +0.00% BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-8 80 80 +0.00% BenchmarkStructSimpleCrossStructCrossFieldFailure-8 304 304 +0.00% BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-8 304 304 +0.00% BenchmarkStructSimpleSuccess-8 0 0 +0.00% BenchmarkStructSimpleSuccessParallel-8 0 0 +0.00% BenchmarkStructSimpleFailure-8 392 392 +0.00% BenchmarkStructSimpleFailureParallel-8 392 392 +0.00% BenchmarkStructComplexSuccess-8 128 128 +0.00% BenchmarkStructComplexSuccessParallel-8 128 128 +0.00% BenchmarkStructComplexFailure-8 2833 2833 +0.00% BenchmarkStructComplexFailureParallel-8 2833 2833 +0.00% ```
8 years ago
###### Run on MacBook Pro (Retina, 15-inch, Late 2013) 2.6 GHz Intel Core i7 16 GB 1600 MHz DDR3 using Go version go1.7 darwin/amd64
```go
BenchmarkFieldSuccess-8 20000000 105 ns/op 0 B/op 0 allocs/op
BenchmarkFieldSuccessParallel-8 50000000 35.1 ns/op 0 B/op 0 allocs/op
BenchmarkFieldFailure-8 5000000 337 ns/op 208 B/op 4 allocs/op
BenchmarkFieldFailureParallel-8 20000000 120 ns/op 208 B/op 4 allocs/op
BenchmarkFieldDiveSuccess-8 2000000 716 ns/op 201 B/op 11 allocs/op
BenchmarkFieldDiveSuccessParallel-8 10000000 253 ns/op 201 B/op 11 allocs/op
BenchmarkFieldDiveFailure-8 1000000 1060 ns/op 412 B/op 16 allocs/op
BenchmarkFieldDiveFailureParallel-8 5000000 360 ns/op 413 B/op 16 allocs/op
BenchmarkFieldCustomTypeSuccess-8 5000000 299 ns/op 32 B/op 2 allocs/op
BenchmarkFieldCustomTypeSuccessParallel-8 20000000 86.0 ns/op 32 B/op 2 allocs/op
BenchmarkFieldCustomTypeFailure-8 5000000 341 ns/op 208 B/op 4 allocs/op
BenchmarkFieldCustomTypeFailureParallel-8 20000000 140 ns/op 208 B/op 4 allocs/op
BenchmarkFieldOrTagSuccess-8 2000000 893 ns/op 16 B/op 1 allocs/op
BenchmarkFieldOrTagSuccessParallel-8 5000000 431 ns/op 16 B/op 1 allocs/op
BenchmarkFieldOrTagFailure-8 2000000 563 ns/op 224 B/op 5 allocs/op
BenchmarkFieldOrTagFailureParallel-8 5000000 417 ns/op 224 B/op 5 allocs/op
BenchmarkStructLevelValidationSuccess-8 5000000 339 ns/op 32 B/op 2 allocs/op
BenchmarkStructLevelValidationSuccessParallel-8 20000000 114 ns/op 32 B/op 2 allocs/op
BenchmarkStructLevelValidationFailure-8 2000000 630 ns/op 304 B/op 8 allocs/op
BenchmarkStructLevelValidationFailureParallel-8 5000000 291 ns/op 304 B/op 8 allocs/op
BenchmarkStructSimpleCustomTypeSuccess-8 3000000 540 ns/op 32 B/op 2 allocs/op
BenchmarkStructSimpleCustomTypeSuccessParallel-8 10000000 176 ns/op 32 B/op 2 allocs/op
BenchmarkStructSimpleCustomTypeFailure-8 2000000 821 ns/op 424 B/op 9 allocs/op
BenchmarkStructSimpleCustomTypeFailureParallel-8 5000000 336 ns/op 440 B/op 10 allocs/op
BenchmarkStructPartialSuccess-8 2000000 686 ns/op 256 B/op 6 allocs/op
BenchmarkStructPartialSuccessParallel-8 5000000 282 ns/op 256 B/op 6 allocs/op
BenchmarkStructPartialFailure-8 2000000 931 ns/op 480 B/op 11 allocs/op
BenchmarkStructPartialFailureParallel-8 5000000 394 ns/op 480 B/op 11 allocs/op
BenchmarkStructExceptSuccess-8 1000000 1017 ns/op 496 B/op 12 allocs/op
BenchmarkStructExceptSuccessParallel-8 10000000 233 ns/op 240 B/op 5 allocs/op
BenchmarkStructExceptFailure-8 2000000 864 ns/op 464 B/op 10 allocs/op
BenchmarkStructExceptFailureParallel-8 5000000 393 ns/op 464 B/op 10 allocs/op
BenchmarkStructSimpleCrossFieldSuccess-8 3000000 552 ns/op 72 B/op 3 allocs/op
BenchmarkStructSimpleCrossFieldSuccessParallel-8 10000000 202 ns/op 72 B/op 3 allocs/op
BenchmarkStructSimpleCrossFieldFailure-8 2000000 798 ns/op 304 B/op 8 allocs/op
BenchmarkStructSimpleCrossFieldFailureParallel-8 5000000 356 ns/op 304 B/op 8 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccess-8 2000000 825 ns/op 80 B/op 4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-8 5000000 300 ns/op 80 B/op 4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailure-8 2000000 1103 ns/op 320 B/op 9 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-8 3000000 433 ns/op 320 B/op 9 allocs/op
BenchmarkStructSimpleSuccess-8 5000000 360 ns/op 0 B/op 0 allocs/op
BenchmarkStructSimpleSuccessParallel-8 20000000 110 ns/op 0 B/op 0 allocs/op
BenchmarkStructSimpleFailure-8 2000000 783 ns/op 424 B/op 9 allocs/op
BenchmarkStructSimpleFailureParallel-8 5000000 358 ns/op 424 B/op 9 allocs/op
BenchmarkStructComplexSuccess-8 1000000 2120 ns/op 128 B/op 8 allocs/op
BenchmarkStructComplexSuccessParallel-8 2000000 659 ns/op 128 B/op 8 allocs/op
BenchmarkStructComplexFailure-8 300000 5126 ns/op 3041 B/op 53 allocs/op
BenchmarkStructComplexFailureParallel-8 1000000 2261 ns/op 3041 B/op 53 allocs/op
```
Complimentary Software
----------------------
Here is a list of software that compliments using this library either pre or post validation.
8 years ago
* [form](https://github.com/go-playground/form) - Decodes url.Values into Go value(s) and Encodes Go value(s) into url.Values. Dual Array and Full map support.
* [Conform](https://github.com/leebenson/conform) - Trims, sanitizes & scrubs data based on struct tags.
How to Contribute
------
8 years ago
Make a pull request...
License
------
10 years ago
Distributed under MIT License, please see license file in code for more details.