Documentation Index
Fetch the complete documentation index at: https://docs.thru.org/llms.txt
Use this file to discover all available pages before exploring further.
Messages
AnyRules
| Field | Type | Description |
|---|---|---|
in | repeated ``string | in requires the field’s type_url to be equal to one of the specified values. If it doesn’t match any of the specified values, an error message is generated. proto message MyAny { // The `value` field must have a `type_url` equal to one of the specified values. google.protobuf.Any value = 1 [(buf.validate.field).any = { in: ["type.googleapis.com/MyType1", "type.googleapis.com/MyType2"] }]; } |
not_in | repeated ``string | requires the field’s type_url to be not equal to any of the specified values. If it matches any of the specified values, an error message is generated. proto message MyAny { // The `value` field must not have a `type_url` equal to any of the specified values. google.protobuf.Any value = 1 [(buf.validate.field).any = { not_in: ["type.googleapis.com/ForbiddenType1", "type.googleapis.com/ForbiddenType2"] }]; } |
BoolRules
| Field | Type | Description |
|---|---|---|
const | optional ``bool | const requires the field value to exactly match the specified boolean value. If the field value doesn’t match, an error message is generated. proto message MyBool { // value must equal true bool value = 1 [(buf.validate.field).bool.const = true]; } |
example | repeated ``bool | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyBool { bool value = 1 [ (buf.validate.field).bool.example = 1, (buf.validate.field).bool.example = 2 ]; } |
BytesRules
| Field | Type | Description |
|---|---|---|
const | optional ``bytes | const requires the field value to exactly match the specified bytes value. If the field value doesn’t match, an error message is generated. proto message MyBytes { // value must be "\x01\x02\x03\x04" bytes value = 1 [(buf.validate.field).bytes.const = "\x01\x02\x03\x04"]; } |
len | optional ``uint64 | len requires the field value to have the specified length in bytes. If the field value doesn’t match, an error message is generated. proto message MyBytes { // value length must be 4 bytes. optional bytes value = 1 [(buf.validate.field).bytes.len = 4]; } |
min_len | optional ``uint64 | min_len requires the field value to have at least the specified minimum length in bytes. If the field value doesn’t meet the requirement, an error message is generated. proto message MyBytes { // value length must be at least 2 bytes. optional bytes value = 1 [(buf.validate.field).bytes.min_len = 2]; } |
max_len | optional ``uint64 | max_len requires the field value to have at most the specified maximum length in bytes. If the field value exceeds the requirement, an error message is generated. proto message MyBytes { // value must be at most 6 bytes. optional bytes value = 1 [(buf.validate.field).bytes.max_len = 6]; } |
pattern | optional ``string | pattern requires the field value to match the specified regular expression (RE2 syntax). The value of the field must be valid UTF-8 or validation will fail with a runtime error. If the field value doesn’t match the pattern, an error message is generated. proto message MyBytes { // value must match regex pattern "^[a-zA-Z0-9]+$". optional bytes value = 1 [(buf.validate.field).bytes.pattern = "^[a-zA-Z0-9]+$"]; } |
prefix | optional ``bytes | prefix requires the field value to have the specified bytes at the beginning of the string. If the field value doesn’t meet the requirement, an error message is generated. proto message MyBytes { // value does not have prefix \x01\x02 optional bytes value = 1 [(buf.validate.field).bytes.prefix = "\x01\x02"]; } |
suffix | optional ``bytes | suffix requires the field value to have the specified bytes at the end of the string. If the field value doesn’t meet the requirement, an error message is generated. proto message MyBytes { // value does not have suffix \x03\x04 optional bytes value = 1 [(buf.validate.field).bytes.suffix = "\x03\x04"]; } |
contains | optional ``bytes | contains requires the field value to have the specified bytes anywhere in the string. If the field value doesn’t meet the requirement, an error message is generated. protobuf message MyBytes { // value does not contain \x02\x03 optional bytes value = 1 [(buf.validate.field).bytes.contains = "\x02\x03"]; } |
in | repeated ``bytes | in requires the field value to be equal to one of the specified values. If the field value doesn’t match any of the specified values, an error message is generated. protobuf message MyBytes { // value must in ["\x01\x02", "\x02\x03", "\x03\x04"] optional bytes value = 1 [(buf.validate.field).bytes.in = {"\x01\x02", "\x02\x03", "\x03\x04"}]; } |
not_in | repeated ``bytes | not_in requires the field value to be not equal to any of the specified values. If the field value matches any of the specified values, an error message is generated. proto message MyBytes { // value must not in ["\x01\x02", "\x02\x03", "\x03\x04"] optional bytes value = 1 [(buf.validate.field).bytes.not_in = {"\x01\x02", "\x02\x03", "\x03\x04"}]; } |
ip | optional ``bool | ip ensures that the field value is a valid IP address (v4 or v6) in byte format. If the field value doesn’t meet this rule, an error message is generated. proto message MyBytes { // value must be a valid IP address optional bytes value = 1 [(buf.validate.field).bytes.ip = true]; } |
ipv4 | optional ``bool | ipv4 ensures that the field value is a valid IPv4 address in byte format. If the field value doesn’t meet this rule, an error message is generated. proto message MyBytes { // value must be a valid IPv4 address optional bytes value = 1 [(buf.validate.field).bytes.ipv4 = true]; } |
ipv6 | optional ``bool | ipv6 ensures that the field value is a valid IPv6 address in byte format. If the field value doesn’t meet this rule, an error message is generated. proto message MyBytes { // value must be a valid IPv6 address optional bytes value = 1 [(buf.validate.field).bytes.ipv6 = true]; } |
example | repeated ``bytes | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyBytes { bytes value = 1 [ (buf.validate.field).bytes.example = "\x01\x02", (buf.validate.field).bytes.example = "\x02\x03" ]; } |
DoubleRules
| Field | Type | Description |
|---|---|---|
const | optional ``double | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MyDouble { // value must equal 42.0 double value = 1 [(buf.validate.field).double.const = 42.0]; } |
lt | optional ``double | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MyDouble { // value must be less than 10.0 double value = 1 [(buf.validate.field).double.lt = 10.0]; } |
lte | optional ``double | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MyDouble { // value must be less than or equal to 10.0 double value = 1 [(buf.validate.field).double.lte = 10.0]; } |
gt | optional ``double | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyDouble { // value must be greater than 5.0 [double.gt] double value = 1 [(buf.validate.field).double.gt = 5.0]; // value must be greater than 5 and less than 10.0 [double.gt_lt] double other_value = 2 [(buf.validate.field).double = { gt: 5.0, lt: 10.0 }]; // value must be greater than 10 or less than 5.0 [double.gt_lt_exclusive] double another_value = 3 [(buf.validate.field).double = { gt: 10.0, lt: 5.0 }]; } |
gte | optional ``double | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyDouble { // value must be greater than or equal to 5.0 [double.gte] double value = 1 [(buf.validate.field).double.gte = 5.0]; // value must be greater than or equal to 5.0 and less than 10.0 [double.gte_lt] double other_value = 2 [(buf.validate.field).double = { gte: 5.0, lt: 10.0 }]; // value must be greater than or equal to 10.0 or less than 5.0 [double.gte_lt_exclusive] double another_value = 3 [(buf.validate.field).double = { gte: 10.0, lt: 5.0 }]; } |
in | repeated ``double | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MyDouble { // value must be in list [1.0, 2.0, 3.0] double value = 1 [(buf.validate.field).double = { in: [1.0, 2.0, 3.0] }]; } |
not_in | repeated ``double | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MyDouble { // value must not be in list [1.0, 2.0, 3.0] double value = 1 [(buf.validate.field).double = { not_in: [1.0, 2.0, 3.0] }]; } |
finite | optional ``bool | finite requires the field value to be finite. If the field value is infinite or NaN, an error message is generated. |
example | repeated ``double | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyDouble { double value = 1 [ (buf.validate.field).double.example = 1.0, (buf.validate.field).double.example = inf ]; } |
DurationRules
| Field | Type | Description |
|---|---|---|
const | optional ``google.protobuf.Duration | const dictates that the field must match the specified value of the google.protobuf.Duration type exactly. If the field’s value deviates from the specified value, an error message will be generated. proto message MyDuration { // value must equal 5s google.protobuf.Duration value = 1 [(buf.validate.field).duration.const = "5s"]; } |
lt | optional ``google.protobuf.Duration | lt stipulates that the field must be less than the specified value of the google.protobuf.Duration type, exclusive. If the field’s value is greater than or equal to the specified value, an error message will be generated. proto message MyDuration { // value must be less than 5s google.protobuf.Duration value = 1 [(buf.validate.field).duration.lt = "5s"]; } |
lte | optional ``google.protobuf.Duration | lte indicates that the field must be less than or equal to the specified value of the google.protobuf.Duration type, inclusive. If the field’s value is greater than the specified value, an error message will be generated. proto message MyDuration { // value must be less than or equal to 10s google.protobuf.Duration value = 1 [(buf.validate.field).duration.lte = "10s"]; } |
gt | optional ``google.protobuf.Duration | gt requires the duration field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyDuration { // duration must be greater than 5s [duration.gt] google.protobuf.Duration value = 1 [(buf.validate.field).duration.gt = { seconds: 5 }]; // duration must be greater than 5s and less than 10s [duration.gt_lt] google.protobuf.Duration another_value = 2 [(buf.validate.field).duration = { gt: { seconds: 5 }, lt: { seconds: 10 } }]; // duration must be greater than 10s or less than 5s [duration.gt_lt_exclusive] google.protobuf.Duration other_value = 3 [(buf.validate.field).duration = { gt: { seconds: 10 }, lt: { seconds: 5 } }]; } |
gte | optional ``google.protobuf.Duration | gte requires the duration field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyDuration { // duration must be greater than or equal to 5s [duration.gte] google.protobuf.Duration value = 1 [(buf.validate.field).duration.gte = { seconds: 5 }]; // duration must be greater than or equal to 5s and less than 10s [duration.gte_lt] google.protobuf.Duration another_value = 2 [(buf.validate.field).duration = { gte: { seconds: 5 }, lt: { seconds: 10 } }]; // duration must be greater than or equal to 10s or less than 5s [duration.gte_lt_exclusive] google.protobuf.Duration other_value = 3 [(buf.validate.field).duration = { gte: { seconds: 10 }, lt: { seconds: 5 } }]; } |
in | repeated ``google.protobuf.Duration | in asserts that the field must be equal to one of the specified values of the google.protobuf.Duration type. If the field’s value doesn’t correspond to any of the specified values, an error message will be generated. proto message MyDuration { // value must be in list [1s, 2s, 3s] google.protobuf.Duration value = 1 [(buf.validate.field).duration.in = ["1s", "2s", "3s"]]; } |
not_in | repeated ``google.protobuf.Duration | not_in denotes that the field must not be equal to any of the specified values of the google.protobuf.Duration type. If the field’s value matches any of these values, an error message will be generated. proto message MyDuration { // value must not be in list [1s, 2s, 3s] google.protobuf.Duration value = 1 [(buf.validate.field).duration.not_in = ["1s", "2s", "3s"]]; } |
example | repeated ``google.protobuf.Duration | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyDuration { google.protobuf.Duration value = 1 [ (buf.validate.field).duration.example = { seconds: 1 }, (buf.validate.field).duration.example = { seconds: 2 }, ]; } |
EnumRules
| Field | Type | Description |
|---|---|---|
const | optional ``int32 | const requires the field value to exactly match the specified enum value. If the field value doesn’t match, an error message is generated. proto enum MyEnum { MY_ENUM_UNSPECIFIED = 0; MY_ENUM_VALUE1 = 1; MY_ENUM_VALUE2 = 2; } message MyMessage { // The field `value` must be exactly MY_ENUM_VALUE1. MyEnum value = 1 [(buf.validate.field).enum.const = 1]; } |
defined_only | optional ``bool | defined_only requires the field value to be one of the defined values for this enum, failing on any undefined value. proto enum MyEnum { MY_ENUM_UNSPECIFIED = 0; MY_ENUM_VALUE1 = 1; MY_ENUM_VALUE2 = 2; } message MyMessage { // The field `value` must be a defined value of MyEnum. MyEnum value = 1 [(buf.validate.field).enum.defined_only = true]; } |
in | repeated ``int32 | in requires the field value to be equal to one of the specified enum values. If the field value doesn’t match any of the specified values, an error message is generated. proto enum MyEnum { MY_ENUM_UNSPECIFIED = 0; MY_ENUM_VALUE1 = 1; MY_ENUM_VALUE2 = 2; } message MyMessage { // The field `value` must be equal to one of the specified values. MyEnum value = 1 [(buf.validate.field).enum = { in: [1, 2]}]; } |
not_in | repeated ``int32 | not_in requires the field value to be not equal to any of the specified enum values. If the field value matches one of the specified values, an error message is generated. proto enum MyEnum { MY_ENUM_UNSPECIFIED = 0; MY_ENUM_VALUE1 = 1; MY_ENUM_VALUE2 = 2; } message MyMessage { // The field `value` must not be equal to any of the specified values. MyEnum value = 1 [(buf.validate.field).enum = { not_in: [1, 2]}]; } |
example | repeated ``int32 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto enum MyEnum { MY_ENUM_UNSPECIFIED = 0; MY_ENUM_VALUE1 = 1; MY_ENUM_VALUE2 = 2; } message MyMessage { (buf.validate.field).enum.example = 1, (buf.validate.field).enum.example = 2 } |
FieldPath
| Field | Type | Description |
|---|---|---|
elements | repeated ``FieldPathElement | elements contains each element of the path, starting from the root and recursing downward. |
FieldPathElement
| Field | Type | Description |
|---|---|---|
field_number | optional ``int32 | field_number is the field number this path element refers to. |
field_name | optional ``string | field_name contains the field name this path element refers to. This can be used to display a human-readable path even if the field number is unknown. |
field_type | optional ``google.protobuf.FieldDescriptorProto.Type | field_type specifies the type of this field. When using reflection, this value is not needed. This value is provided to make it possible to traverse unknown fields through wire data. When traversing wire data, be mindful of both packed[1] and delimited[2] encoding schemes. [1]: https://protobuf.dev/programming-guides/encoding/#packed [2]: https://protobuf.dev/programming-guides/encoding/#groups N.B.: Although groups are deprecated, the corresponding delimited encoding scheme is not, and can be explicitly used in Protocol Buffers 2023 Edition. |
key_type | optional ``google.protobuf.FieldDescriptorProto.Type | key_type specifies the map key type of this field. This value is useful when traversing unknown fields through wire data: specifically, it allows handling the differences between different integer encodings. |
value_type | optional ``google.protobuf.FieldDescriptorProto.Type | value_type specifies map value type of this field. This is useful if you want to display a value inside unknown fields through wire data. |
index | optional ``uint64 | index specifies a 0-based index into a repeated field. |
bool_key | optional ``bool | bool_key specifies a map key of type bool. |
int_key | optional ``int64 | int_key specifies a map key of type int32, int64, sint32, sint64, sfixed32 or sfixed64. |
uint_key | optional ``uint64 | uint_key specifies a map key of type uint32, uint64, fixed32 or fixed64. |
string_key | optional ``string | string_key specifies a map key of type string. |
FieldRules
| Field | Type | Description |
|---|---|---|
cel | repeated ``Rule | cel is a repeated field used to represent a textual expression in the Common Expression Language (CEL) syntax. For more information, see our documentation. proto message MyMessage { // The field `value` must be greater than 42. optional int32 value = 1 [(buf.validate.field).cel = { id: "my_message.value", message: "value must be greater than 42", expression: "this > 42", }]; } |
required | optional ``bool | If required is true, the field must be set. A validation error is returned if the field is not set. proto syntax="proto3"; message FieldsWithPresence { // Requires any string to be set, including the empty string. optional string link = 1 [ (buf.validate.field).required = true ]; // Requires true or false to be set. optional bool disabled = 2 [ (buf.validate.field).required = true ]; // Requires a message to be set, including the empty message. SomeMessage msg = 4 [ (buf.validate.field).required = true ]; } All fields in the example above track presence. By default, Protovalidate ignores rules on those fields if no value is set. required ensures that the fields are set and valid. Fields that don’t track presence are always validated by Protovalidate, whether they are set or not. It is not necessary to add required. It can be added to indicate that the field cannot be the zero value. proto syntax="proto3"; message FieldsWithoutPresence { // `string.email` always applies, even to an empty string. string link = 1 [ (buf.validate.field).string.email = true ]; // `repeated.min_items` always applies, even to an empty list. repeated string labels = 2 [ (buf.validate.field).repeated.min_items = 1 ]; // `required`, for fields that don't track presence, indicates // the value of the field can't be the zero value. int32 zero_value_not_allowed = 3 [ (buf.validate.field).required = true ]; } To learn which fields track presence, see the Field Presence cheat sheet. Note: While field rules can be applied to repeated items, map keys, and map values, the elements are always considered to be set. Consequently, specifying repeated.items.required is redundant. |
ignore | optional ``Ignore | Ignore validation rules on the field if its value matches the specified criteria. See the Ignore enum for details. proto message UpdateRequest { // The uri rule only applies if the field is not an empty string. string url = 1 [ (buf.validate.field).ignore = IGNORE_IF_ZERO_VALUE, (buf.validate.field).string.uri = true ]; } |
float | optional ``FloatRules | Scalar Field Types |
double | optional ``DoubleRules | |
int32 | optional ``Int32Rules | |
int64 | optional ``Int64Rules | |
uint32 | optional ``UInt32Rules | |
uint64 | optional ``UInt64Rules | |
sint32 | optional ``SInt32Rules | |
sint64 | optional ``SInt64Rules | |
fixed32 | optional ``Fixed32Rules | |
fixed64 | optional ``Fixed64Rules | |
sfixed32 | optional ``SFixed32Rules | |
sfixed64 | optional ``SFixed64Rules | |
bool | optional ``BoolRules | |
string | optional ``StringRules | |
bytes | optional ``BytesRules | |
enum | optional ``EnumRules | Complex Field Types |
repeated | optional ``RepeatedRules | |
map | optional ``MapRules | |
any | optional ``AnyRules | Well-Known Field Types |
duration | optional ``DurationRules | |
timestamp | optional ``TimestampRules |
Fixed32Rules
| Field | Type | Description |
|---|---|---|
const | optional ``fixed32 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MyFixed32 { // value must equal 42 fixed32 value = 1 [(buf.validate.field).fixed32.const = 42]; } |
lt | optional ``fixed32 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MyFixed32 { // value must be less than 10 fixed32 value = 1 [(buf.validate.field).fixed32.lt = 10]; } |
lte | optional ``fixed32 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MyFixed32 { // value must be less than or equal to 10 fixed32 value = 1 [(buf.validate.field).fixed32.lte = 10]; } |
gt | optional ``fixed32 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyFixed32 { // value must be greater than 5 [fixed32.gt] fixed32 value = 1 [(buf.validate.field).fixed32.gt = 5]; // value must be greater than 5 and less than 10 [fixed32.gt_lt] fixed32 other_value = 2 [(buf.validate.field).fixed32 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [fixed32.gt_lt_exclusive] fixed32 another_value = 3 [(buf.validate.field).fixed32 = { gt: 10, lt: 5 }]; } |
gte | optional ``fixed32 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyFixed32 { // value must be greater than or equal to 5 [fixed32.gte] fixed32 value = 1 [(buf.validate.field).fixed32.gte = 5]; // value must be greater than or equal to 5 and less than 10 [fixed32.gte_lt] fixed32 other_value = 2 [(buf.validate.field).fixed32 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [fixed32.gte_lt_exclusive] fixed32 another_value = 3 [(buf.validate.field).fixed32 = { gte: 10, lt: 5 }]; } |
in | repeated ``fixed32 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MyFixed32 { // value must be in list [1, 2, 3] fixed32 value = 1 [(buf.validate.field).fixed32 = { in: [1, 2, 3] }]; } |
not_in | repeated ``fixed32 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MyFixed32 { // value must not be in list [1, 2, 3] fixed32 value = 1 [(buf.validate.field).fixed32 = { not_in: [1, 2, 3] }]; } |
example | repeated ``fixed32 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyFixed32 { fixed32 value = 1 [ (buf.validate.field).fixed32.example = 1, (buf.validate.field).fixed32.example = 2 ]; } |
Fixed64Rules
| Field | Type | Description |
|---|---|---|
const | optional ``fixed64 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MyFixed64 { // value must equal 42 fixed64 value = 1 [(buf.validate.field).fixed64.const = 42]; } |
lt | optional ``fixed64 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MyFixed64 { // value must be less than 10 fixed64 value = 1 [(buf.validate.field).fixed64.lt = 10]; } |
lte | optional ``fixed64 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MyFixed64 { // value must be less than or equal to 10 fixed64 value = 1 [(buf.validate.field).fixed64.lte = 10]; } |
gt | optional ``fixed64 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyFixed64 { // value must be greater than 5 [fixed64.gt] fixed64 value = 1 [(buf.validate.field).fixed64.gt = 5]; // value must be greater than 5 and less than 10 [fixed64.gt_lt] fixed64 other_value = 2 [(buf.validate.field).fixed64 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [fixed64.gt_lt_exclusive] fixed64 another_value = 3 [(buf.validate.field).fixed64 = { gt: 10, lt: 5 }]; } |
gte | optional ``fixed64 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyFixed64 { // value must be greater than or equal to 5 [fixed64.gte] fixed64 value = 1 [(buf.validate.field).fixed64.gte = 5]; // value must be greater than or equal to 5 and less than 10 [fixed64.gte_lt] fixed64 other_value = 2 [(buf.validate.field).fixed64 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [fixed64.gte_lt_exclusive] fixed64 another_value = 3 [(buf.validate.field).fixed64 = { gte: 10, lt: 5 }]; } |
in | repeated ``fixed64 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MyFixed64 { // value must be in list [1, 2, 3] fixed64 value = 1 [(buf.validate.field).fixed64 = { in: [1, 2, 3] }]; } |
not_in | repeated ``fixed64 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MyFixed64 { // value must not be in list [1, 2, 3] fixed64 value = 1 [(buf.validate.field).fixed64 = { not_in: [1, 2, 3] }]; } |
example | repeated ``fixed64 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyFixed64 { fixed64 value = 1 [ (buf.validate.field).fixed64.example = 1, (buf.validate.field).fixed64.example = 2 ]; } |
FloatRules
| Field | Type | Description |
|---|---|---|
const | optional ``float | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MyFloat { // value must equal 42.0 float value = 1 [(buf.validate.field).float.const = 42.0]; } |
lt | optional ``float | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MyFloat { // value must be less than 10.0 float value = 1 [(buf.validate.field).float.lt = 10.0]; } |
lte | optional ``float | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MyFloat { // value must be less than or equal to 10.0 float value = 1 [(buf.validate.field).float.lte = 10.0]; } |
gt | optional ``float | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyFloat { // value must be greater than 5.0 [float.gt] float value = 1 [(buf.validate.field).float.gt = 5.0]; // value must be greater than 5 and less than 10.0 [float.gt_lt] float other_value = 2 [(buf.validate.field).float = { gt: 5.0, lt: 10.0 }]; // value must be greater than 10 or less than 5.0 [float.gt_lt_exclusive] float another_value = 3 [(buf.validate.field).float = { gt: 10.0, lt: 5.0 }]; } |
gte | optional ``float | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyFloat { // value must be greater than or equal to 5.0 [float.gte] float value = 1 [(buf.validate.field).float.gte = 5.0]; // value must be greater than or equal to 5.0 and less than 10.0 [float.gte_lt] float other_value = 2 [(buf.validate.field).float = { gte: 5.0, lt: 10.0 }]; // value must be greater than or equal to 10.0 or less than 5.0 [float.gte_lt_exclusive] float another_value = 3 [(buf.validate.field).float = { gte: 10.0, lt: 5.0 }]; } |
in | repeated ``float | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MyFloat { // value must be in list [1.0, 2.0, 3.0] float value = 1 [(buf.validate.field).float = { in: [1.0, 2.0, 3.0] }]; } |
not_in | repeated ``float | in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MyFloat { // value must not be in list [1.0, 2.0, 3.0] float value = 1 [(buf.validate.field).float = { not_in: [1.0, 2.0, 3.0] }]; } |
finite | optional ``bool | finite requires the field value to be finite. If the field value is infinite or NaN, an error message is generated. |
example | repeated ``float | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyFloat { float value = 1 [ (buf.validate.field).float.example = 1.0, (buf.validate.field).float.example = inf ]; } |
Int32Rules
| Field | Type | Description |
|---|---|---|
const | optional ``int32 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MyInt32 { // value must equal 42 int32 value = 1 [(buf.validate.field).int32.const = 42]; } |
lt | optional ``int32 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MyInt32 { // value must be less than 10 int32 value = 1 [(buf.validate.field).int32.lt = 10]; } |
lte | optional ``int32 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MyInt32 { // value must be less than or equal to 10 int32 value = 1 [(buf.validate.field).int32.lte = 10]; } |
gt | optional ``int32 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyInt32 { // value must be greater than 5 [int32.gt] int32 value = 1 [(buf.validate.field).int32.gt = 5]; // value must be greater than 5 and less than 10 [int32.gt_lt] int32 other_value = 2 [(buf.validate.field).int32 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [int32.gt_lt_exclusive] int32 another_value = 3 [(buf.validate.field).int32 = { gt: 10, lt: 5 }]; } |
gte | optional ``int32 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyInt32 { // value must be greater than or equal to 5 [int32.gte] int32 value = 1 [(buf.validate.field).int32.gte = 5]; // value must be greater than or equal to 5 and less than 10 [int32.gte_lt] int32 other_value = 2 [(buf.validate.field).int32 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [int32.gte_lt_exclusive] int32 another_value = 3 [(buf.validate.field).int32 = { gte: 10, lt: 5 }]; } |
in | repeated ``int32 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MyInt32 { // value must be in list [1, 2, 3] int32 value = 1 [(buf.validate.field).int32 = { in: [1, 2, 3] }]; } |
not_in | repeated ``int32 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MyInt32 { // value must not be in list [1, 2, 3] int32 value = 1 [(buf.validate.field).int32 = { not_in: [1, 2, 3] }]; } |
example | repeated ``int32 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyInt32 { int32 value = 1 [ (buf.validate.field).int32.example = 1, (buf.validate.field).int32.example = -10 ]; } |
Int64Rules
| Field | Type | Description |
|---|---|---|
const | optional ``int64 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MyInt64 { // value must equal 42 int64 value = 1 [(buf.validate.field).int64.const = 42]; } |
lt | optional ``int64 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MyInt64 { // value must be less than 10 int64 value = 1 [(buf.validate.field).int64.lt = 10]; } |
lte | optional ``int64 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MyInt64 { // value must be less than or equal to 10 int64 value = 1 [(buf.validate.field).int64.lte = 10]; } |
gt | optional ``int64 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyInt64 { // value must be greater than 5 [int64.gt] int64 value = 1 [(buf.validate.field).int64.gt = 5]; // value must be greater than 5 and less than 10 [int64.gt_lt] int64 other_value = 2 [(buf.validate.field).int64 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [int64.gt_lt_exclusive] int64 another_value = 3 [(buf.validate.field).int64 = { gt: 10, lt: 5 }]; } |
gte | optional ``int64 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyInt64 { // value must be greater than or equal to 5 [int64.gte] int64 value = 1 [(buf.validate.field).int64.gte = 5]; // value must be greater than or equal to 5 and less than 10 [int64.gte_lt] int64 other_value = 2 [(buf.validate.field).int64 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [int64.gte_lt_exclusive] int64 another_value = 3 [(buf.validate.field).int64 = { gte: 10, lt: 5 }]; } |
in | repeated ``int64 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MyInt64 { // value must be in list [1, 2, 3] int64 value = 1 [(buf.validate.field).int64 = { in: [1, 2, 3] }]; } |
not_in | repeated ``int64 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MyInt64 { // value must not be in list [1, 2, 3] int64 value = 1 [(buf.validate.field).int64 = { not_in: [1, 2, 3] }]; } |
example | repeated ``int64 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyInt64 { int64 value = 1 [ (buf.validate.field).int64.example = 1, (buf.validate.field).int64.example = -10 ]; } |
MapRules
| Field | Type | Description |
|---|---|---|
min_pairs | optional ``uint64 | Specifies the minimum number of key-value pairs allowed. If the field has fewer key-value pairs than specified, an error message is generated. proto message MyMap { // The field `value` must have at least 2 key-value pairs. map<string, string> value = 1 [(buf.validate.field).map.min_pairs = 2]; } |
max_pairs | optional ``uint64 | Specifies the maximum number of key-value pairs allowed. If the field has more key-value pairs than specified, an error message is generated. proto message MyMap { // The field `value` must have at most 3 key-value pairs. map<string, string> value = 1 [(buf.validate.field).map.max_pairs = 3]; } |
keys | optional ``FieldRules | Specifies the rules to be applied to each key in the field. proto message MyMap { // The keys in the field `value` must follow the specified rules. map<string, string> value = 1 [(buf.validate.field).map.keys = { string: { min_len: 3 max_len: 10 } }]; } Note that the required rule does not apply. Map keys cannot be unset. |
values | optional ``FieldRules | Specifies the rules to be applied to the value of each key in the field. Message values will still have their validations evaluated unless ignore is specified. proto message MyMap { // The values in the field `value` must follow the specified rules. map<string, string> value = 1 [(buf.validate.field).map.values = { string: { min_len: 5 max_len: 20 } }]; } Note that the required rule does not apply. Map values cannot be unset. |
MessageOneofRule
| Field | Type | Description |
|---|---|---|
fields | repeated ``string | A list of field names to include in the oneof. All field names must be defined in the message. At least one field must be specified, and duplicates are not permitted. |
required | optional ``bool | If true, one of the fields specified must be set. |
MessageRules
| Field | Type | Description |
|---|---|---|
cel | repeated ``Rule | cel is a repeated field of type Rule. Each Rule specifies a validation rule to be applied to this message. These rules are written in Common Expression Language (CEL) syntax. For more information, see our documentation. proto message MyMessage { // The field `foo` must be greater than 42. option (buf.validate.message).cel = { id: "my_message.value", message: "value must be greater than 42", expression: "this.foo > 42", }; optional int32 foo = 1; } |
oneof | repeated ``MessageOneofRule | oneof is a repeated field of type MessageOneofRule that specifies a list of fields of which at most one can be present. If required is also specified, then exactly one of the specified fields must be present. This will enforce oneof-like constraints with a few features not provided by actual Protobuf oneof declarations: 1. Repeated and map fields are allowed in this validation. In a Protobuf oneof, only scalar fields are allowed. 2. Fields with implicit presence are allowed. In a Protobuf oneof, all member fields have explicit presence. This means that, for the purpose of determining how many fields are set, explicitly setting such a field to its zero value is effectively the same as not setting it at all. 3. This will always generate validation errors for a message unmarshalled from serialized data that sets more than one field. With a Protobuf oneof, when multiple fields are present in the serialized form, earlier values are usually silently ignored when unmarshalling, with only the last field being set when unmarshalling completes. Note that adding a field to a oneof will also set the IGNORE_IF_ZERO_VALUE on the fields. This means only the field that is set will be validated and the unset fields are not validated according to the field rules. This behavior can be overridden by setting ignore against a field. proto message MyMessage { // Only one of `field1` or `field2` _can_ be present in this message. option (buf.validate.message).oneof = { fields: ["field1", "field2"] }; // Exactly one of `field3` or `field4` _must_ be present in this message. option (buf.validate.message).oneof = { fields: ["field3", "field4"], required: true }; string field1 = 1; bytes field2 = 2; bool field3 = 3; int32 field4 = 4; } |
OneofRules
| Field | Type | Description |
|---|---|---|
required | optional ``bool | If required is true, exactly one field of the oneof must be set. A validation error is returned if no fields in the oneof are set. Further rules should be placed on the fields themselves to ensure they are valid values, such as min_len or gt. proto message MyMessage { oneof value { // Either `a` or `b` must be set. If `a` is set, it must also be // non-empty; whereas if `b` is set, it can still be an empty string. option (buf.validate.oneof).required = true; string a = 1 [(buf.validate.field).string.min_len = 1]; string b = 2; } } |
PredefinedRules
| Field | Type | Description |
|---|---|---|
cel | repeated ``Rule | cel is a repeated field used to represent a textual expression in the Common Expression Language (CEL) syntax. For more information, see our documentation. proto message MyMessage { // The field `value` must be greater than 42. optional int32 value = 1 [(buf.validate.predefined).cel = { id: "my_message.value", message: "value must be greater than 42", expression: "this > 42", }]; } |
RepeatedRules
| Field | Type | Description |
|---|---|---|
min_items | optional ``uint64 | min_items requires that this field must contain at least the specified minimum number of items. Note that min_items = 1 is equivalent to setting a field as required. proto message MyRepeated { // value must contain at least 2 items repeated string value = 1 [(buf.validate.field).repeated.min_items = 2]; } |
max_items | optional ``uint64 | max_items denotes that this field must not exceed a certain number of items as the upper limit. If the field contains more items than specified, an error message will be generated, requiring the field to maintain no more than the specified number of items. proto message MyRepeated { // value must contain no more than 3 item(s) repeated string value = 1 [(buf.validate.field).repeated.max_items = 3]; } |
unique | optional ``bool | unique indicates that all elements in this field must be unique. This rule is strictly applicable to scalar and enum types, with message types not being supported. proto message MyRepeated { // repeated value must contain unique items repeated string value = 1 [(buf.validate.field).repeated.unique = true]; } |
items | optional ``FieldRules | items details the rules to be applied to each item in the field. Even for repeated message fields, validation is executed against each item unless ignore is specified. proto message MyRepeated { // The items in the field `value` must follow the specified rules. repeated string value = 1 [(buf.validate.field).repeated.items = { string: { min_len: 3 max_len: 10 } }]; } Note that the required rule does not apply. Repeated items cannot be unset. |
Rule
| Field | Type | Description |
|---|---|---|
id | optional ``string | id is a string that serves as a machine-readable name for this Rule. It should be unique within its scope, which could be either a message or a field. |
message | optional ``string | message is an optional field that provides a human-readable error message for this Rule when the CEL expression evaluates to false. If a non-empty message is provided, any strings resulting from the CEL expression evaluation are ignored. |
expression | optional ``string | expression is the actual CEL expression that will be evaluated for validation. This string must resolve to either a boolean or a string value. If the expression evaluates to false or a non-empty string, the validation is considered failed, and the message is rejected. |
SFixed32Rules
| Field | Type | Description |
|---|---|---|
const | optional ``sfixed32 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MySFixed32 { // value must equal 42 sfixed32 value = 1 [(buf.validate.field).sfixed32.const = 42]; } |
lt | optional ``sfixed32 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MySFixed32 { // value must be less than 10 sfixed32 value = 1 [(buf.validate.field).sfixed32.lt = 10]; } |
lte | optional ``sfixed32 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MySFixed32 { // value must be less than or equal to 10 sfixed32 value = 1 [(buf.validate.field).sfixed32.lte = 10]; } |
gt | optional ``sfixed32 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MySFixed32 { // value must be greater than 5 [sfixed32.gt] sfixed32 value = 1 [(buf.validate.field).sfixed32.gt = 5]; // value must be greater than 5 and less than 10 [sfixed32.gt_lt] sfixed32 other_value = 2 [(buf.validate.field).sfixed32 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [sfixed32.gt_lt_exclusive] sfixed32 another_value = 3 [(buf.validate.field).sfixed32 = { gt: 10, lt: 5 }]; } |
gte | optional ``sfixed32 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MySFixed32 { // value must be greater than or equal to 5 [sfixed32.gte] sfixed32 value = 1 [(buf.validate.field).sfixed32.gte = 5]; // value must be greater than or equal to 5 and less than 10 [sfixed32.gte_lt] sfixed32 other_value = 2 [(buf.validate.field).sfixed32 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [sfixed32.gte_lt_exclusive] sfixed32 another_value = 3 [(buf.validate.field).sfixed32 = { gte: 10, lt: 5 }]; } |
in | repeated ``sfixed32 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MySFixed32 { // value must be in list [1, 2, 3] sfixed32 value = 1 [(buf.validate.field).sfixed32 = { in: [1, 2, 3] }]; } |
not_in | repeated ``sfixed32 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MySFixed32 { // value must not be in list [1, 2, 3] sfixed32 value = 1 [(buf.validate.field).sfixed32 = { not_in: [1, 2, 3] }]; } |
example | repeated ``sfixed32 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MySFixed32 { sfixed32 value = 1 [ (buf.validate.field).sfixed32.example = 1, (buf.validate.field).sfixed32.example = 2 ]; } |
SFixed64Rules
| Field | Type | Description |
|---|---|---|
const | optional ``sfixed64 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MySFixed64 { // value must equal 42 sfixed64 value = 1 [(buf.validate.field).sfixed64.const = 42]; } |
lt | optional ``sfixed64 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MySFixed64 { // value must be less than 10 sfixed64 value = 1 [(buf.validate.field).sfixed64.lt = 10]; } |
lte | optional ``sfixed64 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MySFixed64 { // value must be less than or equal to 10 sfixed64 value = 1 [(buf.validate.field).sfixed64.lte = 10]; } |
gt | optional ``sfixed64 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MySFixed64 { // value must be greater than 5 [sfixed64.gt] sfixed64 value = 1 [(buf.validate.field).sfixed64.gt = 5]; // value must be greater than 5 and less than 10 [sfixed64.gt_lt] sfixed64 other_value = 2 [(buf.validate.field).sfixed64 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [sfixed64.gt_lt_exclusive] sfixed64 another_value = 3 [(buf.validate.field).sfixed64 = { gt: 10, lt: 5 }]; } |
gte | optional ``sfixed64 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MySFixed64 { // value must be greater than or equal to 5 [sfixed64.gte] sfixed64 value = 1 [(buf.validate.field).sfixed64.gte = 5]; // value must be greater than or equal to 5 and less than 10 [sfixed64.gte_lt] sfixed64 other_value = 2 [(buf.validate.field).sfixed64 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [sfixed64.gte_lt_exclusive] sfixed64 another_value = 3 [(buf.validate.field).sfixed64 = { gte: 10, lt: 5 }]; } |
in | repeated ``sfixed64 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MySFixed64 { // value must be in list [1, 2, 3] sfixed64 value = 1 [(buf.validate.field).sfixed64 = { in: [1, 2, 3] }]; } |
not_in | repeated ``sfixed64 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MySFixed64 { // value must not be in list [1, 2, 3] sfixed64 value = 1 [(buf.validate.field).sfixed64 = { not_in: [1, 2, 3] }]; } |
example | repeated ``sfixed64 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MySFixed64 { sfixed64 value = 1 [ (buf.validate.field).sfixed64.example = 1, (buf.validate.field).sfixed64.example = 2 ]; } |
SInt32Rules
| Field | Type | Description |
|---|---|---|
const | optional ``sint32 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MySInt32 { // value must equal 42 sint32 value = 1 [(buf.validate.field).sint32.const = 42]; } |
lt | optional ``sint32 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MySInt32 { // value must be less than 10 sint32 value = 1 [(buf.validate.field).sint32.lt = 10]; } |
lte | optional ``sint32 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MySInt32 { // value must be less than or equal to 10 sint32 value = 1 [(buf.validate.field).sint32.lte = 10]; } |
gt | optional ``sint32 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MySInt32 { // value must be greater than 5 [sint32.gt] sint32 value = 1 [(buf.validate.field).sint32.gt = 5]; // value must be greater than 5 and less than 10 [sint32.gt_lt] sint32 other_value = 2 [(buf.validate.field).sint32 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [sint32.gt_lt_exclusive] sint32 another_value = 3 [(buf.validate.field).sint32 = { gt: 10, lt: 5 }]; } |
gte | optional ``sint32 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MySInt32 { // value must be greater than or equal to 5 [sint32.gte] sint32 value = 1 [(buf.validate.field).sint32.gte = 5]; // value must be greater than or equal to 5 and less than 10 [sint32.gte_lt] sint32 other_value = 2 [(buf.validate.field).sint32 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [sint32.gte_lt_exclusive] sint32 another_value = 3 [(buf.validate.field).sint32 = { gte: 10, lt: 5 }]; } |
in | repeated ``sint32 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MySInt32 { // value must be in list [1, 2, 3] sint32 value = 1 [(buf.validate.field).sint32 = { in: [1, 2, 3] }]; } |
not_in | repeated ``sint32 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MySInt32 { // value must not be in list [1, 2, 3] sint32 value = 1 [(buf.validate.field).sint32 = { not_in: [1, 2, 3] }]; } |
example | repeated ``sint32 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MySInt32 { sint32 value = 1 [ (buf.validate.field).sint32.example = 1, (buf.validate.field).sint32.example = -10 ]; } |
SInt64Rules
| Field | Type | Description |
|---|---|---|
const | optional ``sint64 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MySInt64 { // value must equal 42 sint64 value = 1 [(buf.validate.field).sint64.const = 42]; } |
lt | optional ``sint64 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MySInt64 { // value must be less than 10 sint64 value = 1 [(buf.validate.field).sint64.lt = 10]; } |
lte | optional ``sint64 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MySInt64 { // value must be less than or equal to 10 sint64 value = 1 [(buf.validate.field).sint64.lte = 10]; } |
gt | optional ``sint64 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MySInt64 { // value must be greater than 5 [sint64.gt] sint64 value = 1 [(buf.validate.field).sint64.gt = 5]; // value must be greater than 5 and less than 10 [sint64.gt_lt] sint64 other_value = 2 [(buf.validate.field).sint64 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [sint64.gt_lt_exclusive] sint64 another_value = 3 [(buf.validate.field).sint64 = { gt: 10, lt: 5 }]; } |
gte | optional ``sint64 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MySInt64 { // value must be greater than or equal to 5 [sint64.gte] sint64 value = 1 [(buf.validate.field).sint64.gte = 5]; // value must be greater than or equal to 5 and less than 10 [sint64.gte_lt] sint64 other_value = 2 [(buf.validate.field).sint64 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [sint64.gte_lt_exclusive] sint64 another_value = 3 [(buf.validate.field).sint64 = { gte: 10, lt: 5 }]; } |
in | repeated ``sint64 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MySInt64 { // value must be in list [1, 2, 3] sint64 value = 1 [(buf.validate.field).sint64 = { in: [1, 2, 3] }]; } |
not_in | repeated ``sint64 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MySInt64 { // value must not be in list [1, 2, 3] sint64 value = 1 [(buf.validate.field).sint64 = { not_in: [1, 2, 3] }]; } |
example | repeated ``sint64 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MySInt64 { sint64 value = 1 [ (buf.validate.field).sint64.example = 1, (buf.validate.field).sint64.example = -10 ]; } |
StringRules
| Field | Type | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
const | optional ``string | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MyString { // value must equal `hello` string value = 1 [(buf.validate.field).string.const = "hello"]; } | ||||||||||||||||||||
len | optional ``uint64 | len dictates that the field value must have the specified number of characters (Unicode code points), which may differ from the number of bytes in the string. If the field value does not meet the specified length, an error message will be generated. proto message MyString { // value length must be 5 characters string value = 1 [(buf.validate.field).string.len = 5]; } | ||||||||||||||||||||
min_len | optional ``uint64 | min_len specifies that the field value must have at least the specified number of characters (Unicode code points), which may differ from the number of bytes in the string. If the field value contains fewer characters, an error message will be generated. proto message MyString { // value length must be at least 3 characters string value = 1 [(buf.validate.field).string.min_len = 3]; } | ||||||||||||||||||||
max_len | optional ``uint64 | max_len specifies that the field value must have no more than the specified number of characters (Unicode code points), which may differ from the number of bytes in the string. If the field value contains more characters, an error message will be generated. proto message MyString { // value length must be at most 10 characters string value = 1 [(buf.validate.field).string.max_len = 10]; } | ||||||||||||||||||||
len_bytes | optional ``uint64 | len_bytes dictates that the field value must have the specified number of bytes. If the field value does not match the specified length in bytes, an error message will be generated. proto message MyString { // value length must be 6 bytes string value = 1 [(buf.validate.field).string.len_bytes = 6]; } | ||||||||||||||||||||
min_bytes | optional ``uint64 | min_bytes specifies that the field value must have at least the specified number of bytes. If the field value contains fewer bytes, an error message will be generated. proto message MyString { // value length must be at least 4 bytes string value = 1 [(buf.validate.field).string.min_bytes = 4]; } | ||||||||||||||||||||
max_bytes | optional ``uint64 | max_bytes specifies that the field value must have no more than the specified number of bytes. If the field value contains more bytes, an error message will be generated. proto message MyString { // value length must be at most 8 bytes string value = 1 [(buf.validate.field).string.max_bytes = 8]; } | ||||||||||||||||||||
pattern | optional ``string | pattern specifies that the field value must match the specified regular expression (RE2 syntax), with the expression provided without any delimiters. If the field value doesn’t match the regular expression, an error message will be generated. proto message MyString { // value does not match regex pattern `^[a-zA-Z]//$` string value = 1 [(buf.validate.field).string.pattern = "^[a-zA-Z]//$"]; } | ||||||||||||||||||||
prefix | optional ``string | prefix specifies that the field value must have the specified substring at the beginning of the string. If the field value doesn’t start with the specified prefix, an error message will be generated. proto message MyString { // value does not have prefix `pre` string value = 1 [(buf.validate.field).string.prefix = "pre"]; } | ||||||||||||||||||||
suffix | optional ``string | suffix specifies that the field value must have the specified substring at the end of the string. If the field value doesn’t end with the specified suffix, an error message will be generated. proto message MyString { // value does not have suffix `post` string value = 1 [(buf.validate.field).string.suffix = "post"]; } | ||||||||||||||||||||
contains | optional ``string | contains specifies that the field value must have the specified substring anywhere in the string. If the field value doesn’t contain the specified substring, an error message will be generated. proto message MyString { // value does not contain substring `inside`. string value = 1 [(buf.validate.field).string.contains = "inside"]; } | ||||||||||||||||||||
not_contains | optional ``string | not_contains specifies that the field value must not have the specified substring anywhere in the string. If the field value contains the specified substring, an error message will be generated. proto message MyString { // value contains substring `inside`. string value = 1 [(buf.validate.field).string.not_contains = "inside"]; } | ||||||||||||||||||||
in | repeated ``string | in specifies that the field value must be equal to one of the specified values. If the field value isn’t one of the specified values, an error message will be generated. proto message MyString { // value must be in list ["apple", "banana"] string value = 1 [(buf.validate.field).string.in = "apple", (buf.validate.field).string.in = "banana"]; } | ||||||||||||||||||||
not_in | repeated ``string | not_in specifies that the field value cannot be equal to any of the specified values. If the field value is one of the specified values, an error message will be generated. proto message MyString { // value must not be in list ["orange", "grape"] string value = 1 [(buf.validate.field).string.not_in = "orange", (buf.validate.field).string.not_in = "grape"]; } | ||||||||||||||||||||
email | optional ``bool | email specifies that the field value must be a valid email address, for example “foo@example.com”. Conforms to the definition for a valid email address from the HTML standard. Note that this standard willfully deviates from RFC 5322, which allows many unexpected forms of email addresses and will easily match a typographical error. If the field value isn’t a valid email address, an error message will be generated. proto message MyString { // value must be a valid email address string value = 1 [(buf.validate.field).string.email = true]; } | ||||||||||||||||||||
hostname | optional ``bool | hostname specifies that the field value must be a valid hostname, for example “foo.example.com”. A valid hostname follows the rules below: - The name consists of one or more labels, separated by a dot (”.”). - Each label can be 1 to 63 alphanumeric characters. - A label can contain hyphens (”-”), but must not start or end with a hyphen. - The right-most label must not be digits only. - The name can have a trailing dot—for example, “foo.example.com.”. - The name can be 253 characters at most, excluding the optional trailing dot. If the field value isn’t a valid hostname, an error message will be generated. proto message MyString { // value must be a valid hostname string value = 1 [(buf.validate.field).string.hostname = true]; } | ||||||||||||||||||||
ip | optional ``bool | ip specifies that the field value must be a valid IP (v4 or v6) address. IPv4 addresses are expected in the dotted decimal format—for example, “192.168.5.21”. IPv6 addresses are expected in their text representation—for example, “::1”, or “2001:0DB8:ABCD:0012::0”. Both formats are well-defined in the internet standard RFC 3986. Zone identifiers for IPv6 addresses (for example, “fe80::a%en1”) are supported. If the field value isn’t a valid IP address, an error message will be generated. proto message MyString { // value must be a valid IP address string value = 1 [(buf.validate.field).string.ip = true]; } | ||||||||||||||||||||
ipv4 | optional ``bool | ipv4 specifies that the field value must be a valid IPv4 address—for example “192.168.5.21”. If the field value isn’t a valid IPv4 address, an error message will be generated. proto message MyString { // value must be a valid IPv4 address string value = 1 [(buf.validate.field).string.ipv4 = true]; } | ||||||||||||||||||||
ipv6 | optional ``bool | ipv6 specifies that the field value must be a valid IPv6 address—for example “::1”, or “d7a:115c:a1e0:ab12:4843:cd96:626b:430b”. If the field value is not a valid IPv6 address, an error message will be generated. proto message MyString { // value must be a valid IPv6 address string value = 1 [(buf.validate.field).string.ipv6 = true]; } | ||||||||||||||||||||
uri | optional ``bool | uri specifies that the field value must be a valid URI, for example “https://example.com/foo/bar?baz=quux#frag”. URI is defined in the internet standard RFC 3986. Zone Identifiers in IPv6 address literals are supported (RFC 6874). If the field value isn’t a valid URI, an error message will be generated. proto message MyString { // value must be a valid URI string value = 1 [(buf.validate.field).string.uri = true]; } | ||||||||||||||||||||
uri_ref | optional ``bool | uri_ref specifies that the field value must be a valid URI Reference—either a URI such as “https://example.com/foo/bar?baz=quux#frag”, or a Relative Reference such as ”./foo/bar?query”. URI, URI Reference, and Relative Reference are defined in the internet standard RFC 3986. Zone Identifiers in IPv6 address literals are supported (RFC 6874). If the field value isn’t a valid URI Reference, an error message will be generated. proto message MyString { // value must be a valid URI Reference string value = 1 [(buf.validate.field).string.uri_ref = true]; } | ||||||||||||||||||||
address | optional ``bool | address specifies that the field value must be either a valid hostname (for example, “example.com”), or a valid IP (v4 or v6) address (for example, “192.168.0.1”, or “::1”). If the field value isn’t a valid hostname or IP, an error message will be generated. proto message MyString { // value must be a valid hostname, or ip address string value = 1 [(buf.validate.field).string.address = true]; } | ||||||||||||||||||||
uuid | optional ``bool | uuid specifies that the field value must be a valid UUID as defined by RFC 4122. If the field value isn’t a valid UUID, an error message will be generated. proto message MyString { // value must be a valid UUID string value = 1 [(buf.validate.field).string.uuid = true]; } | ||||||||||||||||||||
tuuid | optional ``bool | tuuid (trimmed UUID) specifies that the field value must be a valid UUID as defined by RFC 4122 with all dashes omitted. If the field value isn’t a valid UUID without dashes, an error message will be generated. proto message MyString { // value must be a valid trimmed UUID string value = 1 [(buf.validate.field).string.tuuid = true]; } | ||||||||||||||||||||
ip_with_prefixlen | optional ``bool | ip_with_prefixlen specifies that the field value must be a valid IP (v4 or v6) address with prefix length—for example, “192.168.5.21/16” or “2001:0DB8:ABCD:0012::F1/64”. If the field value isn’t a valid IP with prefix length, an error message will be generated. proto message MyString { // value must be a valid IP with prefix length string value = 1 [(buf.validate.field).string.ip_with_prefixlen = true]; } | ||||||||||||||||||||
ipv4_with_prefixlen | optional ``bool | ipv4_with_prefixlen specifies that the field value must be a valid IPv4 address with prefix length—for example, “192.168.5.21/16”. If the field value isn’t a valid IPv4 address with prefix length, an error message will be generated. proto message MyString { // value must be a valid IPv4 address with prefix length string value = 1 [(buf.validate.field).string.ipv4_with_prefixlen = true]; } | ||||||||||||||||||||
ipv6_with_prefixlen | optional ``bool | ipv6_with_prefixlen specifies that the field value must be a valid IPv6 address with prefix length—for example, “2001:0DB8:ABCD:0012::F1/64”. If the field value is not a valid IPv6 address with prefix length, an error message will be generated. proto message MyString { // value must be a valid IPv6 address prefix length string value = 1 [(buf.validate.field).string.ipv6_with_prefixlen = true]; } | ||||||||||||||||||||
ip_prefix | optional ``bool | ip_prefix specifies that the field value must be a valid IP (v4 or v6) prefix—for example, “192.168.0.0/16” or “2001:0DB8:ABCD:0012::0/64”. The prefix must have all zeros for the unmasked bits. For example, “2001:0DB8:ABCD:0012::0/64” designates the left-most 64 bits for the prefix, and the remaining 64 bits must be zero. If the field value isn’t a valid IP prefix, an error message will be generated. proto message MyString { // value must be a valid IP prefix string value = 1 [(buf.validate.field).string.ip_prefix = true]; } | ||||||||||||||||||||
ipv4_prefix | optional ``bool | ipv4_prefix specifies that the field value must be a valid IPv4 prefix, for example “192.168.0.0/16”. The prefix must have all zeros for the unmasked bits. For example, “192.168.0.0/16” designates the left-most 16 bits for the prefix, and the remaining 16 bits must be zero. If the field value isn’t a valid IPv4 prefix, an error message will be generated. proto message MyString { // value must be a valid IPv4 prefix string value = 1 [(buf.validate.field).string.ipv4_prefix = true]; } | ||||||||||||||||||||
ipv6_prefix | optional ``bool | ipv6_prefix specifies that the field value must be a valid IPv6 prefix—for example, “2001:0DB8:ABCD:0012::0/64”. The prefix must have all zeros for the unmasked bits. For example, “2001:0DB8:ABCD:0012::0/64” designates the left-most 64 bits for the prefix, and the remaining 64 bits must be zero. If the field value is not a valid IPv6 prefix, an error message will be generated. proto message MyString { // value must be a valid IPv6 prefix string value = 1 [(buf.validate.field).string.ipv6_prefix = true]; } | ||||||||||||||||||||
host_and_port | optional ``bool | host_and_port specifies that the field value must be valid host/port pair—for example, “example.com:8080”. The host can be one of: - An IPv4 address in dotted decimal format—for example, “192.168.5.21”. - An IPv6 address enclosed in square brackets—for example, “[2001:0DB8:ABCD:0012::F1]”. - A hostname—for example, “example.com”. The port is separated by a colon. It must be non-empty, with a decimal number in the range of 0-65535, inclusive. | ||||||||||||||||||||
well_known_regex | optional ``KnownRegex | well_known_regex specifies a common well-known pattern defined as a regex. If the field value doesn’t match the well-known regex, an error message will be generated. proto message MyString { // value must be a valid HTTP header value string value = 1 [(buf.validate.field).string.well_known_regex = KNOWN_REGEX_HTTP_HEADER_VALUE]; } #### KnownRegex well_known_regex contains some well-known patterns. | Name | Number | Description | ------------------------------- | -------- | ------------------------------------------- | KNOWN_REGEX_UNSPECIFIED | 0 | KNOWN_REGEX_HTTP_HEADER_NAME | 1 | HTTP header name as defined by RFC 7230 | KNOWN_REGEX_HTTP_HEADER_VALUE | 2 | HTTP header value as defined by RFC 7230 | ||||||
strict | optional ``bool | This applies to regexes HTTP_HEADER_NAME and HTTP_HEADER_VALUE to enable strict header validation. By default, this is true, and HTTP header validations are RFC-compliant. Setting to false will enable looser validations that only disallow \r\n\0 characters, which can be used to bypass header matching rules. proto message MyString { // The field `value` must have be a valid HTTP headers, but not enforced with strict rules. string value = 1 [(buf.validate.field).string.strict = false]; } | ||||||||||||||||||||
example | repeated ``string | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyString { string value = 1 [ (buf.validate.field).string.example = "hello", (buf.validate.field).string.example = "world" ]; } |
TimestampRules
| Field | Type | Description |
|---|---|---|
const | optional ``google.protobuf.Timestamp | const dictates that this field, of the google.protobuf.Timestamp type, must exactly match the specified value. If the field value doesn’t correspond to the specified timestamp, an error message will be generated. proto message MyTimestamp { // value must equal 2023-05-03T10:00:00Z google.protobuf.Timestamp created_at = 1 [(buf.validate.field).timestamp.const = {seconds: 1727998800}]; } |
lt | optional ``google.protobuf.Timestamp | requires the duration field value to be less than the specified value (field < value). If the field value doesn’t meet the required conditions, an error message is generated. proto message MyDuration { // duration must be less than 'P3D' [duration.lt] google.protobuf.Duration value = 1 [(buf.validate.field).duration.lt = { seconds: 259200 }]; } |
lte | optional ``google.protobuf.Timestamp | requires the timestamp field value to be less than or equal to the specified value (field <= value). If the field value doesn’t meet the required conditions, an error message is generated. proto message MyTimestamp { // timestamp must be less than or equal to '2023-05-14T00:00:00Z' [timestamp.lte] google.protobuf.Timestamp value = 1 [(buf.validate.field).timestamp.lte = { seconds: 1678867200 }]; } |
lt_now | optional ``bool | lt_now specifies that this field, of the google.protobuf.Timestamp type, must be less than the current time. lt_now can only be used with the within rule. proto message MyTimestamp { // value must be less than now google.protobuf.Timestamp created_at = 1 [(buf.validate.field).timestamp.lt_now = true]; } |
gt | optional ``google.protobuf.Timestamp | gt requires the timestamp field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyTimestamp { // timestamp must be greater than '2023-01-01T00:00:00Z' [timestamp.gt] google.protobuf.Timestamp value = 1 [(buf.validate.field).timestamp.gt = { seconds: 1672444800 }]; // timestamp must be greater than '2023-01-01T00:00:00Z' and less than '2023-01-02T00:00:00Z' [timestamp.gt_lt] google.protobuf.Timestamp another_value = 2 [(buf.validate.field).timestamp = { gt: { seconds: 1672444800 }, lt: { seconds: 1672531200 } }]; // timestamp must be greater than '2023-01-02T00:00:00Z' or less than '2023-01-01T00:00:00Z' [timestamp.gt_lt_exclusive] google.protobuf.Timestamp other_value = 3 [(buf.validate.field).timestamp = { gt: { seconds: 1672531200 }, lt: { seconds: 1672444800 } }]; } |
gte | optional ``google.protobuf.Timestamp | gte requires the timestamp field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyTimestamp { // timestamp must be greater than or equal to '2023-01-01T00:00:00Z' [timestamp.gte] google.protobuf.Timestamp value = 1 [(buf.validate.field).timestamp.gte = { seconds: 1672444800 }]; // timestamp must be greater than or equal to '2023-01-01T00:00:00Z' and less than '2023-01-02T00:00:00Z' [timestamp.gte_lt] google.protobuf.Timestamp another_value = 2 [(buf.validate.field).timestamp = { gte: { seconds: 1672444800 }, lt: { seconds: 1672531200 } }]; // timestamp must be greater than or equal to '2023-01-02T00:00:00Z' or less than '2023-01-01T00:00:00Z' [timestamp.gte_lt_exclusive] google.protobuf.Timestamp other_value = 3 [(buf.validate.field).timestamp = { gte: { seconds: 1672531200 }, lt: { seconds: 1672444800 } }]; } |
gt_now | optional ``bool | gt_now specifies that this field, of the google.protobuf.Timestamp type, must be greater than the current time. gt_now can only be used with the within rule. proto message MyTimestamp { // value must be greater than now google.protobuf.Timestamp created_at = 1 [(buf.validate.field).timestamp.gt_now = true]; } |
within | optional ``google.protobuf.Duration | within specifies that this field, of the google.protobuf.Timestamp type, must be within the specified duration of the current time. If the field value isn’t within the duration, an error message is generated. proto message MyTimestamp { // value must be within 1 hour of now google.protobuf.Timestamp created_at = 1 [(buf.validate.field).timestamp.within = {seconds: 3600}]; } |
example | repeated ``google.protobuf.Timestamp | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyTimestamp { google.protobuf.Timestamp value = 1 [ (buf.validate.field).timestamp.example = { seconds: 1672444800 }, (buf.validate.field).timestamp.example = { seconds: 1672531200 }, ]; } |
UInt32Rules
| Field | Type | Description |
|---|---|---|
const | optional ``uint32 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MyUInt32 { // value must equal 42 uint32 value = 1 [(buf.validate.field).uint32.const = 42]; } |
lt | optional ``uint32 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MyUInt32 { // value must be less than 10 uint32 value = 1 [(buf.validate.field).uint32.lt = 10]; } |
lte | optional ``uint32 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MyUInt32 { // value must be less than or equal to 10 uint32 value = 1 [(buf.validate.field).uint32.lte = 10]; } |
gt | optional ``uint32 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyUInt32 { // value must be greater than 5 [uint32.gt] uint32 value = 1 [(buf.validate.field).uint32.gt = 5]; // value must be greater than 5 and less than 10 [uint32.gt_lt] uint32 other_value = 2 [(buf.validate.field).uint32 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [uint32.gt_lt_exclusive] uint32 another_value = 3 [(buf.validate.field).uint32 = { gt: 10, lt: 5 }]; } |
gte | optional ``uint32 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyUInt32 { // value must be greater than or equal to 5 [uint32.gte] uint32 value = 1 [(buf.validate.field).uint32.gte = 5]; // value must be greater than or equal to 5 and less than 10 [uint32.gte_lt] uint32 other_value = 2 [(buf.validate.field).uint32 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [uint32.gte_lt_exclusive] uint32 another_value = 3 [(buf.validate.field).uint32 = { gte: 10, lt: 5 }]; } |
in | repeated ``uint32 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MyUInt32 { // value must be in list [1, 2, 3] uint32 value = 1 [(buf.validate.field).uint32 = { in: [1, 2, 3] }]; } |
not_in | repeated ``uint32 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MyUInt32 { // value must not be in list [1, 2, 3] uint32 value = 1 [(buf.validate.field).uint32 = { not_in: [1, 2, 3] }]; } |
example | repeated ``uint32 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyUInt32 { uint32 value = 1 [ (buf.validate.field).uint32.example = 1, (buf.validate.field).uint32.example = 10 ]; } |
UInt64Rules
| Field | Type | Description |
|---|---|---|
const | optional ``uint64 | const requires the field value to exactly match the specified value. If the field value doesn’t match, an error message is generated. proto message MyUInt64 { // value must equal 42 uint64 value = 1 [(buf.validate.field).uint64.const = 42]; } |
lt | optional ``uint64 | lt requires the field value to be less than the specified value (field < value). If the field value is equal to or greater than the specified value, an error message is generated. proto message MyUInt64 { // value must be less than 10 uint64 value = 1 [(buf.validate.field).uint64.lt = 10]; } |
lte | optional ``uint64 | lte requires the field value to be less than or equal to the specified value (field <= value). If the field value is greater than the specified value, an error message is generated. proto message MyUInt64 { // value must be less than or equal to 10 uint64 value = 1 [(buf.validate.field).uint64.lte = 10]; } |
gt | optional ``uint64 | gt requires the field value to be greater than the specified value (exclusive). If the value of gt is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyUInt64 { // value must be greater than 5 [uint64.gt] uint64 value = 1 [(buf.validate.field).uint64.gt = 5]; // value must be greater than 5 and less than 10 [uint64.gt_lt] uint64 other_value = 2 [(buf.validate.field).uint64 = { gt: 5, lt: 10 }]; // value must be greater than 10 or less than 5 [uint64.gt_lt_exclusive] uint64 another_value = 3 [(buf.validate.field).uint64 = { gt: 10, lt: 5 }]; } |
gte | optional ``uint64 | gte requires the field value to be greater than or equal to the specified value (exclusive). If the value of gte is larger than a specified lt or lte, the range is reversed, and the field value must be outside the specified range. If the field value doesn’t meet the required conditions, an error message is generated. proto message MyUInt64 { // value must be greater than or equal to 5 [uint64.gte] uint64 value = 1 [(buf.validate.field).uint64.gte = 5]; // value must be greater than or equal to 5 and less than 10 [uint64.gte_lt] uint64 other_value = 2 [(buf.validate.field).uint64 = { gte: 5, lt: 10 }]; // value must be greater than or equal to 10 or less than 5 [uint64.gte_lt_exclusive] uint64 another_value = 3 [(buf.validate.field).uint64 = { gte: 10, lt: 5 }]; } |
in | repeated ``uint64 | in requires the field value to be equal to one of the specified values. If the field value isn’t one of the specified values, an error message is generated. proto message MyUInt64 { // value must be in list [1, 2, 3] uint64 value = 1 [(buf.validate.field).uint64 = { in: [1, 2, 3] }]; } |
not_in | repeated ``uint64 | not_in requires the field value to not be equal to any of the specified values. If the field value is one of the specified values, an error message is generated. proto message MyUInt64 { // value must not be in list [1, 2, 3] uint64 value = 1 [(buf.validate.field).uint64 = { not_in: [1, 2, 3] }]; } |
example | repeated ``uint64 | example specifies values that the field may have. These values SHOULD conform to other rules. example values will not impact validation but may be used as helpful guidance on how to populate the given field. proto message MyUInt64 { uint64 value = 1 [ (buf.validate.field).uint64.example = 1, (buf.validate.field).uint64.example = -10 ]; } |
Violation
| Field | Type | Description |
|---|---|---|
field | optional ``FieldPath | field is a machine-readable path to the field that failed validation. This could be a nested field, in which case the path will include all the parent fields leading to the actual field that caused the violation. For example, consider the following message: proto message Message { bool a = 1 [(buf.validate.field).required = true]; } It could produce the following violation: textproto violation { field { element { field_number: 1, field_name: "a", field_type: 8 } } ... } |
rule | optional ``FieldPath | rule is a machine-readable path that points to the specific rule that failed validation. This will be a nested field starting from the FieldRules of the field that failed validation. For custom rules, this will provide the path of the rule, e.g. cel[0]. For example, consider the following message: proto message Message { bool a = 1 [(buf.validate.field).required = true]; bool b = 2 [(buf.validate.field).cel = { id: "custom_rule", expression: "!this ? 'b must be true': ''" }] } It could produce the following violations: textproto violation { rule { element { field_number: 25, field_name: "required", field_type: 8 } } ... } violation { rule { element { field_number: 23, field_name: "cel", field_type: 11, index: 0 } } ... } |
rule_id | optional ``string | rule_id is the unique identifier of the Rule that was not fulfilled. This is the same id that was specified in the Rule message, allowing easy tracing of which rule was violated. |
message | optional ``string | message is a human-readable error message that describes the nature of the violation. This can be the default error message from the violated Rule, or it can be a custom message that gives more context about the violation. |
for_key | optional ``bool | for_key indicates whether the violation was caused by a map key, rather than a value. |
Violations
| Field | Type | Description |
|---|---|---|
violations | repeated ``Violation | violations is a repeated field that contains all the Violation messages corresponding to the violations detected. |
Enums
Ignore
Specifies howFieldRules.ignore behaves, depending on the field’s value, and
whether the field tracks presence.
| Value | Number | Description |
|---|---|---|
IGNORE_UNSPECIFIED | 0 | Ignore rules if the field tracks presence and is unset. This is the default behavior. In proto3, only message fields, members of a Protobuf oneof, and fields with the optional label track presence. Consequently, the following fields are always validated, whether a value is set or not: proto syntax="proto3"; message RulesApply { string email = 1 [ (buf.validate.field).string.email = true ]; int32 age = 2 [ (buf.validate.field).int32.gt = 0 ]; repeated string labels = 3 [ (buf.validate.field).repeated.min_items = 1 ]; } In contrast, the following fields track presence, and are only validated if a value is set: proto syntax="proto3"; message RulesApplyIfSet { optional string email = 1 [ (buf.validate.field).string.email = true ]; oneof ref { string reference = 2 [ (buf.validate.field).string.uuid = true ]; string name = 3 [ (buf.validate.field).string.min_len = 4 ]; } SomeMessage msg = 4 [ (buf.validate.field).cel = {/* ... */} ]; } To ensure that such a field is set, add the required rule. To learn which fields track presence, see the Field Presence cheat sheet. |
IGNORE_IF_ZERO_VALUE | 1 | Ignore rules if the field is unset, or set to the zero value. The zero value depends on the field type: - For strings, the zero value is the empty string. - For bytes, the zero value is empty bytes. - For bool, the zero value is false. - For numeric types, the zero value is zero. - For enums, the zero value is the first defined enum value. - For repeated fields, the zero is an empty list. - For map fields, the zero is an empty map. - For message fields, absence of the message (typically a null-value) is considered zero value. For fields that track presence (e.g. adding the optional label in proto3), this a no-op and behavior is the same as the default IGNORE_UNSPECIFIED. |
IGNORE_ALWAYS | 3 | Always ignore rules, including the required rule. This is useful for ignoring the rules of a referenced message, or to temporarily ignore rules during development. proto message MyMessage { // The field's rules will always be ignored, including any validations // on value's fields. MyOtherMessage value = 1 [ (buf.validate.field).ignore = IGNORE_ALWAYS ]; } |