search
HomeBackend DevelopmentGolangSimplify Gin Input Validation in Go with ginvalidator

Simplify Gin Input Validation in Go with ginvalidator

Overview

ginvalidator is a set of Gin middlewares that wraps the extensive collection of validators and sanitizers offered by my other open source package validatorgo. It also uses the popular open-source package gjson for JSON field syntax, providing efficient querying and extraction of data from JSON objects.

It allows you to combine them in many ways so that you can validate and sanitize your Gin requests, and offers tools to determine if the request is valid or not, which data was matched according to your validators.

It is based on the popular js/express library express-validator

Support

This version of ginvalidator requires that your application is running on Go 1.16 .
It's also verified to work with Gin 1.x.x.

Rationale

Why not use?

  • Handwritten Validators: You could write your own validation logic manually, but that gets repetitive and messy fast. Every time you need a new validation, you’re writing the same kind of code over and over. It’s easy to make mistakes, and it’s a pain to maintain.
  • Gin's Built-in Model Binding and Validation: Gin has validation built in, but it’s not ideal for everyone. Struct tags are limiting and make your code harder to read, especially when you need complex rules. Plus, the validation gets tied too tightly to your models, which isn't great for flexibility.
  • Other Libraries (like Galidator): There are other libraries out there, but they often feel too complex for what they do. They require more setup and work than you’d expect, especially when you just want a simple, straightforward solution for validation.

Installation

Make sure you have Go installed on your machine.

Step 1: Create a New Go Module

  1. Create an empty folder with a name of your choice.
  2. Open a terminal, navigate (cd) into that folder, and initialize a new Go module:
go mod init example.com/learning

Step 2: Install Required Packages

Use go get to install the necessary packages.

  1. Install Gin:
go get -u github.com/gin-gonic/gin
  1. Install ginvalidator:
go get -u github.com/bube054/ginvalidator

Getting Started

One of the best ways to learn something is by example! So let's roll the sleeves up and get some coding happening.

Setup

The first thing that one needs is a Gin server running. Let's implement one that says hi to someone; for this, create a main.go then add the following code:

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

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

    r.GET("/hello", func(ctx *gin.Context) {
        person := ctx.Query("person")
        ctx.String(http.StatusOK, "Hello, %s!", person)
    })

    r.Run() // listen and serve on 0.0.0.0:8080
}

Now run this file by executing go run main.go on your terminal.

go mod init example.com/learning

The HTTP server should be running, and you can open http://localhost:8080/hello?person=John to salute John!

? Tip:
You can use Air with Go and Gin to implement live reload. These automatically restart the server whenever a file is changed, so you don't have to do this yourself!

Adding a validator

So the server is working, but there are problems with it. Most notably, you don't want to say hello to someone when the person's name is not set.
For example, going to http://localhost:8080/hello will print "Hello, ".

That's where ginvalidator comes in handy. It provides validators, sanitizers and modifiers that are used to validate your request.
Let's add a validator and a modifier that checks that the person query string cannot be empty, with the validator named Empty and modifier named Not:

go get -u github.com/gin-gonic/gin

? Note:

For brevity, gv is used as an alias for ginvalidator in the code examples.

Now, restart your server, and go to http://localhost:8080/hello again. Hmm, it still prints "Hello, !"... why?

Handling validation errors

ginvalidator validation chain does not report validation errors to users automatically.
The reason for this is simple: as you add more validators, or for more fields, how do you want to collect the errors? Do you want a list of all errors, only one per field, only one overall...?

So the next obvious step is to change the above code again, this time verifying the validation result with the ValidationResult function:

go get -u github.com/bube054/ginvalidator

Now, if you access http://localhost:8080/hello again, you’ll see the following JSON content, formatted for clarity:

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

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

    r.GET("/hello", func(ctx *gin.Context) {
        person := ctx.Query("person")
        ctx.String(http.StatusOK, "Hello, %s!", person)
    })

    r.Run() // listen and serve on 0.0.0.0:8080
}

