Documentation
¶
Overview ¶
Example ¶
person := &pb.Person{ Id: 1234, Email: "protovalidate@buf.build", Name: "Buf Build", Home: &pb.Coordinates{ Lat: 27.380583333333334, Lng: 33.631838888888886, }, } err := Validate(person) fmt.Println("valid:", err) person.Email = "not an email" err = Validate(person) fmt.Println("invalid:", err)
Output: valid: <nil> invalid: validation error: - email: value must be a valid email address [string.email]
Index ¶
- func FieldPathString(path *validate.FieldPath) string
- func Validate(msg proto.Message) error
- type CompilationError
- type RuntimeError
- type ValidationError
- type Validator
- type ValidatorOption
- func WithAllowUnknownFields() ValidatorOption
- func WithDisableLazy() ValidatorOption
- func WithExtensionTypeResolver(extensionTypeResolver protoregistry.ExtensionTypeResolver) ValidatorOption
- func WithFailFast() ValidatorOption
- func WithMessageDescriptors(descriptors ...protoreflect.MessageDescriptor) ValidatorOption
- func WithMessages(messages ...proto.Message) ValidatorOption
- type Violation
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FieldPathString ¶ added in v0.8.0
FieldPathString takes a FieldPath and encodes it to a string-based dotted field path.
func Validate ¶ added in v0.7.2
Validate uses a global instance of Validator constructed with no ValidatorOptions and calls its Validate function. For the vast majority of validation cases, using this global function is safe and acceptable. If you need to provide i.e. a custom ExtensionTypeResolver, you'll need to construct a Validator.
Types ¶
type CompilationError ¶
type CompilationError struct {
// contains filtered or unexported fields
}
A CompilationError is returned if a CEL expression cannot be compiled & type-checked or if invalid standard constraints are applied.
func (*CompilationError) Error ¶ added in v0.9.0
func (err *CompilationError) Error() string
func (*CompilationError) Unwrap ¶ added in v0.9.0
func (err *CompilationError) Unwrap() error
type RuntimeError ¶
type RuntimeError struct {
// contains filtered or unexported fields
}
A RuntimeError is returned if a valid CEL expression evaluation is terminated. The two built-in reasons are 'no_matching_overload' when a CEL function has no overload for the types of the arguments or 'no_such_field' when a map or message does not contain the desired field.
func (*RuntimeError) Error ¶ added in v0.9.0
func (err *RuntimeError) Error() string
func (*RuntimeError) Unwrap ¶ added in v0.9.0
func (err *RuntimeError) Unwrap() error
type ValidationError ¶
type ValidationError struct {
Violations []*Violation
}
A ValidationError is returned if one or more constraint violations were detected.
Example ¶
validator, err := New() if err != nil { log.Fatal(err) } loc := &pb.Coordinates{Lat: 999.999} err = validator.Validate(loc) var valErr *ValidationError if ok := errors.As(err, &valErr); ok { violation := valErr.Violations[0] fmt.Println(violation.Proto.GetField().GetElements()[0].GetFieldName(), violation.Proto.GetConstraintId()) fmt.Println(violation.RuleValue, violation.FieldValue) }
Output: lat double.gte_lte -90 999.999
Example (Localized) ¶
validator, err := New() if err != nil { log.Fatal(err) } type ErrorInfo struct { FieldName string RuleValue any FieldValue any } var ruleMessages = map[string]string{ "string.email_empty": "{{.FieldName}}: メールアドレスは空であってはなりません。\n", "string.pattern": "{{.FieldName}}: 値はパターン「{{.RuleValue}}」一致する必要があります。\n", "uint64.gt": "{{.FieldName}}: 値は{{.RuleValue}}を超える必要があります。(価値:{{.FieldValue}})\n", } loc := &pb.Person{Id: 900} err = validator.Validate(loc) var valErr *ValidationError if ok := errors.As(err, &valErr); ok { for _, violation := range valErr.Violations { _ = template. Must(template.New("").Parse(ruleMessages[violation.Proto.GetConstraintId()])). Execute(os.Stdout, ErrorInfo{ FieldName: violation.Proto.GetField().GetElements()[0].GetFieldName(), RuleValue: violation.RuleValue.Interface(), FieldValue: violation.FieldValue.Interface(), }) } }
Output: id: 値は999を超える必要があります。(価値:900) email: メールアドレスは空であってはなりません。 name: 値はパターン「^[[:alpha:]]+( [[:alpha:]]+)*$」一致する必要があります。
func (*ValidationError) Error ¶ added in v0.9.0
func (err *ValidationError) Error() string
func (*ValidationError) ToProto ¶ added in v0.9.0
func (err *ValidationError) ToProto() *validate.Violations
ToProto converts this error into its proto.Message form.
type Validator ¶
type Validator interface { // Validate checks that message satisfies its constraints. Constraints are // defined within the Protobuf file as options from the buf.validate // package. An error is returned if the constraints are violated // (ValidationError), the evaluation logic for the message cannot be built // (CompilationError), or there is a type error when attempting to evaluate // a CEL expression associated with the message (RuntimeError). Validate(msg proto.Message) error }
func New ¶
func New(options ...ValidatorOption) (Validator, error)
New creates a Validator with the given options. An error may occur in setting up the CEL execution environment if the configuration is invalid. See the individual ValidatorOption for how they impact the fallibility of New.
type ValidatorOption ¶
type ValidatorOption func(*config)
A ValidatorOption modifies the default configuration of a Validator. See the individual options for their defaults and affects on the fallibility of configuring a Validator.
func WithAllowUnknownFields ¶ added in v0.7.0
func WithAllowUnknownFields() ValidatorOption
WithAllowUnknownFields specifies if the presence of unknown field constraints should cause compilation to fail with an error. When set to false, an unknown field will simply be ignored, which will cause constraints to silently not be applied. This condition may occur if a predefined constraint definition isn't present in the extension type resolver, or when passing dynamic messages with standard constraints defined in a newer version of protovalidate. The default value is false, to prevent silently-incorrect validation from occurring.
func WithDisableLazy ¶
func WithDisableLazy() ValidatorOption
WithDisableLazy prevents the Validator from lazily building validation logic for a message it has not encountered before. Disabling lazy logic additionally eliminates any internal locking as the validator becomes read-only.
Note: All expected messages must be provided by WithMessages or WithMessageDescriptors during initialization.
Example ¶
person := &pb.Person{ Id: 1234, Email: "protovalidate@buf.build", Name: "Buf Build", Home: &pb.Coordinates{ Lat: 27.380583333333334, Lng: 33.631838888888886, }, } validator, err := New( WithMessages(&pb.Coordinates{}), WithDisableLazy(), ) if err != nil { log.Fatal(err) } err = validator.Validate(person.GetHome()) fmt.Println("person.Home:", err) err = validator.Validate(person) fmt.Println("person:", err)
Output: person.Home: <nil> person: compilation error: no evaluator available for tests.example.v1.Person
func WithExtensionTypeResolver ¶ added in v0.7.0
func WithExtensionTypeResolver(extensionTypeResolver protoregistry.ExtensionTypeResolver) ValidatorOption
WithExtensionTypeResolver specifies a resolver to use when reparsing unknown extension types. When dealing with dynamic file descriptor sets, passing this option will allow extensions to be resolved using a custom resolver.
To ignore unknown extension fields, use the WithAllowUnknownFields option. Note that this may result in messages being treated as valid even though not all constraints are being applied.
func WithFailFast ¶
func WithFailFast() ValidatorOption
WithFailFast specifies whether validation should fail on the first constraint violation encountered or if all violations should be accumulated. By default, all violations are accumulated.
Example ¶
loc := &pb.Coordinates{Lat: 999.999, Lng: -999.999} validator, err := New() if err != nil { log.Fatal(err) } err = validator.Validate(loc) fmt.Println("default:", err) validator, err = New(WithFailFast()) if err != nil { log.Fatal(err) } err = validator.Validate(loc) fmt.Println("fail fast:", err)
Output: default: validation error: - lat: value must be greater than or equal to -90 and less than or equal to 90 [double.gte_lte] - lng: value must be greater than or equal to -180 and less than or equal to 180 [double.gte_lte] fail fast: validation error: - lat: value must be greater than or equal to -90 and less than or equal to 90 [double.gte_lte]
func WithMessageDescriptors ¶ added in v0.9.0
func WithMessageDescriptors(descriptors ...protoreflect.MessageDescriptor) ValidatorOption
WithMessageDescriptors allows warming up the Validator with message descriptors that are expected to be validated. Messages included transitively (i.e., fields with message values) are automatically handled.
Example ¶
pbType, err := protoregistry.GlobalTypes.FindMessageByName("tests.example.v1.Person") if err != nil { log.Fatal(err) } validator, err := New( WithMessageDescriptors( pbType.Descriptor(), ), ) if err != nil { log.Fatal(err) } person := &pb.Person{ Id: 1234, Email: "protovalidate@buf.build", Name: "Protocol Buffer", } err = validator.Validate(person) fmt.Println(err)
Output: <nil>
func WithMessages ¶
func WithMessages(messages ...proto.Message) ValidatorOption
WithMessages allows warming up the Validator with messages that are expected to be validated. Messages included transitively (i.e., fields with message values) are automatically handled.
Example ¶
validator, err := New( WithMessages(&pb.Person{}), ) if err != nil { log.Fatal(err) } person := &pb.Person{ Id: 1234, Email: "protovalidate@buf.build", Name: "Protocol Buffer", } err = validator.Validate(person) fmt.Println(err)
Output: <nil>
type Violation ¶ added in v0.8.0
type Violation struct { // Proto contains the violation's proto.Message form. Proto *validate.Violation // FieldValue contains the value of the specific field that failed // validation. If there was no value, this will contain an invalid value. FieldValue protoreflect.Value // FieldDescriptor contains the field descriptor corresponding to the // field that failed validation. FieldDescriptor protoreflect.FieldDescriptor // RuleValue contains the value of the rule that specified the failed // constraint. Not all constraints have a value; only standard and // predefined constraints have rule values. In violations caused by other // kinds of constraints, like custom contraints, this will contain an // invalid value. RuleValue protoreflect.Value // RuleDescriptor contains the field descriptor corresponding to the // rule that failed validation. RuleDescriptor protoreflect.FieldDescriptor }
Violation represents a single instance where a validation rule was not met. It provides information about the field that caused the violation, the specific unfulfilled constraint, and a human-readable error message.