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/master/_examples
9 10 # Singleton
11 12 Validator is designed to be thread-safe and used as a singleton instance.
13 It caches information about your struct and validations,
14 in essence only parsing your validation tags once per struct type.
15 Using multiple instances neglects the benefit of caching.
16 The not thread-safe functions are explicitly marked as such in the documentation.
17 18 # Validation Functions Return Type error
19 20 Doing things this way is actually the way the standard library does, see the
21 file.Open method here:
22 23 https://golang.org/pkg/os/#Open.
24 25 The authors return type "error" to avoid the issue discussed in the following,
26 where err is always != nil:
27 28 http://stackoverflow.com/a/29138676/3158232
29 https://github.com/go-playground/validator/issues/134
30 31 Validator only InvalidValidationError for bad validation input, nil or
32 ValidationErrors as type error; so, in your code all you need to do is check
33 if the error returned is not nil, and if it's not check if error is
34 InvalidValidationError ( if necessary, most of the time it isn't ) type cast
35 it to type ValidationErrors like so err.(validator.ValidationErrors).
36 37 # Custom Validation Functions
38 39 Custom Validation functions can be added. Example:
40 41 // Structure
42 func customFunc(fl validator.FieldLevel) bool {
43 44 if fl.Field().String() == "invalid" {
45 return false
46 }
47 48 return true
49 }
50 51 validate.RegisterValidation("custom tag name", customFunc)
52 // NOTES: using the same tag name as an existing function
53 // will overwrite the existing one
54 55 # Cross-Field Validation
56 57 Cross-Field Validation can be done via the following tags:
58 - eqfield
59 - nefield
60 - gtfield
61 - gtefield
62 - ltfield
63 - ltefield
64 - eqcsfield
65 - necsfield
66 - gtcsfield
67 - gtecsfield
68 - ltcsfield
69 - ltecsfield
70 71 If, however, some custom cross-field validation is required, it can be done
72 using a custom validation.
73 74 Why not just have cross-fields validation tags (i.e. only eqcsfield and not
75 eqfield)?
76 77 The reason is efficiency. If you want to check a field within the same struct
78 "eqfield" only has to find the field on the same struct (1 level). But, if we
79 used "eqcsfield" it could be multiple levels down. Example:
80 81 type Inner struct {
82 StartDate time.Time
83 }
84 85 type Outer struct {
86 InnerStructField *Inner
87 CreatedAt time.Time `validate:"ltecsfield=InnerStructField.StartDate"`
88 }
89 90 now := time.Now()
91 92 inner := &Inner{
93 StartDate: now,
94 }
95 96 outer := &Outer{
97 InnerStructField: inner,
98 CreatedAt: now,
99 }
100 101 errs := validate.Struct(outer)
102 103 // NOTE: when calling validate.Struct(val) topStruct will be the top level struct passed
104 // into the function
105 // when calling validate.VarWithValue(val, field, tag) val will be
106 // whatever you pass, struct, field...
107 // when calling validate.Field(field, tag) val will be nil
108 109 # Multiple Validators
110 111 Multiple validators on a field will process in the order defined. Example:
112 113 type Test struct {
114 Field `validate:"max=10,min=1"`
115 }
116 117 // max will be checked then min
118 119 Bad Validator definitions are not handled by the library. Example:
120 121 type Test struct {
122 Field `validate:"min=10,max=0"`
123 }
124 125 // this definition of min max will never succeed
126 127 # Using Validator Tags
128 129 Baked In Cross-Field validation only compares fields on the same struct.
130 If Cross-Field + Cross-Struct validation is needed you should implement your
131 own custom validator.
132 133 Comma (",") is the default separator of validation tags. If you wish to
134 have a comma included within the parameter (i.e. excludesall=,) you will need to
135 use the UTF-8 hex representation 0x2C, which is replaced in the code as a comma,
136 so the above will become excludesall=0x2C.
137 138 type Test struct {
139 Field `validate:"excludesall=,"` // BAD! Do not include a comma.
140 Field `validate:"excludesall=0x2C"` // GOOD! Use the UTF-8 hex representation.
141 }
142 143 Pipe ("|") is the 'or' validation tags deparator. If you wish to
144 have a pipe included within the parameter i.e. excludesall=| you will need to
145 use the UTF-8 hex representation 0x7C, which is replaced in the code as a pipe,
146 so the above will become excludesall=0x7C
147 148 type Test struct {
149 Field `validate:"excludesall=|"` // BAD! Do not include a pipe!
150 Field `validate:"excludesall=0x7C"` // GOOD! Use the UTF-8 hex representation.
151 }
152 153 # Baked In Validators and Tags
154 155 Here is a list of the current built in validators:
156 157 # Skip Field
158 159 Tells the validation to skip this struct field; this is particularly
160 handy in ignoring embedded structs from being validated. (Usage: -)
161 162 Usage: -
163 164 # Or Operator
165 166 This is the 'or' operator allowing multiple validators to be used and
167 accepted. (Usage: rgb|rgba) <-- this would allow either rgb or rgba
168 colors to be accepted. This can also be combined with 'and' for example
169 ( Usage: omitempty,rgb|rgba)
170 171 Usage: |
172 173 # StructOnly
174 175 When a field that is a nested struct is encountered, and contains this flag
176 any validation on the nested struct will be run, but none of the nested
177 struct fields will be validated. This is useful if inside of your program
178 you know the struct will be valid, but need to verify it has been assigned.
179 NOTE: only "required" and "omitempty" can be used on a struct itself.
180 181 Usage: structonly
182 183 # NoStructLevel
184 185 Same as structonly tag except that any struct level validations will not run.
186 187 Usage: nostructlevel
188 189 # Omit Empty
190 191 Allows conditional validation, for example if a field is not set with
192 a value (Determined by the "required" validator) then other validation
193 such as min or max won't run, but if a value is set validation will run.
194 195 Usage: omitempty
196 197 # Omit Nil
198 199 Allows to skip the validation if the value is nil (same as omitempty, but
200 only for the nil-values).
201 202 Usage: omitnil
203 204 # Dive
205 206 This tells the validator to dive into a slice, array or map and validate that
207 level of the slice, array or map with the validation tags that follow.
208 Multidimensional nesting is also supported, each level you wish to dive will
209 require another dive tag. dive has some sub-tags, 'keys' & 'endkeys', please see
210 the Keys & EndKeys section just below.
211 212 Usage: dive
213 214 Example #1
215 216 [][]string with validation tag "gt=0,dive,len=1,dive,required"
217 // gt=0 will be applied to []
218 // len=1 will be applied to []string
219 // required will be applied to string
220 221 Example #2
222 223 [][]string with validation tag "gt=0,dive,dive,required"
224 // gt=0 will be applied to []
225 // []string will be spared validation
226 // required will be applied to string
227 228 Keys & EndKeys
229 230 These are to be used together directly after the dive tag and tells the validator
231 that anything between 'keys' and 'endkeys' applies to the keys of a map and not the
232 values; think of it like the 'dive' tag, but for map keys instead of values.
233 Multidimensional nesting is also supported, each level you wish to validate will
234 require another 'keys' and 'endkeys' tag. These tags are only valid for maps.
235 236 Usage: dive,keys,othertagvalidation(s),endkeys,valuevalidationtags
237 238 Example #1
239 240 map[string]string with validation tag "gt=0,dive,keys,eq=1|eq=2,endkeys,required"
241 // gt=0 will be applied to the map itself
242 // eq=1|eq=2 will be applied to the map keys
243 // required will be applied to map values
244 245 Example #2
246 247 map[[2]string]string with validation tag "gt=0,dive,keys,dive,eq=1|eq=2,endkeys,required"
248 // gt=0 will be applied to the map itself
249 // eq=1|eq=2 will be applied to each array element in the map keys
250 // required will be applied to map values
251 252 # Required
253 254 This validates that the value is not the data types default zero value.
255 For numbers ensures value is not zero. For strings ensures value is
256 not "". For booleans ensures value is not false. For slices, maps, pointers, interfaces, channels and functions
257 ensures the value is not nil. For structs ensures value is not the zero value when using WithRequiredStructEnabled.
258 259 Usage: required
260 261 # Required If
262 263 The field under validation must be present and not empty only if all
264 the other specified fields are equal to the value following the specified
265 field. For strings ensures value is not "". For slices, maps, pointers,
266 interfaces, channels and functions ensures the value is not nil. For structs ensures value is not the zero value.
267 268 Usage: required_if
269 270 Examples:
271 272 // require the field if the Field1 is equal to the parameter given:
273 Usage: required_if=Field1 foobar
274 275 // require the field if the Field1 and Field2 is equal to the value respectively:
276 Usage: required_if=Field1 foo Field2 bar
277 278 # Required Unless
279 280 The field under validation must be present and not empty unless all
281 the other specified fields are equal to the value following the specified
282 field. For strings ensures value is not "". For slices, maps, pointers,
283 interfaces, channels and functions ensures the value is not nil. For structs ensures value is not the zero value.
284 285 Usage: required_unless
286 287 Examples:
288 289 // require the field unless the Field1 is equal to the parameter given:
290 Usage: required_unless=Field1 foobar
291 292 // require the field unless the Field1 and Field2 is equal to the value respectively:
293 Usage: required_unless=Field1 foo Field2 bar
294 295 # Required With
296 297 The field under validation must be present and not empty only if any
298 of the other specified fields are present. For strings ensures value is
299 not "". For slices, maps, pointers, interfaces, channels and functions
300 ensures the value is not nil. For structs ensures value is not the zero value.
301 302 Usage: required_with
303 304 Examples:
305 306 // require the field if the Field1 is present:
307 Usage: required_with=Field1
308 309 // require the field if the Field1 or Field2 is present:
310 Usage: required_with=Field1 Field2
311 312 # Required With All
313 314 The field under validation must be present and not empty only if all
315 of the other specified fields are present. For strings ensures value is
316 not "". For slices, maps, pointers, interfaces, channels and functions
317 ensures the value is not nil. For structs ensures value is not the zero value.
318 319 Usage: required_with_all
320 321 Example:
322 323 // require the field if the Field1 and Field2 is present:
324 Usage: required_with_all=Field1 Field2
325 326 # Required Without
327 328 The field under validation must be present and not empty only when any
329 of the other specified fields are not present. For strings ensures value is
330 not "". For slices, maps, pointers, interfaces, channels and functions
331 ensures the value is not nil. For structs ensures value is not the zero value.
332 333 Usage: required_without
334 335 Examples:
336 337 // require the field if the Field1 is not present:
338 Usage: required_without=Field1
339 340 // require the field if the Field1 or Field2 is not present:
341 Usage: required_without=Field1 Field2
342 343 # Required Without All
344 345 The field under validation must be present and not empty only when all
346 of the other specified fields are not present. For strings ensures value is
347 not "". For slices, maps, pointers, interfaces, channels and functions
348 ensures the value is not nil. For structs ensures value is not the zero value.
349 350 Usage: required_without_all
351 352 Example:
353 354 // require the field if the Field1 and Field2 is not present:
355 Usage: required_without_all=Field1 Field2
356 357 # Excluded If
358 359 The field under validation must not be present or not empty only if all
360 the other specified fields are equal to the value following the specified
361 field. For strings ensures value is not "". For slices, maps, pointers,
362 interfaces, channels and functions ensures the value is not nil. For structs ensures value is not the zero value.
363 364 Usage: excluded_if
365 366 Examples:
367 368 // exclude the field if the Field1 is equal to the parameter given:
369 Usage: excluded_if=Field1 foobar
370 371 // exclude the field if the Field1 and Field2 is equal to the value respectively:
372 Usage: excluded_if=Field1 foo Field2 bar
373 374 # Excluded Unless
375 376 The field under validation must not be present or empty unless all
377 the other specified fields are equal to the value following the specified
378 field. For strings ensures value is not "". For slices, maps, pointers,
379 interfaces, channels and functions ensures the value is not nil. For structs ensures value is not the zero value.
380 381 Usage: excluded_unless
382 383 Examples:
384 385 // exclude the field unless the Field1 is equal to the parameter given:
386 Usage: excluded_unless=Field1 foobar
387 388 // exclude the field unless the Field1 and Field2 is equal to the value respectively:
389 Usage: excluded_unless=Field1 foo Field2 bar
390 391 # Is Default
392 393 This validates that the value is the default value and is almost the
394 opposite of required.
395 396 Usage: isdefault
397 398 # Length
399 400 For numbers, length will ensure that the value is
401 equal to the parameter given. For strings, it checks that
402 the string length is exactly that number of characters. For slices,
403 arrays, and maps, validates the number of items.
404 405 Example #1
406 407 Usage: len=10
408 409 Example #2 (time.Duration)
410 411 For time.Duration, len will ensure that the value is equal to the duration given
412 in the parameter.
413 414 Usage: len=1h30m
415 416 # Maximum
417 418 For numbers, max will ensure that the value is
419 less than or equal to the parameter given. For strings, it checks
420 that the string length is at most that number of characters. For
421 slices, arrays, and maps, validates the number of items.
422 423 Example #1
424 425 Usage: max=10
426 427 Example #2 (time.Duration)
428 429 For time.Duration, max will ensure that the value is less than or equal to the
430 duration given in the parameter.
431 432 Usage: max=1h30m
433 434 # Minimum
435 436 For numbers, min will ensure that the value is
437 greater or equal to the parameter given. For strings, it checks that
438 the string length is at least that number of characters. For slices,
439 arrays, and maps, validates the number of items.
440 441 Example #1
442 443 Usage: min=10
444 445 Example #2 (time.Duration)
446 447 For time.Duration, min will ensure that the value is greater than or equal to
448 the duration given in the parameter.
449 450 Usage: min=1h30m
451 452 # Equals
453 454 For strings & numbers, eq will ensure that the value is
455 equal to the parameter given. For slices, arrays, and maps,
456 validates the number of items.
457 458 Example #1
459 460 Usage: eq=10
461 462 Example #2 (time.Duration)
463 464 For time.Duration, eq will ensure that the value is equal to the duration given
465 in the parameter.
466 467 Usage: eq=1h30m
468 469 # Not Equal
470 471 For strings & numbers, ne will ensure that the value is not
472 equal to the parameter given. For slices, arrays, and maps,
473 validates the number of items.
474 475 Example #1
476 477 Usage: ne=10
478 479 Example #2 (time.Duration)
480 481 For time.Duration, ne will ensure that the value is not equal to the duration
482 given in the parameter.
483 484 Usage: ne=1h30m
485 486 # One Of
487 488 For strings, ints, and uints, oneof will ensure that the value
489 is one of the values in the parameter. The parameter should be
490 a list of values separated by whitespace. Values may be
491 strings or numbers. To match strings with spaces in them, include
492 the target string between single quotes. Kind of like an 'enum'.
493 494 Usage: oneof=red green
495 oneof='red green' 'blue yellow'
496 oneof=5 7 9
497 498 # One Of Case Insensitive
499 500 Works the same as oneof but is case insensitive and therefore only accepts strings.
501 502 Usage: oneofci=red green
503 oneofci='red green' 'blue yellow'
504 505 # Greater Than
506 507 For numbers, this will ensure that the value is greater than the
508 parameter given. For strings, it checks that the string length
509 is greater than that number of characters. For slices, arrays
510 and maps it validates the number of items.
511 512 Example #1
513 514 Usage: gt=10
515 516 Example #2 (time.Time)
517 518 For time.Time ensures the time value is greater than time.Now.UTC().
519 520 Usage: gt
521 522 Example #3 (time.Duration)
523 524 For time.Duration, gt will ensure that the value is greater than the duration
525 given in the parameter.
526 527 Usage: gt=1h30m
528 529 # Greater Than or Equal
530 531 Same as 'min' above. Kept both to make terminology with 'len' easier.
532 533 Example #1
534 535 Usage: gte=10
536 537 Example #2 (time.Time)
538 539 For time.Time ensures the time value is greater than or equal to time.Now.UTC().
540 541 Usage: gte
542 543 Example #3 (time.Duration)
544 545 For time.Duration, gte will ensure that the value is greater than or equal to
546 the duration given in the parameter.
547 548 Usage: gte=1h30m
549 550 # Less Than
551 552 For numbers, this will ensure that the value is less than the parameter given.
553 For strings, it checks that the string length is less than that number of
554 characters. For slices, arrays, and maps it validates the number of items.
555 556 Example #1
557 558 Usage: lt=10
559 560 Example #2 (time.Time)
561 562 For time.Time ensures the time value is less than time.Now.UTC().
563 564 Usage: lt
565 566 Example #3 (time.Duration)
567 568 For time.Duration, lt will ensure that the value is less than the duration given
569 in the parameter.
570 571 Usage: lt=1h30m
572 573 # Less Than or Equal
574 575 Same as 'max' above. Kept both to make terminology with 'len' easier.
576 577 Example #1
578 579 Usage: lte=10
580 581 Example #2 (time.Time)
582 583 For time.Time ensures the time value is less than or equal to time.Now.UTC().
584 585 Usage: lte
586 587 Example #3 (time.Duration)
588 589 For time.Duration, lte will ensure that the value is less than or equal to the
590 duration given in the parameter.
591 592 Usage: lte=1h30m
593 594 # Field Equals Another Field
595 596 This will validate the field value against another fields value either within
597 a struct or passed in field.
598 599 Example #1:
600 601 // Validation on Password field using:
602 Usage: eqfield=ConfirmPassword
603 604 Example #2:
605 606 // Validating by field:
607 validate.VarWithValue(password, confirmpassword, "eqfield")
608 609 Field Equals Another Field (relative)
610 611 This does the same as eqfield except that it validates the field provided relative
612 to the top level struct.
613 614 Usage: eqcsfield=InnerStructField.Field)
615 616 # Field Does Not Equal Another Field
617 618 This will validate the field value against another fields value either within
619 a struct or passed in field.
620 621 Examples:
622 623 // Confirm two colors are not the same:
624 //
625 // Validation on Color field:
626 Usage: nefield=Color2
627 628 // Validating by field:
629 validate.VarWithValue(color1, color2, "nefield")
630 631 Field Does Not Equal Another Field (relative)
632 633 This does the same as nefield except that it validates the field provided
634 relative to the top level struct.
635 636 Usage: necsfield=InnerStructField.Field
637 638 # Field Greater Than Another Field
639 640 Only valid for Numbers, time.Duration and time.Time types, this will validate
641 the field value against another fields value either within a struct or passed in
642 field. usage examples are for validation of a Start and End date:
643 644 Example #1:
645 646 // Validation on End field using:
647 validate.Struct Usage(gtfield=Start)
648 649 Example #2:
650 651 // Validating by field:
652 validate.VarWithValue(start, end, "gtfield")
653 654 # Field Greater Than Another Relative Field
655 656 This does the same as gtfield except that it validates the field provided
657 relative to the top level struct.
658 659 Usage: gtcsfield=InnerStructField.Field
660 661 # Field Greater Than or Equal To Another Field
662 663 Only valid for Numbers, time.Duration and time.Time types, this will validate
664 the field value against another fields value either within a struct or passed in
665 field. usage examples are for validation of a Start and End date:
666 667 Example #1:
668 669 // Validation on End field using:
670 validate.Struct Usage(gtefield=Start)
671 672 Example #2:
673 674 // Validating by field:
675 validate.VarWithValue(start, end, "gtefield")
676 677 # Field Greater Than or Equal To Another Relative Field
678 679 This does the same as gtefield except that it validates the field provided relative
680 to the top level struct.
681 682 Usage: gtecsfield=InnerStructField.Field
683 684 # Less Than Another Field
685 686 Only valid for Numbers, time.Duration and time.Time types, this will validate
687 the field value against another fields value either within a struct or passed in
688 field. usage examples are for validation of a Start and End date:
689 690 Example #1:
691 692 // Validation on End field using:
693 validate.Struct Usage(ltfield=Start)
694 695 Example #2:
696 697 // Validating by field:
698 validate.VarWithValue(start, end, "ltfield")
699 700 # Less Than Another Relative Field
701 702 This does the same as ltfield except that it validates the field provided relative
703 to the top level struct.
704 705 Usage: ltcsfield=InnerStructField.Field
706 707 # Less Than or Equal To Another Field
708 709 Only valid for Numbers, time.Duration and time.Time types, this will validate
710 the field value against another fields value either within a struct or passed in
711 field. usage examples are for validation of a Start and End date:
712 713 Example #1:
714 715 // Validation on End field using:
716 validate.Struct Usage(ltefield=Start)
717 718 Example #2:
719 720 // Validating by field:
721 validate.VarWithValue(start, end, "ltefield")
722 723 # Less Than or Equal To Another Relative Field
724 725 This does the same as ltefield except that it validates the field provided relative
726 to the top level struct.
727 728 Usage: ltecsfield=InnerStructField.Field
729 730 # Field Contains Another Field
731 732 This does the same as contains except for struct fields. It should only be used
733 with string types. See the behavior of reflect.Value.String() for behavior on
734 other types.
735 736 Usage: containsfield=InnerStructField.Field
737 738 # Field Excludes Another Field
739 740 This does the same as excludes except for struct fields. It should only be used
741 with string types. See the behavior of reflect.Value.String() for behavior on
742 other types.
743 744 Usage: excludesfield=InnerStructField.Field
745 746 # Unique
747 748 For arrays & slices, unique will ensure that there are no duplicates.
749 For maps, unique will ensure that there are no duplicate values.
750 For slices of struct, unique will ensure that there are no duplicate values
751 in a field of the struct specified via a parameter.
752 753 // For arrays, slices, and maps:
754 Usage: unique
755 756 // For slices of struct:
757 Usage: unique=field
758 759 # Alpha Only
760 761 This validates that a string value contains ASCII alpha characters only
762 763 Usage: alpha
764 765 # Alphanumeric
766 767 This validates that a string value contains ASCII alphanumeric characters only
768 769 Usage: alphanum
770 771 # Alpha Unicode
772 773 This validates that a string value contains unicode alpha characters only
774 775 Usage: alphaunicode
776 777 # Alphanumeric Unicode
778 779 This validates that a string value contains unicode alphanumeric characters only
780 781 Usage: alphanumunicode
782 783 # Boolean
784 785 This validates that a string value can successfully be parsed into a boolean with strconv.ParseBool
786 787 Usage: boolean
788 789 # Number
790 791 This validates that a string value contains number values only.
792 For integers or float it returns true.
793 794 Usage: number
795 796 # Numeric
797 798 This validates that a string value contains a basic numeric value.
799 basic excludes exponents etc...
800 for integers or float it returns true.
801 802 Usage: numeric
803 804 # Hexadecimal String
805 806 This validates that a string value contains a valid hexadecimal.
807 808 Usage: hexadecimal
809 810 # Hexcolor String
811 812 This validates that a string value contains a valid hex color including
813 hashtag (#)
814 815 Usage: hexcolor
816 817 # Lowercase String
818 819 This validates that a string value contains only lowercase characters. An empty string is not a valid lowercase string.
820 821 Usage: lowercase
822 823 # Uppercase String
824 825 This validates that a string value contains only uppercase characters. An empty string is not a valid uppercase string.
826 827 Usage: uppercase
828 829 # RGB String
830 831 This validates that a string value contains a valid rgb color
832 833 Usage: rgb
834 835 # RGBA String
836 837 This validates that a string value contains a valid rgba color
838 839 Usage: rgba
840 841 # HSL String
842 843 This validates that a string value contains a valid hsl color
844 845 Usage: hsl
846 847 # HSLA String
848 849 This validates that a string value contains a valid hsla color
850 851 Usage: hsla
852 853 # E.164 Phone Number String
854 855 This validates that a string value contains a valid E.164 Phone number
856 https://en.wikipedia.org/wiki/E.164 (ex. +1123456789)
857 858 Usage: e164
859 860 # E-mail String
861 862 This validates that a string value contains a valid email
863 This may not conform to all possibilities of any rfc standard, but neither
864 does any email provider accept all possibilities.
865 866 Usage: email
867 868 # JSON String
869 870 This validates that a string value is valid JSON
871 872 Usage: json
873 874 # JWT String
875 876 This validates that a string value is a valid JWT
877 878 Usage: jwt
879 880 # File
881 882 This validates that a string value contains a valid file path and that
883 the file exists on the machine.
884 This is done using os.Stat, which is a platform independent function.
885 886 Usage: file
887 888 # Image path
889 890 This validates that a string value contains a valid file path and that
891 the file exists on the machine and is an image.
892 This is done using os.Stat and github.com/gabriel-vasile/mimetype
893 894 Usage: image
895 896 # File Path
897 898 This validates that a string value contains a valid file path but does not
899 validate the existence of that file.
900 This is done using os.Stat, which is a platform independent function.
901 902 Usage: filepath
903 904 # URL String
905 906 This validates that a string value contains a valid url
907 This will accept any url the golang request uri accepts but must contain
908 a schema for example http:// or rtmp://
909 910 Usage: url
911 912 # URI String
913 914 This validates that a string value contains a valid uri
915 This will accept any uri the golang request uri accepts
916 917 Usage: uri
918 919 # Urn RFC 2141 String
920 921 This validates that a string value contains a valid URN
922 according to the RFC 2141 spec.
923 924 Usage: urn_rfc2141
925 926 # Base32 String
927 928 This validates that a string value contains a valid bas324 value.
929 Although an empty string is valid base32 this will report an empty string
930 as an error, if you wish to accept an empty string as valid you can use
931 this with the omitempty tag.
932 933 Usage: base32
934 935 # Base64 String
936 937 This validates that a string value contains a valid base64 value.
938 Although an empty string is valid base64 this will report an empty string
939 as an error, if you wish to accept an empty string as valid you can use
940 this with the omitempty tag.
941 942 Usage: base64
943 944 # Base64URL String
945 946 This validates that a string value contains a valid base64 URL safe value
947 according the RFC4648 spec.
948 Although an empty string is a valid base64 URL safe value, this will report
949 an empty string as an error, if you wish to accept an empty string as valid
950 you can use this with the omitempty tag.
951 952 Usage: base64url
953 954 # Base64RawURL String
955 956 This validates that a string value contains a valid base64 URL safe value,
957 but without = padding, according the RFC4648 spec, section 3.2.
958 Although an empty string is a valid base64 URL safe value, this will report
959 an empty string as an error, if you wish to accept an empty string as valid
960 you can use this with the omitempty tag.
961 962 Usage: base64url
963 964 # Bitcoin Address
965 966 This validates that a string value contains a valid bitcoin address.
967 The format of the string is checked to ensure it matches one of the three formats
968 P2PKH, P2SH and performs checksum validation.
969 970 Usage: btc_addr
971 972 Bitcoin Bech32 Address (segwit)
973 974 This validates that a string value contains a valid bitcoin Bech32 address as defined
975 by bip-0173 (https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki)
976 Special thanks to Pieter Wuille for providing reference implementations.
977 978 Usage: btc_addr_bech32
979 980 # Ethereum Address
981 982 This validates that a string value contains a valid ethereum address.
983 The format of the string is checked to ensure it matches the standard Ethereum address format.
984 985 Usage: eth_addr
986 987 # Contains
988 989 This validates that a string value contains the substring value.
990 991 Usage: contains=@
992 993 # Contains Any
994 995 This validates that a string value contains any Unicode code points
996 in the substring value.
997 998 Usage: containsany=!@#?
999 1000 # Contains Rune
1001 1002 This validates that a string value contains the supplied rune value.
1003 1004 Usage: containsrune=@
1005 1006 # Excludes
1007 1008 This validates that a string value does not contain the substring value.
1009 1010 Usage: excludes=@
1011 1012 # Excludes All
1013 1014 This validates that a string value does not contain any Unicode code
1015 points in the substring value.
1016 1017 Usage: excludesall=!@#?
1018 1019 # Excludes Rune
1020 1021 This validates that a string value does not contain the supplied rune value.
1022 1023 Usage: excludesrune=@
1024 1025 # Starts With
1026 1027 This validates that a string value starts with the supplied string value
1028 1029 Usage: startswith=hello
1030 1031 # Ends With
1032 1033 This validates that a string value ends with the supplied string value
1034 1035 Usage: endswith=goodbye
1036 1037 # Does Not Start With
1038 1039 This validates that a string value does not start with the supplied string value
1040 1041 Usage: startsnotwith=hello
1042 1043 # Does Not End With
1044 1045 This validates that a string value does not end with the supplied string value
1046 1047 Usage: endsnotwith=goodbye
1048 1049 # International Standard Book Number
1050 1051 This validates that a string value contains a valid isbn10 or isbn13 value.
1052 1053 Usage: isbn
1054 1055 # International Standard Book Number 10
1056 1057 This validates that a string value contains a valid isbn10 value.
1058 1059 Usage: isbn10
1060 1061 # International Standard Book Number 13
1062 1063 This validates that a string value contains a valid isbn13 value.
1064 1065 Usage: isbn13
1066 1067 # Universally Unique Identifier UUID
1068 1069 This validates that a string value contains a valid UUID. Uppercase UUID values will not pass - use `uuid_rfc4122` instead.
1070 1071 Usage: uuid
1072 1073 # Universally Unique Identifier UUID v3
1074 1075 This validates that a string value contains a valid version 3 UUID. Uppercase UUID values will not pass - use `uuid3_rfc4122` instead.
1076 1077 Usage: uuid3
1078 1079 # Universally Unique Identifier UUID v4
1080 1081 This validates that a string value contains a valid version 4 UUID. Uppercase UUID values will not pass - use `uuid4_rfc4122` instead.
1082 1083 Usage: uuid4
1084 1085 # Universally Unique Identifier UUID v5
1086 1087 This validates that a string value contains a valid version 5 UUID. Uppercase UUID values will not pass - use `uuid5_rfc4122` instead.
1088 1089 Usage: uuid5
1090 1091 # Universally Unique Lexicographically Sortable Identifier ULID
1092 1093 This validates that a string value contains a valid ULID value.
1094 1095 Usage: ulid
1096 1097 # ASCII
1098 1099 This validates that a string value contains only ASCII characters.
1100 NOTE: if the string is blank, this validates as true.
1101 1102 Usage: ascii
1103 1104 # Printable ASCII
1105 1106 This validates that a string value contains only printable ASCII characters.
1107 NOTE: if the string is blank, this validates as true.
1108 1109 Usage: printascii
1110 1111 # Multi-Byte Characters
1112 1113 This validates that a string value contains one or more multibyte characters.
1114 NOTE: if the string is blank, this validates as true.
1115 1116 Usage: multibyte
1117 1118 # Data URL
1119 1120 This validates that a string value contains a valid DataURI.
1121 NOTE: this will also validate that the data portion is valid base64
1122 1123 Usage: datauri
1124 1125 # Latitude
1126 1127 This validates that a string value contains a valid latitude.
1128 1129 Usage: latitude
1130 1131 # Longitude
1132 1133 This validates that a string value contains a valid longitude.
1134 1135 Usage: longitude
1136 1137 # Social Security Number SSN
1138 1139 This validates that a string value contains a valid U.S. Social Security Number.
1140 1141 Usage: ssn
1142 1143 # Internet Protocol Address IP
1144 1145 This validates that a string value contains a valid IP Address.
1146 1147 Usage: ip
1148 1149 # Internet Protocol Address IPv4
1150 1151 This validates that a string value contains a valid v4 IP Address.
1152 1153 Usage: ipv4
1154 1155 # Internet Protocol Address IPv6
1156 1157 This validates that a string value contains a valid v6 IP Address.
1158 1159 Usage: ipv6
1160 1161 # Classless Inter-Domain Routing CIDR
1162 1163 This validates that a string value contains a valid CIDR Address.
1164 1165 Usage: cidr
1166 1167 # Classless Inter-Domain Routing CIDRv4
1168 1169 This validates that a string value contains a valid v4 CIDR Address.
1170 1171 Usage: cidrv4
1172 1173 # Classless Inter-Domain Routing CIDRv6
1174 1175 This validates that a string value contains a valid v6 CIDR Address.
1176 1177 Usage: cidrv6
1178 1179 # Transmission Control Protocol Address TCP
1180 1181 This validates that a string value contains a valid resolvable TCP Address.
1182 1183 Usage: tcp_addr
1184 1185 # Transmission Control Protocol Address TCPv4
1186 1187 This validates that a string value contains a valid resolvable v4 TCP Address.
1188 1189 Usage: tcp4_addr
1190 1191 # Transmission Control Protocol Address TCPv6
1192 1193 This validates that a string value contains a valid resolvable v6 TCP Address.
1194 1195 Usage: tcp6_addr
1196 1197 # User Datagram Protocol Address UDP
1198 1199 This validates that a string value contains a valid resolvable UDP Address.
1200 1201 Usage: udp_addr
1202 1203 # User Datagram Protocol Address UDPv4
1204 1205 This validates that a string value contains a valid resolvable v4 UDP Address.
1206 1207 Usage: udp4_addr
1208 1209 # User Datagram Protocol Address UDPv6
1210 1211 This validates that a string value contains a valid resolvable v6 UDP Address.
1212 1213 Usage: udp6_addr
1214 1215 # Internet Protocol Address IP
1216 1217 This validates that a string value contains a valid resolvable IP Address.
1218 1219 Usage: ip_addr
1220 1221 # Internet Protocol Address IPv4
1222 1223 This validates that a string value contains a valid resolvable v4 IP Address.
1224 1225 Usage: ip4_addr
1226 1227 # Internet Protocol Address IPv6
1228 1229 This validates that a string value contains a valid resolvable v6 IP Address.
1230 1231 Usage: ip6_addr
1232 1233 # Unix domain socket end point Address
1234 1235 This validates that a string value contains a valid Unix Address.
1236 1237 Usage: unix_addr
1238 1239 # Media Access Control Address MAC
1240 1241 This validates that a string value contains a valid MAC Address.
1242 1243 Usage: mac
1244 1245 Note: See Go's ParseMAC for accepted formats and types:
1246 1247 http://golang.org/src/net/mac.go?s=866:918#L29
1248 1249 # Hostname RFC 952
1250 1251 This validates that a string value is a valid Hostname according to RFC 952 https://tools.ietf.org/html/rfc952
1252 1253 Usage: hostname
1254 1255 # Hostname RFC 1123
1256 1257 This validates that a string value is a valid Hostname according to RFC 1123 https://tools.ietf.org/html/rfc1123
1258 1259 Usage: hostname_rfc1123 or if you want to continue to use 'hostname' in your tags, create an alias.
1260 1261 Full Qualified Domain Name (FQDN)
1262 1263 This validates that a string value contains a valid FQDN.
1264 1265 Usage: fqdn
1266 1267 # HTML Tags
1268 1269 This validates that a string value appears to be an HTML element tag
1270 including those described at https://developer.mozilla.org/en-US/docs/Web/HTML/Element
1271 1272 Usage: html
1273 1274 # HTML Encoded
1275 1276 This validates that a string value is a proper character reference in decimal
1277 or hexadecimal format
1278 1279 Usage: html_encoded
1280 1281 # URL Encoded
1282 1283 This validates that a string value is percent-encoded (URL encoded) according
1284 to https://tools.ietf.org/html/rfc3986#section-2.1
1285 1286 Usage: url_encoded
1287 1288 # Directory
1289 1290 This validates that a string value contains a valid directory and that
1291 it exists on the machine.
1292 This is done using os.Stat, which is a platform independent function.
1293 1294 Usage: dir
1295 1296 # Directory Path
1297 1298 This validates that a string value contains a valid directory but does
1299 not validate the existence of that directory.
1300 This is done using os.Stat, which is a platform independent function.
1301 It is safest to suffix the string with os.PathSeparator if the directory
1302 may not exist at the time of validation.
1303 1304 Usage: dirpath
1305 1306 # HostPort
1307 1308 This validates that a string value contains a valid DNS hostname and port that
1309 can be used to validate fields typically passed to sockets and connections.
1310 1311 Usage: hostname_port
1312 1313 # Datetime
1314 1315 This validates that a string value is a valid datetime based on the supplied datetime format.
1316 Supplied format must match the official Go time format layout as documented in https://golang.org/pkg/time/
1317 1318 Usage: datetime=2006-01-02
1319 1320 # Iso3166-1 alpha-2
1321 1322 This validates that a string value is a valid country code based on iso3166-1 alpha-2 standard.
1323 see: https://www.iso.org/iso-3166-country-codes.html
1324 1325 Usage: iso3166_1_alpha2
1326 1327 # Iso3166-1 alpha-3
1328 1329 This validates that a string value is a valid country code based on iso3166-1 alpha-3 standard.
1330 see: https://www.iso.org/iso-3166-country-codes.html
1331 1332 Usage: iso3166_1_alpha3
1333 1334 # Iso3166-1 alpha-numeric
1335 1336 This validates that a string value is a valid country code based on iso3166-1 alpha-numeric standard.
1337 see: https://www.iso.org/iso-3166-country-codes.html
1338 1339 Usage: iso3166_1_alpha3
1340 1341 # BCP 47 Language Tag
1342 1343 This validates that a string value is a valid BCP 47 language tag, as parsed by language.Parse.
1344 More information on https://pkg.go.dev/golang.org/x/text/language
1345 1346 Usage: bcp47_language_tag
1347 1348 BIC (SWIFT code)
1349 1350 This validates that a string value is a valid Business Identifier Code (SWIFT code), defined in ISO 9362.
1351 More information on https://www.iso.org/standard/60390.html
1352 1353 Usage: bic
1354 1355 # RFC 1035 label
1356 1357 This validates that a string value is a valid dns RFC 1035 label, defined in RFC 1035.
1358 More information on https://datatracker.ietf.org/doc/html/rfc1035
1359 1360 Usage: dns_rfc1035_label
1361 1362 # TimeZone
1363 1364 This validates that a string value is a valid time zone based on the time zone database present on the system.
1365 Although empty value and Local value are allowed by time.LoadLocation golang function, they are not allowed by this validator.
1366 More information on https://golang.org/pkg/time/#LoadLocation
1367 1368 Usage: timezone
1369 1370 # Semantic Version
1371 1372 This validates that a string value is a valid semver version, defined in Semantic Versioning 2.0.0.
1373 More information on https://semver.org/
1374 1375 Usage: semver
1376 1377 # CVE Identifier
1378 1379 This validates that a string value is a valid cve id, defined in cve mitre.
1380 More information on https://cve.mitre.org/
1381 1382 Usage: cve
1383 1384 # Credit Card
1385 1386 This validates that a string value contains a valid credit card number using Luhn algorithm.
1387 1388 Usage: credit_card
1389 1390 # Luhn Checksum
1391 1392 Usage: luhn_checksum
1393 1394 This validates that a string or (u)int value contains a valid checksum using the Luhn algorithm.
1395 1396 # MongoDB
1397 1398 This validates that a string is a valid 24 character hexadecimal string or valid connection string.
1399 1400 Usage: mongodb
1401 mongodb_connection_string
1402 1403 Example:
1404 1405 type Test struct {
1406 ObjectIdField string `validate:"mongodb"`
1407 ConnectionStringField string `validate:"mongodb_connection_string"`
1408 }
1409 1410 # Cron
1411 1412 This validates that a string value contains a valid cron expression.
1413 1414 Usage: cron
1415 1416 # SpiceDb ObjectID/Permission/Object Type
1417 1418 This validates that a string is valid for use with SpiceDb for the indicated purpose. If no purpose is given, a purpose of 'id' is assumed.
1419 1420 Usage: spicedb=id|permission|type
1421 1422 # Alias Validators and Tags
1423 1424 Alias Validators and Tags
1425 NOTE: When returning an error, the tag returned in "FieldError" will be
1426 the alias tag unless the dive tag is part of the alias. Everything after the
1427 dive tag is not reported as the alias tag. Also, the "ActualTag" in the before
1428 case will be the actual tag within the alias that failed.
1429 1430 Here is a list of the current built in alias tags:
1431 1432 "iscolor"
1433 alias is "hexcolor|rgb|rgba|hsl|hsla" (Usage: iscolor)
1434 "country_code"
1435 alias is "iso3166_1_alpha2|iso3166_1_alpha3|iso3166_1_alpha_numeric" (Usage: country_code)
1436 1437 Validator notes:
1438 1439 regex
1440 a regex validator won't be added because commas and = signs can be part
1441 of a regex which conflict with the validation definitions. Although
1442 workarounds can be made, they take away from using pure regex's.
1443 Furthermore it's quick and dirty but the regex's become harder to
1444 maintain and are not reusable, so it's as much a programming philosophy
1445 as anything.
1446 1447 In place of this new validator functions should be created; a regex can
1448 be used within the validator function and even be precompiled for better
1449 efficiency within regexes.go.
1450 1451 And the best reason, you can submit a pull request and we can keep on
1452 adding to the validation library of this package!
1453 1454 # Non standard validators
1455 1456 A collection of validation rules that are frequently needed but are more
1457 complex than the ones found in the baked in validators.
1458 A non standard validator must be registered manually like you would
1459 with your own custom validation functions.
1460 1461 Example of registration and use:
1462 1463 type Test struct {
1464 TestField string `validate:"yourtag"`
1465 }
1466 1467 t := &Test{
1468 TestField: "Test"
1469 }
1470 1471 validate := validator.New()
1472 validate.RegisterValidation("yourtag", validators.NotBlank)
1473 1474 Here is a list of the current non standard validators:
1475 1476 NotBlank
1477 This validates that the value is not blank or with length zero.
1478 For strings ensures they do not contain only spaces. For channels, maps, slices and arrays
1479 ensures they don't have zero length. For others, a non empty value is required.
1480 1481 Usage: notblank
1482 1483 # Panics
1484 1485 This package panics when bad input is provided, this is by design, bad code like
1486 that should not make it to production.
1487 1488 type Test struct {
1489 TestField string `validate:"nonexistantfunction=1"`
1490 }
1491 1492 t := &Test{
1493 TestField: "Test"
1494 }
1495 1496 validate.Struct(t) // this will panic
1497 */
1498 package validator
1499