Now, what this is telling us is that

  • there's been exactly one error in this request;
  • this field is called person;
  • it's located in the query string (location: "queries");
  • the error message that was given was "Invalid value".

This is a better scenario, but it can still be improved. Let's continue.

Creating better error messages

All request location validators accept an optional second argument, which is a function used to format the error message. If nil is provided, a default, generic error message will be used, as shown in the example above.

go run main.go

Now if you access http://localhost:8080/hello again, what you'll see is the following JSON content, with the new error message:

package main

import (
    "net/http"

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

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

    r.GET("/hello", gv.NewQuery("person", nil).
        Chain().
        Not().
        Empty(nil).
        Validate(), func(ctx *gin.Context) {
            person := ctx.Query("person")
            ctx.String(http.StatusOK, "Hello, %s!", person)
        })

    r.Run()
}

Accessing validated/sanitized data

You can use GetMatchedData, which automatically collects all data that ginvalidator has validated and/or sanitized. This data can then be accessed using the Get method of MatchedData:

go mod init example.com/learning

open http://localhost:8080/hello?person=John to salute John!

The available locations are BodyLocation, CookieLocation QueryLocation, ParamLocation and HeaderLocation.
Each of these locations includes a String method that returns the location where validated/sanitized data is being stored.

Sanitizing inputs

While the user can no longer send empty person names, it can still inject HTML into your page! This is known as the Cross-Site Scripting vulnerability (XSS).
Let's see how it works. Go to http://localhost:8080/hello?person=John, and you should see "Hello, John!".
While this example is fine, an attacker could change the person query string to a <script> tag which loads its own JavaScript that could be harmful.<br> In this scenario, one way to mitigate the issue with ginvalidator is to use a sanitizer, most specifically Escape, which transforms special HTML characters with others that can be represented as text.<br> </script>

go get -u github.com/gin-gonic/gin

Now, if you restart the server and refresh the page, what you'll see is "Hello, John!". Our example page is no longer vulnerable to XSS!

⚠️ Caution:

ginvalidator does not modify http.Request values during sanitization. To access sanitized data, always use the GetMatchedData function.

The Validation Chain

The validation chain is one of the main concepts in ginvalidator, therefore it's useful to learn about it, so that you can use it effectively.

But don't worry: if you've read through the Getting Started guide, you have already used validation chains without even noticing!

What are validation chains?

Validation chains are created using the following functions, each targeting a specific location in the HTTP request:

  • NewBody: Validates data from the http.Request body. Its location is BodyLocation.
  • NewCookie: Validates data from the http.Request cookies. Its location is CookieLocation.
  • NewHeader: Validates data from the http.Request headers. Its location is HeaderLocation.
  • NewParam: Validates data from the Gin route parameters. Its location is ParamLocation.
  • NewQuery: Validates data from the http.Request query parameters. Its location is QueryLocation.

They have this name because they wrap the value of a field with validations (or sanitizations), and each of its methods returns itself.
This pattern is usually called method chaining, hence why the name validation chain.

Validation chains not only have a number of useful methods for defining validations, sanitizations and modifications but they also have methods Validate which returns the Gin middleware handler function.

This is an example of how validation chains are usually used, and how you can read one:

go mod init example.com/learning

Features

A validation chain has three kinds of methods: validators, sanitizers and modifiers.

Validators determine if the value of a request field is valid. This means checking if the field is in the format that you expect it to be. For example, if you're building a sign up form, your requirements could be that the username must be an e-mail address, and that passwords must be at least 8 characters long.

If the value is invalid, an error is recorded for that field using some error message. This validation error can then be retrieved at a later point in the Gin route handler and returned to the user.

