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