Skip to content

Protovalidate in gRPC and Java

This tutorial shows how to add Protovalidate to a Java RPC powered by gRPC:

  1. Adding the Protovalidate dependency.
  2. Annotating Protobuf files and regenerating code.
  3. Adding a Connect interceptor.
  4. Testing your validation logic.

Just need an example?

There's an example of Protovalidate for gRPC and Java in GitHub.

Prerequisites

  • Install the Buf CLI. If you already have, run buf --version to verify that you're using at least 1.32.0.
  • Have git and Java 11+ installed and in your $PATH.

  • Clone the buf-examples repo and navigate to the protovalidate/grpc-java/start directory:

    $ git clone git@github.com:bufbuild/buf-examples.git && cd buf-examples/protovalidate/grpc-java/start

Goal

This tutorial's CreateInvoice RPC doesn't have any input validation. Your goal is to pass a unit test verifying that you've added two validation rules using Protovalidate:

  1. Requests must provide an Invoice with a UUID invoice_id.
  2. Within the Invoice message, all of its repeated LineItem line_items must have unique combinations of product_id and unit_price.

Run the test now, and you can see that it fails:

$ ./gradlew test
InvoiceServerTest > InvoiceId is required FAILED
    org.opentest4j.AssertionFailedError at InvoiceServerTest.java:98
InvoiceServerTest > Two line items cannot have the same product_id and unit price FAILED
    org.opentest4j.AssertionFailedError at InvoiceServerTest.java:123

When this test passes, you've met your goal.

Run the server

Before you begin to code, verify that the example is working. Compile and run the server using its Gradle wrapper:

$ ./gradlew run

After a few seconds, you should see that it has started:

INFO: Server started on port 50051

In a second terminal window, use buf curl to send an invalid CreateInvoiceRequest:

$ buf curl \
    --data '{ "invoice": { "invoice_id": "" } }' \
    --protocol grpc \
    --http2-prior-knowledge \
    http://localhost:50051/invoice.v1.InvoiceService/CreateInvoice

The server should respond with the version number of the invoice that was created, despite the invalid request. That's what you're here to fix.

{
  "version": "1"
}

Before you start coding, take a few minutes to explore the code in the example.

Explore tutorial code

This tutorial uses the example in grpc-java/start. Following standard Java project structure, source code is in src/main. Tests are in src/test.

Protobuf

The project provides a single unary RPC:

proto/invoice/v1/invoice_service.proto
// InvoiceService is a simple CRUD service for managing invoices.
service InvoiceService {
  // CreateInvoice creates a new invoice.
  rpc CreateInvoice(CreateInvoiceRequest) returns (CreateInvoiceResponse);
}

CreateInvoiceRequest includes an invoice field that's an Invoice message. An Invoice has a repeated field of type LineItem:

proto/invoice/v1/invoice.proto (excerpt)
message Invoice {
  // invoice_id is a unique identifier for this invoice.
  string invoice_id = 1;
  // line_items represent individual items on this invoice.
  repeated LineItem line_items = 4;
}

// LineItem is an individual good or service added to an invoice.
message LineItem {
  // product_id is the unique identifier for the good or service on this line.
  string product_id = 2;

  // quantity is the unit count of the good or service provided.
  uint64 quantity = 3;
}

YAML

When you add Protovalidate, you'll update the following files:

  • buf.yaml: Protovalidate must be added as a dependency.
  • buf.gen.yaml: To avoid a common Go issue in projects using the Buf CLI's managed mode, you'll see how to exclude Protovalidate from package renaming.

Java

You'll be working in invoice.v1.InvoiceServer. It's an executable that runs a server on port 50051. You'll edit it to add a Protovalidate interceptor to gRPC.

Where's the service itself?

src/main/java/invoice/v1/InvoiceService.java provides InvoiceService, an implementation of the generated InvoiceServiceGrpc.InvoiceServiceImplBase. Its createInvoice function sends back a static response.

Now that you know your way around the example code, it's time to integrate Protovalidate.

Integrate Protovalidate

It's time to add Protovalidate to your project. It may be useful to read the Protovalidate overview and its quickstart before continuing.

Add Protovalidate dependency