They are:

  • CustomValidator
  • Contains
  • Equals
  • AbaRouting
  • After
  • Alpha
  • Alphanumeric
  • Ascii
  • Base32
  • Base58
  • Base64
  • Before
  • Bic
  • Boolean
  • BTCAddress
  • ByteLength
  • CreditCard
  • Currency
  • DataURI
  • Date
  • Decimal
  • DivisibleBy
  • EAN
  • Email
  • Empty
  • EthereumAddress
  • Float
  • FQDN
  • FreightContainerID
  • FullWidth
  • HalfWidth
  • Hash
  • Hexadecimal
  • HexColor
  • HSL
  • IBAN
  • IdentityCard
  • IMEI
  • In
  • Int
  • IP
  • IPRange
  • ISIN
  • ISO4217
  • ISO6346
  • ISO6391
  • ISO8601
  • ISO31661Alpha2
  • ISO31661Alpha3
  • ISO31661Numeric
  • ISRC
  • ISSN
  • JSON
  • LatLong
  • LicensePlate
  • Locale
  • LowerCase
  • LuhnNumber
  • MacAddress
  • MagnetURI
  • MailtoURI
  • MD5
  • MimeType
  • MobilePhone
  • MongoID
  • Multibyte
  • Numeric
  • Octal
  • PassportNumber
  • Port
  • PostalCode
  • RFC3339
  • RgbColor
  • SemVer
  • Slug
  • StrongPassword
  • TaxID
  • SurrogatePair
  • Time
  • ULID
  • UpperCase
  • URL
  • UUID
  • VariableWidth
  • VAT
  • Whitelisted
  • Matches

Sanitizers transform the field value. They are useful to remove noise from the value and perhaps even to provide some basic line of defense against threats.

Sanitizers persist the updated fields value back into the Gin Contexts, so that it's usable by other ginvalidator functions, your own route handler code, and even other middlewares.

They are:

  • CustomSanitizer
  • Blacklist
  • Escape
  • LTrim
  • NormalizeEmail
  • RTrim
  • StripLow
  • ToBoolean
  • ToDate
  • ToFloat
  • ToInt
  • Trim
  • Unescape
  • Whitelist

Modifiers define how validation chains behave when they are run.

They are:

  • Bail
  • If
  • Not
  • Skip
  • Optional

? Note:

These methods are thoroughly documented using GoDoc within the pkg.go.dev ginvalidator documentation. If any details are unclear, you may also want to refer to related functions within the validatorgo package for additional context, which I’ll be explaining below.

Standard validators/sanitizers

All of the functionality exposed by the validation chain actually comes from validatorgo, one of my other open source go packages which specializes in string validation/sanitation. Please check it out, star and share ???, Thank You.

This includes all of validatorgo validators and sanitizers, from commonly used IsEmail, IsLength, and Trim to the more niche IsISBN, IsMultibyte and StripLow!

These are called standard validators and standard sanitizers in ginvalidator. But without the Is prefix from validatorgo.

Chaining order

The order in which you call methods on a validation chain usually matters.
They are almost always run in the order that they are specified, therefore you can tell what a validation chain will do just by reading its definition, from first chained method to last.

Take the following snippet as an example:

go mod init example.com/learning

In this case, if the user passes a "search_query" value that is composed of whitespaces only, it won't be empty, therefore the validation passes. But since the .Trim() sanitizer is there, the whitespace's will be removed, and the field will become empty, so you actually end up with a false positive.

Now, compare it with the below snippet:

go get -u github.com/gin-gonic/gin

This chain will more sensibly remove whitespace's, and then validate if the value is not empty.

One exception to this rule is .Optional(): It can be placed at any point in the chain and it will mark the chain as optional.

Reusing validation chains

If you wish to reuse the same chain, it's a good idea to return them from functions:

go get -u github.com/bube054/ginvalidator

Field Selection

In ginvalidator, a field is any value that is either validated or sanitized and it is string.

Pretty much every function or value returned by ginvalidator reference fields in some way. For this reason, it's important to understand the field path syntax both for when selecting fields for validation, and when accessing the validation errors or validated data.

