vendor/gopkg.in/go-playground/validator.v8/doc.go

   1 /*
   2 Package validator implements value validations for structs and individual fields
   3 based on tags.
   4
   5 It can also handle Cross-Field and Cross-Struct validation for nested structs
   6 and has the ability to dive into arrays and maps of any type.
   7
   8 Why not a better error message?
   9 Because this library intends for you to handle your own error messages.
  10
  11 Why should I handle my own errors?
  12 Many reasons. We built an internationalized application and needed to know the
  13 field, and what validation failed so we could provide a localized error.
  14
  15         if fieldErr.Field == "Name" {
  16                 switch fieldErr.ErrorTag
  17                 case "required":
  18                         return "Translated string based on field + error"
  19                 default:
  20                 return "Translated string based on field"
  21         }
  22
  23
  24 Validation Functions Return Type error
  25
  26 Doing things this way is actually the way the standard library does, see the
  27 file.Open method here:
  28
  29         https://golang.org/pkg/os/#Open.
  30
  31 The authors return type "error" to avoid the issue discussed in the following,
  32 where err is always != nil:
  33
  34         http://stackoverflow.com/a/29138676/3158232
  35         https://github.com/go-playground/validator/issues/134
  36
  37 Validator only returns nil or ValidationErrors as type error; so, in your code
  38 all you need to do is check if the error returned is not nil, and if it's not
  39 type cast it to type ValidationErrors like so err.(validator.ValidationErrors).
  40
  41 Custom Functions
  42
  43 Custom functions can be added. Example:
  44
  45         // Structure
  46         func customFunc(v *Validate, topStruct reflect.Value, currentStructOrField reflect.Value, field reflect.Value, fieldType reflect.Type, fieldKind reflect.Kind, param string) bool {
  47
  48                 if whatever {
  49                         return false
  50                 }
  51
  52                 return true
  53         }
  54
  55         validate.RegisterValidation("custom tag name", customFunc)
  56         // NOTES: using the same tag name as an existing function
  57         //        will overwrite the existing one
  58
  59 Cross-Field Validation
  60
  61 Cross-Field Validation can be done via the following tags:
  62         - eqfield
  63         - nefield
  64         - gtfield
  65         - gtefield
  66         - ltfield
  67         - ltefield
  68         - eqcsfield
  69         - necsfield
  70         - gtcsfield
  71         - ftecsfield
  72         - ltcsfield
  73         - ltecsfield
  74
  75 If, however, some custom cross-field validation is required, it can be done
  76 using a custom validation.
  77
  78 Why not just have cross-fields validation tags (i.e. only eqcsfield and not
  79 eqfield)?
  80
  81 The reason is efficiency. If you want to check a field within the same struct
  82 "eqfield" only has to find the field on the same struct (1 level). But, if we
  83 used "eqcsfield" it could be multiple levels down. Example:
  84
  85         type Inner struct {
  86                 StartDate time.Time
  87         }
  88
  89         type Outer struct {
  90                 InnerStructField *Inner
  91                 CreatedAt time.Time      `validate:"ltecsfield=InnerStructField.StartDate"`
  92         }
  93
  94         now := time.Now()
  95
  96         inner := &Inner{
  97                 StartDate: now,
  98         }
  99
 100         outer := &Outer{
 101                 InnerStructField: inner,
 102                 CreatedAt: now,
 103         }
 104
 105         errs := validate.Struct(outer)
 106
 107         // NOTE: when calling validate.Struct(val) topStruct will be the top level struct passed
 108         //       into the function
 109         //       when calling validate.FieldWithValue(val, field, tag) val will be
 110         //       whatever you pass, struct, field...
 111         //       when calling validate.Field(field, tag) val will be nil
 112
 113 Multiple Validators
 114
 115 Multiple validators on a field will process in the order defined. Example:
 116
 117         type Test struct {
 118                 Field `validate:"max=10,min=1"`
 119         }
 120
 121         // max will be checked then min
 122
 123 Bad Validator definitions are not handled by the library. Example:
 124
 125         type Test struct {
 126                 Field `validate:"min=10,max=0"`
 127         }
 128
 129         // this definition of min max will never succeed
 130
 131 Using Validator Tags
 132
 133 Baked In Cross-Field validation only compares fields on the same struct.
 134 If Cross-Field + Cross-Struct validation is needed you should implement your
 135 own custom validator.
 136
 137 Comma (",") is the default separator of validation tags. If you wish to
 138 have a comma included within the parameter (i.e. excludesall=,) you will need to
 139 use the UTF-8 hex representation 0x2C, which is replaced in the code as a comma,
 140 so the above will become excludesall=0x2C.
 141
 142         type Test struct {
 143                 Field `validate:"excludesall=,"`    // BAD! Do not include a comma.
 144                 Field `validate:"excludesall=0x2C"` // GOOD! Use the UTF-8 hex representation.
 145         }
 146
 147 Pipe ("|") is the default separator of validation tags. If you wish to
 148 have a pipe included within the parameter i.e. excludesall=| you will need to
 149 use the UTF-8 hex representation 0x7C, which is replaced in the code as a pipe,
 150 so the above will become excludesall=0x7C
 151
 152         type Test struct {
 153                 Field `validate:"excludesall=|"`    // BAD! Do not include a a pipe!
 154                 Field `validate:"excludesall=0x7C"` // GOOD! Use the UTF-8 hex representation.
 155         }
 156
 157
 158 Baked In Validators and Tags
 159
 160 Here is a list of the current built in validators:
 161
 162
 163 Skip Field
 164
 165 Tells the validation to skip this struct field; this is particularly
 166 handy in ignoring embedded structs from being validated. (Usage: -)
 167         Usage: -
 168
 169
 170 Or Operator
 171
 172 This is the 'or' operator allowing multiple validators to be used and
 173 accepted. (Usage: rbg|rgba) <-- this would allow either rgb or rgba
 174 colors to be accepted. This can also be combined with 'and' for example
 175 ( Usage: omitempty,rgb|rgba)
 176
 177         Usage: |
 178
 179 StructOnly
 180
 181 When a field that is a nested struct is encountered, and contains this flag
 182 any validation on the nested struct will be run, but none of the nested
 183 struct fields will be validated. This is usefull if inside of you program
 184 you know the struct will be valid, but need to verify it has been assigned.
 185 NOTE: only "required" and "omitempty" can be used on a struct itself.
 186
 187         Usage: structonly
 188
 189 NoStructLevel
 190
 191 Same as structonly tag except that any struct level validations will not run.
 192
 193         Usage: nostructlevel
 194
 195 Exists
 196
 197 Is a special tag without a validation function attached. It is used when a field
 198 is a Pointer, Interface or Invalid and you wish to validate that it exists.
 199 Example: want to ensure a bool exists if you define the bool as a pointer and
 200 use exists it will ensure there is a value; couldn't use required as it would
 201 fail when the bool was false. exists will fail is the value is a Pointer, Interface
 202 or Invalid and is nil.
 203
 204         Usage: exists
 205
 206 Omit Empty
 207
 208 Allows conditional validation, for example if a field is not set with
 209 a value (Determined by the "required" validator) then other validation
 210 such as min or max won't run, but if a value is set validation will run.
 211
 212         Usage: omitempty
 213
 214 Dive
 215
 216 This tells the validator to dive into a slice, array or map and validate that
 217 level of the slice, array or map with the validation tags that follow.
 218 Multidimensional nesting is also supported, each level you wish to dive will
 219 require another dive tag.
 220
 221         Usage: dive
 222
 223 Example #1
 224
 225         [][]string with validation tag "gt=0,dive,len=1,dive,required"
 226         // gt=0 will be applied to []
 227         // len=1 will be applied to []string
 228         // required will be applied to string
 229
 230 Example #2
 231
 232         [][]string with validation tag "gt=0,dive,dive,required"
 233         // gt=0 will be applied to []
 234         // []string will be spared validation
 235         // required will be applied to string
 236
 237 Required
 238
 239 This validates that the value is not the data types default zero value.
 240 For numbers ensures value is not zero. For strings ensures value is
 241 not "". For slices, maps, pointers, interfaces, channels and functions
 242 ensures the value is not nil.
 243
 244         Usage: required
 245
 246 Length
 247
 248 For numbers, max will ensure that the value is
 249 equal to the parameter given. For strings, it checks that
 250 the string length is exactly that number of characters. For slices,
 251 arrays, and maps, validates the number of items.
 252
 253         Usage: len=10
 254
 255 Maximum
 256
 257 For numbers, max will ensure that the value is
 258 less than or equal to the parameter given. For strings, it checks
 259 that the string length is at most that number of characters. For
 260 slices, arrays, and maps, validates the number of items.
 261
 262         Usage: max=10
 263
 264 Mininum
 265
 266 For numbers, min will ensure that the value is
 267 greater or equal to the parameter given. For strings, it checks that
 268 the string length is at least that number of characters. For slices,
 269 arrays, and maps, validates the number of items.
 270
 271         Usage: min=10
 272
 273 Equals
 274
 275 For strings & numbers, eq will ensure that the value is
 276 equal to the parameter given. For slices, arrays, and maps,
 277 validates the number of items.
 278
 279         Usage: eq=10
 280
 281 Not Equal
 282
 283 For strings & numbers, ne will ensure that the value is not
 284 equal to the parameter given. For slices, arrays, and maps,
 285 validates the number of items.
 286
 287         Usage: ne=10
 288
 289 Greater Than
 290
 291 For numbers, this will ensure that the value is greater than the
 292 parameter given. For strings, it checks that the string length
 293 is greater than that number of characters. For slices, arrays
 294 and maps it validates the number of items.
 295
 296 Example #1
 297
 298         Usage: gt=10
 299
 300 Example #2 (time.Time)
 301
 302 For time.Time ensures the time value is greater than time.Now.UTC().
 303
 304         Usage: gt
 305
 306 Greater Than or Equal
 307
 308 Same as 'min' above. Kept both to make terminology with 'len' easier.
 309
 310
 311 Example #1
 312
 313         Usage: gte=10
 314
 315 Example #2 (time.Time)
 316
 317 For time.Time ensures the time value is greater than or equal to time.Now.UTC().
 318
 319         Usage: gte
 320
 321 Less Than
 322
 323 For numbers, this will ensure that the value is less than the parameter given.
 324 For strings, it checks that the string length is less than that number of
 325 characters. For slices, arrays, and maps it validates the number of items.
 326
 327 Example #1
 328
 329         Usage: lt=10
 330
 331 Example #2 (time.Time)
 332 For time.Time ensures the time value is less than time.Now.UTC().
 333
 334         Usage: lt
 335
 336 Less Than or Equal
 337
 338 Same as 'max' above. Kept both to make terminology with 'len' easier.
 339
 340 Example #1
 341
 342         Usage: lte=10
 343
 344 Example #2 (time.Time)
 345
 346 For time.Time ensures the time value is less than or equal to time.Now.UTC().
 347
 348         Usage: lte
 349
 350 Field Equals Another Field
 351
 352 This will validate the field value against another fields value either within
 353 a struct or passed in field.
 354
 355 Example #1:
 356
 357         // Validation on Password field using:
 358         Usage: eqfield=ConfirmPassword
 359
 360 Example #2:
 361
 362         // Validating by field:
 363         validate.FieldWithValue(password, confirmpassword, "eqfield")
 364
 365 Field Equals Another Field (relative)
 366
 367 This does the same as eqfield except that it validates the field provided relative
 368 to the top level struct.
 369
 370         Usage: eqcsfield=InnerStructField.Field)
 371
 372 Field Does Not Equal Another Field
 373
 374 This will validate the field value against another fields value either within
 375 a struct or passed in field.
 376
 377 Examples:
 378
 379         // Confirm two colors are not the same:
 380         //
 381         // Validation on Color field:
 382         Usage: nefield=Color2
 383
 384         // Validating by field:
 385         validate.FieldWithValue(color1, color2, "nefield")
 386
 387 Field Does Not Equal Another Field (relative)
 388
 389 This does the same as nefield except that it validates the field provided
 390 relative to the top level struct.
 391
 392         Usage: necsfield=InnerStructField.Field
 393
 394 Field Greater Than Another Field
 395
 396 Only valid for Numbers and time.Time types, this will validate the field value
 397 against another fields value either within a struct or passed in field.
 398 usage examples are for validation of a Start and End date:
 399
 400 Example #1:
 401
 402         // Validation on End field using:
 403         validate.Struct Usage(gtfield=Start)
 404
 405 Example #2:
 406
 407         // Validating by field:
 408         validate.FieldWithValue(start, end, "gtfield")
 409
 410
 411 Field Greater Than Another Relative Field
 412
 413 This does the same as gtfield except that it validates the field provided
 414 relative to the top level struct.
 415
 416         Usage: gtcsfield=InnerStructField.Field
 417
 418 Field Greater Than or Equal To Another Field
 419
 420 Only valid for Numbers and time.Time types, this will validate the field value
 421 against another fields value either within a struct or passed in field.
 422 usage examples are for validation of a Start and End date:
 423
 424 Example #1:
 425
 426         // Validation on End field using:
 427         validate.Struct Usage(gtefield=Start)
 428
 429 Example #2:
 430
 431         // Validating by field:
 432         validate.FieldWithValue(start, end, "gtefield")
 433
 434 Field Greater Than or Equal To Another Relative Field
 435
 436 This does the same as gtefield except that it validates the field provided relative
 437 to the top level struct.
 438
 439         Usage: gtecsfield=InnerStructField.Field
 440
 441 Less Than Another Field
 442
 443 Only valid for Numbers and time.Time types, this will validate the field value
 444 against another fields value either within a struct or passed in field.
 445 usage examples are for validation of a Start and End date:
 446
 447 Example #1:
 448
 449         // Validation on End field using:
 450         validate.Struct Usage(ltfield=Start)
 451
 452 Example #2:
 453
 454         // Validating by field:
 455         validate.FieldWithValue(start, end, "ltfield")
 456
 457 Less Than Another Relative Field
 458
 459 This does the same as ltfield except that it validates the field provided relative
 460 to the top level struct.
 461
 462         Usage: ltcsfield=InnerStructField.Field
 463
 464 Less Than or Equal To Another Field
 465
 466 Only valid for Numbers and time.Time types, this will validate the field value
 467 against another fields value either within a struct or passed in field.
 468 usage examples are for validation of a Start and End date:
 469
 470 Example #1:
 471
 472         // Validation on End field using:
 473         validate.Struct Usage(ltefield=Start)
 474
 475 Example #2:
 476
 477         // Validating by field:
 478         validate.FieldWithValue(start, end, "ltefield")
 479
 480 Less Than or Equal To Another Relative Field
 481
 482 This does the same as ltefield except that it validates the field provided relative
 483 to the top level struct.
 484
 485         Usage: ltecsfield=InnerStructField.Field
 486
 487 Alpha Only
 488
 489 This validates that a string value contains alpha characters only
 490
 491         Usage: alpha
 492
 493 Alphanumeric
 494
 495 This validates that a string value contains alphanumeric characters only
 496
 497         Usage: alphanum
 498
 499 Numeric
 500
 501 This validates that a string value contains a basic numeric value.
 502 basic excludes exponents etc...
 503
 504         Usage: numeric
 505
 506 Hexadecimal String
 507
 508 This validates that a string value contains a valid hexadecimal.
 509
 510         Usage: hexadecimal
 511
 512 Hexcolor String
 513
 514 This validates that a string value contains a valid hex color including
 515 hashtag (#)
 516
 517                 Usage: hexcolor
 518
 519 RGB String
 520
 521 This validates that a string value contains a valid rgb color
 522
 523         Usage: rgb
 524
 525 RGBA String
 526
 527 This validates that a string value contains a valid rgba color
 528
 529         Usage: rgba
 530
 531 HSL String
 532
 533 This validates that a string value contains a valid hsl color
 534
 535         Usage: hsl
 536
 537 HSLA String
 538
 539 This validates that a string value contains a valid hsla color
 540
 541         Usage: hsla
 542
 543 E-mail String
 544
 545 This validates that a string value contains a valid email
 546 This may not conform to all possibilities of any rfc standard, but neither
 547 does any email provider accept all posibilities.
 548
 549         Usage: email
 550
 551 URL String
 552
 553 This validates that a string value contains a valid url
 554 This will accept any url the golang request uri accepts but must contain
 555 a schema for example http:// or rtmp://
 556
 557         Usage: url
 558
 559 URI String
 560
 561 This validates that a string value contains a valid uri
 562 This will accept any uri the golang request uri accepts
 563
 564         Usage: uri
 565
 566 Base64 String
 567
 568 This validates that a string value contains a valid base64 value.
 569 Although an empty string is valid base64 this will report an empty string
 570 as an error, if you wish to accept an empty string as valid you can use
 571 this with the omitempty tag.
 572
 573         Usage: base64
 574
 575 Contains
 576
 577 This validates that a string value contains the substring value.
 578
 579         Usage: contains=@
 580
 581 Contains Any
 582
 583 This validates that a string value contains any Unicode code points
 584 in the substring value.
 585
 586         Usage: containsany=!@#?
 587
 588 Contains Rune
 589
 590 This validates that a string value contains the supplied rune value.
 591
 592         Usage: containsrune=@
 593
 594 Excludes
 595
 596 This validates that a string value does not contain the substring value.
 597
 598         Usage: excludes=@
 599
 600 Excludes All
 601
 602 This validates that a string value does not contain any Unicode code
 603 points in the substring value.
 604
 605         Usage: excludesall=!@#?
 606
 607 Excludes Rune
 608
 609 This validates that a string value does not contain the supplied rune value.
 610
 611         Usage: excludesrune=@
 612
 613 International Standard Book Number
 614
 615 This validates that a string value contains a valid isbn10 or isbn13 value.
 616
 617         Usage: isbn
 618
 619 International Standard Book Number 10
 620
 621 This validates that a string value contains a valid isbn10 value.
 622
 623         Usage: isbn10
 624
 625 International Standard Book Number 13
 626
 627 This validates that a string value contains a valid isbn13 value.
 628
 629         Usage: isbn13
 630
 631
 632 Universally Unique Identifier UUID
 633
 634 This validates that a string value contains a valid UUID.
 635
 636         Usage: uuid
 637
 638 Universally Unique Identifier UUID v3
 639
 640 This validates that a string value contains a valid version 3 UUID.
 641
 642         Usage: uuid3
 643
 644 Universally Unique Identifier UUID v4
 645
 646 This validates that a string value contains a valid version 4 UUID.
 647
 648         Usage: uuid4
 649
 650 Universally Unique Identifier UUID v5
 651
 652 This validates that a string value contains a valid version 5 UUID.
 653
 654         Usage: uuid5
 655
 656 ASCII
 657
 658 This validates that a string value contains only ASCII characters.
 659 NOTE: if the string is blank, this validates as true.
 660
 661         Usage: ascii
 662
 663 Printable ASCII
 664
 665 This validates that a string value contains only printable ASCII characters.
 666 NOTE: if the string is blank, this validates as true.
 667
 668         Usage: asciiprint
 669
 670 Multi-Byte Characters
 671
 672 This validates that a string value contains one or more multibyte characters.
 673 NOTE: if the string is blank, this validates as true.
 674
 675         Usage: multibyte
 676
 677 Data URL
 678
 679 This validates that a string value contains a valid DataURI.
 680 NOTE: this will also validate that the data portion is valid base64
 681
 682         Usage: datauri
 683
 684 Latitude
 685
 686 This validates that a string value contains a valid latitude.
 687
 688         Usage: latitude
 689
 690 Longitude
 691
 692 This validates that a string value contains a valid longitude.
 693
 694         Usage: longitude
 695
 696 Social Security Number SSN
 697
 698 This validates that a string value contains a valid U.S. Social Security Number.
 699
 700         Usage: ssn
 701
 702 Internet Protocol Address IP
 703
 704 This validates that a string value contains a valid IP Adress.
 705
 706         Usage: ip
 707
 708 Internet Protocol Address IPv4
 709
 710 This validates that a string value contains a valid v4 IP Adress.
 711
 712         Usage: ipv4
 713
 714 Internet Protocol Address IPv6
 715
 716 This validates that a string value contains a valid v6 IP Adress.
 717
 718         Usage: ipv6
 719
 720 Classless Inter-Domain Routing CIDR
 721
 722 This validates that a string value contains a valid CIDR Adress.
 723
 724         Usage: cidr
 725
 726 Classless Inter-Domain Routing CIDRv4
 727
 728 This validates that a string value contains a valid v4 CIDR Adress.
 729
 730         Usage: cidrv4
 731
 732 Classless Inter-Domain Routing CIDRv6
 733
 734 This validates that a string value contains a valid v6 CIDR Adress.
 735
 736         Usage: cidrv6
 737
 738 Transmission Control Protocol Address TCP
 739
 740 This validates that a string value contains a valid resolvable TCP Adress.
 741
 742         Usage: tcp_addr
 743
 744 Transmission Control Protocol Address TCPv4
 745
 746 This validates that a string value contains a valid resolvable v4 TCP Adress.
 747
 748         Usage: tcp4_addr
 749
 750 Transmission Control Protocol Address TCPv6
 751
 752 This validates that a string value contains a valid resolvable v6 TCP Adress.
 753
 754         Usage: tcp6_addr
 755
 756 User Datagram Protocol Address UDP
 757
 758 This validates that a string value contains a valid resolvable UDP Adress.
 759
 760         Usage: udp_addr
 761
 762 User Datagram Protocol Address UDPv4
 763
 764 This validates that a string value contains a valid resolvable v4 UDP Adress.
 765
 766         Usage: udp4_addr
 767
 768 User Datagram Protocol Address UDPv6
 769
 770 This validates that a string value contains a valid resolvable v6 UDP Adress.
 771
 772         Usage: udp6_addr
 773
 774 Internet Protocol Address IP
 775
 776 This validates that a string value contains a valid resolvable IP Adress.
 777
 778         Usage: ip_addr
 779
 780 Internet Protocol Address IPv4
 781
 782 This validates that a string value contains a valid resolvable v4 IP Adress.
 783
 784         Usage: ip4_addr
 785
 786 Internet Protocol Address IPv6
 787
 788 This validates that a string value contains a valid resolvable v6 IP Adress.
 789
 790         Usage: ip6_addr
 791
 792 Unix domain socket end point Address
 793
 794 This validates that a string value contains a valid Unix Adress.
 795
 796         Usage: unix_addr
 797
 798 Media Access Control Address MAC
 799
 800 This validates that a string value contains a valid MAC Adress.
 801
 802         Usage: mac
 803
 804 Note: See Go's ParseMAC for accepted formats and types:
 805
 806         http://golang.org/src/net/mac.go?s=866:918#L29
 807
 808 Alias Validators and Tags
 809
 810 NOTE: When returning an error, the tag returned in "FieldError" will be
 811 the alias tag unless the dive tag is part of the alias. Everything after the
 812 dive tag is not reported as the alias tag. Also, the "ActualTag" in the before
 813 case will be the actual tag within the alias that failed.
 814
 815 Here is a list of the current built in alias tags:
 816
 817         "iscolor"
 818                 alias is "hexcolor|rgb|rgba|hsl|hsla" (Usage: iscolor)
 819
 820 Validator notes:
 821
 822         regex
 823                 a regex validator won't be added because commas and = signs can be part
 824                 of a regex which conflict with the validation definitions. Although
 825                 workarounds can be made, they take away from using pure regex's.
 826                 Furthermore it's quick and dirty but the regex's become harder to
 827                 maintain and are not reusable, so it's as much a programming philosiphy
 828                 as anything.
 829
 830                 In place of this new validator functions should be created; a regex can
 831                 be used within the validator function and even be precompiled for better
 832                 efficiency within regexes.go.
 833
 834                 And the best reason, you can submit a pull request and we can keep on
 835                 adding to the validation library of this package!
 836
 837 Panics
 838
 839 This package panics when bad input is provided, this is by design, bad code like
 840 that should not make it to production.
 841
 842         type Test struct {
 843                 TestField string `validate:"nonexistantfunction=1"`
 844         }
 845
 846         t := &Test{
 847                 TestField: "Test"
 848         }
 849
 850         validate.Struct(t) // this will panic
 851 */
 852 package validator