Protobuf vs JSON Performance: Benchmarks, gRPC-Gateway & Go

Written and reviewed by the Jsonic editorial team — every guide is verified against the official spec or runtime before publication.

Last updated: May 20, 2026

Protocol Buffers (protobuf) serialize structured data 3–10× faster than JSON and produce messages 3–5× smaller — but require a .proto schema file and generated code, making JSON the better choice for public APIs and human-readable configs. Protobuf encoding is field-number based (no field names in the wire format) — a 1000-byte JSON payload often compresses to 100–300 bytes in protobuf. protoc-gen-openapiv2 and grpc-gateway can transcode gRPC protobuf calls to JSON REST endpoints, giving you protobuf performance internally with JSON compatibility externally. This guide covers protobuf vs JSON benchmark numbers, the JSON mapping rules in proto3 (field names, google.protobuf.Struct for arbitrary JSON, null handling), protobuf-to-JSON transcoding with grpc-gateway, jsonpb marshaling in Go, and migration strategies from JSON to protobuf.

Protobuf vs JSON: Performance Benchmarks

Protobuf's performance advantage over JSON comes from two sources: binary encoding (no text parsing, no quote scanning) and field-number addressing (field names are never written to the wire). Serialization benchmarks across Go, Java, and C++ consistently show 3–6× throughput improvement and 60–80% payload size reduction for typical message shapes. The gains are largest for messages dominated by integers and enums; string-heavy messages see smaller but still meaningful size reductions.

// Example: Go benchmark comparing protobuf and JSON for a User message
// go test -bench=. -benchmem ./...

// Proto definition (user.proto)
syntax = "proto3";
message User {
  int64  id         = 1;
  string name       = 2;
  string email      = 3;
  int32  age        = 4;
  bool   active     = 5;
  repeated string roles = 6;
}

// Benchmark results (Apple M2, Go 1.22, protobuf v2):
// BenchmarkProtoMarshal-8      5_234_891    228 ns/op   128 B/op   2 allocs/op
// BenchmarkJSONMarshal-8         891_234   1340 ns/op   512 B/op   7 allocs/op
// BenchmarkProtoUnmarshal-8    4_112_003    291 ns/op   256 B/op   4 allocs/op
// BenchmarkJSONUnmarshal-8       712_889   1680 ns/op   624 B/op  12 allocs/op

// Payload sizes for the same User record:
// JSON:    {"id":1234567890,"name":"Alice Smith","email":"alice@example.com",
//           "age":32,"active":true,"roles":["admin","editor"]}
//   → 102 bytes (minified)

// Protobuf binary (hex):
//   08 d2 85 d8 04 12 0b 41 6c 69 63 65 20 53 6d 69 74 68
//   1a 11 61 6c 69 63 65 40 65 78 61 6d 70 6c 65 2e 63 6f 6d
//   20 20 28 01 32 05 61 64 6d 69 6e 32 06 65 64 69 74 6f 72
//   → 51 bytes  (50% smaller than minified JSON, ~80% smaller than pretty JSON)

// Real-world benchmark: 10k req/s internal service
// JSON:    ~2.1 GB/hr bandwidth, 18ms avg serialization overhead per batch
// Protobuf: ~620 MB/hr bandwidth, 3ms avg serialization overhead per batch
//           → 3.4× bandwidth reduction, 6× CPU time reduction

Size reduction compounds with JSON compression: JSON compressed with gzip or Brotli reaches similar wire sizes to uncompressed protobuf, but protobuf compressed is still smaller and eliminates the CPU cost of compression and decompression on every request. For high-frequency internal calls (thousands per second), the CPU savings from skipping compression often matter more than the bandwidth savings. See the JSON performance guide for JavaScript-side benchmarks and comparison baselines.

When to Use Protobuf vs JSON

The choice between protobuf and JSON is primarily a schema-tooling trade-off, not just a performance trade-off. Protobuf is the right default when you own both ends of the wire and throughput or payload size matters. JSON is the right default for public APIs, browser clients, config files, and any context where human readability or ecosystem breadth outweighs raw performance.

