Skip to content

JavaScript/TypeScript quickstart#

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

  1. Add buf.build/bufbuild/protovalidate to buf.yaml then buf dep update.
  2. Add validation rules and generate code. 
    message User {
    string name = 1 [(buf.validate.field).required = true];
}
  3. Install Protovalidate: npm install @bufbuild/protovalidate.
  4. Validate Protobuf messages: 
    const validator = createValidator();
const result = validator.validate(Schema, message);
  5. Validate RPC requests with @connectrpc/validate.

Step-by-step example#

Start by setting up the example project:

  1. Install the Buf CLI. If you already have, run buf --version to verify that you're using at least 1.54.0.
  2. Have git and Node.js installed.

  3. Clone the buf-examples repository:

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

  4. Open a terminal to the repository and navigate to protovalidate/quickstart-es/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.

Include imports#

You'll need to generate code for Protovalidate. Update the settings for the bufbuild/es plugin in buf.gen.yaml, adding include_imports: true:

buf.gen.yaml
version: v2
clean: true
inputs:
  - directory: proto
plugins:
  - remote: buf.build/bufbuild/es:v2.5.1
    out: src/gen
    opt:
      - target=ts
      - import_extension=js
+   include_imports: true

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:

  1. A BuyMovieTicketsRequest request must be for a showtime in the future but no more than two weeks in the future.
  2. A CreateTeamRequest with repeated members must ensure all email addresses are unique across the team.
  3. 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.js). Let's get it to pass, using Protovalidate's API to validate sample messages.

  1. Navigate to protovalidate/quickstart-es/start within the buf-examples repository.

  2. Install Protovalidate using npm.

    $ npm install @bufbuild/protovalidate

  3. Run src/weather.test.ts with npm test. It should fail: it expects invalid latitudes and longitudes to be rejected, but you haven't yet added any validation.

    $ npm run test

❯ src/weather.test.ts (4 tests | 4 failed) 5ms
  × valid message 3ms
    → expected undefined to be defined
  × latitude too high 0ms
    → expected undefined to be defined
  × latitude too low 0ms
    → expected undefined to be defined
  × too far in the future 1ms
    → expected undefined to be defined

  4. Open src/weather.ts and make the following modifications.

    src/weather.ts
    + import { createValidator, type ValidationResult } from "@bufbuild/protovalidate";
import {
    GetWeatherRequest,
+   GetWeatherRequestSchema
} from "./gen/bufbuild/weather/v1/weather_service_pb.js";

+ const validator = createValidator();

- export function validateWeather(msg: GetWeatherRequest): any {
+ export function validateWeather(msg: GetWeatherRequest): ValidationResult {
-    // TODO: validate the request
+   return validator.validate(GetWeatherRequestSchema, msg);
}

  5. Run npm test. Now that you've added validation, all tests should pass.

    $ npm run test

✓ src/weather.test.ts (4 tests) 26ms
✓ valid message 24ms
✓ latitude too high 1ms
✓ latitude too low 0ms
✓ too far in the future 1ms

Test Files  1 passed (1)
Tests  4 passed (4)

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. Use the @connectrpc/validate interceptor for automatic validation across your APIs.

Next steps#

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