0
# Validation Rules Schema
1

2
The validation rules schema defines comprehensive validation constraints for all protocol buffer field types through protocol buffer extensions. These rules are applied as field options in proto files and processed by the plugin to generate validation code.
3

4
## Protocol Buffer Extensions
5

6
### Message-Level Extensions
7

8
```protobuf { .api }
9
extend google.protobuf.MessageOptions {
10
  optional bool disabled = 1071;
11
  optional bool ignored = 1072;
12
}
13
```
14

15
**disabled**: Nullifies all validation rules for the message and its fields
16
**ignored**: Skips generation of validation methods entirely for the message
17

18
Usage:
19
```protobuf
20
message Example {
21
  option (validate.disabled) = true;
22
  // validation rules are ignored
23
}
24
```
25

26
### Oneof Extensions
27

28
```protobuf { .api }
29
extend google.protobuf.OneofOptions {
30
  optional bool required = 1071;
31
}
32
```
33

34
**required**: Ensures exactly one field in the oneof is set
35

36
Usage:
37
```protobuf
38
oneof choice {
39
  option (validate.required) = true;
40
  string option_a = 1;
41
  int32 option_b = 2;
42
}
43
```
44

45
### Field Extensions
46

47
```protobuf { .api }
48
extend google.protobuf.FieldOptions {
49
  optional FieldRules rules = 1071;
50
}
51
```
52

53
**rules**: Main validation rules container for field-level constraints
54

55
## Core Rule Types
56

57
### Field Rules Container
58

59
```protobuf { .api }
60
message FieldRules {
61
  optional MessageRules message = 17;
62
  oneof type {
63
    FloatRules    float    = 1;
64
    DoubleRules   double   = 2;
65
    Int32Rules    int32    = 3;
66
    Int64Rules    int64    = 4;
67
    UInt32Rules   uint32   = 5;
68
    UInt64Rules   uint64   = 6;
69
    SInt32Rules   sint32   = 7;
70
    SInt64Rules   sint64   = 8;
71
    Fixed32Rules  fixed32  = 9;
72
    Fixed64Rules  fixed64  = 10;
73
    SFixed32Rules sfixed32 = 11;
74
    SFixed64Rules sfixed64 = 12;
75
    BoolRules     bool     = 13;
76
    StringRules   string   = 14;
77
    BytesRules    bytes    = 15;
78
    EnumRules     enum     = 16;
79
    RepeatedRules repeated = 18;
80
    MapRules      map      = 19;
81
    AnyRules      any      = 20;
82
    DurationRules duration = 21;
83
    TimestampRules timestamp = 22;
84
  }
85
}
86
```
87

88
Main container for all validation rules. Contains message-level rules and a oneof for type-specific rules.
89

90
## Numeric Validation Rules
91

92
All numeric types share the same rule structure for consistency:
93

94
```protobuf { .api }
95
message FloatRules {
96
  optional float const = 1;
97
  optional float lt = 2;
98
  optional float lte = 3;
99
  optional float gt = 4;
100
  optional float gte = 5;
101
  repeated float in = 6;
102
  repeated float not_in = 7;
103
  optional bool ignore_empty = 8;
104
}
105
```
106

107
**const**: Field must equal exact value
108
**lt**: Field must be less than value (exclusive)
109
**lte**: Field must be less than or equal to value (inclusive)
110
**gt**: Field must be greater than value (exclusive)
111
**gte**: Field must be greater than or equal to value (inclusive)
112
**in**: Field must be one of the specified values
113
**not_in**: Field cannot be any of the specified values
114
**ignore_empty**: Skip validation if field is empty/default
115

116
Usage examples:
117
```protobuf
118
float price = 1 [(validate.rules).float = {gt: 0, lte: 1000}];
119
int32 count = 2 [(validate.rules).int32 = {in: [1, 5, 10, 25]}];
120
uint64 id = 3 [(validate.rules).uint64 = {ignore_empty: true, gt: 999}];
121
```
122

123
## String Validation Rules
124

