How bufbuild/protoc-gen-validate works
PGV is a protoc plugin that turns validation rules attached to protobuf fields into language-specific validators. The main workflow is proto constraints → plugin and rule checking → language templates → generated validation code. Java also provides a validator runtime and optional gRPC interceptors; Python instead generates and caches validation functions at runtime. The graph reflects documented capabilities, but several template and runtime implementations were not sampled, so their internal connections are limited to relationships shown in the README or source index.
Main entry points: pkg.go Template selection · ValidatorIndex.java Validator index · validate.go Validation module · ValidatingClientInterceptor.java gRPC client interceptor
Components 23
Rules and checking
- Validation schema
validate/validate.proto - Rule checker
module/checker.go
Code generation
- Plugin entry points
cmd/protoc-gen-validate-go/main.go - Default entry point
main.go - Validation module
module/validate.go - Rule context
templates/shared/context.go - Template selection
templates/pkg.go - Go templates
templates/goshared/register.go - C++ templates
templates/cc/register.go - Java templates
templates/java/register.go
Validation runtimes
- Python validation API
python/protoc_gen_validate/__init__.py - JIT validator
python/protoc_gen_validate/validator.py - Validator index
java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidatorIndex.java - Reflective index
java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ReflectiveValidatorIndex.java - Java rule helpers
java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/StringValidation.java - Validation errors
java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/ValidationException.java
Protocol integrations
- gRPC client interceptor
java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java - gRPC server interceptor
java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingServerInterceptor.java - gRPC error mapping
java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidationExceptions.java
Other components
- protoc
- Generated validators
- Proto developer
- Java gRPC app
Connections 28
- Proto developer → Validation schema: annotates messages
- protoc → Plugin entry points: invokes plugin
- Plugin entry points → Validation module: registers language module
cmd/protoc-gen-validate-go/main.go - protoc → Default entry point: invokes plugin
- Default entry point → Validation module: registers module
main.go - Validation module → Rule checker: checks rules
module/checker.go - Rule checker → Validation schema: reads constraints
module/checker.go - Validation module → Template selection: selects templates
module/validate.go - Template selection → Rule context: registers shared functions
templates/pkg.go - Rule context → Validation schema: resolves rule types
templates/shared/context.go - Template selection → Go templates: selects Go templates
templates/pkg.go - Template selection → C++ templates: selects C++ templates
templates/pkg.go - Template selection → Java templates: selects Java templates
templates/pkg.go - Go templates → Generated validators: renders validators
- C++ templates → Generated validators: renders validators
- Java templates → Generated validators: renders validators
- Proto developer → Python validation API: calls validate
- Python validation API → JIT validator: generates on demand
- Reflective index → Validator index: implements lookup
java/pgv-java-validation/src/main/java/io/envoyproxy/pgv/validation/JavaHarness.java - Java gRPC app → Validator index: requests validator
- gRPC client interceptor → Validator index: looks up validator
java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java - gRPC server interceptor → Validator index: looks up validator
java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingServerInterceptor.java - Validator index → Java rule helpers: runs validation
- Java rule helpers → Validation errors: reports failures
java/pgv-java-stub/src/main/java/io/envoyproxy/pgv/StringValidation.java - gRPC client interceptor → gRPC error mapping: maps failures
java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingClientInterceptor.java - gRPC server interceptor → gRPC error mapping: maps failures
java/pgv-java-grpc/src/main/java/io/envoyproxy/pgv/grpc/ValidatingServerInterceptor.java - Java gRPC app → gRPC client interceptor: installs interceptor
- Java gRPC app → gRPC server interceptor: installs interceptor