0
# protoc-gen-validate
1

2
protoc-gen-validate (PGV) is a protoc plugin that generates polyglot message validators for protocol buffer messages. It enables semantic validation rules for protocol buffer fields that cannot be expressed through basic type constraints alone, supporting Go, Java, C++, and Python with generated validation methods.
3

4
## Package Information
5

6
- **Package Name**: protoc-gen-validate
7
- **Package Type**: Go tool/protoc plugin
8
- **Language**: Go
9
- **Installation**: Download from [GitHub Releases](https://github.com/bufbuild/protoc-gen-validate/releases) or build from source
10

11
## Core Imports
12

13
For validation rules in proto files:
14

15
```protobuf
16
import "validate/validate.proto";
17
```
18

19
For Python runtime validation:
20

21
```python
22
from protoc_gen_validate.validator import validate, ValidationFailed
23
```
24

25
## Basic Usage
26

27
### Define validation rules in proto files:
28

29
```protobuf
30
syntax = "proto3";
31
package example;
32
import "validate/validate.proto";
33

34
message User {
35
  uint64 id = 1 [(validate.rules).uint64.gt = 999];
36
  string email = 2 [(validate.rules).string.email = true];
37
  string name = 3 [(validate.rules).string = {
38
    pattern: "^[A-Za-z]+( [A-Za-z]+)*$",
39
    max_bytes: 256,
40
  }];
41
}
42
```
43

44
### Generate validation code:
45

46
```bash
47
protoc \
48
  -I . \
49
  -I path/to/validate/ \
50
  --go_out="./generated" \
51
  --validate_out="lang=go:./generated" \
52
  user.proto
53
```
54

55
### Use generated validators:
56

57
```go
58
user := &User{
59
  Id:    1000,
60
  Email: "user@example.com", 
61
  Name:  "John Doe",
62
}
63

64
if err := user.Validate(); err != nil {
65
  // Handle validation error
66
}
67
```
68

69
## Architecture
70

71
PGV uses a plugin architecture built on the protoc-gen-star framework:
72

73
- **Core Plugin**: Main protoc plugin entry point that processes proto files
74
- **Module System**: Extensible module for different target languages
75
- **Template Engine**: Language-specific code generation templates
76
- **Validation Schema**: Comprehensive protocol buffer extension definitions
77
- **Runtime Libraries**: Language-specific validation utilities
78

79
## Capabilities
80

81
### Core Plugin System
82

83
Provides the main protoc plugin functionality for code generation.
84

85
```go { .api }
86
// Main entry point for protoc plugin
87
func main()
88

89
// Core module interface
90
type Module struct {
91
  *pgs.ModuleBase
92
  ctx pgsgo.Context
93
  lang string
94
}
95

96
func Validator() pgs.Module
97
func ValidatorForLanguage(lang string) pgs.Module
98
```
99

100
[Core Plugin System](./core-plugin.md)
101

102
### Validation Rules Schema
103

104
Defines comprehensive validation rules for all protocol buffer field types.
105

106
```protobuf { .api }
107
// Main field rules container
108
message FieldRules {
109
  optional MessageRules message = 17;
110
  oneof type {
111
    FloatRules    float    = 1;
112
    DoubleRules   double   = 2;
113
    Int32Rules    int32    = 3;
114
    // ... all numeric types
115
    StringRules   string   = 14;
116
    BytesRules    bytes    = 15;
117
    EnumRules     enum     = 16;
118
    RepeatedRules repeated = 18;
119
    MapRules      map      = 19;
120
    AnyRules      any      = 20;
121
    DurationRules duration = 21;
122
    TimestampRules timestamp = 22;
123
  }
124
}
125

126
// Protocol buffer extensions
127
extend google.protobuf.FieldOptions {
128
  optional FieldRules rules = 1071;
129
}
130
```
131

132
[Validation Rules Schema](./validation-rules.md)
133

134
### Code Generation Templates
135

136
Template system for generating validation code in multiple languages.
137

138
```go { .api }
139
type RegisterFn func(tpl *template.Template, params pgs.Parameters)
140
type FilePathFn func(f pgs.File, ctx pgsgo.Context, tpl *template.Template) *pgs.FilePath
141

142
func Template(params pgs.Parameters) map[string][]*template.Template
143
func FilePathFor(tpl *template.Template) FilePathFn
144
```
145

146
[Code Generation Templates](./code-generation.md)
147

148
### Generated Code API
149

150
APIs provided by generated validation code in each target language.
151

152
```go { .api }
153
// Go generated methods
154
func (m *Message) Validate() error
155
func (m *Message) ValidateAll() error
156
```
157

158
```java { .api }
159
// Java validation interface
160
class ReflectiveValidatorIndex {
161
  Validator validatorFor(Class<?> clazz)
162
}
163
```
164

165
```python { .api }
166
# Python runtime validation
167
def validate(msg) -> None  # raises ValidationFailed
168
def print_validate(msg) -> None
169
```
170

171
[Generated Code API](./generated-code.md)
172

173
### Runtime Libraries
174

175
Language-specific runtime libraries and utilities for validation.
176

177
```python { .api }
178
class ValidationFailed(Exception):
179
  """Raised when message validation fails"""
180
  pass
181
```
182

183
[Runtime Libraries](./runtime-libraries.md)
184

185
## Supported Languages
186

187
- **Go**: Full support with `Validate()` and `ValidateAll()` methods
188
- **Java**: Full support with ReflectiveValidatorIndex and gRPC interceptors  
189
- **C++**: Header and implementation file generation
190
- **Python**: JIT runtime validation with caching
191

192
## Types
193

194
```go { .api }
195
// Module represents the core PGV module
196
type Module struct {
197
  *pgs.ModuleBase
198
  ctx pgsgo.Context
199
  lang string
200
}
201

202
// Template registration function
203
type RegisterFn func(tpl *template.Template, params pgs.Parameters)
204

205
// File path generation function  
206
type FilePathFn func(f pgs.File, ctx pgsgo.Context, tpl *template.Template) *pgs.FilePath
207
```
208

209
```protobuf { .api }
210
// Core validation rule types
211
message FieldRules { /* see validation rules schema */ }
212
message StringRules { /* string validation rules */ }
213
message MessageRules { /* message validation rules */ }
214
message RepeatedRules { /* repeated field validation rules */ }
215
message MapRules { /* map field validation rules */ }
216
```
217

218
```python { .api }
219
class ValidationFailed(Exception):
220
  """Exception raised when validation fails"""
221
  pass
222
```