Protobuf Developer
This skill provides best practices and rules for developing Protocol Buffer schemas (proto3).
When to Apply
Reference these guidelines when:
- Defining new gRPC services and message types.
- Modifying existing
.protofiles. - Refactoring message structures.
- Ensuring backwards compatibility for evolving APIs.
- Configuring Protobuf management, linting, and code generation using Buf.
Google AIP References
The following references are based on Google API Improvement Proposals (AIPs). Use these when designing resource-oriented APIs.
Important: When implementing these patterns, you must modify the protobuf package name and resource type domains to match the current application context (e.g., use package imrenagi.com.v1; instead of package google.example.v1;).
Resource Design
| Reference | When to Use |
|---|---|
| AIP-121: Resource-Oriented Design | Designing a new API or service; need to structure resources and collections consistently. |
| AIP-122: Resource Names | Defining the name field for resources; need the correct URI path format for identifiers. |
| AIP-123: Resource Types | Annotating messages with google.api.resource; need to define resource type patterns. |
| AIP-124: Resource Association | Referencing resources from other messages; using google.api.resource_reference. |
| AIP-126: Enumerations | Defining enum types; need _UNSPECIFIED zero-value and naming conventions. |
| AIP-127: HTTP/gRPC Transcoding | Adding google.api.http annotations; need to map gRPC methods to REST endpoints. |
| AIP-128: Declarative-Friendly Interfaces | Building APIs consumed by infrastructure-as-code tools like Terraform. |
| AIP-129: Server-Modified Values | Handling fields computed or modified by the server (e.g., create_time, update_time). |
Standard Methods
| Reference | When to Use |
|---|---|
| AIP-130: Methods | Understanding the general structure and naming of RPC methods. |
| AIP-131: Get Methods | Implementing a method to retrieve a single resource by name. |
| AIP-132: List Methods | Implementing a method to list resources with pagination. |
| AIP-133: Create Methods | Implementing a method to create a new resource. |
| AIP-134: Update Methods | Implementing a method to update an existing resource with field masks. |
| AIP-135: Delete Methods | Implementing a method to delete a resource. |
| AIP-136: Custom Methods | Implementing non-CRUD actions (e.g., :cancel, :move, :archive). |
Field Conventions
| Reference | When to Use |
|---|---|
| AIP-140: Field Names | Naming fields; need snake_case conventions and standard suffixes. |
| AIP-141: Quantities | Defining numeric fields for counts, sizes, or quantities. |
| AIP-142: Time and Duration | Using google.protobuf.Timestamp and google.protobuf.Duration. |
| AIP-143: Standardized Codes | Defining status codes, language codes, or other standardized values. |
| AIP-144: Repeated Fields | Using repeated fields for lists; understanding pluralization and ordering. |
| AIP-145: Ranges | Defining start/end or min/max field pairs for ranges. |
| AIP-146: Generic Fields | Using google.protobuf.Any or google.protobuf.Struct for dynamic data. |
| AIP-147: Sensitive Fields | Marking fields containing PII or secrets. |
| AIP-148: Standard Fields | Using common fields like name, display_name, title, description. |
| AIP-149: Unset Field Values | Distinguishing between unset and default values with optional fields. |
| AIP-203: Field Behavior | Annotating fields with REQUIRED, OUTPUT_ONLY, IMMUTABLE, etc. |
Operations & Patterns
| Reference | When to Use |
|---|---|
| AIP-151: Long-Running Operations | Operations taking > 2 seconds; using google.longrunning.Operation. |
| AIP-152: Jobs | Modeling user-managed background tasks or recurring operations. |
| AIP-153: Import/Export | Implementing bulk data import or export operations. |
| AIP-154: ETags | Adding optimistic concurrency control with ETags. |
| AIP-155: Request IDs | Supporting client-provided request IDs for idempotency. |
| AIP-156: Singleton Resources | Modeling resources with only one instance (e.g., settings, config). |
| AIP-157: Partial Responses | Allowing clients to request specific fields with read masks. |
| AIP-158: Pagination | Implementing page_size and page_token for list methods. |
| AIP-159: Reading Across Collections | Listing resources across multiple parents (using - wildcard). |
| AIP-160: Filtering | Adding filter expressions to list methods. |
| AIP-161: Field Masks | Using google.protobuf.FieldMask for partial updates. |
| AIP-162: Resource Revisions | Tracking historical versions or revisions of resources. |
| AIP-163: Change Validation | Validating changes before applying (dry-run mode). |
| AIP-164: Soft Delete | Implementing soft-delete with Undelete and retention periods. |
| AIP-165: Purge | Implementing bulk deletion of soft-deleted resources. |
Batch Operations
| Reference | When to Use |
|---|---|
| AIP-231: Batch Get | Retrieving multiple resources by name in a single request. |
| AIP-233: Batch Create | Creating multiple resources in a single request. |
| AIP-234: Batch Update | Updating multiple resources in a single request. |
| AIP-235: Batch Delete | Deleting multiple resources in a single request. |
| AIP-236: Policy Preview | Previewing the effect of policy changes before applying them. |
Compatibility & Versioning
| Reference | When to Use |
|---|---|
| AIP-180: Backwards Compatibility | Understanding what constitutes a breaking change; evolving APIs safely. |
| AIP-181: Stability Levels | Marking APIs as alpha, beta, or stable. |
| AIP-182: External Dependencies | Managing dependencies on external proto definitions. |
| AIP-185: Versioning | Structuring package names with version suffixes (v1, v2). |
Style & Documentation
| Reference | When to Use |
|---|---|
| AIP-190: Naming Conventions | Naming messages, enums, fields, and services consistently. |
| AIP-191: File Structure | Organizing proto files within a package. |
| AIP-192: Documentation | Writing comments and documentation in proto files. |
| AIP-193: Errors | Returning structured errors with google.rpc.Status. |
| AIP-194: Retry | Documenting retry behavior and idempotency. |
| AIP-200: Precedent | Understanding when to follow existing patterns vs. innovation. |
| AIP-202: Field Formats | Using format annotations for UUIDs, emails, URIs, etc. |
| AIP-205: Beta Blocking Changes | Managing breaking changes in beta APIs. |
| AIP-210: Unicode | Handling Unicode strings and normalization. |
| AIP-211: Authorization | Documenting authorization requirements. |
| AIP-213: Common Components | Using shared proto definitions across services. |
| AIP-214: Expiration | Modeling time-to-live or expiration for resources. |
| AIP-215: Isolation | Designing multi-tenant or isolated resource APIs. |
| AIP-216: States | Modeling resource lifecycle states. |
| AIP-217: Unreachable Resources | Handling references to resources that may not exist. |
Buf References
Use these references when configuring Buf for linting, breaking change detection, and code generation.
| Reference | When to Use |
|---|---|
| Protobuf Management with Buf | Setting up Buf for a new project; understanding buf.yaml and core commands. |
| Linting | Configuring lint rules; resolving conflicts between Buf linter and AIP standards. |
| Breaking Change Detection | Running buf breaking to prevent backwards-incompatible changes. |
| Directory Structure | Organizing proto files and packages for Buf modules. |
| Code Generation | Configuring buf.gen.yaml for Go, gRPC-Gateway, and OpenAPI code generation. |
How to Use
- Read the Rules: Before starting a new feature or refactor, browse the relevant rule files.
- Follow the Examples: Use the provided "Correct" code patterns as templates.
- Ensure Consistency: Apply the same patterns across all proto files.
Each rule file contains:
- Brief explanation of the rule
- "Incorrect" examples (Bad patterns)
- "Correct" examples (Recommended patterns)
- Additional context and references