Overview ¶

Package validate is yet another Go struct/object validation package, with a focus on simplicity, flexibility, and full control over validation logic.

Interface ¶

To add validation to any type, simply implement the Validatable interface:

type Validatable interface {
    Validate() error
}

To mark a object as failing validation, the Validate method simply needs to return a error.

When validating array, slice, map, and struct types each item and/or field that implements Validatable will be validated, meaning deeply nested structs can be fully validated, and the nested path to each object is tracked and reported back any validation errors.

Multiple Errors ¶

Multiple errors can be reported from the Validate method using one of the available Append helper functions which append errors together. Under the hood the go.uber.org/multierr package is used to represent multiple errors as a single error return type, and you can in fact just directly use multierr in the a type's Validate method.

Structs and Field-specific Errors ¶

When validating a struct, you are likely to have multiple errors for multiple fields. To specify which field on the struct the error relates to, you have to return a *validate.Error instead of a normal Go error type. For example:

type Book struct {
    Title  string
    Author string
}

func (s *Book) Validate() error {
    var errs error

    if s.Title == "" {
        errs = validate.Append(errs, &validate.Error{
            Field: "Title", Msg: "is required",
        })
    }

    if s.Author == "" {
        // Yields the same result as the Title field check above.
        errs = validate.AppendFieldError(errs, "Author", "is required")
    }

    return errs
}

With the above example, if you validate a empty *Book:

err := validate.Validate(&Book{})
for _, e := range validate.Errors(err) {
    fmt.Println(e.Error())
}

The following errors would be printed:

Title: is required
Kind: is required

Error type ¶

All errors will be wrapped in a *Error before being returned, which is used to keep track of the path and field the error relates to. There are various helpers available to create Error instances.

Handling Validation Errors ¶

As mentioned above, multiple errors are wrapped up into a single error return value using go.uber.org/multierr. You can access all errors individually with Errors(), which accepts a single error, and returns []error. The Errors() function is just wrapper around multierr.Errors(), so you could use that instead if you prefer.

Struct Field Tags ¶

Fields on a struct which customize the name via a json, yaml, or form field tag, will automatically have the field name converted to the name in the tag in returned *Error types with a non-empty Field value.

You can customize the field name conversion logic by creating a custom Validator instance, and calling FieldNameFunc() on it.

Nested Validatable Objects ¶

All items/fields on any structs, maps, slices or arrays which are encountered will be validated if they implement the Validatable interface. While traversing nested data structures, a path list tracks the location of the current object being validation in relation to the top-level object being validated. This path is used within the field in the final output errors.

By default path components are joined with a dot, but this can be customized when using a custom Validator instance and calling FieldJoinFunc() passing in a custom function to handle path joining.

As an example, if our Book struct from above is nested within the following structs:

type Order struct {
    Items []*Item `json:"items"`
}

type Item struct {
    Book *Book `json:"book"`
}

And we have a Order where the book in the second Item has a empty Author field:

err := validate.Validate(&Order{
    Items: []*Item{
        {Book: &Book{Title: "The Traveler", Author: "John Twelve Hawks"}},
        {Book: &Book{Title: "The Firm"}},
    },
})
for _, e := range validate.Errors(err) {
    fmt.Println(e.Error())
}

Then we would get the following error:

items.1.book.Author: is required

Note how both "items" and "book" are lower cased thanks to the json tags on the struct fields, while our Book struct does not have a json tag for the Author field.

Also note that the error message does not start with "Order". The field path is relative to the object being validated, hence the top-level object is not part of the returned field path.