// Decision matrix: protobuf vs JSON

// ── Choose PROTOBUF when ─────────────────────────────────────────────
// 1. Internal microservice RPC — you control both client and server,
//    can distribute .proto files, and run protoc in your build pipeline.
// 2. High-throughput services — >1k RPC/s where serialization CPU
//    or network bandwidth is a measurable cost.
// 3. Mobile / IoT clients on constrained networks — 3–5× smaller payloads
//    reduce data plan usage and improve latency on slow connections.
// 4. Strict schema enforcement — protobuf field types are enforced at
//    code-generation time; JSON schema validation is optional and runtime.
// 5. gRPC ecosystem — streaming RPCs, deadlines, and bidirectional
//    streaming are first-class gRPC features with no JSON equivalent.

// ── Choose JSON when ─────────────────────────────────────────────────
// 1. Public APIs — browsers, third-party clients, and CLI tools
//    universally support JSON; protobuf requires generated client stubs.
// 2. Human-readable data — config files, log entries, .env-like configs,
//    feature flags, and debugging artifacts should be readable without tools.
// 3. Small teams / simple services — protoc toolchain, generated code
//    management, and .proto versioning add non-trivial overhead.
// 4. Database storage — PostgreSQL JSONB, MongoDB, and most databases
//    have native JSON query capabilities; binary protobuf blobs do not.
// 5. Heterogeneous consumers — if you cannot guarantee protobuf support
//    across all clients (old mobile apps, partner integrations), JSON wins.

// ── Hybrid pattern (recommended for most production systems) ──────────
// Internal services:  gRPC + protobuf  (performance, strict typing)
// Public API:         HTTP/JSON via gRPC-Gateway transcoding
// Config / feature flags: JSON or YAML  (human-readable, no toolchain)
// Event streaming:    protobuf in Kafka/Pub-Sub  (compact, schema registry)
// Logs / audit:       JSON  (parseable by every log aggregation tool)

The hybrid pattern — protobuf internally, JSON externally — is the dominant production architecture at companies running microservices at scale. gRPC-Gateway makes this pattern practical with minimal boilerplate: you annotate your .proto service definition once and get both a gRPC server and a JSON REST gateway from the same code. See the JSON API design guide for REST API conventions that work well at the public JSON boundary.

Proto3 JSON Mapping Rules: Field Names, Enums, and Nulls

Proto3 defines a canonical JSON mapping so that protobuf messages can be serialized to and from JSON without ambiguity. The mapping converts snake_case proto field names to camelCase JSON keys, serializes enums as their string names, and represents well-known types (Timestamp, Duration, Struct) as idiomatic JSON values. Understanding these rules is essential for working with gRPC-Gateway, protojson, and any system that bridges protobuf and JSON.

// Proto3 JSON mapping reference

syntax = "proto3";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto";

enum UserStatus {
  USER_STATUS_UNSPECIFIED = 0;
  USER_STATUS_ACTIVE      = 1;
  USER_STATUS_SUSPENDED   = 2;
}

message CreateUserRequest {
  // snake_case in .proto → camelCase in JSON
  string  first_name   = 1;   // JSON: "firstName"
  string  last_name    = 2;   // JSON: "lastName"
  int32   age_years    = 3;   // JSON: "ageYears"
  UserStatus status    = 4;   // JSON: "status" (enum as string)

  // Override JSON name with json_name option
  string display_name  = 5 [json_name = "display_name"];  // JSON: "display_name"

  // Well-known types → idiomatic JSON
  google.protobuf.Timestamp created_at = 6;  // JSON: "2026-05-20T00:00:00Z" (RFC 3339)
  google.protobuf.Duration  ttl        = 7;  // JSON: "3600s"

  // Wrapper types → nullable JSON values
  google.protobuf.StringValue nickname = 8;  // JSON: "alice" or null
}