Syntax

  • Body fields are only valid for the following Content-Types:

    • application/json: This uses GJSON path syntax for extracting values. Please refer to the linked documentation for details.
    • Example:
    go mod init example.com/learning
    

    With path user.name, the extracted value would be "John".

    • application/x-www-form-urlencoded: Typically used for HTML form submissions. Fields are submitted as key-value pairs in the body.
    • Example:
    go get -u github.com/gin-gonic/gin
    

    Body:

    go get -u github.com/bube054/ginvalidator
    

    Field "name" would have the value "John", and "email" would have the value "john.doe@example.com".

    • multipart/form-data: Commonly used for file uploads or when submitting form data with files.
    • Example:
    package main
    
    import (
        "net/http"
    
        "github.com/gin-gonic/gin"
    )
    
    func main() {
        r := gin.Default()
    
        r.GET("/hello", func(ctx *gin.Context) {
            person := ctx.Query("person")
            ctx.String(http.StatusOK, "Hello, %s!", person)
        })
    
        r.Run() // listen and serve on 0.0.0.0:8080
    }
    

    Body:

    go run main.go
    

    Field "name" would have the value "John", and "file" would be the uploaded file.

  • Query fields correspond to URL search parameters, and their values are automatically url unescaped by Gin.

    Examples:

    • Field: "name", Value: "John"
    package main
    
    import (
        "net/http"
    
        gv "github.com/bube054/ginvalidator"
        "github.com/gin-gonic/gin"
    )
    
    func main() {
        r := gin.Default()
    
        r.GET("/hello", gv.NewQuery("person", nil).
            Chain().
            Not().
            Empty(nil).
            Validate(), func(ctx *gin.Context) {
                person := ctx.Query("person")
                ctx.String(http.StatusOK, "Hello, %s!", person)
            })
    
        r.Run()
    }
    
    • Field: "full_name", Value: "John Doe"
    package main
    
    import (
        "net/http"
    
        gv "github.com/bube054/ginvalidator"
        "github.com/gin-gonic/gin"
    )
    
    func main() {
        r := gin.Default()
    
        r.GET("/hello",
            gv.NewQuery("person", nil).
                Chain().
                Not().
                Empty(nil).
                Validate(),
            func(ctx *gin.Context) {
                result, err := gv.ValidationResult(ctx)
                if err != nil {
                    ctx.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{
                        "message": "The server encountered an unexpected error.",
                    })
                    return
                }
    
                if len(result) != 0 {
                    ctx.AbortWithStatusJSON(http.StatusUnprocessableEntity, gin.H{
                        "errors": result,
                    })
                    return
                }
    
                person := ctx.Query("person")
                ctx.String(http.StatusOK, "Hello, %s!", person)
            })
    
        r.Run()
    }
    
  • Param fields represent URL path parameters, and their values are automatically unescaped by ginvalidator.

    Example:

    • Field: "id", Value: "123"
    {
      "errors": [
        {
          "location": "queries",
          "message": "Invalid value",
          "field": "person",
          "value": ""
        }
      ]
    }
    
  • Header fields are HTTP request headers, and their values are not unescaped. A log warning will appear if you provide a non-canonical header key.

    Example:

    • Field: "User-Agent", Value: "Mozilla/5.0"
    package main
    
    import (
        "net/http"
    
        gv "github.com/bube054/ginvalidator"
        "github.com/gin-gonic/gin"
    )
    
    func main() {
        r := gin.Default()
    
        r.GET("/hello",
            gv.NewQuery("person",
                func(initialValue, sanitizedValue, validatorName string) string {
                    return "Please enter your name."
                },
            ).Chain().
                Not().
                Empty(nil).
                Validate(),
            func(ctx *gin.Context) {
                result, err := gv.ValidationResult(ctx)
                if err != nil {
                    ctx.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{
                        "message": "The server encountered an unexpected error.",
                    })
                    return
                }
    
                if len(result) != 0 {
                    ctx.AbortWithStatusJSON(http.StatusUnprocessableEntity, gin.H{
                        "errors": result,
                    })
                    return
                }
    
                person := ctx.Query("person")
                ctx.String(http.StatusOK, "Hello, %s!", person)
            })
    
        r.Run()
    }
    
  • Cookies fields are HTTP cookies, and their values are automatically url unescaped by Gin.

    Example:

    • Field: "session_id", Value: "abc 123"
    {
      "errors": [
        {
          "location": "queries",
          "message": "Please enter your name.",
          "field": "person",
          "value": ""
        }
      ]
    }
    

