From e48f41828bf86b6ea2262afc424e3efe34e881c8 Mon Sep 17 00:00:00 2001
From: Volodymyr Borysenko <borysoff21@gmail.com>
Date: Sun, 1 Nov 2026 17:53:01 -0800
Subject: [PATCH] Complete truncated example in validation.properties comments
 (#913)

---
 configuration/esapi/validation.properties      | 15 +++++++++++----
 src/test/resources/esapi/validation.properties | 15 +++++++++++----
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/configuration/esapi/validation.properties b/configuration/esapi/validation.properties
index 6a3363b03..33b992a93 100644
--- a/configuration/esapi/validation.properties
+++ b/configuration/esapi/validation.properties
@@ -1,17 +1,17 @@
 # The ESAPI validator does many security checks on input, such as canonicalization
 # and whitelist validation. Note that all of these validation rules are applied *after*
-# canonicalization. Double-encoded characters (even with different encodings involved,
+# canonicalization. Double-encoded characters (even with different encodings involved)
 # are never allowed.
 #
 # To use:
 #
 # First set up a pattern below. You can choose any name you want, prefixed by the word
-# "Validation." For example:
-#   Validation.Email=^[A-Za-z0-9._%-]+@[A-Za-z0-9.-]+\\.[a-zA-Z]{2,4}$
+# "Validator." For example:
+#   Validator.Email=^[A-Za-z0-9._%-]+@[A-Za-z0-9.-]+\\.[a-zA-Z]{2,4}$
 # 
 # Then you can validate in your code against the pattern like this:
 #     ESAPI.validator().isValidInput("User Email", input, "Email", maxLength, allowNull);
-# Where maxLength and allowNull are set for you needs, respectively.
+# Where maxLength and allowNull are set for your needs, respectively.
 #
 # But note, when you use boolean variants of validation functions, you lose critical 
 # canonicalization. It is preferable to use the "get" methods (which throw exceptions) 
@@ -19,6 +19,13 @@
 #  
 # try {
 #    someObject.setEmail(ESAPI.validator().getValidInput("User Email", input, "Email", maxLength, allowNull));
+# } catch (ValidationException e) {
+#    // The input did not match the "Email" pattern, so reject it.
+# }
+#
+# Here setEmail() receives the canonicalized input, not the raw input. Note that
+# getValidInput() can also throw IntrusionException, which is unchecked, when the
+# input looks like an attack (for example, multiple or mixed encoding).
 #
 Validator.SafeString=^[.\\p{Alnum}\\p{Space}]{0,1024}$
 Validator.Email=^[A-Za-z0-9._%'-]+@[A-Za-z0-9.-]+\\.[a-zA-Z]{2,4}$
diff --git a/src/test/resources/esapi/validation.properties b/src/test/resources/esapi/validation.properties
index cf36cbdb7..7bbb9e19e 100644
--- a/src/test/resources/esapi/validation.properties
+++ b/src/test/resources/esapi/validation.properties
@@ -13,18 +13,18 @@
 #
 # The ESAPI validator does many security checks on input, such as canonicalization
 # and whitelist validation. Note that all of these validation rules are applied *after*
-# canonicalization. Double-encoded characters (even with different encodings involved,
+# canonicalization. Double-encoded characters (even with different encodings involved)
 # are never allowed.
 #
 # To use:
 #
 # First set up a pattern below. You can choose any name you want, prefixed by the word
-# "Validation." For example:
-#   Validation.Email=^[A-Za-z0-9._%-]+@[A-Za-z0-9.-]+\\.[a-zA-Z]{2,4}$
+# "Validator." For example:
+#   Validator.Email=^[A-Za-z0-9._%-]+@[A-Za-z0-9.-]+\\.[a-zA-Z]{2,4}$
 # 
 # Then you can validate in your code against the pattern like this:
 #     ESAPI.validator().isValidInput("User Email", input, "Email", maxLength, allowNull);
-# Where maxLength and allowNull are set for you needs, respectively.
+# Where maxLength and allowNull are set for your needs, respectively.
 #
 # But note, when you use boolean variants of validation functions, you lose critical 
 # canonicalization. It is preferable to use the "get" methods (which throw exceptions)
@@ -32,6 +32,13 @@
 #  
 # try {
 #    someObject.setEmail(ESAPI.validator().getValidInput("User Email", input, "Email", maxLength, allowNull));
+# } catch (ValidationException e) {
+#    // The input did not match the "Email" pattern, so reject it.
+# }
+#
+# Here setEmail() receives the canonicalized input, not the raw input. Note that
+# getValidInput() can also throw IntrusionException, which is unchecked, when the
+# input looks like an attack (for example, multiple or mixed encoding).
 #
 Validator.SafeString=^[.\\p{Alnum}\\p{Space}]{0,1024}$
 #Given the discussion: https://github.com/ESAPI/esapi-java-legacy/issues/374, a better upper-bound for domain name