What are the best practices for designing Protocol Buffer schemas in Go microservices?

Protobuf schema design has long-term consequences — once published, breaking changes require coordinated version bumps across all consumers. Good schema design minimises future pain.

// Best practices:

// 1. Use well-known types for common data
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/wrappers.proto"; // for nullable primitives

message Order {
    string order_id = 1;  // UUIDs as strings, not int64
    google.protobuf.Timestamp created_at = 2; // not int64 unix
    google.protobuf.Duration  processing_time = 3;
    google.protobuf.StringValue discount_code = 4; // nullable string
    repeated OrderItem items = 5;
    OrderStatus status = 6;
}

// 2. Use enums with an UNSPECIFIED zero value
enum OrderStatus {
    ORDER_STATUS_UNSPECIFIED = 0; // default/unknown — must be 0
    ORDER_STATUS_PENDING     = 1;
    ORDER_STATUS_PAID        = 2;
    ORDER_STATUS_SHIPPED     = 3;
    ORDER_STATUS_CANCELLED   = 4;
}

// 3. OneOf for discriminated unions
message PaymentMethod {
    oneof method {
        CreditCard credit_card = 1;
        BankTransfer bank_transfer = 2;
        CryptoCurrency crypto = 3;
    }
}

// 4. Avoid nested types — prefer separate top-level messages
// Bad: message User { message Address { ... } address = 5; }
// Good: message Address { ... }  message User { Address address = 5; }

// 5. Name convention: snake_case fields, PascalCase messages
// 6. Namespace your protos: package company.service.v1;
// 7. One service per .proto file; one message per concern

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.