validator

Package validator

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 and the Valuer interface
• 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

A Call for Maintainers

Please read the discussion started here if you are interested in contributing/helping maintain this package.

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:

• http://stackoverflow.com/a/29138676/3158232
• https://github.com/go-playground/validator/issues/134

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)
var validationErrors validator.ValidationErrors
errors.As(err, &validationErrors)

Usage and documentation

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

Examples:

• Simple
• Custom Field Types
• Struct Level
• Translations & Custom Errors
• Gin upgrade and/or override validator
• wash - an example application putting it all together

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:

Tag Description eqcsfield Field Equals Another Field (relative) eqfield Field Equals Another Field fieldcontains Check the indicated characters are present in the Field fieldexcludes Current field does not contain another field's value gtcsfield Field Greater Than Another Relative Field gtecsfield Field Greater Than or Equal To Another Relative Field gtefield Field Greater Than or Equal To Another Field gtfield Field Greater Than Another Field ltcsfield Less Than Another Relative Field ltecsfield Less Than or Equal To Another Relative Field ltefield Less Than or Equal To Another Field ltfield Less Than Another Field necsfield Field Does Not Equal Another Field (relative) nefield Field Does Not Equal Another Field

Network:

Tag Description cidr Classless Inter-Domain Routing CIDR cidrv4 Classless Inter-Domain Routing CIDRv4 cidrv6 Classless Inter-Domain Routing CIDRv6 datauri Data URL fqdn Full Qualified Domain Name (FQDN) hostname Hostname RFC 952 hostname_rfc1123 Hostname RFC 1123 hostname_port HostPort port Port number ip Internet Protocol Address IP ip4_addr Internet Protocol Address IPv4 ip6_addr Internet Protocol Address IPv6 ip_addr Internet Protocol Address IP ipv4 Internet Protocol Address IPv4 ipv6 Internet Protocol Address IPv6 mac Media Access Control Address MAC tcp4_addr Transmission Control Protocol Address TCPv4 tcp6_addr Transmission Control Protocol Address TCPv6 tcp_addr Transmission Control Protocol Address TCP udp4_addr User Datagram Protocol Address UDPv4 udp6_addr User Datagram Protocol Address UDPv6 udp_addr User Datagram Protocol Address UDP unix_addr Unix domain socket end point Address uds_exists Unix domain socket exists (checks filesystem sockets and Linux abstract sockets) uri URI String url URL String http_url HTTP(s) URL String https_url HTTPS-only URL String origin Web origin (URL with HTTP(S) scheme and host, but no path/query/fragment) url_encoded URL Encoded urn_rfc2141 Urn RFC 2141 String urn_rfc8141 Urn RFC 8141 String

Strings:

Tag Description alpha Alpha Only alphaspace Alpha Space alphanum Alphanumeric alphanumspace Alphanumeric Space alphanumunicode Alphanumeric Unicode alphaunicode Alpha Unicode ascii ASCII boolean Boolean contains Contains containsany Contains Any containsrune Contains Rune endsnotwith Ends Not With endswith Ends With excludes Excludes excludesall Excludes All excludesrune Excludes Rune lowercase Lowercase multibyte Multi-Byte Characters number Number numeric Numeric printascii Printable ASCII startsnotwith Starts Not With startswith Starts With uppercase Uppercase

Format:

Tag Description base64 Base64 String base64url Base64URL String base64rawurl Base64RawURL String bic_iso_9362_2014 Business Identifier Code (ISO 9362:2014) bic Business Identifier Code (ISO 9362:2022) bcp47_language_tag Language tag (BCP 47) bcp47_strict_language_tag Language tag (BCP 47), strictly following RFC 5646 btc_addr Bitcoin Address btc_addr_bech32 Bitcoin Bech32 Address (segwit) credit_card Credit Card Number mongodb MongoDB ObjectID mongodb_connection_string MongoDB Connection String cron Cron spicedb SpiceDb ObjectID/Permission/Type datetime Datetime e164 e164 formatted phone number ein U.S. Employer Identification Number email E-mail String eth_addr Ethereum Address hexadecimal Hexadecimal String hexcolor Hexcolor String hsl HSL String hsla HSLA String cmyk CMYK String html HTML Tags html_encoded HTML Encoded isbn International Standard Book Number isbn10 International Standard Book Number 10 isbn13 International Standard Book Number 13 issn International Standard Serial Number iso3166_1_alpha2 Two-letter country code (ISO 3166-1 alpha-2) iso3166_1_alpha3 Three-letter country code (ISO 3166-1 alpha-3) iso3166_1_alpha_numeric Numeric country code (ISO 3166-1 numeric) iso3166_2 Country subdivision code (ISO 3166-2) iso4217 Currency code (ISO 4217) json JSON jwt JSON Web Token (JWT) latitude Latitude longitude Longitude luhn_checksum Luhn Algorithm Checksum (for strings and (u)int) postcode_iso3166_alpha2 Postcode postcode_iso3166_alpha2_field Postcode rgb RGB String rgba RGBA String ssn Social Security Number SSN timezone Timezone uuid Universally Unique Identifier UUID uuid3 Universally Unique Identifier UUID v3 uuid3_rfc4122 Universally Unique Identifier UUID v3 RFC4122 uuid4 Universally Unique Identifier UUID v4 uuid4_rfc4122 Universally Unique Identifier UUID v4 RFC4122 uuid5 Universally Unique Identifier UUID v5 uuid5_rfc4122 Universally Unique Identifier UUID v5 RFC4122 uuid_rfc4122 Universally Unique Identifier UUID RFC4122 md4 MD4 hash md5 MD5 hash sha256 SHA256 hash sha384 SHA384 hash sha512 SHA512 hash ripemd128 RIPEMD-128 hash ripemd160 RIPEMD-160 hash tiger128 TIGER128 hash tiger160 TIGER160 hash tiger192 TIGER192 hash semver Semantic Versioning 2.0.0 ulid Universally Unique Lexicographically Sortable Identifier ULID cve Common Vulnerabilities and Exposures Identifier (CVE id)

Comparisons:

Tag Description eq Equals eq_ignore_case Equals ignoring case gt Greater than gte Greater than or equal lt Less Than lte Less Than or Equal ne Not Equal ne_ignore_case Not Equal ignoring case

Other:

Tag Description dir Existing Directory dirpath Directory Path file Existing File filepath File Path image Image mimetype MIME Type isdefault Is Default len Length max Maximum min Minimum oneof One Of noneof None Of required Required required_if Required If required_unless Required Unless required_with Required With required_with_all Required With All required_without Required Without required_without_all Required Without All excluded_if Excluded If excluded_unless Excluded Unless excluded_with Excluded With excluded_with_all Excluded With All excluded_without Excluded Without excluded_without_all Excluded Without All unique Unique validateFn Verify if the method Validate() error does not return an error (or any specified method)

Aliases:

Tag Description iscolor hexcolor|rgb|rgba|hsl|hsla|cmyk country_code iso3166_1_alpha2|iso3166_1_alpha3|iso3166_1_alpha_numeric

Benchmarks

Run on MacBook Pro Max M3

…

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...

Maintenance and support for SDK major versions

See prior discussion here for more details.

This package is aligned with the Go release policy in that support is guaranteed for the two most recent major versions.

This does not mean the package will not work with older versions of Go, only that we reserve the right to increase the MSGV(Minimum Supported Go Version) when the need arises to address Security issues/patches, OS issues & support or newly introduced functionali