|
| 1 | +// Copyright 2023 Buf Technologies, Inc. |
| 2 | +// |
| 3 | +// Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +// you may not use this file except in compliance with the License. |
| 5 | +// You may obtain a copy of the License at |
| 6 | +// |
| 7 | +// http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +// |
| 9 | +// Unless required by applicable law or agreed to in writing, software |
| 10 | +// distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +// See the License for the specific language governing permissions and |
| 13 | +// limitations under the License. |
| 14 | + |
| 15 | +syntax = "proto3"; |
| 16 | + |
| 17 | +package buf.validate; |
| 18 | + |
| 19 | +option go_package = "buf.build/gen/go/bufbuild/protovalidate/protocolbuffers/go/buf/validate"; |
| 20 | +option java_multiple_files = true; |
| 21 | +option java_outer_classname = "ExpressionProto"; |
| 22 | +option java_package = "build.buf.validate"; |
| 23 | + |
| 24 | +// `Constraint` represents a validation rule written in the Common Expression |
| 25 | +// Language (CEL) syntax. Each Constraint includes a unique identifier, an |
| 26 | +// optional error message, and the CEL expression to evaluate. For more |
| 27 | +// information on CEL, [see our documentation](https://github.com/bufbuild/protovalidate/blob/main/docs/cel.md). |
| 28 | +// |
| 29 | +// ```proto |
| 30 | +// message Foo { |
| 31 | +// option (buf.validate.message).cel = { |
| 32 | +// id: "foo.bar" |
| 33 | +// message: "bar must be greater than 0" |
| 34 | +// expression: "this.bar > 0" |
| 35 | +// }; |
| 36 | +// int32 bar = 1; |
| 37 | +// } |
| 38 | +// ``` |
| 39 | +message Constraint { |
| 40 | + // `id` is a string that serves as a machine-readable name for this Constraint. |
| 41 | + // It should be unique within its scope, which could be either a message or a field. |
| 42 | + string id = 1; |
| 43 | + |
| 44 | + // `message` is an optional field that provides a human-readable error message |
| 45 | + // for this Constraint when the CEL expression evaluates to false. If a |
| 46 | + // non-empty message is provided, any strings resulting from the CEL |
| 47 | + // expression evaluation are ignored. |
| 48 | + string message = 2; |
| 49 | + |
| 50 | + // `expression` is the actual CEL expression that will be evaluated for |
| 51 | + // validation. This string must resolve to either a boolean or a string |
| 52 | + // value. If the expression evaluates to false or a non-empty string, the |
| 53 | + // validation is considered failed, and the message is rejected. |
| 54 | + string expression = 3; |
| 55 | +} |
| 56 | + |
| 57 | +// `Violations` is a collection of `Violation` messages. This message type is returned by |
| 58 | +// protovalidate when a proto message fails to meet the requirements set by the `Constraint` validation rules. |
| 59 | +// Each individual violation is represented by a `Violation` message. |
| 60 | +message Violations { |
| 61 | + // `violations` is a repeated field that contains all the `Violation` messages corresponding to the violations detected. |
| 62 | + repeated Violation violations = 1; |
| 63 | +} |
| 64 | + |
| 65 | +// `Violation` represents a single instance where a validation rule, expressed |
| 66 | +// as a `Constraint`, was not met. It provides information about the field that |
| 67 | +// caused the violation, the specific constraint that wasn't fulfilled, and a |
| 68 | +// human-readable error message. |
| 69 | +// |
| 70 | +// ```json |
| 71 | +// { |
| 72 | +// "fieldPath": "bar", |
| 73 | +// "constraintId": "foo.bar", |
| 74 | +// "message": "bar must be greater than 0" |
| 75 | +// } |
| 76 | +// ``` |
| 77 | +message Violation { |
| 78 | + // `field_path` is a machine-readable identifier that points to the specific field that failed the validation. |
| 79 | + // This could be a nested field, in which case the path will include all the parent fields leading to the actual field that caused the violation. |
| 80 | + string field_path = 1; |
| 81 | + |
| 82 | + // `constraint_id` is the unique identifier of the `Constraint` that was not fulfilled. |
| 83 | + // This is the same `id` that was specified in the `Constraint` message, allowing easy tracing of which rule was violated. |
| 84 | + string constraint_id = 2; |
| 85 | + |
| 86 | + // `message` is a human-readable error message that describes the nature of the violation. |
| 87 | + // This can be the default error message from the violated `Constraint`, or it can be a custom message that gives more context about the violation. |
| 88 | + string message = 3; |
| 89 | + |
| 90 | + // `for_key` indicates whether the violation was caused by a map key, rather than a value. |
| 91 | + bool for_key = 4; |
| 92 | +} |
0 commit comments