DOCSEARCHbyAlgolia
Submit Docs

go-playground/validator v10

repository·master·Indexed 12 days ago

https://github.com/go-playground/validator

A Go package for implementing value validations for structs and individual fields based on tags. It supports cross-field, cross-struct, and deep diving validations, providing tools for custom validation functions via the FieldLevel and StructLevel interfaces, as well as translation support for validation errors.

Tokens
9.7K
Snippets
30
Records
35
Agent score
93%

What's inside go-playground/validator

  2. Initialize validator with required struct support

    master

    It is highly recommended to initialize the validator using the WithRequiredStructEnabled option. This enables behavior that will become the default in v11+ and ensures consistent validation for required fields.

    validate := validator.New(validator.WithRequiredStructEnabled())

  3. Configure validator with functional options

    master

    The validator package uses the functional options pattern for configuration during initialization. You can pass one or more Option functions to your validator constructor to modify its behavior. An Option is a function with the signature func(*Validate).

    // Example of applying options during initialization
validate := validator.New(WithRequiredStructEnabled(), WithPrivateFieldValidation())

  4. Implement custom struct-level validation

    master

    To perform validation on an entire struct (rather than individual fields), you can register a custom struct-level validation function. This is useful when validation logic depends on multiple fields within the same struct.

    There are two types of function signatures you can use:

    1. StructLevelFunc: The standard signature for struct-level validation.
    2. StructLevelFuncCtx: A signature that allows you to pass a context.Context for carrying contextual information through the validation process.

    When implementing these, you use the StructLevel interface to access the struct's data and report errors.

    // Example of a StructLevelFunc
func MyStructLevelValidation(sl validator.StructLevel) {
    // Access the struct being validated
    myStruct := sl.Current().Interface().(MyStruct)
    
    // Perform cross-field logic
    if myStruct.FieldA == myStruct.FieldB {
        // Report an error
        sl.ReportError(myStruct.FieldA, "FieldA", "FieldA", "must_not_equal_field_b", "")
    }
}

  5. Process multiple validation failures with ValidationErrors

    master

    When a validation fails, the validator returns a ValidationErrors type, which is a slice of FieldError interfaces.

    • Debugging: Calling .Error() on a ValidationErrors collection returns a concatenated string of all field errors, intended for development and debugging rather than production user messages.
    • Translation: You can call .Translate(ut ut.Translator) on a ValidationErrors collection to get a ValidationErrorsTranslations map. This map uses the field's namespace as the key and the translated error message as the value.
    // Assuming 'err' is the error returned by validate.Struct(s)
if err != nil {
    if ve, ok := err.(validator.ValidationErrors); ok {
        // Access individual errors
        for _, fe := range ve {
            fmt.Println(fe.Field(), fe.Tag())
        }

        // Or translate all errors at once
        translations := ve.Translate(translator)
        // translations is map[string]string where key is namespace
    }
}

  6. Initialize a validator instance with New()

    master

    Use New() to create a new Validate instance. The Validate instance is designed to be thread-safe and should be used as a singleton to benefit from internal caching of struct tags and validation rules. You can pass optional Option functions to New() to configure the instance during creation.

    Note: Using multiple instances instead of a singleton will bypass the performance benefits of the internal cache.

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

validate := validator.New()

  7. Handle validation error returns

    master

    Validation functions return a standard Go error. To distinguish between a system error (like invalid input to the validator itself) and actual validation failures, you should check the error type.

    Most of the time, you only need to check if the error is not nil. If you need to access specific field errors, use errors.As to cast the error to validator.ValidationErrors.

    err := validate.Struct(mystruct)
var validationErrors validator.ValidationErrors
errors.As(err, &validationErrors)

  8. Reference: Baked-in validation tags

    master

    The validator provides a wide array of built-in tags for different data types. Below are the categorized available tags.

    ### 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 | Check the indicated characters are not present in the field |
| 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) |

  9. Reference: Validation Aliases

    master

    The validator allows defining aliases to map multiple validation tags to a single custom tag for cleaner struct definitions.

    ### Aliases:
| Tag | Description |
| - | - |
| iscolor | hexcolor\|rgb\|rgba\|hsl\|hsla\|cmyk |
| country_code | iso3166_1_alpha2\|iso3166_1_alpha3\|iso3166_1_alpha_numeric |

  10. Extract details from a FieldError

    master

    The FieldError interface provides methods to inspect exactly why and where a validation failed. This is essential for building custom error responses for your API.

    MethodDescription
    Tag()Returns the validation tag that failed (or the alias name if an alias was used).
    ActualTag()Returns the underlying validation tag (e.g., if an alias iscolor failed because of hexcolor, this returns hexcolor).
    Namespace()Returns the namespace for the error, prioritizing the tag name (e.g., a JSON name like User.fname).
    StructNamespace()Returns the namespace using the actual Go struct field names (e.g., User.FirstName).
    Field()Returns the field name, prioritizing the tag name (requires RegisterTagNameFunc to be used for JSON tags).
    StructField()Returns the actual Go struct field name.
    Value()Returns the actual value that failed validation.
    Param()Returns the parameter string associated with the tag (e.g., the 10 in min=10).
    Kind()Returns the reflect.Kind of the field.
    Type()Returns the reflect.Type of the field.
    Translate(ut)Returns a translated error string using the provided translator.
    Error()Returns a default error message: Key: '%s' Error:Field validation for '%s' failed on the '%s' tag.

  11. Validate all fields except specific ones with StructExcept()

    master

    Use StructExcept() to validate every field in a struct except for the ones explicitly provided in the fields argument. Like StructPartial, fields can be specified using namespaced strings (e.g., NestedStruct.Field).

    For context-aware validation, use StructExceptCtx().

    // Validates everything EXCEPT the 'Password' field
err := validate.StructExcept(user, "Password")