Socket
Socket
Sign inDemoInstall

github.com/go-playground/validator/v10

Package Overview
Dependencies
Alerts
File Explorer
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

github.com/go-playground/validator/v10


Version published
Created
Source

Package validator

Join the chat at https://gitter.im/go-playground/validator Project status Build Status Coverage Status Go Report Card GoDoc License

Package validator implements value validations for structs and individual fields based on tags.

It has the following unique features:

  • Cross Field and Cross Struct validations by using validation tags or custom validators.
  • Slice, Array and Map diving, which allows any or all levels of a multidimensional field to be validated.
  • Ability to dive into both map keys and values for validation
  • Handles type interface by determining it's underlying type prior to validation.
  • Handles custom field types such as sql driver Valuer see Valuer
  • Alias validation tags, which allows for mapping of several validations to a single tag for easier defining of validations on structs
  • Extraction of custom defined Field Name e.g. can specify to extract the JSON name while validating and have it available in the resulting FieldError
  • Customizable i18n aware error messages.
  • Default validator for the gin web framework; upgrading from v8 to v9 in gin see here

Installation

Use go get.

go get github.com/go-playground/validator/v10

Then import the validator package into your own code.

import "github.com/go-playground/validator/v10"

Error Return Value

Validation functions return type error

They return type error to avoid the issue discussed in the following, where err is always != nil:

Validator returns only InvalidValidationError for bad validation input, nil or ValidationErrors as type error; so, in your code all you need to do is check if the error returned is not nil, and if it's not check if error is InvalidValidationError ( if necessary, most of the time it isn't ) type cast it to type ValidationErrors like so:

err := validate.Struct(mystruct)
validationErrors := err.(validator.ValidationErrors)

Usage and documentation

Please see https://pkg.go.dev/github.com/go-playground/validator/v10 for detailed usage docs.

Examples:

Baked-in Validations

Special Notes:

  • If new to using validator it is highly recommended to initialize it using the WithRequiredStructEnabled option which is opt-in to new behaviour that will become the default behaviour in v11+. See documentation for more details.
validate := validator.New(validator.WithRequiredStructEnabled())

Fields:

TagDescription
eqcsfieldField Equals Another Field (relative)
eqfieldField Equals Another Field
fieldcontainsCheck the indicated characters are present in the Field
fieldexcludesCheck the indicated characters are not present in the field
gtcsfieldField Greater Than Another Relative Field
gtecsfieldField Greater Than or Equal To Another Relative Field
gtefieldField Greater Than or Equal To Another Field
gtfieldField Greater Than Another Field
ltcsfieldLess Than Another Relative Field
ltecsfieldLess Than or Equal To Another Relative Field
ltefieldLess Than or Equal To Another Field
ltfieldLess Than Another Field
necsfieldField Does Not Equal Another Field (relative)
nefieldField Does Not Equal Another Field

Network:

TagDescription
cidrClassless Inter-Domain Routing CIDR
cidrv4Classless Inter-Domain Routing CIDRv4
cidrv6Classless Inter-Domain Routing CIDRv6
datauriData URL
fqdnFull Qualified Domain Name (FQDN)
hostnameHostname RFC 952
hostname_portHostPort
hostname_rfc1123Hostname RFC 1123
ipInternet Protocol Address IP
ip4_addrInternet Protocol Address IPv4
ip6_addrInternet Protocol Address IPv6
ip_addrInternet Protocol Address IP
ipv4Internet Protocol Address IPv4
ipv6Internet Protocol Address IPv6
macMedia Access Control Address MAC
tcp4_addrTransmission Control Protocol Address TCPv4
tcp6_addrTransmission Control Protocol Address TCPv6
tcp_addrTransmission Control Protocol Address TCP
udp4_addrUser Datagram Protocol Address UDPv4
udp6_addrUser Datagram Protocol Address UDPv6
udp_addrUser Datagram Protocol Address UDP
unix_addrUnix domain socket end point Address
uriURI String
urlURL String
http_urlHTTP URL String
url_encodedURL Encoded
urn_rfc2141Urn RFC 2141 String

Strings:

