Model binding and validation

To bind a request body into a type, use model binding. We currently support binding of JSON, XML, YAML and standard form values (foo=bar&boo=baz).

Gin uses go-playground/validator/v10 for validation. Check the full docs on tags usage here.

Note that you need to set the corresponding binding tag on all fields you want to bind. For example, when binding from JSON, set json:"fieldname".

Also, Gin provides two sets of methods for binding:

  • Type - Must bind
    • Methods - Bind, BindJSON, BindXML, BindQuery, BindYAML
    • Behavior - These methods use MustBindWith under the hood. If there is a binding error, the request is aborted with c.AbortWithError(400, err).SetType(ErrorTypeBind). This sets the response status code to 400 and the Content-Type header is set to text/plain; charset=utf-8. Note that if you try to set the response code after this, it will result in a warning [GIN-debug] [WARNING] Headers were already written. Wanted to override status code 400 with 422. If you wish to have greater control over the behavior, consider using the ShouldBind equivalent method.
  • Type - Should bind
    • Methods - ShouldBind, ShouldBindJSON, ShouldBindXML, ShouldBindQuery, ShouldBindYAML
    • Behavior - These methods use ShouldBindWith under the hood. If there is a binding error, the error is returned and it is the developer’s responsibility to handle the request and error appropriately.

When using the Bind-method, Gin tries to infer the binder depending on the Content-Type header. If you are sure what you are binding, you can use MustBindWith or ShouldBindWith.

You can also specify that specific fields are required. If a field is decorated with binding:"required" and has a empty value when binding, an error will be returned.

  1. // Binding from JSON
  2. type Login struct {
  3.     User     string `form:"user" json:"user" xml:"user"  binding:"required"`
  4.     Password string `form:"password" json:"password" xml:"password" binding:"required"`
  5. }
  7. func main() {
  8.     router := gin.Default()
  10.     // Example for binding JSON ({"user": "manu", "password": "123"})
  11.     router.POST("/loginJSON", func(c *gin.Context) {
  12.         var json Login
  13.         if err := c.ShouldBindJSON(&json); err != nil {
  14.             c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
  15.             return
  16.         }
  18.         if json.User != "manu" || json.Password != "123" {
  19.             c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
  20.             return
  21.         } 
  23.         c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
  24.     })
  26.     // Example for binding XML (
  27.     //    <?xml version="1.0" encoding="UTF-8"?>
  28.     //    <root>
  29.     //        <user>manu</user>
  30.     //        <password>123</password>
  31.     //    </root>)
  32.     router.POST("/loginXML", func(c *gin.Context) {
  33.         var xml Login
  34.         if err := c.ShouldBindXML(&xml); err != nil {
  35.             c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
  36.             return
  37.         }
  39.         if xml.User != "manu" || xml.Password != "123" {
  40.             c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
  41.             return
  42.         } 
  44.         c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
  45.     })
  47.     // Example for binding a HTML form (user=manu&password=123)
  48.     router.POST("/loginForm", func(c *gin.Context) {
  49.         var form Login
  50.         // This will infer what binder to use depending on the content-type header.
  51.         if err := c.ShouldBind(&form); err != nil {
  52.             c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
  53.             return
  54.         }
  56.         if form.User != "manu" || form.Password != "123" {
  57.             c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
  58.             return
  59.         } 
  61.         c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
  62.     })
  64.     // Listen and serve on 0.0.0.0:8080
  65.     router.Run(":8080")
  66. }

Sample request

  1. $ curl -v -X POST \
  2.   http://localhost:8080/loginJSON \
  3.   -H 'content-type: application/json' \
  4.   -d '{ "user": "manu" }'
  5. > POST /loginJSON HTTP/1.1
  6. > Host: localhost:8080
  7. > User-Agent: curl/7.51.0
  8. > Accept: */*
  9. > content-type: application/json
  10. > Content-Length: 18
  11. >
  12. * upload completely sent off: 18 out of 18 bytes
  13. < HTTP/1.1 400 Bad Request
  14. < Content-Type: application/json; charset=utf-8
  15. < Date: Fri, 04 Aug 2017 03:51:31 GMT
  16. < Content-Length: 100
  17. <
  18. {"error":"Key: 'Login.Password' Error:Field validation for 'Password' failed on the 'required' tag"}

Skip validate

When running the above example using the above the curl command, it returns error. Because the example use binding:"required" for Password. If use binding:"-" for Password, then it will not return error when running the above example again.

Last modified May 19, 2021 : chore: update example (81f837f)