Python quickstart#

Getting started with Protovalidate is simple if you're familiar with Python and Buf—otherwise, you may want to follow the step-by-step example.

Add buf.build/bufbuild/protovalidate to buf.yaml then buf dep update.

Add validation rules and generate code.

message User {
    string name = 1 [(buf.validate.field).required = true];
}

Install Protovalidate: pip install protovalidate
Validate Protobuf messages:
```
protovalidate.validate(message)
```
Validate RPC requests with interceptors. See gRPC and Python for an example.

Step-by-step example#

Start by setting up the example project:

Install the Buf CLI. If you already have, run buf --version to verify that you're using at least 1.54.0.
Have git and Python 3.9+ installed.

Clone the buf-examples repository:

$ git clone https://github.com/bufbuild/buf-examples.git

Open a terminal to the repository and navigate to protovalidate/quickstart-python/start.

The quickstart code contains Buf CLI configuration files (buf.yaml, buf.gen.yaml), a simple weather_service.proto, and an idiomatic unit test.

Add Protovalidate to schemas#

Depend on Protovalidate#

Protovalidate is available through the Buf Schema Registry and provides the Protobuf extensions, options, and messages powering validation.

Add it as a dependency in buf.yaml:

buf.yaml

version: v2
modules:
  - path: proto
+ deps:
+   - buf.build/bufbuild/protovalidate
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

Next, update dependencies. You may see a warning that Protovalidate hasn't yet been used. That's fine.

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

Add rules to a message#

Open proto/bufbuild/weather/v1/weather_service.proto, import Protovalidate, and add validation rules to GetWeatherRequest.

proto/bufbuild/weather/v1/weather_service.proto

syntax = "proto3";

package bufbuild.weather.v1;

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

// GetWeatherRequest is a request for weather at a point on Earth.
message GetWeatherRequest {
  // latitude must be between -90 and 90, inclusive, to be valid. Use of a
  // float allows precision to about one square meter.
- float latitude = 1;
+ float latitude = 1 [
+   (buf.validate.field).float.gte = -90,
+   (buf.validate.field).float.lte = 90
+ ];

  // longitude must be between -180 and 180, inclusive, to be valid. Use of a
  // float allows precision to about one square meter.
- float longitude = 2;
+ float longitude = 2 [
+   (buf.validate.field).float.gte = -180,
+   (buf.validate.field).float.lte = 180
+ ];

  // forecast_date for the weather request. It must be within the next
  // three days.
  google.protobuf.Timestamp forecast_date = 3;
}

Try it in the Playground#

Experiment with Protovalidate rules in the Protovalidate playground—modify this example, try out a custom CEL rule, or write your own validation logic without any local setup.

Lint your changes#

Some rule combinations compile successfully but fail at runtime. This example requires latitude but also skips its validation when it has its zero value, creating a logical contradiction:

Example IGNORE_IF_ZERO_VALUE lint error

message GetWeatherRequest {
  float latitude = 1 [
    (buf.validate.field).ignore = IGNORE_IF_ZERO_VALUE,
    (buf.validate.field).required = true,
    (buf.validate.field).float.gte = -90,
    (buf.validate.field).float.lte = 90
  ];
}

buf lint identifies these and other problems, like invalid CEL expressions, with its PROTOVALIDATE rule :

Buf lint errors for the PROTOVALIDATE rule

$ buf lint
proto/bufbuild/weather/v1/weather_service.proto:29:5:Field "latitude" has both
(buf.validate.field).required and (buf.validate.field).ignore=IGNORE_IF_ZERO_VALUE.
A field cannot be empty if it is required.

Run buf lint whenever you edit your schemas and in GitHub Actions or other CI/CD tools.

Build the module#

Now that you've added Protovalidate as a dependency, updated your schema with rules, and validated changes with buf lint, your module should build with no errors:

$ buf build

Generate code#

With Protovalidate, you don't need any new code generation plugins: its rules are compiled as part of your message descriptors.

Run buf generate to include your new rules in the GetWeatherRequest descriptor:

$ buf generate

