README.md (19925B)
1 Package validator 2 ================= 3 <img align="right" src="https://raw.githubusercontent.com/go-playground/validator/v10/logo.png">[](https://gitter.im/go-playground/validator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) 4  5 [](https://travis-ci.org/go-playground/validator) 6 [](https://coveralls.io/github/go-playground/validator?branch=master) 7 [](https://goreportcard.com/report/github.com/go-playground/validator) 8 [](https://pkg.go.dev/github.com/go-playground/validator/v10) 9  10 11 Package validator implements value validations for structs and individual fields based on tags. 12 13 It has the following **unique** features: 14 15 - Cross Field and Cross Struct validations by using validation tags or custom validators. 16 - Slice, Array and Map diving, which allows any or all levels of a multidimensional field to be validated. 17 - Ability to dive into both map keys and values for validation 18 - Handles type interface by determining it's underlying type prior to validation. 19 - Handles custom field types such as sql driver Valuer see [Valuer](https://golang.org/src/database/sql/driver/types.go?s=1210:1293#L29) 20 - Alias validation tags, which allows for mapping of several validations to a single tag for easier defining of validations on structs 21 - 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 22 - Customizable i18n aware error messages. 23 - 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/master/_examples/gin-upgrading-overriding) 24 25 Installation 26 ------------ 27 28 Use go get. 29 30 go get github.com/go-playground/validator/v10 31 32 Then import the validator package into your own code. 33 34 import "github.com/go-playground/validator/v10" 35 36 Error Return Value 37 ------- 38 39 Validation functions return type error 40 41 They return type error to avoid the issue discussed in the following, where err is always != nil: 42 43 * http://stackoverflow.com/a/29138676/3158232 44 * https://github.com/go-playground/validator/issues/134 45 46 Validator returns 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: 47 48 ```go 49 err := validate.Struct(mystruct) 50 validationErrors := err.(validator.ValidationErrors) 51 ``` 52 53 Usage and documentation 54 ------ 55 56 Please see https://pkg.go.dev/github.com/go-playground/validator/v10 for detailed usage docs. 57 58 ##### Examples: 59 60 - [Simple](https://github.com/go-playground/validator/blob/master/_examples/simple/main.go) 61 - [Custom Field Types](https://github.com/go-playground/validator/blob/master/_examples/custom/main.go) 62 - [Struct Level](https://github.com/go-playground/validator/blob/master/_examples/struct-level/main.go) 63 - [Translations & Custom Errors](https://github.com/go-playground/validator/blob/master/_examples/translations/main.go) 64 - [Gin upgrade and/or override validator](https://github.com/go-playground/validator/tree/v9/_examples/gin-upgrading-overriding) 65 - [wash - an example application putting it all together](https://github.com/bluesuncorp/wash) 66 67 Baked-in Validations 68 ------ 69 70 ### Fields: 71 72 | Tag | Description | 73 | - | - | 74 | eqcsfield | Field Equals Another Field (relative)| 75 | eqfield | Field Equals Another Field | 76 | fieldcontains | Check the indicated characters are present in the Field | 77 | fieldexcludes | Check the indicated characters are not present in the field | 78 | gtcsfield | Field Greater Than Another Relative Field | 79 | gtecsfield | Field Greater Than or Equal To Another Relative Field | 80 | gtefield | Field Greater Than or Equal To Another Field | 81 | gtfield | Field Greater Than Another Field | 82 | ltcsfield | Less Than Another Relative Field | 83 | ltecsfield | Less Than or Equal To Another Relative Field | 84 | ltefield | Less Than or Equal To Another Field | 85 | ltfield | Less Than Another Field | 86 | necsfield | Field Does Not Equal Another Field (relative) | 87 | nefield | Field Does Not Equal Another Field | 88 89 ### Network: 90 91 | Tag | Description | 92 | - | - | 93 | cidr | Classless Inter-Domain Routing CIDR | 94 | cidrv4 | Classless Inter-Domain Routing CIDRv4 | 95 | cidrv6 | Classless Inter-Domain Routing CIDRv6 | 96 | datauri | Data URL | 97 | fqdn | Full Qualified Domain Name (FQDN) | 98 | hostname | Hostname RFC 952 | 99 | hostname_port | HostPort | 100 | hostname_rfc1123 | Hostname RFC 1123 | 101 | ip | Internet Protocol Address IP | 102 | ip4_addr | Internet Protocol Address IPv4 | 103 | ip6_addr | Internet Protocol Address IPv6 | 104 | ip_addr | Internet Protocol Address IP | 105 | ipv4 | Internet Protocol Address IPv4 | 106 | ipv6 | Internet Protocol Address IPv6 | 107 | mac | Media Access Control Address MAC | 108 | tcp4_addr | Transmission Control Protocol Address TCPv4 | 109 | tcp6_addr | Transmission Control Protocol Address TCPv6 | 110 | tcp_addr | Transmission Control Protocol Address TCP | 111 | udp4_addr | User Datagram Protocol Address UDPv4 | 112 | udp6_addr | User Datagram Protocol Address UDPv6 | 113 | udp_addr | User Datagram Protocol Address UDP | 114 | unix_addr | Unix domain socket end point Address | 115 | uri | URI String | 116 | url | URL String | 117 | http_url | HTTP URL String | 118 | url_encoded | URL Encoded | 119 | urn_rfc2141 | Urn RFC 2141 String | 120 121 ### Strings: 122 123 | Tag | Description | 124 | - | - | 125 | alpha | Alpha Only | 126 | alphanum | Alphanumeric | 127 | alphanumunicode | Alphanumeric Unicode | 128 | alphaunicode | Alpha Unicode | 129 | ascii | ASCII | 130 | boolean | Boolean | 131 | contains | Contains | 132 | containsany | Contains Any | 133 | containsrune | Contains Rune | 134 | endsnotwith | Ends Not With | 135 | endswith | Ends With | 136 | excludes | Excludes | 137 | excludesall | Excludes All | 138 | excludesrune | Excludes Rune | 139 | lowercase | Lowercase | 140 | multibyte | Multi-Byte Characters | 141 | number | Number | 142 | numeric | Numeric | 143 | printascii | Printable ASCII | 144 | startsnotwith | Starts Not With | 145 | startswith | Starts With | 146 | uppercase | Uppercase | 147 148 ### Format: 149 | Tag | Description | 150 | - | - | 151 | base64 | Base64 String | 152 | base64url | Base64URL String | 153 | base64rawurl | Base64RawURL String | 154 | bic | Business Identifier Code (ISO 9362) | 155 | bcp47_language_tag | Language tag (BCP 47) | 156 | btc_addr | Bitcoin Address | 157 | btc_addr_bech32 | Bitcoin Bech32 Address (segwit) | 158 | credit_card | Credit Card Number | 159 | mongodb | MongoDB ObjectID | 160 | cron | Cron | 161 | datetime | Datetime | 162 | e164 | e164 formatted phone number | 163 | email | E-mail String 164 | eth_addr | Ethereum Address | 165 | hexadecimal | Hexadecimal String | 166 | hexcolor | Hexcolor String | 167 | hsl | HSL String | 168 | hsla | HSLA String | 169 | html | HTML Tags | 170 | html_encoded | HTML Encoded | 171 | isbn | International Standard Book Number | 172 | isbn10 | International Standard Book Number 10 | 173 | isbn13 | International Standard Book Number 13 | 174 | iso3166_1_alpha2 | Two-letter country code (ISO 3166-1 alpha-2) | 175 | iso3166_1_alpha3 | Three-letter country code (ISO 3166-1 alpha-3) | 176 | iso3166_1_alpha_numeric | Numeric country code (ISO 3166-1 numeric) | 177 | iso3166_2 | Country subdivision code (ISO 3166-2) | 178 | iso4217 | Currency code (ISO 4217) | 179 | json | JSON | 180 | jwt | JSON Web Token (JWT) | 181 | latitude | Latitude | 182 | longitude | Longitude | 183 | luhn_checksum | Luhn Algorithm Checksum (for strings and (u)int) | 184 | postcode_iso3166_alpha2 | Postcode | 185 | postcode_iso3166_alpha2_field | Postcode | 186 | rgb | RGB String | 187 | rgba | RGBA String | 188 | ssn | Social Security Number SSN | 189 | timezone | Timezone | 190 | uuid | Universally Unique Identifier UUID | 191 | uuid3 | Universally Unique Identifier UUID v3 | 192 | uuid3_rfc4122 | Universally Unique Identifier UUID v3 RFC4122 | 193 | uuid4 | Universally Unique Identifier UUID v4 | 194 | uuid4_rfc4122 | Universally Unique Identifier UUID v4 RFC4122 | 195 | uuid5 | Universally Unique Identifier UUID v5 | 196 | uuid5_rfc4122 | Universally Unique Identifier UUID v5 RFC4122 | 197 | uuid_rfc4122 | Universally Unique Identifier UUID RFC4122 | 198 | md4 | MD4 hash | 199 | md5 | MD5 hash | 200 | sha256 | SHA256 hash | 201 | sha384 | SHA384 hash | 202 | sha512 | SHA512 hash | 203 | ripemd128 | RIPEMD-128 hash | 204 | ripemd128 | RIPEMD-160 hash | 205 | tiger128 | TIGER128 hash | 206 | tiger160 | TIGER160 hash | 207 | tiger192 | TIGER192 hash | 208 | semver | Semantic Versioning 2.0.0 | 209 | ulid | Universally Unique Lexicographically Sortable Identifier ULID | 210 | cve | Common Vulnerabilities and Exposures Identifier (CVE id) | 211 212 ### Comparisons: 213 | Tag | Description | 214 | - | - | 215 | eq | Equals | 216 | eq_ignore_case | Equals ignoring case | 217 | gt | Greater than| 218 | gte | Greater than or equal | 219 | lt | Less Than | 220 | lte | Less Than or Equal | 221 | ne | Not Equal | 222 | ne_ignore_case | Not Equal ignoring case | 223 224 ### Other: 225 | Tag | Description | 226 | - | - | 227 | dir | Existing Directory | 228 | dirpath | Directory Path | 229 | file | Existing File | 230 | filepath | File Path | 231 | image | Image | 232 | isdefault | Is Default | 233 | len | Length | 234 | max | Maximum | 235 | min | Minimum | 236 | oneof | One Of | 237 | required | Required | 238 | required_if | Required If | 239 | required_unless | Required Unless | 240 | required_with | Required With | 241 | required_with_all | Required With All | 242 | required_without | Required Without | 243 | required_without_all | Required Without All | 244 | excluded_if | Excluded If | 245 | excluded_unless | Excluded Unless | 246 | excluded_with | Excluded With | 247 | excluded_with_all | Excluded With All | 248 | excluded_without | Excluded Without | 249 | excluded_without_all | Excluded Without All | 250 | unique | Unique | 251 252 #### Aliases: 253 | Tag | Description | 254 | - | - | 255 | iscolor | hexcolor\|rgb\|rgba\|hsl\|hsla | 256 | country_code | iso3166_1_alpha2\|iso3166_1_alpha3\|iso3166_1_alpha_numeric | 257 258 Benchmarks 259 ------ 260 ###### Run on MacBook Pro (15-inch, 2017) go version go1.10.2 darwin/amd64 261 ```go 262 goos: darwin 263 goarch: amd64 264 pkg: github.com/go-playground/validator 265 BenchmarkFieldSuccess-8 20000000 83.6 ns/op 0 B/op 0 allocs/op 266 BenchmarkFieldSuccessParallel-8 50000000 26.8 ns/op 0 B/op 0 allocs/op 267 BenchmarkFieldFailure-8 5000000 291 ns/op 208 B/op 4 allocs/op 268 BenchmarkFieldFailureParallel-8 20000000 107 ns/op 208 B/op 4 allocs/op 269 BenchmarkFieldArrayDiveSuccess-8 2000000 623 ns/op 201 B/op 11 allocs/op 270 BenchmarkFieldArrayDiveSuccessParallel-8 10000000 237 ns/op 201 B/op 11 allocs/op 271 BenchmarkFieldArrayDiveFailure-8 2000000 859 ns/op 412 B/op 16 allocs/op 272 BenchmarkFieldArrayDiveFailureParallel-8 5000000 335 ns/op 413 B/op 16 allocs/op 273 BenchmarkFieldMapDiveSuccess-8 1000000 1292 ns/op 432 B/op 18 allocs/op 274 BenchmarkFieldMapDiveSuccessParallel-8 3000000 467 ns/op 432 B/op 18 allocs/op 275 BenchmarkFieldMapDiveFailure-8 1000000 1082 ns/op 512 B/op 16 allocs/op 276 BenchmarkFieldMapDiveFailureParallel-8 5000000 425 ns/op 512 B/op 16 allocs/op 277 BenchmarkFieldMapDiveWithKeysSuccess-8 1000000 1539 ns/op 480 B/op 21 allocs/op 278 BenchmarkFieldMapDiveWithKeysSuccessParallel-8 3000000 613 ns/op 480 B/op 21 allocs/op 279 BenchmarkFieldMapDiveWithKeysFailure-8 1000000 1413 ns/op 721 B/op 21 allocs/op 280 BenchmarkFieldMapDiveWithKeysFailureParallel-8 3000000 575 ns/op 721 B/op 21 allocs/op 281 BenchmarkFieldCustomTypeSuccess-8 10000000 216 ns/op 32 B/op 2 allocs/op 282 BenchmarkFieldCustomTypeSuccessParallel-8 20000000 82.2 ns/op 32 B/op 2 allocs/op 283 BenchmarkFieldCustomTypeFailure-8 5000000 274 ns/op 208 B/op 4 allocs/op 284 BenchmarkFieldCustomTypeFailureParallel-8 20000000 116 ns/op 208 B/op 4 allocs/op 285 BenchmarkFieldOrTagSuccess-8 2000000 740 ns/op 16 B/op 1 allocs/op 286 BenchmarkFieldOrTagSuccessParallel-8 3000000 474 ns/op 16 B/op 1 allocs/op 287 BenchmarkFieldOrTagFailure-8 3000000 471 ns/op 224 B/op 5 allocs/op 288 BenchmarkFieldOrTagFailureParallel-8 3000000 414 ns/op 224 B/op 5 allocs/op 289 BenchmarkStructLevelValidationSuccess-8 10000000 213 ns/op 32 B/op 2 allocs/op 290 BenchmarkStructLevelValidationSuccessParallel-8 20000000 91.8 ns/op 32 B/op 2 allocs/op 291 BenchmarkStructLevelValidationFailure-8 3000000 473 ns/op 304 B/op 8 allocs/op 292 BenchmarkStructLevelValidationFailureParallel-8 10000000 234 ns/op 304 B/op 8 allocs/op 293 BenchmarkStructSimpleCustomTypeSuccess-8 5000000 385 ns/op 32 B/op 2 allocs/op 294 BenchmarkStructSimpleCustomTypeSuccessParallel-8 10000000 161 ns/op 32 B/op 2 allocs/op 295 BenchmarkStructSimpleCustomTypeFailure-8 2000000 640 ns/op 424 B/op 9 allocs/op 296 BenchmarkStructSimpleCustomTypeFailureParallel-8 5000000 318 ns/op 440 B/op 10 allocs/op 297 BenchmarkStructFilteredSuccess-8 2000000 597 ns/op 288 B/op 9 allocs/op 298 BenchmarkStructFilteredSuccessParallel-8 10000000 266 ns/op 288 B/op 9 allocs/op 299 BenchmarkStructFilteredFailure-8 3000000 454 ns/op 256 B/op 7 allocs/op 300 BenchmarkStructFilteredFailureParallel-8 10000000 214 ns/op 256 B/op 7 allocs/op 301 BenchmarkStructPartialSuccess-8 3000000 502 ns/op 256 B/op 6 allocs/op 302 BenchmarkStructPartialSuccessParallel-8 10000000 225 ns/op 256 B/op 6 allocs/op 303 BenchmarkStructPartialFailure-8 2000000 702 ns/op 480 B/op 11 allocs/op 304 BenchmarkStructPartialFailureParallel-8 5000000 329 ns/op 480 B/op 11 allocs/op 305 BenchmarkStructExceptSuccess-8 2000000 793 ns/op 496 B/op 12 allocs/op 306 BenchmarkStructExceptSuccessParallel-8 10000000 193 ns/op 240 B/op 5 allocs/op 307 BenchmarkStructExceptFailure-8 2000000 639 ns/op 464 B/op 10 allocs/op 308 BenchmarkStructExceptFailureParallel-8 5000000 300 ns/op 464 B/op 10 allocs/op 309 BenchmarkStructSimpleCrossFieldSuccess-8 3000000 417 ns/op 72 B/op 3 allocs/op 310 BenchmarkStructSimpleCrossFieldSuccessParallel-8 10000000 163 ns/op 72 B/op 3 allocs/op 311 BenchmarkStructSimpleCrossFieldFailure-8 2000000 645 ns/op 304 B/op 8 allocs/op 312 BenchmarkStructSimpleCrossFieldFailureParallel-8 5000000 285 ns/op 304 B/op 8 allocs/op 313 BenchmarkStructSimpleCrossStructCrossFieldSuccess-8 3000000 588 ns/op 80 B/op 4 allocs/op 314 BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-8 10000000 221 ns/op 80 B/op 4 allocs/op 315 BenchmarkStructSimpleCrossStructCrossFieldFailure-8 2000000 868 ns/op 320 B/op 9 allocs/op 316 BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-8 5000000 337 ns/op 320 B/op 9 allocs/op 317 BenchmarkStructSimpleSuccess-8 5000000 260 ns/op 0 B/op 0 allocs/op 318 BenchmarkStructSimpleSuccessParallel-8 20000000 90.6 ns/op 0 B/op 0 allocs/op 319 BenchmarkStructSimpleFailure-8 2000000 619 ns/op 424 B/op 9 allocs/op 320 BenchmarkStructSimpleFailureParallel-8 5000000 296 ns/op 424 B/op 9 allocs/op 321 BenchmarkStructComplexSuccess-8 1000000 1454 ns/op 128 B/op 8 allocs/op 322 BenchmarkStructComplexSuccessParallel-8 3000000 579 ns/op 128 B/op 8 allocs/op 323 BenchmarkStructComplexFailure-8 300000 4140 ns/op 3041 B/op 53 allocs/op 324 BenchmarkStructComplexFailureParallel-8 1000000 2127 ns/op 3041 B/op 53 allocs/op 325 BenchmarkOneof-8 10000000 140 ns/op 0 B/op 0 allocs/op 326 BenchmarkOneofParallel-8 20000000 70.1 ns/op 0 B/op 0 allocs/op 327 ``` 328 329 Complementary Software 330 ---------------------- 331 332 Here is a list of software that complements using this library either pre or post validation. 333 334 * [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. 335 * [mold](https://github.com/go-playground/mold) - A general library to help modify or set data within data structures and other objects 336 337 How to Contribute 338 ------ 339 340 Make a pull request... 341 342 License 343 ------- 344 Distributed under MIT License, please see license file within the code for more details. 345 346 Maintainers 347 ----------- 348 This project has grown large enough that more than one person is required to properly support the community. 349 If you are interested in becoming a maintainer please reach out to me https://github.com/deankarn