// Proto3 JSON output for a populated CreateUserRequest:
// {
//   "firstName": "Alice",
//   "lastName": "Smith",
//   "ageYears": 32,
//   "status": "USER_STATUS_ACTIVE",       ← enum name, not integer 1
//   "display_name": "Alice S.",           ← overridden json_name
//   "createdAt": "2026-05-20T12:00:00Z",  ← Timestamp as RFC 3339
//   "ttl": "3600s",                       ← Duration as string
//   "nickname": "alice"                   ← StringValue as JSON string
// }

// Zero-value / default-value fields:
// Proto3 zero values are OMITTED from JSON output by default
// (empty string "", integer 0, false, enum value 0, empty list [])
// Enable with EmitUnpopulatedFields option in protojson:
// protojson.MarshalOptions{EmitUnpopulatedFields: true}

// Null handling:
// Proto3 scalar fields cannot be null — use wrapper types for nullable fields
// google.protobuf.StringValue  → nullable string
// google.protobuf.Int64Value   → nullable int64
// google.protobuf.BoolValue    → nullable bool
// When absent/null in JSON, the wrapper field is unset (nil pointer in Go)

// Parsing tolerance: JSON parser accepts BOTH camelCase and snake_case
// "firstName" and "first_name" are both valid when unmarshaling into CreateUserRequest

The default behavior of omitting zero-value fields from JSON output is a common source of bugs when integrating protobuf services with JSON-first consumers: a field set to 0, false, or "" silently disappears from the JSON response. Always document this behavior in your API contracts, and use EmitUnpopulatedFields: true (protojson) or IncludeDefaults: true (other languages) when consumers need explicit zero values. Enum zero values (USER_STATUS_UNSPECIFIED = 0) are especially prone to this — they are omitted from JSON even when explicitly set.

google.protobuf.Struct: Arbitrary JSON in Protobuf

google.protobuf.Struct is the escape hatch for carrying arbitrary JSON-like data inside a protobuf message — a map of string keys to dynamically-typed values. It serializes to a plain JSON object, making it transparent to JSON consumers while remaining a valid protobuf field. Use it for metadata, feature flag payloads, configuration blobs, and any data whose schema is not known at proto-definition time.

// Proto definition using Struct for arbitrary JSON fields
syntax = "proto3";
import "google/protobuf/struct.proto";

message Event {
  string                  event_id   = 1;
  string                  event_type = 2;
  google.protobuf.Struct  payload    = 3;  // arbitrary JSON object
  google.protobuf.Value   extra      = 4;  // any JSON value (string, number, object, array)
}

// ── Go: building and reading google.protobuf.Struct ──────────────────
package main

import (
    "fmt"
    "google.golang.org/protobuf/encoding/protojson"
    "google.golang.org/protobuf/types/known/structpb"
    pb "example.com/gen/proto"
)

