interface:
  display_name: "Use Protobuf"
  short_description: "Design robust gRPC and HTTP Protobuf schemas"
  default_prompt: "Use $use-protobuf to design or review this Protobuf API contract."

# API and Protobuf Design Sources

Use these as selected references, not as mutually mandatory specifications. Preserve the repository's established API style unless the user requests a migration.

- [Protocol Buffers style guide](https://protobuf.dev/programming-guides/style/): file layout, identifier casing, enum zero values, services, and naming hazards.
- [Proto3 language guide](https://protobuf.dev/programming-guides/proto3/): field numbers, presence, `oneof`, imports, `Any`, JSON mapping, and compatible evolution.
- [gRPC core concepts](https://grpc.io/docs/what-is-grpc/core-concepts/): unary, client-streaming, server-streaming, bidirectional-streaming, cancellation, deadlines, and metadata.
- [JSON:API error objects](https://jsonapi.org/format/#errors): structured HTTP error identity, status, code, title, detail, source, links, and metadata.
- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines): public REST consistency, resources, methods, errors, versioning, pagination, and long-running operations.
- [Kratos Protobuf guideline](https://go-kratos.dev/docs/guide/api-protobuf/): API directory/version organization, HTTP annotations, and generated service conventions.
- [Boston Dynamics API Protobuf guidelines](https://dev.bostondynamics.com/docs/protos/style_guide.html): production schema conventions, services, errors, timestamps, units, and compatibility.
- [VictoriaMetrics Practical Protobuf](https://victoriametrics.com/blog/go-protobuf-basic/): practical Go/Protobuf encoding and generated-code considerations; cross-check advice against official Protobuf compatibility rules.
- [Go generated code guide](https://protobuf.dev/reference/go/go-generated/): `go_package`, generated package mapping, and Go API generation.
- [Python generated code guide](https://protobuf.dev/reference/python/python-generated/): Python module generation and runtime behavior.

When sources disagree, prioritize wire compatibility, explicit repository policy, official Protobuf/gRPC behavior, and the user's stated API lifecycle.

# grpc-gateway, Validation, and OpenAPI

## Classify the Transport

For gRPC-only services, omit all of the following:

- `google/api/annotations.proto` and `google.api.http`;
- `protoc-gen-openapiv2/options/annotations.proto`;
- grpc-gateway/OpenAPI service, operation, message, enum, and field options.

Keep ordinary Protobuf comments and runtime validation when required by the gRPC service itself, but do not make a gRPC-only contract depend on an HTTP documentation toolchain.

For an HTTP-exposed RPC, define the binding and document the operation:

```proto
rpc CreateWidget(CreateWidgetRequest) returns (CreateWidgetResponse) {
  option (google.api.http) = {
    post: "/v1/widgets"
    body: "*"
  };
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
    operation_id: "widgets_create"
    summary: "Create a widget."
    tags: "Widgets"
  };
}
```

## Validate Every HTTP Request

Apply Protovalidate to every accepted request field regardless of whether it comes from a path, query string, GET request, POST body, or other HTTP method. Validate strings, numbers, enums, collections, nested messages, cross-field constraints, and identifiers according to domain semantics.

```proto
message ListWidgetsRequest {
  string parent = 1 [
    (buf.validate.field).string = {
      min_len: 1
      max_len: 200
    },
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Parent collection identifier."
      example: "\"accounts/42\""
    }
  ];
  int32 page_size = 2 [
    (buf.validate.field).int32 = {
      gte: 0
      lte: 100
    },
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "Maximum number of widgets to return."
      example: "50"
      minimum: 0
      maximum: 100
    }
  ];
}
```

Treat validation as the executable acceptance rule. Mirror relevant range, pattern, length, format, example, description, and collection information into OpenAPI so generated clients and documentation do not contradict runtime behavior.

## Inspect Extension Definitions Without Cache Paths

Do not hardcode `~/.cache`, platform-specific cache roots, module digests, or commit directories. Inspect the dependency declared in `buf.yaml` and pinned in `buf.lock`, then use Buf:

```sh
buf dep graph --format json

inspection_dir="$(mktemp -d)"
buf export buf.build/grpc-ecosystem/grpc-gateway:<pinned-ref> \
  --path protoc-gen-openapiv2/options/annotations.proto \
  --path protoc-gen-openapiv2/options/openapiv2.proto \
  --output "$inspection_dir"

rg -n "message JSONSchema|openapiv2_field|example|description" "$inspection_dir"
```

Resolve `<pinned-ref>` from repository configuration/lock state. Remove the temporary directory after inspection. Consult `$use-buf` for dependency resolution and `$use-buf-plugins` for generator behavior.

The grpc-gateway OpenAPI documentation explains comment propagation, operation/schema/field options, visibility, merge behavior, enum rendering, and output configuration:

- https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/customizing_openapi_output/

## Public HTTP API Shape

Use a consistent resource and error model. When the application adopts JSON:API errors, model typed equivalents of useful members such as status, code, title, detail, source pointer/parameter/header, links, and meta rather than returning an unstructured object. Do not combine mutually incompatible envelope conventions without an explicit API-wide decision.

Use the Microsoft API Guidelines and JSON:API as design references for resource naming, HTTP semantics, pagination, idempotency, errors, and long-running operations. Adapt them to the existing API contract rather than importing conventions piecemeal.

# Protobuf Schema Design

## Contents

- RPC and message boundaries
- Streaming protocols
- Strong typing and presence
- Reuse without abstraction leakage
- Evolution and versioning
- Source and generated layout

## RPC and Message Boundaries

Give each operation its own request and response, named after the method:

```proto
service CatalogService {
  rpc CreateItem(CreateItemRequest) returns (CreateItemResponse);
  rpc GetItem(GetItemRequest) returns (GetItemResponse);
}
```

Do not use a generic `Request`, `Response`, `Payload`, or `Envelope` across unrelated methods. Dedicated messages allow validation, documentation, authorization, and evolution to diverge safely.

Model method inputs in the request even when the transport could carry them elsewhere. Model method results in the response instead of returning a domain entity directly; the response leaves room for metadata and future compatible fields.

## Streaming Protocols

Choose the cardinality from behavior:

- client streaming: large or incremental input such as JSON records, file chunks, or query batches;
- server streaming: progress, events, task steps, query results, or binary output;
- bidirectional streaming: interactive/duplex protocols where both sides advance independently.

MUST NOT define abstract or generic base stream events or payloads. For heterogeneous streams, use separate messages under `oneof`:

```proto
message WatchImportStreamResponse {
  oneof event {
    ImportStarted started = 1;
    ImportProgress progress = 2;
    ImportWarning warning = 3;
    ImportCompleted completed = 4;
  }
}

message ImportStarted {
  string import_id = 1;
}

message ImportProgress {
  int64 records_processed = 1;
  optional int64 records_total = 2;
}
```

Use the same structure for heterogeneous client streams. For example, define separate header, JSON record, file chunk, commit, and abort messages rather than a base packet with many nullable fields.

Use one homogeneous stream message only when every packet has exactly the same semantics. A fixed-shape file chunk can be:

```proto
message DownloadFileStreamResponse {
  bytes data = 1;
}
```

If the stream also carries headers, checksums, progress, or trailers, return to `oneof` with concrete variants.

Document ordering, which event may appear first/last, repetition, completion, cancellation, resumability, offsets, checksums, and whether an error arrives as gRPC status or an in-band event.

## Strong Typing and Presence

- Use enums for finite controlled vocabularies. Prefix top-level enum values with the enum name and give the zero value `_UNSPECIFIED` or `_UNKNOWN` semantics.
- Use `optional` when presence differs from the scalar default. Do not add presence when unset and default are semantically identical.
- Use `google.protobuf.Timestamp`, `Duration`, `FieldMask`, or other appropriate well-known types instead of strings with implicit formats.
- Include units in names or comments for numeric quantities, such as `timeout_seconds` or `size_bytes`.
- Use `bytes` for opaque binary content, not base64 text fields.
- Use maps only for truly dynamic keyed collections. Prefer repeated typed entries when keys or values need validation, ordering, metadata, or future evolution.
- Avoid `Struct` and `Any`. If an upstream opaque payload must be preserved, isolate it at that boundary, document its schema/version and validation, and provide typed projections for first-class fields.

For Go JSON conversion, use `google.golang.org/protobuf/encoding/protojson`. For `Any`, configure a resolver/type registry. Research and use the canonical Protobuf JSON/runtime API in every other language.

## Reuse Without Abstraction Leakage

Reuse a message when two fields mean the same contract and must evolve together. Import the canonical message instead of duplicating its fields and writing conversion code. Keep package dependency direction intentional and acyclic.

Do not reuse merely because two messages currently have the same shape. Separate them when their ownership, validation, authorization, lifecycle, or future evolution differs. Never introduce a generic base request/response/event solely to reduce line count.

## Evolution and Versioning

Before a feature is released, while explicitly experimental or feature-flagged, a coordinated breaking redesign may change structure or field numbers. Rebuild all generated SDKs, services, clients, fixtures, queues, and stored payloads together, and still run breaking-change detection so the break is visible.

After release:

- never change or reuse a field number;
- reserve deleted numbers and names;
- add fields compatibly whenever possible;
- avoid moving fields into or out of an existing `oneof` without studying wire behavior;
- introduce `v2` for incompatible changes;
- use `v1alpha1`/`v1beta1` to signal unstable contracts when appropriate.

Put the version in both directory and package identity, for example `example/catalog/v1` and `example.catalog.v1`. Keep imports explicit and avoid confusing relative resolution across packages.

## Source and Generated Layout

- Name source files `lower_snake_case.proto`.
- Sort imports and set language file options such as `go_package` where required by the project's generation model.
- Keep source directories language-neutral.
- Preserve the schema's path in generated Go, Python, TypeScript, and other targets unless the language plugin's established convention adds a conventional leaf directory.
- Verify Python with runtime and typing plugins instead of reorganizing the schema tree preemptively.
- Never edit generated files by hand.