Enums

This page documents why Protovalidate uses enums and describes those provided by the Protovalidate API.

Background

Protovalidate uses enums when the value of a field should be one of a small set of valid values. For example, whether to ignore a field's validation rules often isn't a simple boolean decision: what if you only want to ignore validation when the field isn't populated, or if it's populated and its value is the default value?

By providing an Ignore enum with values like IGNORE_IF_ZERO_VALUE and IGNORE_ALWAYS, Protovalidate lets you express your semantic requirements in easy-to-read code:

syntax="proto3";

message Request {
  string uri = 1 [
    // If no value is provided, skip validation.
    (buf.validate.field).ignore = IGNORE_IF_ZERO_VALUE,
    (buf.validate.field).string.uri = true
  ];
}

Ignore

Specifies how FieldRules.ignore behaves, depending on the field's value, and whether the field tracks presence.

IGNORE_UNSPECIFIED

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:

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:

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

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

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.

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];
}

KnownRegex

KnownRegex contains some well-known patterns.

KNOWN_REGEX_HTTP_HEADER_NAME

HTTP header name as defined by RFC 7230.

KNOWN_REGEX_HTTP_HEADER_VALUE

HTTP header value as defined by RFC 7230.