Merge pull request #847 from SpineEventEngine/use-field-paths

Talk about `field.path` in API of validation options

Author: yevhenii-nadtochii

dependencies.md

@@ -1,6 +1,6 @@
 
 
-# Dependencies of `io.spine:spine-base:2.0.0-SNAPSHOT.234`
+# Dependencies of `io.spine:spine-base:2.0.0-SNAPSHOT.235`
 
 ## Runtime
 1.  **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2.
@@ -845,4 +845,4 @@
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Dec 20 11:30:40 CET 2024** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
+This report was generated on **Tue Jan 07 13:42:22 CET 2025** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).

pom.xml

@@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject.
  -->
 <groupId>io.spine</groupId>
 <artifactId>base</artifactId>
-<version>2.0.0-SNAPSHOT.234</version>
+<version>2.0.0-SNAPSHOT.235</version>
 
 <inceptionYear>2015</inceptionYear>
 

src/main/proto/spine/options.proto

@@ -148,8 +148,7 @@ extend google.protobuf.FieldOptions {
     //
     bool validate = 73821;
 
-    // See `IfInvalidOption`.
-    IfInvalidOption if_invalid = 73822;
+    // Reserved 73822 for deleted `(if_invalid)` option.
 
     // See `GoesOption`.
     GoesOption goes = 73823;
@@ -361,7 +360,7 @@ extend google.protobuf.MessageOptions {
     // ```
     // message GoesOption {
     //   // The default error message.
-    //   option (default_message) = "The field `${goes.companion}` must also be set when `${field.name}` is set.";
+    //   option (default_message) = "The field `${goes.companion}` must also be set when `${field.path}` is set.";
     // }
     // ```
     //
@@ -372,7 +371,7 @@ extend google.protobuf.MessageOptions {
 
     // The constraint to require at least one of the fields or a combination of fields.
     //
-    // Unlike the `required` field constraint which always require corresponding field,
+    // Unlike the `required` field constraint which always requires corresponding field,
     // this message option allows to require alternative fields or a combination of them as
     // an alternative. Field names and `oneof` group names are acceptable.
     //
@@ -650,7 +649,7 @@ extend google.protobuf.ServiceOptions {
 message IfMissingOption {
 
     // The default error message.
-    option (default_message) = "The field `${parent.type}.${field.name}` of the type `${field.type}` must have a value.";
+    option (default_message) = "The field `${parent.type}.${field.path}` of the type `${field.type}` must have a value.";
 
     // A user-defined validation error format message.
     //
@@ -662,17 +661,17 @@ message IfMissingOption {
     //
     // The specified message may include the following placeholders:
     //
-    // 1. `${field.name}` – the field name.
+    // 1. `${field.path}` – the field path.
     // 2. `${field.type}` – the fully qualified name of the field type.
-    // 3. `${parent.type}` – the fully qualified name of the field declaring type.
+    // 3. `${parent.type}` – the fully qualified name of the validated message.
     //
     // The placeholders will be replaced at runtime when the error is constructed.
     //
     // Example: Using the `(if_missing)` option.
     //
     //    message Student {
     //        Name name = 1 [(required) = true,
-    //                       (if_missing).error_msg = "The `${field.name}` field is mandatory for `${parent.type}`."];
+    //                       (if_missing).error_msg = "The `${field.path}` field is mandatory for `${parent.type}`."];
     //    }
     //
     string error_msg = 2;
@@ -696,7 +695,7 @@ message IfMissingOption {
 message MinOption {
 
     // The default error message.
-    option (default_message) = "The field `${parent.type}.${field.name}` must be ${max.operator} ${min.value}.";
+    option (default_message) = "The field `${parent.type}.${field.path}` must be ${max.operator} ${min.value}.";
 
     // The string representation of the minimum field value.
     string value = 1;
@@ -715,9 +714,9 @@ message MinOption {
     // The specified message may include the following placeholders:
     //
     // 1. `${field.value}` - the field value.
-    // 2. `${field.name}` – the field name.
+    // 2. `${field.path}` – the field path.
     // 3. `${field.type}` – the fully qualified name of the field type.
-    // 4. `${parent.type}` – the fully qualified name of the field declaring type.
+    // 4. `${parent.type}` – the fully qualified name of the validated message.
     // 5. `${min.value}` – the specified minimum `value`.
     // 6. `${min.operator}` – if `exclusive` is set to `true`, this placeholder equals to ">".
     //    Otherwise, ">=".
@@ -742,7 +741,7 @@ message MinOption {
 message MaxOption {
 
     // The default error message.
-    option (default_message) = "The field `${parent.type}.${field.name}` must be ${max.operator} ${max.value}.";
+    option (default_message) = "The field `${parent.type}.${field.path}` must be ${max.operator} ${max.value}.";
 
     // The string representation of the maximum field value.
     string value = 1;
@@ -760,10 +759,10 @@ message MaxOption {
     //
     // The specified message may include the following placeholders:
     //
-    // 1. `${field.name}` – the field name.
+    // 1. `${field.path}` – the field path.
     // 2. `${field.value}` - the field value.
     // 3. `${field.type}` – the fully qualified name of the field type.
-    // 4. `${parent.type}` – the fully qualified name of the field declaring type.
+    // 4. `${parent.type}` – the fully qualified name of the validated message.
     // 5. `${max.value}` – the specified maximum `value`.
     // 6. `${max.operator}` – if `exclusive` is set to `true`, this placeholder equals to "<".
     //    Otherwise, "<=".
@@ -788,7 +787,7 @@ message MaxOption {
 message PatternOption {
 
     // The default error message.
-    option (default_message) = "The `${parent.type}.${field.name}` field must match the regular expression `${regex.pattern}` (modifiers: `${regex.modifiers}`). The passed value: `${field.value}`.";
+    option (default_message) = "The `${parent.type}.${field.path}` field must match the regular expression `${regex.pattern}` (modifiers: `${regex.modifiers}`). The passed value: `${field.value}`.";
 
     // The regular expression to match.
     string regex = 1;
@@ -806,10 +805,10 @@ message PatternOption {
     //
     // The specified message may include the following placeholders:
     //
-    // 1. `${field.name}` – the field name.
+    // 1. `${field.path}` – the field path.
     // 2. `${field.value}` - the field value.
     // 3. `${field.type}` – the fully qualified name of the field type.
-    // 4. `${parent.type}` – the fully qualified name of the field declaring type.
+    // 4. `${parent.type}` – the fully qualified name of the validated message.
     // 5. `${regex.pattern}` – the specified regex pattern.
     // 6. `${regex.modifiers}` – the specified modifiers, if any. For example, `[dot_all, unicode]`.
     //
@@ -869,42 +868,6 @@ message PatternOption {
     }
 }
 
-// Specifies the message to show if a validated field happens to be invalid.
-//
-// It is applicable only to fields marked with `(validate)`.
-//
-message IfInvalidOption {
-
-    // The default error message.
-    option (default_message) = "The field `${parent.type}.${field.name}` of the type `${field.type}` is invalid. The field value: `${field.value}`.";
-
-    // A user-defined validation error format message.
-    //
-    // Use `error_msg` instead.
-    //
-    string msg_format = 1 [deprecated = true];
-
-    // A user-defined error message.
-    //
-    // The specified message may include the following placeholders:
-    //
-    // 1. `${field.name}` – the field name.
-    // 2. `${field.value}` - the field value.
-    // 3. `${field.type}` – the fully qualified name of the field type.
-    // 4. `${parent.type}` – the fully qualified name of the field declaring type.
-    //
-    // The placeholders will be replaced at runtime when the error is constructed.
-    //
-    // Example: Using the `(if_invalid)` option.
-    //
-    //     message Transaction {
-    //         TransactionDetails details = 1 [(validate) = true,
-    //                                         (if_invalid).error_msg = "The `${field.name}` field is invalid."];
-    //    }
-    //
-    string error_msg = 2;
-}
-
 // Specifies that another field must be present if the option's target field is present.
 //
 // Unlike the `required_field` that handles combination of required fields, this option is useful
@@ -929,7 +892,7 @@ message IfInvalidOption {
 message GoesOption {
 
     // The default error message.
-    option (default_message) = "The field `${goes.companion}` must also be set when `${field.name}` is set in `${parent.type}`.";
+    option (default_message) = "The field `${goes.companion}` must also be set when `${field.path}` is set in `${parent.type}`.";
 
     // The name of the companion field whose presence is required for this field to be valid.
     string with = 1;
@@ -941,10 +904,10 @@ message GoesOption {
     //
     // The specified message may include the following placeholders:
     //
-    // 1. `${field.name}` – the field name.
+    // 1. `${field.path}` – the field path.
     // 2. `${field.value}` – the field value.
     // 3. `${field.type}` – the fully qualified name of the field type.
-    // 4. `${parent.type}` – the fully qualified name of the field declaring type.
+    // 4. `${parent.type}` – the fully qualified name of the validated message.
     // 5. `${goes.companion}` – the name of the companion specified in `with`.
     //
     // The placeholders will be replaced at runtime when the error is constructed.
@@ -1121,17 +1084,17 @@ message CompareByOption {
 message IfSetAgainOption {
 
     // The default error message.
-    option (default_message) = "The field `${parent.type}.${field.name}` of the type `${field.type}` already has the value `${field.value}` and cannot be reassigned to `${field.proposed_value}`.";
+    option (default_message) = "The field `${parent.type}.${field.path}` of the type `${field.type}` already has the value `${field.value}` and cannot be reassigned to `${field.proposed_value}`.";
 
     // A user-defined error message.
     //
     // The specified message may include the following placeholders:
     //
-    // 1. `${field.name}` – the field name.
+    // 1. `${field.path}` – the field path.
     // 2. `${field.type}` – the fully qualified name of the field type.
     // 3. `${field.value}` – the current field value.
     // 4. `${field.proposed_value}` – the value, which was attempted to be set.
-    // 5. `${parent.type}` – the fully qualified name of the field declaring type.
+    // 5. `${parent.type}` – the fully qualified name of the validated message.
     //
     // The placeholders will be replaced at runtime when the error is constructed.
     //
@@ -1152,17 +1115,17 @@ message IfSetAgainOption {
 message IfHasDuplicatesOption {
 
     // The default error message.
-    option (default_message) = "The field `${parent.type}.${field.name}` of the type `${field.type}` must not contain duplicates. The duplicates found: `${field.duplicates}`.";
+    option (default_message) = "The field `${parent.type}.${field.path}` of the type `${field.type}` must not contain duplicates. The duplicates found: `${field.duplicates}`.";
 
     // A user-defined error message.
     //
     // The specified message may include the following placeholders:
     //
-    // 1. `${field.name}` – the field name.
+    // 1. `${field.path}` – the field path.
     // 2. `${field.type}` – the fully qualified name of the field type.
     // 3. `${field.value}` – the field value (the whole collection).
     // 4. `${field.duplicates}` – the duplicates found (elements that occur more than once).
-    // 5. `${parent.type}` – the fully qualified name of the field declaring type.
+    // 5. `${parent.type}` – the fully qualified name of the validated message.
     //
     // The placeholders will be replaced at runtime when the error is constructed.
     //
@@ -1184,7 +1147,7 @@ message IfHasDuplicatesOption {
 message RangeOption {
 
     // The default error message.
-    option (default_message) = "The field `${parent.type}.${field.name}` must be within the following range: `${range.value}`.";
+    option (default_message) = "The field `${parent.type}.${field.path}` must be within the following range: `${range.value}`.";
 
     // The string representation of the range.
     //
@@ -1212,10 +1175,10 @@ message RangeOption {
     //
     // The specified message may include the following placeholders:
     //
-    // 1. `${field.name}` – the field name.
+    // 1. `${field.path}` – the field path.
     // 2. `${field.value}` - the field value.
     // 3. `${field.type}` – the fully qualified name of the field type.
-    // 4. `${parent.type}` – the fully qualified name of the field declaring type.
+    // 4. `${parent.type}` – the fully qualified name of the validated message.
     // 5. `${range.value}` – the specified range.
     //
     // The placeholders will be replaced at runtime when the error is constructed.

version.gradle.kts

@@ -24,4 +24,4 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-val versionToPublish: String by extra("2.0.0-SNAPSHOT.234")
+val versionToPublish: String by extra("2.0.0-SNAPSHOT.235")