To learn more about generating code with the Buf CLI, read the code generation overview.

Add business logic with CEL#

Real world validation rules are often complicated and need more than a simple set of static rules:

A BuyMovieTicketsRequest request must be for a showtime in the future but no more than two weeks in the future.
A CreateTeamRequest with repeated members must ensure all email addresses are unique across the team.
A ScheduleMeetingRequest must have a start_time before its end_time, and the meeting duration can't exceed 8 hours.

Protovalidate can meet all of these requirements because all Protovalidate rules are defined in Common Expression Language (CEL). CEL is a lightweight, high-performance expression language that allows expressions like this.first_flight_duration + this.second_flight_duration < duration('48h') to evaluate consistently across languages.

Adding a CEL-based rule to a field is straightforward. Instead of a providing a static value, you provide a unique identifier (id), an error message, and a CEL expression. Building on the prior GetWeatherRequest example, add a custom rule stating that users must ask for weather forecasts within the next 72 hours:

proto/bufbuild/weather/v1/weather_service.proto

syntax = "proto3";

package bufbuild.weather.v1;

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

// GetWeatherRequest is a request for weather at a point on Earth.
message GetWeatherRequest {
  // latitude must be between -90 and 90, inclusive, to be valid. Use of a
  // float allows precision to about one square meter.
  float latitude = 1 [
    (buf.validate.field).float.gte = -90,
    (buf.validate.field).float.lte = 90
  ];
  // longitude must be between -180 and 180, inclusive, to be valid. Use of a
  // float allows precision to about one square meter.
  float longitude = 2 [
    (buf.validate.field).float.gte = -180,
    (buf.validate.field).float.lte = 180
  ];

  // forecast_date for the weather request. It must be within the next
  // three days.
- google.protobuf.Timestamp forecast_date = 3;
+ google.protobuf.Timestamp forecast_date = 3 [(buf.validate.field).cel = {
+     id: "forecast_date.within_72_hours"
+     message: "Forecast date must be in the next 72 hours."
+     expression: "this >= now && this <= now + duration('72h')"
+ }];
}

Remember to recompile and regenerate code:

$ buf generate

Run validation#

The example code has a failing test (weather_test.py). Let's get it to pass, using Protovalidate's Python API to validate sample messages.

Make sure you've navigated to protovalidate/quickstart-python/start within the buf-examples repository.
Using a virtual environment, install dependencies. In your own projects, you'd need to add the protocolbuffers/pyi and protocolbuffers/python generated SDKs for Protovalidate.
```
$ python3 -m venv venv
$ source ./venv/bin/activate
(venv) $ pip install -r requirements.txt --extra-index-url https://buf.build/gen/python
```

Run weather_test.py. It should fail: it expects invalid latitudes and longitudes to be rejected, but you haven't yet added any validation.

$ python3 -m unittest -v weather_test.py
test_bad_forecast_date (weather_test.WeatherTest.test_bad_forecast_date) ... FAIL
test_bad_latitude (weather_test.WeatherTest.test_bad_latitude) ... FAIL
test_bad_longitude (weather_test.WeatherTest.test_bad_longitude) ... FAIL
test_valid_request (weather_test.WeatherTest.test_valid_request) ... ok

Open weather.py. Update the validateWeather function to return the result of protovalidate.validate():
weather.py
```
+ import protovalidate

def validateWeather(request):
-   pass
+   protovalidate.validate(request)
```
Run weather_test.py. Now that you've added validation, all tests should pass.
```
$ python3 -m unittest -v weather_test.py
```

You've now walked through the basic steps for using Protovalidate: adding it as a dependency, annotating your schemas with rules, and validating Protobuf messages.

Validate RPC requests#

One of Protovalidate's most common use cases is for validating requests made to RPCs. See gRPC and Python for an example that uses an interceptor to automatically validate requests.

Next steps#

Read on to learn more about enabling schema-first validation with Protovalidate:

Review Protovalidate's library of ready-to-use standard rules.
Learn how to write custom validation rules with Common Expression Language.
Explore how Protovalidate works in advanced CEL topics.