protovalidate

README

Notice

The import path for protovalidate-go has changed! Please change your import path(s) from github.com/bufbuild/protovalidate-go to buf.build/go/protovalidate.

protovalidate-go

Protovalidate provides standard annotations to validate common rules on messages and fields, as well as the ability to use CEL to write custom rules. It's the next generation of protoc-gen-validate, the only widely used validation library for Protobuf.

With Protovalidate, you can annotate your Protobuf messages with both standard and custom validation rules:

syntax = "proto3";

package banking.v1;

import "buf/validate/validate.proto";

message MoneyTransfer {
  string to_account_id = 1 [
    // Standard rule: `to_account_id` must be a UUID.
    (buf.validate.field).string.uuid = true
  ];

  string from_account_id = 2 [
    // Standard rule: `from_account_id` must be a UUID.
    (buf.validate.field).string.uuid = true
  ];

  // Custom rule: `to_account_id` and `from_account_id` can't be the same.
  option (buf.validate.message).cel = {
    id: "to_account_id.not.from_account_id"
    message: "to_account_id and from_account_id should not be the same value"
    expression: "this.to_account_id != this.from_account_id"
  };
}

Once you've added protovalidate-go to your project, validation is idiomatic Go:

if err = protovalidate.Validate(moneyTransfer); err != nil {
    // Handle failure.
}

Installation

[!TIP] The easiest way to get started with Protovalidate for RPC APIs are the quickstarts in Buf's documentation. They're available for both Connect and gRPC.

To install the package, use go get from within your Go module:

go get github.com/bufbuild/protovalidate-go

Documentation

Comprehensive documentation for Protovalidate is available in Buf's documentation library.

Highlights for Go developers include:

• The developer quickstart
• Comprehensive RPC quickstarts for Connect and gRPC
• A migration guide for protoc-gen-validate users

API documentation for Go is available on pkg.go.dev.

Additional Languages and Repositories

Protovalidate isn't just for Go! You might be interested in sibling repositories for other languages:

• protovalidate-java (Java)
• protovalidate-python (Python)
• protovalidate-cc (C++)
• protovalidate-es (TypeScript and JavaScript, coming soon!)

Additionally, protovalidate's core repository provides:

• Protovalidate's Protobuf API
• Conformance testing utilities for acceptance testing of protovalidate implementations

Contribution

We genuinely appreciate any help! If you'd like to contribute, check out these resources:

• Contributing Guidelines: Guidelines to make your contribution process straightforward and meaningful
• Conformance testing utilities: Utilities providing acceptance testing of protovalidate implementations
• Go conformance executor: Conformance testing executor for protovalidate-go

Related Sites

• Buf: Enterprise-grade Kafka and gRPC for the modern age
• Common Expression Language (CEL): The open-source technology at the core of Protovalidate

Legal

Offered under the Apache 2 license.

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, options ...ValidationOption) error
• type CompilationError
  • func (err *CompilationError) Error() string
  • func (err *CompilationError) Unwrap() error
• type Filter
• type FilterFunc
  • func (f FilterFunc) ShouldValidate(message protoreflect.Message, descriptor protoreflect.Descriptor) bool
• type Option
  • func WithFailFast() Option
  • func WithNowFunc(fn func() *timestamppb.Timestamp) Option
• type RuntimeError
  • func (err *RuntimeError) Error() string
  • func (err *RuntimeError) Unwrap() error
• type ValidationError
  • func (err *ValidationError) Error() string
  • func (err *ValidationError) ToProto() *validate.Violations
• type ValidationOption
  • func WithFilter(filter Filter) ValidationOption
• type Validator
  • func New(options ...ValidatorOption) (Validator, error)
• type ValidatorOption
  • func WithAllowUnknownFields() ValidatorOption
  • func WithDisableLazy() ValidatorOption
  • func WithExtensionTypeResolver(extensionTypeResolver protoregistry.ExtensionTypeResolver) ValidatorOption
  • func WithMessageDescriptors(descriptors ...protoreflect.MessageDescriptor) ValidatorOption
  • func WithMessages(messages ...proto.Message) ValidatorOption
• type Violation

Examples

• Package
• ValidationError
• ValidationError (Localized)
• WithDisableLazy
• WithFailFast
• WithMessageDescriptors
• WithMessages