TagDescription
alphaAlpha Only
alphanumAlphanumeric
alphanumunicodeAlphanumeric Unicode
alphaunicodeAlpha Unicode
asciiASCII
booleanBoolean
containsContains
containsanyContains Any
containsruneContains Rune
endsnotwithEnds Not With
endswithEnds With
excludesExcludes
excludesallExcludes All
excludesruneExcludes Rune
lowercaseLowercase
multibyteMulti-Byte Characters
numberNumber
numericNumeric
printasciiPrintable ASCII
startsnotwithStarts Not With
startswithStarts With
uppercaseUppercase

Format:

TagDescription
base64Base64 String
base64urlBase64URL String
base64rawurlBase64RawURL String
bicBusiness Identifier Code (ISO 9362)
bcp47_language_tagLanguage tag (BCP 47)
btc_addrBitcoin Address
btc_addr_bech32Bitcoin Bech32 Address (segwit)
credit_cardCredit Card Number
mongodbMongoDB ObjectID
mongodb_connection_stringMongoDB Connection String
cronCron
spicedbSpiceDb ObjectID/Permission/Type
datetimeDatetime
e164e164 formatted phone number
emailE-mail String
eth_addrEthereum Address
hexadecimalHexadecimal String
hexcolorHexcolor String
hslHSL String
hslaHSLA String
htmlHTML Tags
html_encodedHTML Encoded
isbnInternational Standard Book Number
isbn10International Standard Book Number 10
isbn13International Standard Book Number 13
issnInternational Standard Serial Number
iso3166_1_alpha2Two-letter country code (ISO 3166-1 alpha-2)
iso3166_1_alpha3Three-letter country code (ISO 3166-1 alpha-3)
iso3166_1_alpha_numericNumeric country code (ISO 3166-1 numeric)
iso3166_2Country subdivision code (ISO 3166-2)
iso4217Currency code (ISO 4217)
jsonJSON
jwtJSON Web Token (JWT)
latitudeLatitude
longitudeLongitude
luhn_checksumLuhn Algorithm Checksum (for strings and (u)int)
postcode_iso3166_alpha2Postcode
postcode_iso3166_alpha2_fieldPostcode
rgbRGB String
rgbaRGBA String
ssnSocial Security Number SSN
timezoneTimezone
uuidUniversally Unique Identifier UUID
uuid3Universally Unique Identifier UUID v3
uuid3_rfc4122Universally Unique Identifier UUID v3 RFC4122
uuid4Universally Unique Identifier UUID v4
uuid4_rfc4122Universally Unique Identifier UUID v4 RFC4122
uuid5Universally Unique Identifier UUID v5
uuid5_rfc4122Universally Unique Identifier UUID v5 RFC4122
uuid_rfc4122Universally Unique Identifier UUID RFC4122
md4MD4 hash
md5MD5 hash
sha256SHA256 hash
sha384SHA384 hash
sha512SHA512 hash
ripemd128RIPEMD-128 hash
ripemd128RIPEMD-160 hash
tiger128TIGER128 hash
tiger160TIGER160 hash
tiger192TIGER192 hash
semverSemantic Versioning 2.0.0
ulidUniversally Unique Lexicographically Sortable Identifier ULID
cveCommon Vulnerabilities and Exposures Identifier (CVE id)

Comparisons:

TagDescription
eqEquals
eq_ignore_caseEquals ignoring case
gtGreater than
gteGreater than or equal
ltLess Than
lteLess Than or Equal
neNot Equal
ne_ignore_caseNot Equal ignoring case

Other:

TagDescription
dirExisting Directory
dirpathDirectory Path
fileExisting File
filepathFile Path
imageImage
isdefaultIs Default
lenLength
maxMaximum
minMinimum
oneofOne Of
requiredRequired
required_ifRequired If
required_unlessRequired Unless
required_withRequired With
required_with_allRequired With All
required_withoutRequired Without
required_without_allRequired Without All
excluded_ifExcluded If
excluded_unlessExcluded Unless
excluded_withExcluded With
excluded_with_allExcluded With All
excluded_withoutExcluded Without
excluded_without_allExcluded Without All
uniqueUnique
Aliases:
TagDescription
iscolorhexcolor|rgb|rgba|hsl|hsla
country_codeiso3166_1_alpha2|iso3166_1_alpha3|iso3166_1_alpha_numeric