Customizing express-validator

If the server you're building is anything but a very simple one, you'll need validators, sanitizers and error messages beyond the ones built into ginvalidator sooner or later.

Custom Validators and Sanitizers

A classic need that ginvalidator can't fulfill for you, and that you might run into, is validating whether an e-mail address is in use or not when a user signing up.

It's possible to do this in ginvalidator by implementing a custom validator.

A CustomValidator is a method available on the validation chain, that receives a special function CustomValidatorFunc, and have to returns a boolean that will determine if the field is valid or not.

A CustomSanitizer is also a method available on the validation chain, that receives a special function CustomSanitizerFunc, and have to returns the new sanitized value.

Implementing a custom validator

A CustomValidator can be asynchronous by using goroutines and a sync.WaitGroup to handle concurrent operations. Within the validator, you can spin up goroutines for each asynchronous task, adding each task to the WaitGroup. Once all tasks complete, the validator should return a boolean.

For example, in order to check that an e-mail is not in use:

go mod init example.com/learning

Or maybe you could also verify that the password matches the repeat:

go get -u github.com/gin-gonic/gin

⚠️ Caution:
If the request body will be accessed multiple times—whether in the same validation chain, in another validation chain for the same request context, or in subsequent handlers—ensure you reset the request body after each read. Failing to do so can lead to errors or missing data when the body is read again.

Implementing a custom sanitizer

CustomSanitizer don't have many rules. Whatever the value that they return, is the new value that the field will acquire.
Custom sanitizers can also be asynchronous by using goroutines and a sync.WaitGroup to handle concurrent operations.

go get -u github.com/bube054/ginvalidator

Error Messages

Whenever a field value is invalid, an error message is recorded for it.
The default error message is "Invalid value", which is not descriptive at all of what the error is, so you might need to customize it. You can customize by

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

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

    r.GET("/hello", func(ctx *gin.Context) {
        person := ctx.Query("person")
        ctx.String(http.StatusOK, "Hello, %s!", person)
    })

    r.Run() // listen and serve on 0.0.0.0:8080
}
  • initialValue is the original value extracted from the request (before any sanitization).
  • sanitizedValue is the value after it has been sanitized (if applicable).
  • validatorName is the name of the validator that failed, which helps identify the validation rule that did not pass.

For a complete list of validator names, refer to the ginvalidator constants.

Maintainers

  • bube054 - Attah Gbubemi David (author)

The above is the detailed content of Simplify Gin Input Validation in Go with ginvalidator. For more information, please follow other related articles on the PHP Chinese website!

Statement
The content of this article is voluntarily contributed by netizens, and the copyright belongs to the original author. This site does not assume corresponding legal responsibility. If you find any content suspected of plagiarism or infringement, please contact admin@php.cn
Golang vs. Python: The Pros and ConsGolang vs. Python: The Pros and ConsApr 21, 2025 am 12:17 AM

Golangisidealforbuildingscalablesystemsduetoitsefficiencyandconcurrency,whilePythonexcelsinquickscriptinganddataanalysisduetoitssimplicityandvastecosystem.Golang'sdesignencouragesclean,readablecodeanditsgoroutinesenableefficientconcurrentoperations,t

Golang and C  : Concurrency vs. Raw SpeedGolang and C : Concurrency vs. Raw SpeedApr 21, 2025 am 12:16 AM

Golang is better than C in concurrency, while C is better than Golang in raw speed. 1) Golang achieves efficient concurrency through goroutine and channel, which is suitable for handling a large number of concurrent tasks. 2)C Through compiler optimization and standard library, it provides high performance close to hardware, suitable for applications that require extreme optimization.

