From e7146cde34593f78ddd8a5bec685ab24ef10b473 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Fri, 9 Oct 2026 12:10:21 +0900 Subject: [PATCH 1/5] Add guidance on reporting errors in implementations --- .github/CONTRIBUTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9c70bb63..625eb51f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -207,6 +207,19 @@ The environment itself is declared in any contribution that introduces a new function or variable must add its signature there. +### Reporting errors + +A failed violation is reported to the user as the error type for the language with a string message. +The error type should provide structured access to the violations, minimally as the language's +protobuf messages for validate.proto itself, though usually it is useful to provide a higher level +wrapper for additional features like accessing failed fields via reflection. + +The string message should be a summary of the violations rather than describing the entire +structrued violations. For example, a common format is to print the first validation error message, +and if there are more violations, the count of remaining violations, e.g., + +`user.email: must be a valid email address [string.email], and 2 more violations` + ## Questions? If you have any questions, please don't hesitate to create an issue, and we'll From db5a23e4126b8ec05e79e211e18c48dd26f80c81 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Sat, 10 Oct 2026 11:33:05 +0900 Subject: [PATCH 2/5] fixes --- .github/CONTRIBUTING.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 625eb51f..536774a8 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -210,15 +210,20 @@ signature there. ### Reporting errors A failed violation is reported to the user as the error type for the language with a string message. -The error type should provide structured access to the violations, minimally as the language's +The error type must provide structured access to the violations, minimally as the language's protobuf messages for validate.proto itself, though usually it is useful to provide a higher level wrapper for additional features like accessing failed fields via reflection. The string message should be a summary of the violations rather than describing the entire -structrued violations. For example, a common format is to print the first validation error message, +structured violations. For example, a common format is to print the first validation error message, and if there are more violations, the count of remaining violations, e.g., -`user.email: must be a valid email address [string.email], and 2 more violations` +`user.email: must be a valid email address, and 2 more violations` + +Only the message should be printed when available, and when not, the rule ID should be printed. +If neither is available, print `[unknown]`. + +An option may be provided to generate a message string containing all errors instead of a summary. ## Questions? From 4122d5590fc7c6ab09f33116bcbbd46a7f8026ef Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Tue, 13 Oct 2026 15:31:54 +0900 Subject: [PATCH 3/5] Reword --- .github/CONTRIBUTING.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 536774a8..e52d8893 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -209,22 +209,22 @@ signature there. ### Reporting errors -A failed violation is reported to the user as the error type for the language with a string message. -The error type must provide structured access to the violations, minimally as the language's -protobuf messages for validate.proto itself, though usually it is useful to provide a higher level -wrapper for additional features like accessing failed fields via reflection. +All validation failures found during validation must be reported to the user via the +language's error mechanism. This error must include a string message that contains the +field name with the first validation failure found, the rule ID and description of that +validation failure, and a count of the remaining validation failures. The error may also +contain a string message that lists the field names, rule IDs and descriptions of all validation failures. -The string message should be a summary of the violations rather than describing the entire -structured violations. For example, a common format is to print the first validation error message, -and if there are more violations, the count of remaining violations, e.g., +The error must provide access to all validation failures found during validation. How these validation failures +are accessed is language-specific. + +An example error message string: `user.email: must be a valid email address, and 2 more violations` Only the message should be printed when available, and when not, the rule ID should be printed. If neither is available, print `[unknown]`. -An option may be provided to generate a message string containing all errors instead of a summary. - ## Questions? If you have any questions, please don't hesitate to create an issue, and we'll From 03d36d8eb3dcbbd93338b412f77e093693889d86 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Thu, 15 Oct 2026 12:52:58 +0900 Subject: [PATCH 4/5] allow limiting --- .github/CONTRIBUTING.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index e52d8893..3140676c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -209,14 +209,19 @@ signature there. ### Reporting errors -All validation failures found during validation must be reported to the user via the -language's error mechanism. This error must include a string message that contains the -field name with the first validation failure found, the rule ID and description of that -validation failure, and a count of the remaining validation failures. The error may also -contain a string message that lists the field names, rule IDs and descriptions of all validation failures. - -The error must provide access to all validation failures found during validation. How these validation failures -are accessed is language-specific. +All validation failures found during validation must be reported to the user via +the language's error mechanism. This error must include a string message that +contains the field name with the first validation failure found, the rule ID or +description of that validation failure, and a count of the remaining validation +failures. The error may also contain a string message that lists the field names, +rule IDs and descriptions of all detected validation failures. + +A protovalidate implementation may choose to limit the number of validation failures +detected and reported during validation. If an implementation does so, it must +indicate in the error message that there are unreported validation failures. + +The error must provide access to all validation failures (up to any imposed limit) +found during validation. How these validation failures are accessed is language-specific. An example error message string: From 4ff2b9b4ed9699b26df63812601acf92ce1cfaac Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Fri, 23 Oct 2026 11:10:50 +0900 Subject: [PATCH 5/5] Reduce scope --- .github/CONTRIBUTING.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 3140676c..ff887a65 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -207,28 +207,28 @@ The environment itself is declared in any contribution that introduces a new function or variable must add its signature there. -### Reporting errors +### Reporting validation failures -All validation failures found during validation must be reported to the user via -the language's error mechanism. This error must include a string message that -contains the field name with the first validation failure found, the rule ID or -description of that validation failure, and a count of the remaining validation -failures. The error may also contain a string message that lists the field names, -rule IDs and descriptions of all detected validation failures. +Validation failures must be reported to the user, either via the language's +error mechanism or as a result value that the user checks, whichever is +idiomatic for the language. -A protovalidate implementation may choose to limit the number of validation failures -detected and reported during validation. If an implementation does so, it must -indicate in the error message that there are unreported validation failures. +The error or result value must provide access to the structured failures: each +time a value does not meet a rule, the implementation provides a "violation" +that describes which rule failed, where it failed, and why. -The error must provide access to all validation failures (up to any imposed limit) -found during validation. How these validation failures are accessed is language-specific. +The error or result value may provide a single string representation, either +listing every violation or summarizing them, for example the first violation +and the number of remaining violations. -An example error message string: +Implementations may choose to limit the number of violations reported during +validation. Implementations may also provide an option to "fail fast", and +immediately return the result on the first rule violation encountered. -`user.email: must be a valid email address, and 2 more violations` - -Only the message should be printed when available, and when not, the rule ID should be printed. -If neither is available, print `[unknown]`. +The canonical representation of a violation is the Protobuf message +`buf.validate.Violation`. Implementations may wrap violations in their own type, +for example to add a string representation, access to the failing value, or +other conveniences, but must provide access to the canonical representation. ## Questions?