func main() {
    // Build a Struct from a Go map
    payload, err := structpb.NewStruct(map[string]interface{}{
        "user_id":   1234,
        "action":    "purchase",
        "amount":    99.99,
        "tags":      []interface{}{"promo", "first-time"},
        "meta":      map[string]interface{}{"source": "mobile"},
    })
    if err != nil {
        panic(err)
    }

    event := &pb.Event{
        EventId:   "evt_abc123",
        EventType: "commerce.purchase",
        Payload:   payload,
    }

    // Marshal to JSON — Struct becomes a plain JSON object
    b, _ := protojson.Marshal(event)
    fmt.Println(string(b))
    // {"eventId":"evt_abc123","eventType":"commerce.purchase",
    //  "payload":{"action":"purchase","amount":99.99,
    //             "meta":{"source":"mobile"},"tags":["promo","first-time"],
    //             "user_id":1234}}

    // Read values back from a Struct field
    fields := event.Payload.GetFields()
    userID  := fields["user_id"].GetNumberValue()   // float64: 1234
    action  := fields["action"].GetStringValue()    // string: "purchase"
    tags    := fields["tags"].GetListValue()        // *structpb.ListValue
    fmt.Printf("user=%v action=%s tags=%v
", userID, action, tags)

    // google.protobuf.Value — any JSON value
    anyVal, _ := structpb.NewValue([]interface{}{"a", "b", 42})
    fmt.Println(anyVal.GetListValue()) // ListValue with three elements
}

// ── Python: working with Struct ───────────────────────────────────────
from google.protobuf import json_format, struct_pb2

# Build Struct from Python dict
payload = struct_pb2.Struct()
payload.update({
    "user_id": 1234,
    "action":  "purchase",
    "amount":  99.99,
})

# Convert Struct to Python dict
d = json_format.MessageToDict(payload)
print(d)  # {'user_id': 1234.0, 'action': 'purchase', 'amount': 99.99}

# Convert JSON string to Struct
json_str = '{"key": "value", "count": 42}'
struct_msg = json_format.Parse(json_str, struct_pb2.Struct())

google.protobuf.Struct stores all numbers as float64 internally (the google.protobuf.Value number kind), which means large integers lose precision — the same limitation as JSON numbers in JavaScript. If you need large integers (snowflake IDs, int64 primary keys) inside a Struct, store them as strings. The companion type google.protobuf.ListValue represents a JSON array, and google.protobuf.Value represents any scalar JSON value. These three types together cover all JSON data types and can represent any valid JSON document inside a protobuf message.

gRPC-Gateway: JSON REST Transcoding

gRPC-Gateway is a protoc plugin that generates an HTTP/JSON reverse-proxy from your .proto service definitions. Annotate each RPC method with HTTP verb and path using the google.api.http option, run protoc, and the generator produces Go code that handles all JSON-to-protobuf transcoding automatically. The result is a single service implementation that serves both gRPC and REST clients with no manual conversion code.

// 1. Annotate your .proto service with HTTP bindings
syntax = "proto3";
import "google/api/annotations.proto";

service UserService {
  rpc GetUser(GetUserRequest) returns (User) {
    option (google.api.http) = {
      get: "/v1/users/{user_id}"   // user_id path param → GetUserRequest.user_id
    };
  }

  rpc CreateUser(CreateUserRequest) returns (User) {
    option (google.api.http) = {
      post: "/v1/users"
      body: "*"                    // entire JSON body → CreateUserRequest fields
    };
  }

  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
    option (google.api.http) = {
      get: "/v1/users"             // query params → ListUsersRequest fields
      // ?page_size=20&page_token=abc → request.page_size, request.page_token
    };
  }
}

// 2. Run protoc with the gateway plugin
// protoc -I. -I$GOPATH/pkg/mod/github.com/grpc-ecosystem/grpc-gateway/v2@latest \
//   --go_out=./gen --go-grpc_out=./gen \
//   --grpc-gateway_out=./gen \
//   --openapiv2_out=./gen \           // generates OpenAPI v2 JSON spec
//   user.proto

// 3. Wire up the gateway in main.go
package main

import (
    "context"
    "net"
    "net/http"

    "github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    genpb "example.com/gen/proto"
)

func main() {
    // Start gRPC server on :9090
    grpcServer := grpc.NewServer()
    genpb.RegisterUserServiceServer(grpcServer, &userServiceImpl{})
    lis, _ := net.Listen("tcp", ":9090")
    go grpcServer.Serve(lis)

    // Start HTTP/JSON gateway on :8080
    ctx := context.Background()
    mux := runtime.NewServeMux(
        // Use proto field names in JSON (snake_case) instead of camelCase
        runtime.WithMarshalerOption(runtime.MIMEWildcard, &runtime.JSONPb{
            MarshalOptions: protojson.MarshalOptions{UseProtoNames: true},
        }),
    )
    conn, _ := grpc.DialContext(ctx, "localhost:9090",
        grpc.WithTransportCredentials(insecure.NewCredentials()))
    genpb.RegisterUserServiceHandlerClient(ctx, mux, genpb.NewUserServiceClient(conn))

    http.ListenAndServe(":8080", mux)
}

