Name Last Update
..
.github Loading commit data...
_examples Loading commit data...
translations/en Loading commit data...
.gitignore Loading commit data...
LICENSE Loading commit data...
README.md Loading commit data...
baked_in.go Loading commit data...
benchmarks_test.go Loading commit data...
cache.go Loading commit data...
doc.go Loading commit data...
errors.go Loading commit data...
examples_test.go Loading commit data...
field_level.go Loading commit data...
logo.png Loading commit data...
regexes.go Loading commit data...
struct_level.go Loading commit data...
translations.go Loading commit data...
util.go Loading commit data...
validator.go Loading commit data...
validator_instance.go Loading commit data...
validator_test.go Loading commit data...

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.
  • 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 Dell XPS 15 i7-7700HQ 32GB Go version go1.8.3 linux/amd64
go test -run=XXX -bench=. -benchmem=true
BenchmarkFieldSuccess-8                                         20000000            88.3 ns/op         0 B/op          0 allocs/op
BenchmarkFieldSuccessParallel-8                                 50000000            30.4 ns/op         0 B/op          0 allocs/op
BenchmarkFieldFailure-8                                          3000000           428 ns/op         208 B/op          4 allocs/op
BenchmarkFieldFailureParallel-8                                 20000000            96.0 ns/op       208 B/op          4 allocs/op
BenchmarkFieldDiveSuccess-8                                      2000000           695 ns/op         201 B/op         11 allocs/op
BenchmarkFieldDiveSuccessParallel-8                             10000000           205 ns/op         201 B/op         11 allocs/op
BenchmarkFieldDiveFailure-8                                      1000000          1083 ns/op         412 B/op         16 allocs/op
BenchmarkFieldDiveFailureParallel-8                              5000000           278 ns/op         413 B/op         16 allocs/op
BenchmarkFieldCustomTypeSuccess-8                               10000000           229 ns/op          32 B/op          2 allocs/op
BenchmarkFieldCustomTypeSuccessParallel-8                       20000000            72.4 ns/op        32 B/op          2 allocs/op
BenchmarkFieldCustomTypeFailure-8                                5000000           377 ns/op         208 B/op          4 allocs/op
BenchmarkFieldCustomTypeFailureParallel-8                       20000000            93.0 ns/op       208 B/op          4 allocs/op
BenchmarkFieldOrTagSuccess-8                                     2000000           767 ns/op          16 B/op          1 allocs/op
BenchmarkFieldOrTagSuccessParallel-8                             3000000           425 ns/op          16 B/op          1 allocs/op
BenchmarkFieldOrTagFailure-8                                     2000000           548 ns/op         224 B/op          5 allocs/op
BenchmarkFieldOrTagFailureParallel-8                             3000000           411 ns/op         224 B/op          5 allocs/op
BenchmarkStructLevelValidationSuccess-8                         10000000           219 ns/op          32 B/op          2 allocs/op
BenchmarkStructLevelValidationSuccessParallel-8                 20000000            69.2 ns/op        32 B/op          2 allocs/op
BenchmarkStructLevelValidationFailure-8                          2000000           628 ns/op         304 B/op          8 allocs/op
BenchmarkStructLevelValidationFailureParallel-8                 10000000           165 ns/op         304 B/op          8 allocs/op
BenchmarkStructSimpleCustomTypeSuccess-8                         3000000           411 ns/op          32 B/op          2 allocs/op
BenchmarkStructSimpleCustomTypeSuccessParallel-8                10000000           122 ns/op          32 B/op          2 allocs/op
BenchmarkStructSimpleCustomTypeFailure-8                         1000000          1022 ns/op         424 B/op          9 allocs/op
BenchmarkStructSimpleCustomTypeFailureParallel-8                10000000           228 ns/op         440 B/op         10 allocs/op
BenchmarkStructFilteredSuccess-8                                 2000000           737 ns/op         288 B/op          9 allocs/op
BenchmarkStructFilteredSuccessParallel-8                        10000000           192 ns/op         288 B/op          9 allocs/op
BenchmarkStructFilteredFailure-8                                 3000000           583 ns/op         256 B/op          7 allocs/op
BenchmarkStructFilteredFailureParallel-8                        10000000           152 ns/op         256 B/op          7 allocs/op
BenchmarkStructPartialSuccess-8                                  2000000           731 ns/op         256 B/op          6 allocs/op
BenchmarkStructPartialSuccessParallel-8                         10000000           173 ns/op         256 B/op          6 allocs/op
BenchmarkStructPartialFailure-8                                  1000000          1164 ns/op         480 B/op         11 allocs/op
BenchmarkStructPartialFailureParallel-8                          5000000           253 ns/op         480 B/op         11 allocs/op
BenchmarkStructExceptSuccess-8                                   1000000          1337 ns/op         496 B/op         12 allocs/op
BenchmarkStructExceptSuccessParallel-8                          10000000           153 ns/op         240 B/op          5 allocs/op
BenchmarkStructExceptFailure-8                                   2000000           954 ns/op         464 B/op         10 allocs/op
BenchmarkStructExceptFailureParallel-8                           5000000           234 ns/op         464 B/op         10 allocs/op
BenchmarkStructSimpleCrossFieldSuccess-8                         3000000           420 ns/op          72 B/op          3 allocs/op
BenchmarkStructSimpleCrossFieldSuccessParallel-8                10000000           125 ns/op          72 B/op          3 allocs/op
BenchmarkStructSimpleCrossFieldFailure-8                         2000000           790 ns/op         304 B/op          8 allocs/op
BenchmarkStructSimpleCrossFieldFailureParallel-8                10000000           205 ns/op         304 B/op          8 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccess-8              2000000           611 ns/op          80 B/op          4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-8     10000000           172 ns/op          80 B/op          4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailure-8              1000000          1112 ns/op         320 B/op          9 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-8      5000000           258 ns/op         320 B/op          9 allocs/op
BenchmarkStructSimpleSuccess-8                                   5000000           263 ns/op           0 B/op          0 allocs/op
BenchmarkStructSimpleSuccessParallel-8                          20000000            83.1 ns/op         0 B/op          0 allocs/op
BenchmarkStructSimpleFailure-8                                   2000000           964 ns/op         424 B/op          9 allocs/op
BenchmarkStructSimpleFailureParallel-8                          10000000           212 ns/op         424 B/op          9 allocs/op
BenchmarkStructComplexSuccess-8                                  1000000          1504 ns/op         128 B/op          8 allocs/op
BenchmarkStructComplexSuccessParallel-8                          3000000           427 ns/op         128 B/op          8 allocs/op
BenchmarkStructComplexFailure-8                                   300000          7585 ns/op        3041 B/op         53 allocs/op
BenchmarkStructComplexFailureParallel-8                          1000000          1387 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.
  • Conform - Trims, sanitizes & scrubs data based on struct tags.

How to Contribute

Make a pull request...

License

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