Skip to content

Validation

Kori integrates go-playground/validator and runs validation automatically as part of binding. There is no separate validation step.

Kori initializes a shared *validator.Validate instance with WithRequiredStructEnabled, which makes the required tag apply to structs and non-pointer fields consistently.

The validator is shared across all binding calls and is initialized once. You do not need to configure or instantiate it yourself.

Add validate tags to fields to declare constraints:

type CreateUserInput struct {
Name string `json:"name" validate:"required,min=2,max=100"`
Email string `json:"email" validate:"required,email"`
Age int `json:"age" validate:"required,gte=0,lte=130"`
Role string `json:"role" validate:"required,oneof=admin editor viewer"`
}

Any tag supported by go-playground/validator is accepted. Common tags:

Tag Meaning
required Field must be present and non-zero
omitempty Skip validation if the field is zero
min=N Minimum length (string) or value (number)
max=N Maximum length (string) or value (number)
gte=N Greater than or equal to N
lte=N Less than or equal to N
gt=N Greater than N
lt=N Less than N
email Must be a valid email address
url Must be a valid URL
uuid4 Must be a valid UUID v4
uuid Must be a valid UUID (any version)
oneof=a b c Must be one of the listed values
len=N Must have exactly N characters

The tags above produce a human-readable message in the error response. Any other validator tag still works, but its message falls back to the raw error from go-playground/validator.

Every binding function runs validation after decoding. No explicit call is required:

func createUser(w http.ResponseWriter, r *http.Request) error {
var input CreateUserInput
if err := kori.BindJSON(r, &input); err != nil {
return err // 400 on bad JSON, 422 on validation failure
}
// input is valid here
return kori.JSON(w, http.StatusCreated, input)
}

The binding functions that validate are:

Function Decodes
kori.BindJSON(r, dst) Request body (JSON)
kori.BindQuery(r, dst) URL query parameters
kori.BindPath(r, dst) Chi URL path parameters
kori.BindHeader(r, dst) HTTP headers
kori.BindForm(r, dst) Form values (application/x-www-form-urlencoded)
kori.BindMultipart(r, dst) Multipart form data
kori.Bind(r, dst) Path + query + headers combined

When validation fails, Kori returns a 422 Unprocessable Entity with a structured body:

{
"message": "validation failed",
"details": [
{
"field": "email",
"tag": "email",
"message": "email must be a valid email address"
},
{
"field": "name",
"tag": "min",
"param": "2",
"message": "name must be at least 2"
}
]
}

Each entry corresponds to a ValidationDetail:

type ValidationDetail struct {
Field string `json:"field"`
Tag string `json:"tag"`
Param string `json:"param,omitempty"`
Message string `json:"message"`
}

Kori registers a tag name function on the validator. When reporting errors, field names are resolved from the binding tag of the struct — not the Go field name:

type Query struct {
PageSize int `query:"page_size" validate:"min=1,max=100"`
}

A validation failure on PageSize reports "field": "page_size", not "field": "PageSize". The resolver checks tags in this order: json, query, path, header, form.

Binding and validation share the same struct. Tags for decoding (json, query, path, header, form) and tags for validation (validate) live on the same field:

type ListTodosParams struct {
Completed *bool `query:"completed"`
Search string `query:"search" validate:"omitempty,max=100"`
Page int `query:"page" validate:"omitempty,min=1"`
PageSize int `query:"page_size" validate:"omitempty,min=1,max=100"`
}
func listTodos(w http.ResponseWriter, r *http.Request) error {
var q ListTodosParams
if err := kori.BindQuery(r, &q); err != nil {
return err
}
// q is decoded and validated
return kori.JSON(w, http.StatusOK, results)
}

Path parameters work the same way:

type PathID struct {
ID int `path:"id" validate:"required,min=1"`
}
func getTodo(w http.ResponseWriter, r *http.Request) error {
var p PathID
if err := kori.BindPath(r, &p); err != nil {
return err
}
// p.ID is an int, decoded from the URL and validated
return kori.JSON(w, http.StatusOK, todo)
}