Skip to content
Gin Web Framework

Bind form-data request with custom struct

Gin can bind form data into nested structs automatically. When your data model is composed of smaller structs — either as embedded fields, pointer fields, or anonymous inline structs — Gin walks through the struct hierarchy and maps each form tag to the corresponding query parameter or form field.

This is useful for organizing complex forms into reusable sub-structures rather than defining one flat struct with many fields.

package main


import (
  "net/http"


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


type StructA struct {
  FieldA string `form:"field_a"`
}


type StructB struct {
  NestedStruct StructA
  FieldB       string `form:"field_b"`
}


type StructC struct {
  NestedStructPointer *StructA
  FieldC              string `form:"field_c"`
}


type StructD struct {
  NestedAnonyStruct struct {
    FieldX string `form:"field_x"`
  }
  FieldD string `form:"field_d"`
}


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


  router.GET("/getb", func(c *gin.Context) {
    var b StructB
    c.Bind(&b)
    c.JSON(http.StatusOK, gin.H{
      "a": b.NestedStruct,
      "b": b.FieldB,
    })
  })


  router.GET("/getc", func(c *gin.Context) {
    var b StructC
    c.Bind(&b)
    c.JSON(http.StatusOK, gin.H{
      "a": b.NestedStructPointer,
      "c": b.FieldC,
    })
  })


  router.GET("/getd", func(c *gin.Context) {
    var b StructD
    c.Bind(&b)
    c.JSON(http.StatusOK, gin.H{
      "x": b.NestedAnonyStruct,
      "d": b.FieldD,
    })
  })


  router.Run(":8080")
}

Test it

Terminal window
# Nested struct -- fields from StructA are bound alongside StructB's own fields
curl "http://localhost:8080/getb?field_a=hello&field_b=world"
# Output: {"a":{"FieldA":"hello"},"b":"world"}


# Nested struct pointer -- works the same way, Gin allocates the pointer automatically
curl "http://localhost:8080/getc?field_a=hello&field_c=world"
# Output: {"a":{"FieldA":"hello"},"c":"world"}


# Anonymous inline struct -- fields are bound by their form tags as usual
curl "http://localhost:8080/getd?field_x=hello&field_d=world"
# Output: {"d":"world","x":{"FieldX":"hello"}}

See also