Struct Tags for JSON, DB & Validation

Production structs often carry three tag namespaces on one field: json for APIs, db or ORM-specific keys for storage, and validate for input rules.

Consistent naming across tags keeps serializers, SQL scanners, and validators aligned without duplicate DTO layers.

Summary

Struct tags are string metadata attached to fields, read via reflection at runtime.

Each library parses its own key (json, db, validate, xml, yaml, etc.).

A single struct can serve HTTP and database layers when tags agree on field meaning but differ on wire/column names.

Recipe

Quick-reference recipe card - copy-paste ready.

type User struct {
    ID        int64     `json:"id" db:"id" validate:"required"`
    Email     string    `json:"email" db:"email" validate:"required,email"`
    Nickname  *string   `json:"nickname,omitempty" db:"nickname" validate:"omitempty,min=2,max=32"`
    CreatedAt time.Time `json:"created_at" db:"created_at" validate:"-"`
    Internal  string    `json:"-" db:"internal_note" validate:"-"`
}

When to reach for this:

• One domain model maps to JSON responses and SQL rows.
• Validators run immediately after JSON decode in handlers.
• You want grep-friendly field definitions in code review.

Working Example

package main
 
import (
    "encoding/json"
    "fmt"
    "time"
)
 
type Product struct {
    SKU       string    `json:"sku" db:"sku" validate:"required,alphanum"`
    Title     string    `json:"title" db:"title" validate:"required,min=3,max=120"`
    PriceCents int64    `json:"price_cents" db:"price_cents" validate:"gte=0"`
    Active    bool      `json:"active" db:"is_active" validate:"-"`
    UpdatedAt time.Time `json:"updated_at" db:"updated_at" validate:"-"`
}
 
func main() {
    p := Product{
        SKU:        "ABC123",
        Title:      "Wrench",
        PriceCents: 1299,
        Active:     true,
        UpdatedAt:  time.Now().UTC(),
    }
    b, _ := json.Marshal(p)
    fmt.Println(string(b))
 
    // db tag is ignored by encoding/json; sqlx/jmoiron/sql would use db:"sku" on Scan
    // validate tags are consumed by go-playground/validator after Unmarshal
}

What this demonstrates:

• JSON uses snake_case keys while Go fields stay idiomatic PascalCase.
• db tags name columns for sqlx, scany, or similar scanners.
• validate tags express rules separate from serialization.
• json:"-" hides fields from API output while db may still persist them.

Deep Dive

Tag Grammar

Tags are backtick-quoted strings: `key:"value" other:"value"`.

Commas inside a value are usually options: validate:"omitempty,min=1".

Unknown keys are ignored by each library.

Common Tag Keys

ORMs like GORM use their own struct tags (gorm:"column:...") - pick one persistence style per project.

Naming Conventions

Document exceptions (legacy columns, camelCase JSON) in ADRs.

Multi-DTO vs Single Struct

Start single-struct for small services; split when API versioning diverges from tables.

Go Notes

// Lint: keep json and db names aligned unless legacy schema differs
// validate:"-" skips validation for server-set timestamps

golangci-lint tag checkers (when enabled) flag mismatched json field names vs Go field names.

Gotchas

• json ignored on unexported fields - Tags on lowercase fields do nothing for encoding/json. Fix: export API fields or use custom marshalers.
• validate never runs automatically - Tags are inert until you call validator.Struct. Fix: validate in handlers after Unmarshal.
• db tags without the right library - database/sql alone ignores db tags. Fix: use sqlx/scany or explicit column lists.
• omitempty on pointers vs values - Zero ints always encode unless omitempty; nil pointers omit. Fix: model optional numbers as pointers when 0 is meaningful.
• Tag drift on migrations - Renaming a column without updating db tags causes silent NULL scans. Fix: integration tests for repositories.
• Conflicting json keys - Embedded structs can produce duplicate JSON keys. Fix: rename tags or flatten with custom marshalers.

Alternatives

FAQs

Related

• Serialization Basics - json tag fundamentals
• encoding/json Custom Marshaling - when tags are not enough
• Validation with go-playground/validator - validate tag reference
• Protocol Buffers Schema Design - protobuf as alternate contract
• Serialization Best Practices - tag review checklist

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).