Improve required standard constraint docs + conformance tests

proto/protovalidate-testing/buf/validate/conformance/cases/BUILD.bazel

@@ -28,6 +28,8 @@ proto_library(
         "numbers.proto",
         "oneofs.proto",
         "repeated.proto",
+        "required_field_proto2.proto",
+        "required_field_proto3.proto",
         "strings.proto",
         "wkt_any.proto",
         "wkt_duration.proto",

proto/protovalidate-testing/buf/validate/conformance/cases/oneofs.proto

@@ -48,6 +48,15 @@ message OneofRequired {
   }
 }
 
+message OneofRequiredWithRequiredField {
+  oneof o {
+    option (buf.validate.oneof).required = true;
+
+    string a = 1 [(buf.validate.field).required = true];
+    string b = 2;
+  }
+}
+
 message OneofIgnoreEmpty {
   oneof o {
     string x = 1 [
@@ -66,8 +75,8 @@ message OneofIgnoreEmpty {
     ];
     int32 z = 3 [
       (buf.validate.field).int32 = {
-        lte: 128,
-        gte: 256,
+        gte: 128,
+        lte: 256,
       },
       (buf.validate.field).ignore_empty = true
     ];

proto/protovalidate-testing/buf/validate/conformance/cases/required_field_proto2.proto

@@ -0,0 +1,56 @@
+// Copyright 2023 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto2";
+
+package buf.validate.conformance.cases;
+
+import "buf/validate/validate.proto";
+
+message RequiredProto2ScalarOptional {
+  optional string val = 1 [(buf.validate.field).required = true];
+}
+
+message RequiredProto2ScalarOptionalDefault {
+  optional string val = 1 [
+    (buf.validate.field).required = true,
+    default = "foo"
+  ];
+}
+
+message RequiredProto2ScalarRequired {
+  required string val = 1 [(buf.validate.field).required = true];
+}
+
+message RequiredProto2Message {
+  optional Msg val = 1 [(buf.validate.field).required = true];
+  message Msg {
+    optional string val = 1;
+  }
+}
+
+message RequiredProto2Oneof {
+  oneof val {
+    string a = 1 [(buf.validate.field).required = true];
+    string b = 2;
+  }
+}
+
+message RequiredProto2Repeated {
+  repeated string val = 1 [(buf.validate.field).required = true];
+}
+
+message RequiredProto2Map {
+  map<string, string> val = 1 [(buf.validate.field).required = true];
+}

proto/protovalidate-testing/buf/validate/conformance/cases/required_field_proto3.proto

@@ -0,0 +1,49 @@
+// Copyright 2023 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package buf.validate.conformance.cases;
+
+import "buf/validate/validate.proto";
+
+message RequiredProto3Scalar {
+  string val = 1 [(buf.validate.field).required = true];
+}
+
+message RequiredProto3OptionalScalar {
+  optional string val = 1 [(buf.validate.field).required = true];
+}
+
+message RequiredProto3Message {
+  Msg val = 1 [(buf.validate.field).required = true];
+  message Msg {
+    string val = 1;
+  }
+}
+
+message RequiredProto3OneOf {
+  oneof val {
+    string a = 1 [(buf.validate.field).required = true];
+    string b = 2;
+  }
+}
+
+message RequiredProto3Repeated {
+  repeated string val = 1 [(buf.validate.field).required = true];
+}
+
+message RequiredProto3Map {
+  map<string, string> val = 1 [(buf.validate.field).required = true];
+}

proto/protovalidate/buf/validate/validate.proto

@@ -91,21 +91,22 @@ message MessageConstraints {
 }
 
 // The `OneofConstraints` message type enables you to manage constraints for
-// oneof fields in your protobuf messages. Use the `required` constraint to ensure
-// that exactly one of the fields within a oneof is set; validation will fail
-// if none of the fields in the oneof are set:
+// oneof fields in your protobuf messages.
 message OneofConstraints {
-  // `required` is an optional boolean attribute that ensures that
-  // exactly one of the field options in a oneof is set; validation fails if
-  // no fields in the oneof are set.
+  // If `required` is true, exactly one field of the oneof must be present. A
+  // validation error is returned if no fields in the oneof are present. The
+  // field itself may still be a default value; further constraints
+  // should be placed on the fields themselves to ensure they are valid values,
+  // such as `min_len` or `gt`.
   //
   // ```proto
   // message MyMessage {
   //   oneof value {
-  //     // The field `a` or `b` must be set.
+  //     // 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;
-  //     optional string a = 1;
-  //     optional string b = 2;
+  //     string a = 1 [(buf.validate.field).string.min_len = 1];
+  //     string b = 2;
   //   }
   // }
   // ```
@@ -141,28 +142,37 @@ message FieldConstraints {
   // }
   // ```
   bool skipped = 24;
-  // `required` is an optional boolean attribute that specifies that
-  // this field must be set. If required is set to true, the field value must
-  // not be empty; otherwise, an error message will be generated.
+  // If `required` is true, the field must be populated. Field presence can be
+  // described as "serialized in the wire format," which follows the following rules:
   //
-  // Note that `required` validates that `repeated` fields are non-empty, that is
-  // setting a `repeated` field as `required` is equivalent to `repeated.min_items = 1`.
+  // - the following "nullable" fields must be explicitly set to be considered present:
+  //   - singular message fields (may be their empty value)
+  //   - member fields of a oneof (may be their default value)
+  //   - proto3 optional fields (may be their default value)
+  //   - proto2 scalar fields
+  // - proto3 scalar fields must be non-zero to be considered present
+  // - repeated and map fields must be non-empty to be considered present
   //
   // ```proto
   // message MyMessage {
-  //   // The field `value` must be set.
+  //   // The field `value` must be set to a non-null value.
   //   optional MyOtherMessage value = 1 [(buf.validate.field).required = true];
   // }
   // ```
   bool required = 25;
-  // `ignore_empty` specifies that the validation rules of this field should be
-  // evaluated only if the field isn't empty. If the field is empty, no validation
-  // rules are applied.
+  // If `ignore_empty` is true and applied to a non-nullable field (see
+  // `required` for more details), validation is skipped on the field if it is
+  // the default or empty value. Adding `ignore_empty` to a "nullable" field is
+  // a noop as these unset fields already skip validation (with the exception
+  // of `required`).
   //
   // ```proto
   // message MyRepeated {
-  //   // The field `value` validation rules should be evaluated only if the field isn't empty.
-  //   repeated string value = 1 [(buf.validate.field).ignore_empty = true];
+  //   // The field `value` min_len rule is only applied if the field isn't empty.
+  //   repeated string value = 1 [
+  //     (buf.validate.field).ignore_empty = true,
+  //     (buf.validate.field).min_len = 5
+  //   ];
   // }
   // ```
   bool ignore_empty = 26;