Because Protovalidate is a publicly available Buf Schema Registry (BSR) module, it's simple to add it to any Buf CLI project.

  1. Open build.gradle.kts and verify that build.buf:protovalidate has already been added as a dependency. (In your own projects, you'd need to add it.)

    build.gradle
    dependencies {
    implementation(libs.annotation.api)
    implementation(libs.protobuf.java)
    implementation(libs.protovalidate)

    // Code omitted for brevity
}

  2. Add Protovalidate as a dependency to buf.yaml.

    buf.yaml
    # For details on buf.yaml configuration, visit https://buf.build/docs/configuration/v2/buf-yaml
version: v2
modules:
  - path: proto
+ deps:
+   - buf.build/bufbuild/protovalidate
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

  3. Update dependencies with the Buf CLI. You'll be warned that Protovalidate is declared but unused. That's fine.

    Updating CLI dependencies
    $ buf dep update
WARN    Module buf.build/bufbuild/protovalidate is declared in your buf.yaml deps but is unused...

  4. Because this example uses managed mode, exclude Protovalidate from any updates to java_package.

    buf.gen.yaml
    version: v2
inputs:
  - directory: src/main/proto
plugins:
  - remote: buf.build/protocolbuffers/java:v29.3
    out: src/main/java
  - remote: buf.build/grpc/java:v1.70.0
    out: src/main/java
managed:
  enabled: true
  override:
    - file_option: java_package_suffix
      value: gen
    - file_option: java_package_prefix
      value: ""
+ disable:
+   - file_option: java_package
+     module: buf.build/bufbuild/protovalidate

  5. Verify that configuration is complete by running buf generate. It should complete with no error.

Further reading and protoc

Learn more about incorporating Protovalidate and protoc support in the Adding protovalidate page.

Add a standard rule

You'll now add a standard rule to proto/invoice.proto to require that the invoice_id field is a UUID. Start by importing Protovalidate:

proto/invoice/v1/invoice.proto
syntax = "proto3";

package invoice.v1;

+ import "buf/validate/validate.proto";
import "google/protobuf/timestamp.proto";

You could use the required rule to verify that requests provide this field, but Protovalidate makes it easy to do more specific validations. Use string.uuid to declare that invoice_id must be present and a valid UUID.

proto/invoice/v1/invoice.proto
// Invoice is a collection of goods or services sold to a customer.
message Invoice {
  // invoice_id is a unique identifier for this invoice.
- string invoice_id = 1;
+ string invoice_id = 1 [
+   (buf.validate.field).string.uuid = true
+ ];

  // account_id is the unique identifier for the account purchasing goods.
  string account_id = 2;

  // invoice_date is the date for an invoice. It should represent a date and
  // have no values for time components.
  google.protobuf.Timestamp invoice_date = 3;

  // line_items represent individual items on this invoice.
  repeated LineItem line_items = 4;
}

Learn more about string and standard rules.

Enforce complex rules

In Invoice, the line_items field needs to meet two business rules:

  1. There should always be at least one LineItem.
  2. No two LineItems should ever share the same product_id and price.

Protovalidate can enforce both of these rules by combining a standard rule with a custom rule written in Common Expression Language (CEL).

First, use the min_items standard rule to require at least one LineItem:

proto/invoice.proto
// Invoice is a collection of goods or services sold to a customer.
message Invoice {
  // invoice_id is a unique identifier for this invoice.
  string invoice_id = 1 [
    (buf.validate.field).string.uuid = true
  ];

  // account_id is the unique identifier for the account purchasing goods.
  string account_id = 2;

  // invoice_date is the date for an invoice. It should represent a date and
  // have no values for time components.
  google.protobuf.Timestamp invoice_date = 3;

  // line_items represent individual items on this invoice.
- repeated LineItem line_items = 4;
+ repeated LineItem line_items = 4 [
+    (buf.validate.field).repeated.min_items = 1
+ ];
}

Next, use a CEL expression to add a custom rule. Use the map, string, and unique CEL functions to check that no combination of product_id and unit_price appears twice within the array of LineItems:

proto/invoice.proto
// Invoice is a collection of goods or services sold to a customer.
message Invoice {
  // invoice_id is a unique identifier for this invoice.
  string invoice_id = 1 [
    (buf.validate.field).string.uuid = true
  ];

  // account_id is the unique identifier for the account purchasing goods.
  string account_id = 2;

  // invoice_date is the date for an invoice. It should represent a date and
  // have no values for time components.
  google.protobuf.Timestamp invoice_date = 3;

  // line_items represent individual items on this invoice.
  repeated LineItem line_items = 4 [
-    (buf.validate.field).repeated.min_items = 1
+    (buf.validate.field).repeated.min_items = 1,
+
+    (buf.validate.field).cel = {
+      id: "line_items.logically_unique"
+      message: "line items must be unique combinations of product_id and unit_price"
+      expression: "this.map( it, it.product_id + '-' + string(it.unit_price) ).unique()"
+    }
  ];
}

You've added validation rules to your Protobuf. To enforce them, you still need to regenerate code and add a Protovalidate interceptor to your server.

Learn more about custom rules.

Compile Protobuf and Java

Next, compile your Protobuf and regenerate code, adding the Protovalidate options to all of your message descriptors:

$ buf generate

With regenerated code, your server should still compile and build. (If you're still running the server, stop it with Ctrl-c.)

$ ./gradlew run

After a few seconds, you should see that it has started:

INFO: Server started on port 50051

In a second terminal window, use buf curl to send the same invalid CreateInvoiceRequest:

$ buf curl \
    --data '{ "invoice": { "invoice_id": "" } }' \
    --protocol grpc \
    --http2-prior-knowledge \
    http://localhost:50051/invoice.v1.InvoiceService/CreateInvoice

The response may be a surprise: the server still considers the request valid and returns a version number for the new invoice:

{
  "version": "1"
}

The RPC is still successful because gRPC hasn't been told to validate inbound requests.

Note

No Connect or gRPC implementations automatically enforce Protovalidate rules. To enforce your validation rules, you'll need to add an interceptor.

Add a Protovalidate interceptor

The buf-examples repository provides a sample ValidationInterceptor class, a gRPC ServerInterceptor that's ready to use with Protovalidate. It inspects requests, runs Protovalidate, and returns a gRPC INVALID_ARGUMENT status on failure. Validation failure responses use the same response format as the Connect RPC Protovalidate interceptor.

Follow these steps to begin enforcing Protovalidate rules:

  1. In your first console window, use Ctrl-c to stop your server.

  2. In InvoiceServer, add necessary imports:

    InvoiceServer.java
    package invoice.v1;


+ import buf.build.example.protovalidate.ValidationInterceptor;
+ import build.buf.protovalidate.Validator;
import io.grpc.*;
import io.grpc.protobuf.services.ProtoReflectionServiceV1;

  3. In InvoiceServer's main method, instantiate a ValidationInterceptor and use it when creating InvoiceService's serviceDefinition:

    InvoiceService.java
    public static void main(String[] args) throws IOException, InterruptedException {
    final BindableService service = new InvoiceService();
-   final ServerServiceDefinition serviceDefinition = ServerInterceptors.intercept(service);
+   final ValidationInterceptor validationInterceptor = new ValidationInterceptor( new Validator() );
+   final ServerServiceDefinition serviceDefinition = ServerInterceptors.intercept(service, validationInterceptor);
    final InvoiceServer invoiceServer = new InvoiceServer(50051, InsecureServerCredentials.create(), serviceDefinition);

    invoiceServer.run();
    invoiceServer.awaitTermination();

}

  4. Stop (Ctrl-c) and restart your server:

    $ ./gradlew run

    After a few seconds, you should see that it has started:

    INFO: Server started on port 50051

Now that you've added the Protovalidate interceptor and restarted your server, try the buf curl command again:

$ buf curl \
    --data '{ "invoice": { "invoice_id": "" } }' \
    --protocol grpc \
    --http2-prior-knowledge \
    http://localhost:50051/invoice.v1.InvoiceService/CreateInvoice

This time, you should receive a block of JSON representing Protovalidate's enforcement of your rules. In the abridged excerpt below, you can see that it contains details about every field that violated Protovalidate rules:

Protovalidate violations
{
  "violations": [
    {
      "fieldPath": "invoice.invoice_id",
      "constraintId": "string.uuid_empty",
      "message": "value is empty, which is not a valid UUID"
    },
    {
      "fieldPath": "invoice.line_items",
      "constraintId": "repeated.min_items",
      "message": "value must contain at least 1 item(s)"
    }
  ]
}

Last, use buf curl to test the custom rule that checks for logically unique LineItems:

$ buf curl \
    --data '{ "invoice": { "invoice_id": "079a91c2-cb8b-4f01-9cf9-1b9c0abdd6d2", "line_items": [{"product_id": "A", "unit_price": "1" }, {"product_id": "A", "unit_price": "1" }] } }' \
    --protocol grpc \
    --http2-prior-knowledge \
    http://localhost:50051/invoice.v1.InvoiceService/CreateInvoice

You can see that this more complex expression is enforced at runtime:

Custom CEL rule violation
{
  "violations": [
    {
      "fieldPath": "invoice.line_items",
      "constraintId": "line_items.logically_unique",
      "message": "line items must be unique combinations of product_id and unit_price"
    }
  ]
}

You've now added Protovalidate to a gRPC in Java, but buf curl isn't a great way to make sure you're meeting all of your requirements. Next, you'll see one way to verify Protovalidate rules in tests.

Test Protovalidate errors

The starting code for this tutorial contains InvoiceServerTest, a JUnit 5 test. It starts a server with a Protovalidate interceptor and iterates through a series of test cases.

In the prior section, you saw that the violations list returned by Protovalidate follows a predictable structure. Each violation in the list is a Protobuf message named Violation, defined within Protovalidate itself.

The test already provides a convenient way to declare expected violations through a ViolationSpec class:

ViolationSpec in InvoiceServerTest.java
private static class ViolationSpec {
    public final String constraintId;
    public final String fieldPath;
    public final String message;

    public ViolationSpec(String constraintId, String fieldPath, String message) {
        this.constraintId = constraintId;
        this.fieldPath = fieldPath;
        this.message = message;
    }
}

Examine the highlighted lines in InvoiceServerTest, noting that the tests check for specific expected violations:

InvoiceServerTest.java
public class InvoiceServerTest {
    // Code omitted for brevity

    @Test
    @DisplayName("A valid invoice passes validation")
    public void testValidInvoice() {
        Invoice invoice = newValidInvoice();
        CreateInvoiceRequest req = CreateInvoiceRequest.newBuilder().setInvoice(invoice).build();
        assertDoesNotThrow(() -> invoiceClient.createInvoice(req));
    }

    @Test
    @DisplayName("InvoiceId is required")
    public void testInvoiceIdIsRequired() {
        Invoice invoice = Invoice.newBuilder().mergeFrom(newValidInvoice())
                .setInvoiceId("")
                .build();
        CreateInvoiceRequest req = CreateInvoiceRequest.newBuilder().setInvoice(invoice).build();

        StatusRuntimeException exception = assertThrows(StatusRuntimeException.class, () -> invoiceClient.createInvoice(req));
        checkStatusRuntimeException(exception, List.of(
                new ViolationSpec("string.uuid_empty", "invoice.invoice_id", "value is empty, which is not a valid UUID")
        ));
    }

    @Test
    @DisplayName("Two line items cannot have the same product_id and unit price")
    public void testTwoLineItemsCannotHaveTheSameProductIdAndUnitPrice() {
        Invoice template = newValidInvoice();
        Invoice invoice = Invoice.newBuilder().mergeFrom(template)
                .setLineItems(1,
                        LineItem.newBuilder()
                                .mergeFrom(template.getLineItems(1))
                                .setLineItemId(template.getLineItems(0).getLineItemId())
                                .setUnitPrice(template.getLineItems(0).getUnitPrice())
                )
                .build();

        CreateInvoiceRequest req = CreateInvoiceRequest.newBuilder().setInvoice(invoice).build();

        StatusRuntimeException exception = assertThrows(StatusRuntimeException.class, () -> invoiceClient.createInvoice(req));
        checkStatusRuntimeException(exception, List.of(
                new ViolationSpec("line_items.logically_unique", "invoice.line_items", "line items must be unique combinations of product_id and unit_price")
        ));
    }

    // Code omitted for brevity
}

To check your work, run all tests.

$  ./gradlew test --rerun

If all tests pass, you've met your goal:

Test results
InvoiceServerTest > InvoiceId is required PASSED

InvoiceServerTest > Two line items cannot have the same product_id and unit price PASSED

InvoiceServerTest > A valid invoice passes validation PASSED

More testing examples

The finish directory contains a thorough test that you can use as an example for your own tests. Its invoice.proto file also contains extensive Protovalidate rules.

Wrapping up

In this tutorial, you've learned the basics of working with Protovalidate:

  1. Adding Protovalidate to your project.
  2. Declaring validation rules in your Protobuf files.
  3. Enabing their enforcement within an RPC API.
  4. Testing their functionality.

Further reading