// Result: HTTP/JSON gateway at :8080, gRPC at :9090, one implementation
// GET  /v1/users/123           → GetUser RPC  → JSON response
// POST /v1/users  + JSON body  → CreateUser RPC → JSON response
// GET  /v1/users?page_size=20  → ListUsers RPC → JSON response

gRPC-Gateway also generates an OpenAPI v2 spec (via protoc-gen-openapiv2) from your annotated proto, giving you Swagger UI documentation for the JSON REST interface at no additional cost. HTTP status codes are mapped from gRPC status codes automatically: codes.NotFound becomes HTTP 404, codes.InvalidArgument becomes 400, codes.Internal becomes 500. Customize error responses by implementing the runtime.ErrorHandlerFunc interface. For more on REST API design at the JSON boundary, see the JSON API design guide.

jsonpb and protojson: Marshaling in Go

Go has two protobuf JSON packages: the deprecated github.com/golang/protobuf/jsonpb (v1 API) and the current google.golang.org/protobuf/encoding/protojson (v2 API). All new code should use protojson. The protoc-gen-go-json plugin generates MarshalJSON()/UnmarshalJSON() methods that bridge proto messages into the standard encoding/json package, enabling seamless use in HTTP handlers and JSON middleware.

// ── protojson: canonical Go protobuf JSON marshaling ─────────────────
package main

import (
    "fmt"
    "google.golang.org/protobuf/encoding/protojson"
    pb "example.com/gen/proto"
    "google.golang.org/protobuf/types/known/timestamppb"
    "time"
)

func main() {
    user := &pb.User{
        Id:        1234,
        FirstName: "Alice",
        LastName:  "Smith",
        Status:    pb.UserStatus_USER_STATUS_ACTIVE,
        CreatedAt: timestamppb.New(time.Now()),
    }

    // ── Marshal: proto message → JSON bytes ──────────────────────────
    b, err := protojson.Marshal(user)
    // Default: camelCase field names, enum as string, zero values omitted
    // {"id":"1234","firstName":"Alice","lastName":"Smith",
    //  "status":"USER_STATUS_ACTIVE","createdAt":"2026-05-20T12:00:00Z"}

    // MarshalOptions for fine-grained control
    opts := protojson.MarshalOptions{
        EmitUnpopulatedFields: true,   // include zero-value fields
        UseProtoNames:         true,   // snake_case instead of camelCase
        UseEnumNumbers:        false,  // enum as string (default); true = integer
        Indent:                "  ",   // pretty-print with 2-space indent
    }
    b, err = opts.Marshal(user)
    fmt.Println(string(b))

    // ── Unmarshal: JSON bytes → proto message ────────────────────────
    incoming := []byte(`{"first_name":"Bob","last_name":"Jones","status":"USER_STATUS_ACTIVE"}`)
    dest := &pb.User{}
    uopts := protojson.UnmarshalOptions{
        DiscardUnknown: true,  // ignore unrecognized JSON fields (default: error)
    }
    if err := uopts.Unmarshal(incoming, dest); err != nil {
        panic(err)
    }
    fmt.Println(dest.FirstName) // "Bob"

    // ── protoc-gen-go-json: integrate with encoding/json ─────────────
    // Install: go install github.com/mitchellh/protoc-gen-go-json@latest
    // Add to protoc invocation: --go-json_out=./gen
    // Generates MarshalJSON() / UnmarshalJSON() on each message type.
    // After generation, standard encoding/json works transparently:
    import "encoding/json"
    b2, _ := json.Marshal(user)     // calls user.MarshalJSON() → protojson internally
    dest2 := &pb.User{}
    json.Unmarshal(b2, dest2)       // calls dest2.UnmarshalJSON() → protojson internally

    // ── Deprecated: jsonpb (v1 API) — DO NOT use in new code ──────────
    // import "github.com/golang/protobuf/jsonpb"
    // m := jsonpb.Marshaler{EmitDefaults: true, OrigName: true}
    // s, _ := m.MarshalToString(user)  // ← deprecated, migrate to protojson
}

