criterio

criterio

A composable validation library for Go. Validators are functions that can be combined, reused, and composed to build complex validation logic.

go get github.com/hay-kot/criterio

Requires Go 1.23+

Core Concepts

All validators implement a single type:

type Validator[T any] func(val T) error

Validators return nil on success or an error describing the failure.

API Overview

Running Validators

// Stop on first failure
err := criterio.Run("email", user.Email,
    criterio.Required[string],
    criterio.StrEmail,
)

// Collect all failures
err := criterio.RunAll("email", user.Email,
    criterio.Required[string],
    criterio.StrMin(5),
    criterio.StrEmail,
)

Reusable Validators

validateEmail := criterio.New("email",
    criterio.Required[string],
    criterio.StrEmail,
)

if err := validateEmail(input); err != nil {
    // handle error
}

Struct Validation

func (u User) Validate() error {
    return criterio.ValidateStruct(
        criterio.Run("name", u.Name,
            criterio.Required[string],
            criterio.StrBetween(2, 100),
        ),
        criterio.Run("email", u.Email,
            criterio.Required[string],
            criterio.StrEmail,
        ),
        criterio.Run("age", u.Age,
            criterio.Min(0),
            criterio.Max(150),
        ),
        criterio.Nest("address", u.Address.Validate()),
    )
}

Conditional Validation

// Only validate if condition is true
criterio.When(u.IsPremium, criterio.Required[string])

// Skip validation if condition is true
criterio.SkipIf(u.IsGuest, criterio.StrEmail)

Slice Validation

func (u User) Validate() error {
    return criterio.ValidateStruct(
        criterio.Run("name", u.Name, criterio.Required[string]),
        criterio.ValidateSlice("addresses", u.Addresses, Address.Validate),
    )
}
// Error: "addresses[0].street: is required"

For simple slices:

criterio.ValidateSlice("emails", emails, criterio.StrEmail)
// Error: "emails[1]: must be a valid email address"

Combinators

// Pass if any validator passes
criterio.Or(criterio.StrEmail, criterio.StrNumeric)

// Invert a validator
criterio.Not(criterio.StrNumeric, "cannot be all numbers")

Available Validators

General

Numeric (ordered types)

Strings

Slices

Maps

Network

Time

Duration

Error Handling

Errors are returned as FieldErrors, a slice of FieldError:

type FieldError struct {
    Field string
    Err   error
}

Error Output

Single field error:

email: must be a valid email address

Multiple errors (from RunAll or ValidateStruct):

validation failed: name: must be between 2 and 100 characters; email: must be a valid email address

Nested struct errors use dot notation:

address.street: is required
address.zip: must contain only digits

Slice errors use bracket notation:

addresses[0].street: is required
emails[1]: must be a valid email address

Accessing Individual Errors

if err := user.Validate(); err != nil {
    if fieldErrs, ok := err.(criterio.FieldErrors); ok {
        for _, fe := range fieldErrs {
            fmt.Printf("%s: %s\n", fe.Field, fe.Err.Error())
        }
    }
}

Customization

String validators use exported regex patterns that can be modified globally:

var (
    EmailRegex        *regexp.Regexp
    UUIDRegex         *regexp.Regexp
    AlphaRegex        *regexp.Regexp
    AlphanumericRegex *regexp.Regexp
    NumericRegex      *regexp.Regexp
    WhitespaceRegex   *regexp.Regexp
)

Override in an init function to change validation behavior:

func init() {
    criterio.EmailRegex = regexp.MustCompile(`your-pattern`)
}

Benchmarks

Comparison against manual validation and go-playground/validator.

Run task bench:readme to regenerate.

Key takeaways:

• Zero allocations on valid inputs - the happy path is allocation-free
• ~2x faster than go-playground/validator for struct validation
• Comparable to manual validation for simple cases, with structured error handling
• Error paths are competitive with go-playground/validator for typical structs (User: 1077ns/453B vs 1135ns/665B)
• Complex nested validation has more allocations due to FieldErrors merging, but provides richer error context with field paths

License

MIT