Functions

func FieldPathString

func FieldPathString(path *validate.FieldPath) string

FieldPathString takes a FieldPath and encodes it to a string-based dotted field path.

func Validate

func Validate(msg proto.Message, options ...ValidationOption) error

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 rules are applied.

func (*CompilationError) Error

func (err *CompilationError) Error() string

func (*CompilationError) Unwrap

func (err *CompilationError) Unwrap() error

type Filter

type Filter interface {
	// ShouldValidate returns whether rules for a given message, field, or
	// oneof should be evaluated. For a message or oneof, this only determines
	// whether message-level or oneof-level rules should be evaluated, and
	// ShouldValidate will still be called for each field in the message. If
	// ShouldValidate returns false for a specific field, all rules nested
	// in submessages of that field will be skipped as well.
	// For a message, the message argument provides the message itself. For a
	// field or oneof, the message argument provides the containing message.
	ShouldValidate(message protoreflect.Message, descriptor protoreflect.Descriptor) bool
}

The Filter interface determines which rules should be validated.

type FilterFunc

type FilterFunc func(protoreflect.Message, protoreflect.Descriptor) bool

FilterFunc is a function type that implements the Filter interface, as a convenience for simple filters. A FilterFunc should follow the same semantics as the ShouldValidate method of Filter.

func (FilterFunc) ShouldValidate

func (f FilterFunc) ShouldValidate(
	message protoreflect.Message,
	descriptor protoreflect.Descriptor,
) bool

type Option

type Option interface {
	ValidatorOption
	ValidationOption
}

Option implements both ValidatorOption and ValidationOption, so it can be applied both to validator instances as well as individual validations.

func WithFailFast

func WithFailFast() Option

WithFailFast specifies whether validation should fail on the first rule 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 WithNowFunc

func WithNowFunc(fn func() *timestamppb.Timestamp) Option

WithNowFunc specifies the function used to derive the `now` variable in CEL expressions. By default, timestamppb.Now is used.

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

func (err *RuntimeError) Error() string

func (*RuntimeError) Unwrap

func (err *RuntimeError) Unwrap() error

type ValidationError

type ValidationError struct {
	Violations []*Violation
}

A ValidationError is returned if one or more rule 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.GetRuleId())
	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.GetRuleId()])).
			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

func (err *ValidationError) Error() string

func (*ValidationError) ToProto

func (err *ValidationError) ToProto() *validate.Violations

ToProto converts this error into its proto.Message form.

type ValidationOption

type ValidationOption interface {
	// contains filtered or unexported methods
}

A ValidationOption specifies per-validation configuration. See the individual options for their defaults and effects.

func WithFilter

func WithFilter(filter Filter) ValidationOption

WithFilter specifies a filter to use for this validation. A filter can control which fields are evaluated by the validator.

type Validator

type Validator interface {
	// Validate checks that message satisfies its rules. Rules are
	// defined within the Protobuf file as options from the buf.validate
	// package. An error is returned if the rules 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, options ...ValidationOption) error
}

Validator performs validation on any proto.Message values. The Validator is safe for concurrent use.

var (

	// GlobalValidator provides access to the global Validator instance that is
	// used by the [Validate] function. This is intended to be used by libraries
	// that use protovalidate. This Validator can be used as a default when the
	// user does not specify a Validator instance to use.
	//
	// Using the global Validator instance (either through [Validator] or via
	// GlobalValidator) will result in lower memory usage than using multiple
	// Validator instances, because each Validator instance has its own caches.
	GlobalValidator Validator = globalValidator{}
)

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 interface {
	// contains filtered or unexported methods
}

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

func WithAllowUnknownFields() ValidatorOption

WithAllowUnknownFields specifies if the presence of unknown field rules should cause compilation to fail with an error. When set to false, an unknown field will simply be ignored, which will cause rules to silently not be applied. This condition may occur if a predefined rule definition isn't present in the extension type resolver, or when passing dynamic messages with standard rules 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

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 rules are being applied.

func WithMessageDescriptors

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

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
	// rule. Not all rules have a value; only standard and
	// predefined rules have rule values. In violations caused by other
	// kinds of rules, 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 rule, and a human-readable error message.