Why Use Golang? Benefits and Advantages ExplainedWhy Use Golang? Benefits and Advantages ExplainedApr 21, 2025 am 12:15 AM

Reasons for choosing Golang include: 1) high concurrency performance, 2) static type system, 3) garbage collection mechanism, 4) rich standard libraries and ecosystems, which make it an ideal choice for developing efficient and reliable software.

Golang vs. C  : Performance and Speed ComparisonGolang vs. C : Performance and Speed ComparisonApr 21, 2025 am 12:13 AM

Golang is suitable for rapid development and concurrent scenarios, and C is suitable for scenarios where extreme performance and low-level control are required. 1) Golang improves performance through garbage collection and concurrency mechanisms, and is suitable for high-concurrency Web service development. 2) C achieves the ultimate performance through manual memory management and compiler optimization, and is suitable for embedded system development.

Is Golang Faster Than C  ? Exploring the LimitsIs Golang Faster Than C ? Exploring the LimitsApr 20, 2025 am 12:19 AM

Golang performs better in compilation time and concurrent processing, while C has more advantages in running speed and memory management. 1.Golang has fast compilation speed and is suitable for rapid development. 2.C runs fast and is suitable for performance-critical applications. 3. Golang is simple and efficient in concurrent processing, suitable for concurrent programming. 4.C Manual memory management provides higher performance, but increases development complexity.

Golang: From Web Services to System ProgrammingGolang: From Web Services to System ProgrammingApr 20, 2025 am 12:18 AM

Golang's application in web services and system programming is mainly reflected in its simplicity, efficiency and concurrency. 1) In web services, Golang supports the creation of high-performance web applications and APIs through powerful HTTP libraries and concurrent processing capabilities. 2) In system programming, Golang uses features close to hardware and compatibility with C language to be suitable for operating system development and embedded systems.

Golang vs. C  : Benchmarks and Real-World PerformanceGolang vs. C : Benchmarks and Real-World PerformanceApr 20, 2025 am 12:18 AM

Golang and C have their own advantages and disadvantages in performance comparison: 1. Golang is suitable for high concurrency and rapid development, but garbage collection may affect performance; 2.C provides higher performance and hardware control, but has high development complexity. When making a choice, you need to consider project requirements and team skills in a comprehensive way.

Golang vs. Python: A Comparative AnalysisGolang vs. Python: A Comparative AnalysisApr 20, 2025 am 12:17 AM

Golang is suitable for high-performance and concurrent programming scenarios, while Python is suitable for rapid development and data processing. 1.Golang emphasizes simplicity and efficiency, and is suitable for back-end services and microservices. 2. Python is known for its concise syntax and rich libraries, suitable for data science and machine learning.

See all articles

Hot AI Tools

Undresser.AI Undress

Undresser.AI Undress

AI-powered app for creating realistic nude photos

AI Clothes Remover

AI Clothes Remover

Online AI tool for removing clothes from photos.

Undress AI Tool

Undress AI Tool

Undress images for free

Clothoff.io

Clothoff.io

AI clothes remover

Video Face Swap

Video Face Swap

Swap faces in any video effortlessly with our completely free AI face swap tool!

Hot Tools

Dreamweaver CS6

Dreamweaver CS6

Visual web development tools

SAP NetWeaver Server Adapter for Eclipse

SAP NetWeaver Server Adapter for Eclipse

Integrate Eclipse with SAP NetWeaver application server.

MantisBT

MantisBT

Mantis is an easy-to-deploy web-based defect tracking tool designed to aid in product defect tracking. It requires PHP, MySQL and a web server. Check out our demo and hosting services.

Zend Studio 13.0.1

Zend Studio 13.0.1

Powerful PHP integrated development environment

PhpStorm Mac version

PhpStorm Mac version

The latest (2018.2.1) professional PHP integrated development tool