I built ginvalidator — middleware-based request validation for Gin, modeled on express-validator

Here's how validation in a Gin handler usually goes. You bind JSON to a struct. You write binding:"required,email" tags. It mostly works, until you need something the tags can't express — "this email is already taken," or "this field is only required if that other field has a specific value." Then you're back to writing it by hand.

Or you skip struct binding entirely, pull values out of the request manually, write validation inline, and ten endpoints later you've got the same regex copied four different places.

If you've used express-validator in Node, you know there's a cleaner shape. Chain validators on a field, mix in sanitizers, decide what to do with the errors, move on.

ginvalidator is that, for Gin.

Repo: github.com/bube054/ginvalidator

Quick taste

package main

import (
    gv "github.com/bube054/ginvalidator"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()

    r.POST("/signup",
        gv.NewBodyChain("email", nil).
            Not().Empty(nil).
            Bail().
            Email(nil).
            Validate(),
        gv.NewBodyChain("username", nil).
            Trim("").
            Not().Empty(nil).
            Alphanumeric(nil).
            Validate(),
        func(ctx *gin.Context) {
            result, _ := gv.ValidationResult(ctx)
            if len(result) > 0 {
                ctx.AbortWithStatusJSON(422, gin.H{"errors": result})
                return
            }

            data, _ := gv.GetMatchedData(ctx)
            email, _ := data.Get(gv.BodyLocation, "email")
            username, _ := data.Get(gv.BodyLocation, "username")
            // both are validated, sanitized, ready to use

            ctx.JSON(200, gin.H{"email": email, "username": username})
        },
    )

    r.Run(":8080")
}

Each chain is its own middleware. Gin runs them left to right. Errors don't reject the request — they're collected, and you decide what to do with them in the handler.

What goes in a chain

Validators. Email, URL, UUID, Alpha, Alphanumeric, Numeric, Empty, Contains, Equals, Matches, CreditCard, MobilePhone, PostalCode, StrongPassword, JSON, Boolean, Date, ISO8601, and dozens more. All powered by my other validatorgo.

Sanitizers. Trim, Escape, Unescape, Blacklist, Whitelist, NormalizeEmail, StripLow, ToBoolean, ToInt, ToFloat, ToDate. Sanitized values flow forward through the chain and get stored for you to retrieve after validation.

Modifiers. Not() flips the next validator's result. Bail() stops the chain on first failure. Optional() skips the chain if the field is empty. If() and Skip() give you conditional control via a function.

Custom validators and sanitizers for when the built-ins don't cover what you need:

gv.NewBodyChain("email", nil).
    Email(nil).
    CustomValidator(func(r *http.Request, initialValue, sanitizedValue string) bool {
        return !userExistsByEmail(sanitizedValue)
    }).
    Validate()

Five places to look

Different chain constructor for each part of an HTTP request. Same chain semantics:

• NewBodyChain — JSON, form, multipart body. JSON paths use GJSON syntax, so "user.profile.email" works for nested fields.
• NewQueryChain — URL query parameters
• NewParamChain — Gin route parameters (:id)
• NewHeaderChain — HTTP headers
• NewCookieChain — cookies

A few things I'm really happy with

OneOf for either/or validation. Login that accepts either an email or a phone number:

gv.OneOf(
    []gv.ValidationChain{
        gv.NewBodyChain("email", nil).Not().Empty(nil).Email(nil),
    },
    []gv.ValidationChain{
        gv.NewBodyChain("phone", nil).Not().Empty(nil).MobilePhone(nil, ""),
    },
)

If at least one group passes, the request passes. The matched data from the winning group is what GetMatchedData returns.

CheckSchema for routes with a lot of fields. Twelve fields is twelve chains. That gets verbose. Schemas collapse them into a map:

gv.CheckSchema(gv.Schema{
    "email": {
        In: gv.BodyLocation,
        Build: func(vc gv.ValidationChain) gv.ValidationChain {
            return vc.Not().Empty(nil).Bail().Email(nil)
        },
    },
    "username": {
        In: gv.BodyLocation,
        Build: func(vc gv.ValidationChain) gv.ValidationChain {
            return vc.Not().Empty(nil).Bail().Alphanumeric(nil)
        },
    },
    "bio": {
        In:       gv.BodyLocation,
        Optional: true,
        Build: func(vc gv.ValidationChain) gv.ValidationChain {
            return vc.Trim("").Escape()
        },
    },
})

One middleware. Same semantics. Easier to scan than ten chained calls.

Error reading helpers for different UI shapes. ValidationResult(ctx) gives you everything as a slice, but there's also:

• HasErrors(ctx) — bool, for the "did anything fail" check
• FirstError(ctx) — pointer to the first error, for "show one at a time" UIs
• ErrorsByField(ctx) — map of field to errors, for forms with per-field error lists
• FirstErrorByField(ctx) — same map, but at most one error per field I find myself reaching for FirstErrorByField constantly when wiring up form UIs. The shape lines up with how you'd render it.

How errors look

Standard JSON, with location info:

{
  "errors": [
    {
      "location": "body",
      "field": "email",
      "value": "nope",
      "message": "invalid email",
      "code": "invalid_format"
    },
    {
      "location": "body",
      "field": "username",
      "value": "",
      "message": "Invalid value"
    }
  ]
}

The code and message come from validatorgo when a built-in validator fails, so they're stable strings you can map for i18n or client-side handling. You can override messages per-chain, or globally with DefaultErrFmtFunc.

Where this came from

This is actually the project that spawned validatorgo. I started building a Gin port of express-validator, realized I needed validator.js's whole API surface to do it properly, and ended up extracting that into its own library. That library got finished and published first; this one is the original goal it was built to serve.

So if you've seen validatorgo, you've seen the engine. ginvalidator is what I actually wanted to build all along.

If this is useful to you

A star on the repo helps more than I'd like to admit. Gin middleware is a niche-within-a-niche, and discoverability is probably the biggest blocker for libraries like this.

Forking it and trying it on a real handler is the best way to find rough edges. The five-locations-of-chain thing means there are a lot of permutations, and edge cases tend to hide in the boring ones (cookies with weird characters, multipart fields with the same name twice, that kind of thing).

If you've used express-validator and you notice behavior that doesn't match, open an issue. Spec parity is something I actively want, and "this works in express-validator but not here" is a clear bug to me.

PRs welcome — additional sanitizers, more validators that pass through to validatorgo, doc improvements, all fair game.

Links

• Repo: github.com/bube054/ginvalidator
• Docs: pkg.go.dev/github.com/bube054/ginvalidator
• The engine underneath: validatorgo
• The library this is modeled on: express-validator If you build something with it, I'd genuinely like to hear about it. Drop a comment or tag me on GitHub.

— @bube054