125
```protobuf { .api }
126
message StringRules {
127
  optional string const = 1;
128
  optional uint64 len = 19;
129
  optional uint64 min_len = 2;
130
  optional uint64 max_len = 3;
131
  optional uint64 min_bytes = 4;
132
  optional uint64 max_bytes = 5;
133
  optional string pattern = 6;
134
  optional string prefix = 7;
135
  optional string suffix = 8;
136
  optional string contains = 9;
137
  optional string not_contains = 23;
138
  repeated string in = 10;
139
  repeated string not_in = 11;
140
  optional bool email = 12;
141
  optional bool hostname = 13;
142
  optional bool ip = 14;
143
  optional bool ipv4 = 15;
144
  optional bool ipv6 = 16;
145
  optional bool uri = 17;
146
  optional bool uri_ref = 18;
147
  optional bool address = 21;
148
  optional bool uuid = 22;
149
  optional KnownRegex well_known_regex = 24;
150
  optional bool strict = 25;
151
  optional bool ignore_empty = 26;
152
}
153
```
154

155
**const**: Exact string match
156
**len**: Exact character length (Unicode code points)
157
**min_len/max_len**: Minimum/maximum character length
158
**min_bytes/max_bytes**: Minimum/maximum byte length
159
**pattern**: RE2-compliant regular expression match
160
**prefix/suffix**: Required prefix/suffix
161
**contains/not_contains**: Required/forbidden substring
162
**in/not_in**: Allowed/disallowed string values
163
**email**: RFC 5322 email format validation
164
**hostname**: RFC 1034 hostname format validation
165
**ip**: IP address format (v4 or v6)
166
**ipv4/ipv6**: Specific IP version format
167
**uri**: RFC 3986 absolute URI format
168
**uri_ref**: URI reference format (absolute or relative)
169
**address**: Valid address (IP or hostname)
170
**uuid**: RFC 4122 UUID format
171
**well_known_regex**: Predefined regex patterns
172
**strict**: Strict format validation mode
173
**ignore_empty**: Skip validation if empty
174

175
Usage examples:
176
```protobuf
177
string email = 1 [(validate.rules).string.email = true];
178
string name = 2 [(validate.rules).string = {min_len: 1, max_len: 100}];
179
string token = 3 [(validate.rules).string.uuid = true];
180
```
181

182
## Bytes Validation Rules
183

184
```protobuf { .api }
185
message BytesRules {
186
  optional bytes const = 1;
187
  optional uint64 len = 13;
188
  optional uint64 min_len = 2;
189
  optional uint64 max_len = 3;
190
  optional string pattern = 4;
191
  optional bytes prefix = 5;
192
  optional bytes suffix = 6;
193
  optional bytes contains = 7;
194
  repeated bytes in = 8;
195
  repeated bytes not_in = 9;
196
  optional bool ip = 10;
197
  optional bool ipv4 = 11;
198
  optional bool ipv6 = 12;
199
  optional bool ignore_empty = 14;
200
}
201
```
202

203
Similar to StringRules but for byte sequences:
204
**const**: Exact byte sequence match
205
**len**: Exact byte length
206
**min_len/max_len**: Minimum/maximum byte length
207
**pattern**: RE2 regex pattern for byte content
208
**prefix/suffix/contains**: Required byte subsequences
209
**in/not_in**: Allowed/disallowed byte values
210
**ip/ipv4/ipv6**: IP address in byte format
211
**ignore_empty**: Skip validation if empty
212

213
## Boolean Validation Rules
214

215
```protobuf { .api }
216
message BoolRules {
217
  optional bool const = 1;
218
}
219
```
220

221
**const**: Exact boolean value required
222

223
## Enum Validation Rules
224

225
```protobuf { .api }
226
message EnumRules {
227
  optional int32 const = 1;
228
  optional bool defined_only = 2;
229
  repeated int32 in = 3;
230
  repeated int32 not_in = 4;
231
}
232
```
233

234
**const**: Exact enum value (numeric)
235
**defined_only**: Must be a defined enum value
236
**in/not_in**: Allowed/disallowed enum values
237

238
## Message Validation Rules
239

240
```protobuf { .api }
241
message MessageRules {
242
  optional bool skip = 1;
243
  optional bool required = 2;
244
}
245
```
246