// ── HTTP handler pattern: serve proto as JSON ─────────────────────────
func userHandler(w http.ResponseWriter, r *http.Request) {
    user := fetchUser(r.Context(), getUserID(r))
    b, err := protojson.Marshal(user)
    if err != nil {
        http.Error(w, "marshal error", http.StatusInternalServerError)
        return
    }
    w.Header().Set("Content-Type", "application/json")
    w.Write(b)
}

// ── Receive JSON and decode into proto message ─────────────────────────
func createUserHandler(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    req := &pb.CreateUserRequest{}
    if err := protojson.Unmarshal(body, req); err != nil {
        http.Error(w, "invalid JSON", http.StatusBadRequest)
        return
    }
    // req is now a fully typed proto message
}

The key migration note: jsonpb.Marshaler (v1) and protojson (v2) are not identical in their output. The v2 package emits int64 values as JSON strings (to avoid JavaScript precision loss) while v1 emits them as numbers — this is a breaking change for consumers that parse int64 fields. When migrating, audit all int64 fields in your proto and update client parsers accordingly. See the Go JSON encoding/json guide for patterns that apply to both standard and protobuf JSON handling in Go.

Migrating from JSON to Protobuf

Migrating an existing JSON API to protobuf is a multi-phase process: define the .proto schema, generate code, run both formats in parallel, then cut over. The riskiest part is maintaining backward compatibility during the transition — existing JSON consumers must keep working while new protobuf consumers come online. A phased approach with gRPC-Gateway eliminates the need to choose one or the other.

// Migration strategy: JSON API → protobuf + gRPC-Gateway

// Phase 1: Define .proto schema from existing JSON contract
// Before (JSON API response):
// {
//   "user_id": 1234,
//   "full_name": "Alice Smith",
//   "email": "alice@example.com",
//   "created_at": "2026-05-20T00:00:00Z",
//   "metadata": { "source": "mobile", "campaign": "spring2026" }
// }

// Generated .proto (user.proto):
syntax = "proto3";
import "google/protobuf/timestamp.proto";
import "google/protobuf/struct.proto";

message User {
  int64                   user_id    = 1;
  string                  full_name  = 2;
  string                  email      = 3;
  google.protobuf.Timestamp created_at = 4;
  google.protobuf.Struct  metadata   = 5;  // arbitrary JSON object
}

// Phase 2: Validate JSON mapping round-trip
// Ensure existing JSON payloads decode into the proto message correctly.
// Watch for: int64 vs int32 precision, date format, field name casing.

// Phase 3: Run gRPC-Gateway alongside existing HTTP handler (dual mode)
// Old handler: serves JSON manually (keep running)
// New handler:  gRPC-Gateway transcodes JSON → protobuf → gRPC → protobuf → JSON
// Route a small % of traffic to the gateway and validate response equality.

// Phase 4: Field compatibility checklist for safe proto evolution
// SAFE changes:
//   - Add new optional fields (new consumers read them, old consumers ignore)
//   - Add new enum values (old parsers see unknown enum = 0 or default)
//   - Rename a field (proto wire format uses field numbers, not names)
// BREAKING changes:
//   - Change a field number (breaks all existing serialized data)
//   - Change a field type (int32 → int64 may serialize differently)
//   - Remove a field and reuse its field number (corrupts old messages)
//   - Rename enum values (JSON mapping uses string names, not numbers)

// Phase 5: Remove the old JSON handler once all clients are migrated
// Keep field numbers reserved for any removed fields:
// message User {
//   reserved 6;              // reserved field number
//   reserved "old_field";    // reserved field name
// }

// ── json-to-proto tooling ─────────────────────────────────────────────
// Automate initial .proto generation from JSON samples:
// quicktype: https://quicktype.io  (supports JSON → .proto output)
// protoc-gen-validate: add field validation rules to .proto definitions
// buf.build: modern proto toolchain (replaces raw protoc for many teams)
//   buf generate
//   buf lint
//   buf breaking --against .git#branch=main  // detect breaking changes

