validation

Okapi Validation

Validation is declarative: struct tags drive both runtime enforcement and OpenAPI schema generation. Validation runs automatically inside c.Bind and inside the typed handler wrappers (okapi.Handle, okapi.H, okapi.HandleIO, okapi.HandleO).

For where values come from (JSON body, query, path, header, cookie, form), see the request_binding/ skill.

Constraint Tags

Slices: enum, const, format, pattern, contains, and notContains apply to each element of a []string. Failures are reported per index — element [2]: ....

Empty values: those same tags skip empty strings. Combine with required:"true" to also enforce presence.

Conditional Required Tags

Requiredness that depends on sibling fields in the same struct. Referenced fields use their Go field name, not the JSON name.

type Payment struct {
    Type    string `json:"type"`
    Card    string `json:"card"    requiredIf:"Type card"`
    Pass    string `json:"pass"`
    Confirm string `json:"confirm" requiredWith:"Pass"`
    Email   string `json:"email"`
    Phone   string `json:"phone"   requiredWithout:"Email"`
}

Documentation-Only Tags

These shape the OpenAPI schema; they are not enforced at runtime.

Formats

All formats apply to string fields and to each element of a []string.

Date & time

Network, web & identifiers

String content

Geo & time zones

Custom pattern

Phone string `json:"phone" format:"regex" pattern:"^\\+?[1-9]\\d{1,14}$"`

Example

type CreateUserRequest struct {
    Email    string            `json:"email" required:"true" format:"email" example:"user@example.com"`
    Password string            `json:"password" minLength:"8" writeOnly:"true" description:"User password"`
    Age      int               `json:"age" exclusiveMin:"0" max:"120" default:"18"`
    Website  string            `json:"website" format:"url"`
    Kind     string            `json:"kind" const:"user"`
    Roles    []string          `json:"roles" minItems:"1" uniqueItems:"true" enum:"admin,editor,viewer"`
    Metadata map[string]string `json:"metadata" minProperties:"1" maxProperties:"10"`
    ID       string            `json:"id" format:"uuid" readOnly:"true"`
    Internal string            `json:"-" hidden:"true"`
}

Five Ways to Validate

1. c.Bind() — bind and validate inside the handler

o.Post("/users", func(c *okapi.Context) error {
    var req CreateUserRequest
    if err := c.Bind(&req); err != nil {
        return c.ErrorBadRequest(err)
    }
    return c.JSON(http.StatusOK, req)
})

2. okapi.Handle() — typed input, manual response

o.Post("/books", okapi.Handle(func(c *okapi.Context, book *Book) error {
    book.ID = nextID()
    return c.Created(book)
}),
    okapi.DocRequestBody(&Book{}),
    okapi.DocResponse(&Book{}),
)

3. okapi.H() — shorthand for Handle

o.Get("/books/{id:int}", okapi.H(func(c *okapi.Context, in *BookDetailInput) error {
    b := find(in.ID)
    if b == nil {
        return c.AbortNotFound("Book not found")
    }
    return c.OK(b)
})).WithInput(&BookDetailInput{})

4. okapi.HandleIO() — typed input and typed output

type BookEditInput struct {
    ID   int  `json:"id" path:"id" required:"true"`
    Body Book `json:"body"`
}
type BookOutput struct {
    Status int
    Body   Book
}

o.Put("/books/{id:int}", okapi.HandleIO(func(c *okapi.Context, in *BookEditInput) (*BookOutput, error) {
    b := update(in.ID, in.Body)
    if b == nil {
        return nil, c.AbortNotFound("Book not found")
    }
    return &BookOutput{Body: *b}, nil
})).WithIO(&BookEditInput{}, &BookOutput{})

5. okapi.HandleO() — typed output only

type BooksResponse struct {
    Body []Book `json:"books"`
}

o.Get("/books", okapi.HandleO(func(c *okapi.Context) (*BooksResponse, error) {
    return &BooksResponse{Body: books}, nil
})).WithOutput(&BooksResponse{})

The output struct follows the body-style convention (Status, Body, header/cookie-tagged fields). The response format comes from the client's Accept header, defaulting to JSON.

Schema Helpers

Returning Validation Errors

return c.AbortValidationErrors([]okapi.ValidationError{
    {Field: "email", Message: "must be a valid email", Value: req.Email},
    {Field: "age",   Message: "must be >= 18"},
}, "validation failed")

AbortValidationErrors always uses the ValidationErrorResponse shape (an ErrorResponse plus an errors array), regardless of the configured error handler. Use AbortValidationErrorsWithProblemDetail for the RFC 7807 form.