Lesson 3: Struct Tags, JSON & Protobuf

Why Tags Matter in Cloud-Native Go #

Look at a Kubernetes Custom Resource Definition:

type MyApp struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
    Spec   MyAppSpec   `json:"spec,omitempty"`
    Status MyAppStatus `json:"status,omitempty"`
}

type MyAppSpec struct {
    Replicas  *int32  `json:"replicas,omitempty"`
    Image     string  `json:"image"`
    Resources string  `json:"resources,omitempty" validate:"required"`
}

Those backtick strings — json:"replicas,omitempty" — are struct tags. They're not comments. They're not magic. They're metadata consumed by Go's reflect package at runtime to drive serialization, validation, and code generation.

Every cloud-native Go project uses them. Understanding tags means you can write Kubernetes operators, parse configs, generate protobuf code, and bind environment variables — all with the same mechanism.

Anatomy of a Struct Tag #

type Server struct {
    //     ↓ key   ↓ value with options
    Host string `json:"host"`
    Port int    `json:"port,omitempty"`
    TLS  bool   `json:"tls" env:"SERVER_TLS"`
    //                    ↑ multiple tags separated by space
}

The format is convention — not enforced by the compiler. Libraries use reflect.StructTag to parse them:

import "reflect"

t := reflect.TypeOf(Server{})
field, _ := t.FieldByName("Port")
tag := field.Tag
fmt.Println(tag.Get("json"))   // "port,omitempty"

val, ok := tag.Lookup("json")  // "port,omitempty", true
val, ok := tag.Lookup("xml")   // "", false (tag not present)

JSON Marshal & Unmarshal #

The most common use of struct tags: mapping Go structs to JSON and back.

Basic Marshal #

type Person struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

data, _ := json.Marshal(Person{"Alice", 30})
fmt.Println(string(data))  // {"name":"Alice","age":30}

Basic Unmarshal #

input := []byte(`{"name":"Bob","age":25}`)
var p Person
json.Unmarshal(input, &p)
fmt.Printf("%+v\n", p)  // {Name:Bob Age:25}

Renaming Fields #

type Config struct {
    MaxConnections int `json:"max_connections"`
    // Go field: MaxConnections  →  JSON key: "max_connections"
}

Skipping Fields #

type User struct {
    Name     string `json:"name"`
    Password string `json:"-"`  // never serialized
    internal string             // unexported — also never serialized
}

Embedded Structs (inline) #

type Base struct {
    ID   string `json:"id"`
    Kind string `json:"kind"`
}

type Pod struct {
    Base         // embedded — fields promoted to same JSON level
    Spec PodSpec `json:"spec"`
}

// If Base has json:",inline", its fields are inlined flat.
// Without ",inline", they're nested under "Base":{}.

Custom JSON Marshal/Unmarshal #

Implement these interfaces (from Lesson 0001!) to control JSON behavior:

type Marshaler interface {
    MarshalJSON() ([]byte, error)
}

type Unmarshaler interface {
    UnmarshalJSON([]byte) error
}

Real example: custom duration format in Kubernetes:

type Duration struct {
    time.Duration
}

func (d Duration) MarshalJSON() ([]byte, error) {
    return json.Marshal(d.Duration.String())  // "1h30m"
}

func (d *Duration) UnmarshalJSON(data []byte) error {
    var s string
    if err := json.Unmarshal(data, &s); err != nil {
        return err
    }
    dur, err := time.ParseDuration(s)
    if err != nil {
        return err
    }
    d.Duration = dur
    return nil
}

The omitempty Trap #

omitempty omits a field from JSON output when it has its zero value:

type App struct {
    Name    string  `json:"name,omitempty"`
    Port    int     `json:"port,omitempty"`
    Debug   bool    `json:"debug,omitempty"`
    Config  Settings `json:"config,omitempty"`
}

app := App{Name: "myapp"}
data, _ := json.Marshal(app)
fmt.Println(string(data))  // {"name":"myapp","config":{}}

Solution: use a pointer if you want omit-on-nil:

type App struct {
    Config *Settings `json:"config,omitempty"`  // nil → omitted
}

Zero value reference:

TypeZero value (omitted by omitempty) bool``false int, float``0 string``"" pointer, interface, slice, map, chan, funcnil structStruct{} (never omitted)

Protobuf Struct Tags #

Protobuf tags are generated by protoc, not hand-written. You write a .proto file, and protoc-gen-go produces Go structs with tags:

// Example .proto file:
// message Server {
//   string host = 1;
//   int32  port = 2;
// }

// Generated Go code:
type Server struct {
    state         protoimpl.MessageState
    sizeCache     protoimpl.SizeCache
    unknownFields protoimpl.UnknownFields

    Host string `protobuf:"bytes,1,opt,name=host,proto3" json:"host,omitempty"`
    Port int32  `protobuf:"varint,2,opt,name=port,proto3" json:"port,omitempty"`
}

Notice the generated code includes both protobuf and json tags. The protobuf tag drives protobuf serialization; the json tag drives JSON output (gRPC-Gateway, etcd API, Kubernetes API).

Protobuf Tag Format #

ComponentMeaningExample bytes, varintWire encoding typebytes for strings 1, 2Field number (from .proto)1 opt, repOptional / repeatedopt name=hostProtobuf field namename=host proto3Syntax versionproto3

Protobuf + JSON in Kubernetes #

Kubernetes stores resources as protobuf in etcd, but exposes them as JSON through the API server. The generated structs carry both tags:

// Kubernetes PodSpec (simplified, generated from .proto)
type PodSpec struct {
    Containers []Container `protobuf:"bytes,2,rep,name=containers" json:"containers"`
    NodeName   string        `protobuf:"bytes,4,opt,name=nodeName" json:"nodeName,omitempty"`
    // ...
}

Other Real-World Tag Uses #

YAML (gopkg.in/yaml.v3) #

type Config struct {
    ServerPort int `yaml:"server_port"`
    LogLevel   string `yaml:"log_level"`
}
// Kubernetes operators use this for CRD specs

Validation (go-playground/validator) #

type CreateUserRequest struct {
    Name  string `json:"name" validate:"required,min=2,max=50"`
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"gte=0,lte=130"`
}

Environment Variables (kelseyhightower/envconfig) #

type Spec struct {
    Port    int    `envconfig:"SERVER_PORT" default:"8080"`
    DBUrl   string `envconfig:"DATABASE_URL" required:"true"`
    Workers int    `envconfig:"NUM_WORKERS" default:"4"`
}

SQL Mapping (sqlx) #

type User struct {
    ID        int       `db:"id"`
    Name      string    `db:"name"`
    CreatedAt time.Time `db:"created_at"`
}

Practice #

Quick Check #

What's Next? #

You now understand how Go maps data to JSON, protobuf, and other formats. Next up: Testing — table-driven tests, mocks via interfaces, testing.T, subtests, and how Kubernetes controllers are tested with fake clients.

---

Ask Questions #

Confused about omitempty behavior with structs? Want to see more protobuf examples? Ask.