protovalidate-java

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";
packageacme.user.v1;
import"buf/validate/validate.proto";
messageUser {
stringid=1 [(buf.validate.field).string.uuid = true];
uint32age=2 [(buf.validate.field).uint32.lte = 150]; // We can only hope.stringemail=3 [(buf.validate.field).string.email = true];
stringfirst_name=4 [(buf.validate.field).string.max_len = 64];
stringlast_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-java to your project, validation is idiomatic Java:

ValidationResultresult = validator.validate(message);
if (!result.isSuccess()) {
// Handle failure.
}

Installation

Tip

The easiest way to get started with Protovalidate for RPC APIs are the quickstarts in Buf's documentation. There's one available for Java and gRPC.

protovalidate-java is listed in Maven Central, which provides installation snippets for Gradle, Maven, and other package managers. In Gradle, it's:

dependencies {
implementation 'build.buf:protovalidate:<version>'
}

Documentation

Comprehensive documentation for Protovalidate is available at protovalidate.com.

Highlights for Java developers include:

• The developer quickstart
• A comprehensive RPC quickstart for Java and gRPC
• A migration guide for protoc-gen-validate users

Native rule evaluators (opt-out)

The standard rules can be evaluated either through CEL or through native Java code. Native evaluation is functionally identical (the conformance suite passes in both modes) but skips CEL compilation and runtime overhead for the rules it covers — a single validate() call on a complex message can run an order of magnitude faster and allocate ~10× less.

Native rules are opt-out. Disable them by configuring the validator:

Configconfig = Config.newBuilder().setEnableNativeRules(false).build();
Validatorvalidator = ValidatorFactory.newBuilder().withConfig(config).build();

Forward compatibility is preserved by a clone-and-clear contract: when protovalidate adds a new rule that this codebase hasn't yet implemented natively, the rule remains on the residual FieldRules and CEL enforces it. Native evaluation is an optimization, never a replacement.

Additional languages and repositories

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

• protovalidate-go (Go)
• protovalidate-python (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

Legal

Offered under the Apache 2 license.