247
**skip**: Skip validation of message fields
248
**required**: Message field must be set (not null)
249

250
## Repeated Field Validation Rules
251

252
```protobuf { .api }
253
message RepeatedRules {
254
  optional uint64 min_items = 1;
255
  optional uint64 max_items = 2;
256
  optional bool unique = 3;
257
  optional FieldRules items = 4;
258
  optional bool ignore_empty = 5;
259
}
260
```
261

262
**min_items/max_items**: Minimum/maximum number of items
263
**unique**: All items must be unique (not supported for messages)
264
**items**: Validation rules applied to each item
265
**ignore_empty**: Skip validation if empty
266

267
## Map Validation Rules
268

269
```protobuf { .api }
270
message MapRules {
271
  optional uint64 min_pairs = 1;
272
  optional uint64 max_pairs = 2;
273
  optional bool no_sparse = 3;
274
  optional FieldRules keys = 4;
275
  optional FieldRules values = 5;
276
  optional bool ignore_empty = 6;
277
}
278
```
279

280
**min_pairs/max_pairs**: Minimum/maximum key-value pairs
281
**no_sparse**: Disallow unset message values
282
**keys**: Validation rules for map keys
283
**values**: Validation rules for map values
284
**ignore_empty**: Skip validation if empty
285

286
## Well-Known Types Rules
287

288
### Any Rules
289

290
```protobuf { .api }
291
message AnyRules {
292
  optional bool required = 1;
293
  repeated string in = 2;
294
  repeated string not_in = 3;
295
}
296
```
297

298
**required**: Any field must be set
299
**in/not_in**: Allowed/disallowed type URLs
300

301
### Duration Rules
302

303
```protobuf { .api }
304
message DurationRules {
305
  optional bool required = 1;
306
  optional google.protobuf.Duration const = 2;
307
  optional google.protobuf.Duration lt = 3;
308
  optional google.protobuf.Duration lte = 4;
309
  optional google.protobuf.Duration gt = 5;
310
  optional google.protobuf.Duration gte = 6;
311
  repeated google.protobuf.Duration in = 7;
312
  repeated google.protobuf.Duration not_in = 8;
313
}
314
```
315

316
**required**: Duration field must be set
317
**const**: Exact duration value
318
**lt/lte/gt/gte**: Duration comparison constraints
319
**in/not_in**: Allowed/disallowed duration values
320

321
### Timestamp Rules
322

323
```protobuf { .api }
324
message TimestampRules {
325
  optional bool required = 1;
326
  optional google.protobuf.Timestamp const = 2;
327
  optional google.protobuf.Timestamp lt = 3;
328
  optional google.protobuf.Timestamp lte = 4;
329
  optional google.protobuf.Timestamp gt = 5;
330
  optional google.protobuf.Timestamp gte = 6;
331
  optional bool lt_now = 7;
332
  optional bool gt_now = 8;
333
  optional google.protobuf.Duration within = 9;
334
  repeated google.protobuf.Timestamp in = 10;
335
  repeated google.protobuf.Timestamp not_in = 11;
336
}
337
```
338

339
**required**: Timestamp field must be set
340
**const**: Exact timestamp value
341
**lt/lte/gt/gte**: Timestamp comparison constraints
342
**lt_now/gt_now**: Comparison relative to current time
343
**within**: Must be within duration of current time
344
**in/not_in**: Allowed/disallowed timestamp values
345

346
## Known Regex Patterns
347

348
```protobuf { .api }
349
enum KnownRegex {
350
  UNKNOWN = 0;
351
  HTTP_HEADER_NAME = 1;
352
  HTTP_HEADER_VALUE = 2;
353
}
354
```
355

356
Predefined regex patterns for common validation needs:
357
**HTTP_HEADER_NAME**: RFC 7230 HTTP header name format (`^:?[0-9a-zA-Z!#$%&'*+-.^_|~\x60]+$`)  
358
**HTTP_HEADER_VALUE**: RFC 7230 HTTP header value format (`^[^\u0000-\u0008\u000A-\u001F\u007F]*$`)
359
**HEADER_STRING**: Non-strict header validation (`^[^\u0000\u000A\u000D]*$`)