Configuration Reference

proto2pydantic accepts options via buf.gen.yaml (under opt:) or as protoc flags.

Options

preset

Preset configurations for common use cases.

Value	Effect
a2a	Sets alias_generator=camel + enum_style=raw for ProtoJSON compliance per ADR-001

Individual options below can override preset defaults when specified explicitly.

base_class

Override the Pydantic base class for all generated models.

Default	BaseModel (from pydantic)
Example	a2a._base.A2ABaseModel
Format	Dotted Python import path: module.path.ClassName

When set to a non-default value:

• The base class is imported from the specified module
• Per-model model_config is NOT emitted — the base class is expected to provide its own ConfigDict (alias generator, populate_by_name, etc.)
• to_proto_json() is NOT emitted — the base class may provide its own serialization
• ConfigDict and to_camel are NOT imported — not needed when base handles config

alias_generator

Controls field alias generation for camelCase JSON keys.

Value	Effect
(empty)	No alias generation (default)
camel	Adds model_config = ConfigDict(populate_by_name=True, alias_generator=to_camel) and a to_proto_json() method on every model

Note: When base_class is set, alias config and to_proto_json() are skipped (see above).

enum_style

Controls how proto enum values are named in Python.

Value	Effect	Example
(empty)	Strip prefix, lowercase, skip UNSPECIFIED (default)	TASK_STATE_SUBMITTED → submitted
raw	Preserve original proto names, include UNSPECIFIED	TASK_STATE_SUBMITTED → TASK_STATE_SUBMITTED

output_file

Override the output filename.

Default	{proto_name}_pb2_pydantic.py
Example	types.py

strip_proto_suffix

Use a shorter output filename without _pb2_pydantic suffix.

Default	false
When true	a2a.proto → a2a.py (instead of a2a_pb2_pydantic.py)

description

Override the module-level docstring in the generated file.

Default	"Generated by proto2pydantic from {file}. DO NOT EDIT."
Example	A2A type definitions generated from a2a.proto

Default Behaviors (always active)

These features are always generated regardless of options:

Feature	Description
@field_serializer for Timestamp	Serializes datetime → RFC 3339 string with UTC Z suffix
@field_serializer for bytes	Serializes bytes → base64-encoded string
google.api.field_behavior	REQUIRED → Field(...), OUTPUT_ONLY → Field(exclude=True)
buf/validate constraints	Mapped to Pydantic Field() params: min_length, max_length, gt, ge, etc.
Topological sort	Models ordered so dependencies are defined before dependents
__all__ exports	All enums and models listed in __all__

Example: A2A with custom base class

# buf.gen.yaml
plugins:
  - local: protoc-gen-proto2pydantic
    out: src/a2a
    opt:
      - preset=a2a
      - base_class=a2a._base.A2ABaseModel
      - output_file=types.py
      - description=A2A type definitions generated from a2a.proto

This generates clean models that inherit config from A2ABaseModel:

from a2a._base import A2ABaseModel
from pydantic import Field

class Task(A2ABaseModel):
    """The core unit of action for A2A."""

    id: str = Field(..., description='Unique identifier')
    status: TaskStatus = Field(..., description='Current status')
    ...

No redundant model_config, no duplicate to_camel, no ConfigDict import.