protovalidate-go

Protovalidate is the semantic validation library for Protobuf. It 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.

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

syntax = "proto3";

package acme.user.v1;

import "buf/validate/validate.proto";

message User {
  string id = 1 [(buf.validate.field).string.uuid = true];
  uint32 age = 2 [(buf.validate.field).uint32.lte = 150]; // We can only hope.
  string email = 3 [(buf.validate.field).string.email = true];
  string first_name = 4 [(buf.validate.field).string.max_len = 64];
  string last_name = 5 [(buf.validate.field).string.max_len = 64];

  option (buf.validate.message).cel = {
    id: "first_name_requires_last_name"
    message: "last_name must be present if first_name is present"
    expression: "!has(this.first_name) || has(this.last_name)"
  };
}

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

user := &userv1.User{ /* ... */ }
if err := protovalidate.Validate(user); err != nil {
    // Handle failure.
}

Installation

Tip

The easiest ways 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 buf.build/go/protovalidate

Documentation

Comprehensive documentation for Protovalidate is available at protovalidate.com.

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.

Native standard validation rules

Standard validation rules are evaluated by native Go implementations where available, falling back to CEL. This is enabled by default - pass the WithDisableNativeRules validator option to evaluate all standard rules through CEL instead.

The conformance Makefile target runs the conformance suite twice, once with native rules enabled and once with them disabled, to verify both paths produce identical results.

Additional languages and repositories

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

• protovalidate-java (Java)
• protovalidate-py (Python)
• protovalidate-cc (C++)
• protovalidate-es (TypeScript and JavaScript)

Additionally, protovalidate's core repository provides:

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

Contributing

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

Legal

Offered under the Apache 2 license.