Benchmarks

Run on MacBook Pro (15-inch, 2017) go version go1.10.2 darwin/amd64
go version go1.21.0 darwin/arm64
goos: darwin
goarch: arm64
pkg: github.com/go-playground/validator/v10
BenchmarkFieldSuccess-8                                         33142266                35.94 ns/op            0 B/op          0 allocs/op
BenchmarkFieldSuccessParallel-8                                 200816191                6.568 ns/op           0 B/op          0 allocs/op
BenchmarkFieldFailure-8                                          6779707               175.1 ns/op           200 B/op          4 allocs/op
BenchmarkFieldFailureParallel-8                                 11044147               108.4 ns/op           200 B/op          4 allocs/op
BenchmarkFieldArrayDiveSuccess-8                                 6054232               194.4 ns/op            97 B/op          5 allocs/op
BenchmarkFieldArrayDiveSuccessParallel-8                        12523388                94.07 ns/op           97 B/op          5 allocs/op
BenchmarkFieldArrayDiveFailure-8                                 3587043               334.3 ns/op           300 B/op         10 allocs/op
BenchmarkFieldArrayDiveFailureParallel-8                         5816665               200.8 ns/op           300 B/op         10 allocs/op
BenchmarkFieldMapDiveSuccess-8                                   2217910               540.1 ns/op           288 B/op         14 allocs/op
BenchmarkFieldMapDiveSuccessParallel-8                           4446698               258.7 ns/op           288 B/op         14 allocs/op
BenchmarkFieldMapDiveFailure-8                                   2392759               504.6 ns/op           376 B/op         13 allocs/op
BenchmarkFieldMapDiveFailureParallel-8                           4244199               286.9 ns/op           376 B/op         13 allocs/op
BenchmarkFieldMapDiveWithKeysSuccess-8                           2005857               592.1 ns/op           288 B/op         14 allocs/op
BenchmarkFieldMapDiveWithKeysSuccessParallel-8                   4400850               296.9 ns/op           288 B/op         14 allocs/op
BenchmarkFieldMapDiveWithKeysFailure-8                           1850227               643.8 ns/op           553 B/op         16 allocs/op
BenchmarkFieldMapDiveWithKeysFailureParallel-8                   3293233               375.1 ns/op           553 B/op         16 allocs/op
BenchmarkFieldCustomTypeSuccess-8                               12174412                98.25 ns/op           32 B/op          2 allocs/op
BenchmarkFieldCustomTypeSuccessParallel-8                       34389907                35.49 ns/op           32 B/op          2 allocs/op
BenchmarkFieldCustomTypeFailure-8                                7582524               156.6 ns/op           184 B/op          3 allocs/op
BenchmarkFieldCustomTypeFailureParallel-8                       13019902                92.79 ns/op          184 B/op          3 allocs/op
BenchmarkFieldOrTagSuccess-8                                     3427260               349.4 ns/op            16 B/op          1 allocs/op
BenchmarkFieldOrTagSuccessParallel-8                            15144128                81.25 ns/op           16 B/op          1 allocs/op
BenchmarkFieldOrTagFailure-8                                     5913546               201.9 ns/op           216 B/op          5 allocs/op
BenchmarkFieldOrTagFailureParallel-8                             9810212               113.7 ns/op           216 B/op          5 allocs/op
BenchmarkStructLevelValidationSuccess-8                         13456327                87.66 ns/op           16 B/op          1 allocs/op
BenchmarkStructLevelValidationSuccessParallel-8                 41818888                27.77 ns/op           16 B/op          1 allocs/op
BenchmarkStructLevelValidationFailure-8                          4166284               272.6 ns/op           264 B/op          7 allocs/op
BenchmarkStructLevelValidationFailureParallel-8                  7594581               152.1 ns/op           264 B/op          7 allocs/op
BenchmarkStructSimpleCustomTypeSuccess-8                         6508082               182.6 ns/op            32 B/op          2 allocs/op
BenchmarkStructSimpleCustomTypeSuccessParallel-8                23078605                54.78 ns/op           32 B/op          2 allocs/op
BenchmarkStructSimpleCustomTypeFailure-8                         3118352               381.0 ns/op           416 B/op          9 allocs/op
BenchmarkStructSimpleCustomTypeFailureParallel-8                 5300738               224.1 ns/op           432 B/op         10 allocs/op
BenchmarkStructFilteredSuccess-8                                 4761807               251.1 ns/op           216 B/op          5 allocs/op
BenchmarkStructFilteredSuccessParallel-8                         8792598               128.6 ns/op           216 B/op          5 allocs/op
BenchmarkStructFilteredFailure-8                                 5202573               232.1 ns/op           216 B/op          5 allocs/op
BenchmarkStructFilteredFailureParallel-8                         9591267               121.4 ns/op           216 B/op          5 allocs/op
BenchmarkStructPartialSuccess-8                                  5188512               231.6 ns/op           224 B/op          4 allocs/op
BenchmarkStructPartialSuccessParallel-8                          9179776               123.1 ns/op           224 B/op          4 allocs/op
BenchmarkStructPartialFailure-8                                  3071212               392.5 ns/op           440 B/op          9 allocs/op
BenchmarkStructPartialFailureParallel-8                          5344261               223.7 ns/op           440 B/op          9 allocs/op
BenchmarkStructExceptSuccess-8                                   3184230               375.0 ns/op           424 B/op          8 allocs/op
BenchmarkStructExceptSuccessParallel-8                          10090130               108.9 ns/op           208 B/op          3 allocs/op
BenchmarkStructExceptFailure-8                                   3347226               357.7 ns/op           424 B/op          8 allocs/op
BenchmarkStructExceptFailureParallel-8                           5654923               209.5 ns/op           424 B/op          8 allocs/op
BenchmarkStructSimpleCrossFieldSuccess-8                         5232265               229.1 ns/op            56 B/op          3 allocs/op
BenchmarkStructSimpleCrossFieldSuccessParallel-8                17436674                64.75 ns/op           56 B/op          3 allocs/op
BenchmarkStructSimpleCrossFieldFailure-8                         3128613               383.6 ns/op           272 B/op          8 allocs/op
BenchmarkStructSimpleCrossFieldFailureParallel-8                 6994113               168.8 ns/op           272 B/op          8 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccess-8              3506487               340.9 ns/op            64 B/op          4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-8     13431300                91.77 ns/op           64 B/op          4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailure-8              2410566               500.9 ns/op           288 B/op          9 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-8      6344510               188.2 ns/op           288 B/op          9 allocs/op
BenchmarkStructSimpleSuccess-8                                   8922726               133.8 ns/op             0 B/op          0 allocs/op
BenchmarkStructSimpleSuccessParallel-8                          55291153                23.63 ns/op            0 B/op          0 allocs/op
BenchmarkStructSimpleFailure-8                                   3171553               378.4 ns/op           416 B/op          9 allocs/op
BenchmarkStructSimpleFailureParallel-8                           5571692               212.0 ns/op           416 B/op          9 allocs/op
BenchmarkStructComplexSuccess-8                                  1683750               714.5 ns/op           224 B/op          5 allocs/op
BenchmarkStructComplexSuccessParallel-8                          4578046               257.0 ns/op           224 B/op          5 allocs/op
BenchmarkStructComplexFailure-8                                   481585              2547 ns/op            3041 B/op         48 allocs/op
BenchmarkStructComplexFailureParallel-8                           965764              1577 ns/op            3040 B/op         48 allocs/op
BenchmarkOneof-8                                                17380881                68.50 ns/op            0 B/op          0 allocs/op
BenchmarkOneofParallel-8                                         8084733               153.5 ns/op             0 B/op          0 allocs/op

Complementary Software

Here is a list of software that complements using this library either pre or post validation.

  • form - Decodes url.Values into Go value(s) and Encodes Go value(s) into url.Values. Dual Array and Full map support.
  • mold - A general library to help modify or set data within data structures and other objects

How to Contribute

Make a pull request...

License

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

Maintainers

This project has grown large enough that more than one person is required to properly support the community. If you are interested in becoming a maintainer please reach out to me https://github.com/deankarn

FAQs

Package last updated on 09 Sep 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc