Complete Microservice Schema Example

Real-World Microservice Schema

This example demonstrates a complete, production-style protobuf schema for an inventory management microservice. It combines messages, enums, nested types, map fields, oneof, streaming RPCs, and well-known type imports.

syntax = "proto3";

package inventory.v1;

import "google/protobuf/timestamp.proto";
import "google/protobuf/field_mask.proto";

// ── Enums ────────────────────────────────

enum StockStatus {
  STOCK_STATUS_UNSPECIFIED = 0;
  STOCK_STATUS_IN_STOCK = 1;
  STOCK_STATUS_LOW_STOCK = 2;
  STOCK_STATUS_OUT_OF_STOCK = 3;
  STOCK_STATUS_DISCONTINUED = 4;
}

// ── Core Messages ────────────────────────

message InventoryItem {
  string sku = 1;
  string name = 2;
  string description = 3;
  int32 quantity = 4;
  int32 reorder_threshold = 5;
  StockStatus status = 6;
  double unit_price = 7;
  map<string, string> attributes = 8;
  repeated string tags = 9;
  Warehouse warehouse = 10;
  google.protobuf.Timestamp last_restocked = 11;
  google.protobuf.Timestamp created_at = 12;

  message Warehouse {
    string id = 1;
    string name = 2;
    string zone = 3;
    string aisle = 4;
    string shelf = 5;
  }
}

message StockAdjustment {
  string sku = 1;
  int32 quantity_change = 2;
  AdjustmentReason reason = 3;
  string notes = 4;
  string adjusted_by = 5;
  google.protobuf.Timestamp adjusted_at = 6;

  enum AdjustmentReason {
    ADJUSTMENT_REASON_UNSPECIFIED = 0;
    ADJUSTMENT_REASON_SALE = 1;
    ADJUSTMENT_REASON_RETURN = 2;
    ADJUSTMENT_REASON_RESTOCK = 3;
    ADJUSTMENT_REASON_DAMAGE = 4;
    ADJUSTMENT_REASON_AUDIT = 5;
  }
}

// ── Service Definition ───────────────────

service InventoryService {
  rpc GetItem(GetItemRequest) returns (InventoryItem);
  rpc ListItems(ListItemsRequest) returns (ListItemsResponse);
  rpc UpdateItem(UpdateItemRequest) returns (InventoryItem);
  rpc AdjustStock(AdjustStockRequest) returns (AdjustStockResponse);
  rpc BulkAdjustStock(stream AdjustStockRequest) returns (BulkAdjustResponse);
  rpc WatchStockLevels(WatchStockRequest) returns (stream StockAlert);
}

message GetItemRequest {
  string sku = 1;
}

message ListItemsRequest {
  int32 page_size = 1;
  string page_token = 2;
  StockStatus status_filter = 3;
  string warehouse_id = 4;
}

message ListItemsResponse {
  repeated InventoryItem items = 1;
  string next_page_token = 2;
  int32 total_count = 3;
}

message UpdateItemRequest {
  InventoryItem item = 1;
  google.protobuf.FieldMask update_mask = 2;
}

message AdjustStockRequest {
  StockAdjustment adjustment = 1;
}

message AdjustStockResponse {
  InventoryItem updated_item = 1;
  StockAdjustment applied_adjustment = 2;
}

message BulkAdjustResponse {
  int32 successful = 1;
  int32 failed = 2;
  repeated string failed_skus = 3;
}

message WatchStockRequest {
  repeated string skus = 1;
  int32 low_stock_threshold = 2;
}

message StockAlert {
  string sku = 1;
  string item_name = 2;
  int32 current_quantity = 3;
  StockStatus new_status = 4;
  google.protobuf.Timestamp alert_time = 5;
}

Schema Design Highlights

This schema demonstrates several best practices: versioned packaging, well-known type usage for timestamps, field masks for partial updates, nested messages for logical scoping, client streaming for bulk operations, and server streaming for real-time monitoring. Each RPC has dedicated request/response types for independent evolution.