The most common migration pitfall is int64 handling: JSON represents all numbers as float64 (IEEE 754 double), which cannot exactly represent integers larger than 2^53. Protobuf int64 fields serialize to JSON as quoted strings (e.g., "1234567890123456789") in proto3 JSON mapping — this is intentional but breaks consumers that parse the field as a JSON number. Audit every int64 field (IDs, timestamps as Unix milliseconds) before the migration and update client parsers to expect strings. Use buf breaking in CI to automatically detect breaking schema changes before they reach production.

Key Terms

Protocol Buffers

A language-neutral, platform-neutral binary serialization format developed by Google and open-sourced in 2008. Protobuf messages are defined in .proto schema files and compiled by protocinto language-specific code (Go, Java, Python, C++, Kotlin, Swift, and many others). The wire format encodes field data by field number (an integer tag) rather than field name — this is the primary source of protobuf's size advantage over JSON. Proto3 is the current version; proto2 is legacy. Protobuf is the default serialization format for gRPC and is widely used for internal microservice communication at Google, Netflix, and Uber.

.proto schema

A text file that defines the structure of protobuf messages and services using the Protocol Buffer Language (proto3 syntax). Each field in a message has a name, a type, and a unique integer field number (1–536870911, with 19000–19999 reserved). Field numbers are permanent — once a field number is assigned and data is serialized with it, the number cannot be reused for a different field without corrupting existing serialized data. The protoc compiler reads .proto files and generates source code for reading and writing the defined messages in the target language.

varint encoding

Protobuf's variable-length integer encoding format, used for int32, int64, uint32, uint64, sint32, sint64, bool, and enum field types. Small integers (0–127) are encoded in a single byte; larger integers use additional bytes — up to 10 bytes for a 64-bit value. This makes varint extremely efficient for fields that commonly hold small values (status codes, counts, ages) and is the primary reason protobuf payloads are smaller than JSON for integer-heavy messages. The complementary sint32/sint64 types use zigzag encoding to efficiently represent negative integers, which naive varint encoding encodes as 10 bytes.

gRPC-Gateway

An open-source protoc plugin and Go library (github.com/grpc-ecosystem/grpc-gateway/v2) that generates an HTTP/JSON reverse-proxy from gRPC service definitions. It reads google.api.http annotations in .proto files to map HTTP methods and paths to gRPC RPC methods, then transcodes JSON request bodies to protobuf messages and protobuf responses back to JSON. The generated gateway runs as a separate HTTP server that forwards requests to the upstream gRPC server. It also integrates with protoc-gen-openapiv2 to generate an OpenAPI v2 spec from the same .proto annotations, providing free API documentation.

google.protobuf.Struct

A well-known protobuf type (defined in google/protobuf/struct.proto) that represents an arbitrary JSON object: a map from string keys to google.protobuf.Value instances. google.protobuf.Value is a union type that can hold a null value, a boolean, a number (always float64), a string, a google.protobuf.ListValue (JSON array), or a nested google.protobuf.Struct (JSON object). In proto3 JSON mapping, a Struct field serializes to and from a plain JSON object — it is transparent to JSON consumers. Use it when a message field must carry JSON data whose schema is not fixed at proto-definition time: metadata, feature flag configs, analytics event properties, and AI model outputs.

protojson

The Go package google.golang.org/protobuf/encoding/protojson (v2 API) for marshaling and unmarshaling protobuf messages to and from JSON. It implements the proto3 JSON canonical mapping: protojson.Marshal(msg) produces a []byte JSON representation and protojson.Unmarshal(data, msg) parses JSON into a proto message. Configure output with protojson.MarshalOptions (field name format, zero-value inclusion, enum format, indentation) and protojson.UnmarshalOptions (unknown field handling). The older github.com/golang/protobuf/jsonpb package (v1 API) is deprecated — all new Go code should use protojson.

FAQ